> For the complete documentation index, see [llms.txt](https://developers.coincircuit.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.coincircuit.io/invoices.md).

# Invoices

Create and manage invoices

## List invoices

> Returns all invoices.

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Invoices","description":"Create and manage invoices"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"schemas":{"InvoicesResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"description":"List of invoices","type":"array","items":{"$ref":"#/components/schemas/InvoiceResponseDto"}},"meta":{"description":"Pagination metadata for list responses","allOf":[{"$ref":"#/components/schemas/PaginationMetaDto"}]}},"required":["success","message","meta"]},"InvoiceResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Invoice ID"},"reference":{"type":"string","description":"Invoice reference"},"description":{"type":"string","description":"Invoice description"},"status":{"type":"string","description":"Invoice payment status (pending, partial, paid)","enum":["pending","partial","paid","expired"]},"state":{"type":"string","description":"Invoice state: open (accepting payment) or closed (finalized)","enum":["open","closed"]},"isRefunded":{"type":"boolean","description":"Whether this invoice has been refunded"},"isUnderpaymentAccepted":{"type":"boolean","description":"Whether the merchant accepted this partial payment"},"amount":{"type":"string","description":"Invoice amount (computed as the sum of all item totals)"},"amountPaid":{"type":"string","description":"Amount paid so far"},"currency":{"type":"string","description":"Invoice currency","enum":["NGN","USD"]},"items":{"description":"Invoice items","type":"array","items":{"$ref":"#/components/schemas/InvoiceItemResponseDto"}},"asset":{"type":"string","description":"Cryptocurrency asset","nullable":true},"chain":{"type":"string","description":"Blockchain network","nullable":true},"merchant":{"description":"Merchant information","allOf":[{"$ref":"#/components/schemas/MerchantInfoDto"}]},"customer":{"description":"Customer details","allOf":[{"$ref":"#/components/schemas/CustomerDto"}]},"url":{"type":"string","description":"Public URL to access this invoice"},"successUrl":{"type":"string","description":"Custom success redirect URL for invoice","nullable":true},"cancelUrl":{"type":"string","description":"Custom cancel redirect URL for invoice","nullable":true},"metadata":{"type":"object","description":"Invoice-level metadata","nullable":true},"periodStart":{"format":"date-time","type":"string","description":"Billing period start date (for subscription/recurring invoices)"},"periodEnd":{"format":"date-time","type":"string","description":"Billing period end date (for subscription/recurring invoices)"},"paidAt":{"format":"date-time","type":"string","description":"Invoice paid date (when status became paid)"},"expiresAt":{"format":"date-time","type":"string","description":"Invoice expiration date"},"createdAt":{"format":"date-time","type":"string","description":"Invoice creation date"}},"required":["id","reference","status","state","isRefunded","amount","amountPaid","currency","items","merchant","customer","url","createdAt"]},"InvoiceItemResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Item ID"},"name":{"type":"string","description":"Item name"},"description":{"type":"string","description":"Item description","nullable":true},"unit":{"type":"string","description":"Unit of measure label","nullable":true},"quantity":{"type":"string","description":"Quantity"},"unitPrice":{"type":"string","description":"Price per unit"},"lineTotal":{"type":"string","description":"Line total (quantity x unit price)"}},"required":["id","name","quantity","unitPrice","lineTotal"]},"MerchantInfoDto":{"type":"object","properties":{"businessName":{"type":"string","description":"Merchant business name"},"logoUrl":{"type":"string","description":"Merchant logo URL"}},"required":["businessName"]},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"PaginationMetaDto":{"type":"object","properties":{"page":{"type":"number","description":"Current page (1-based)"},"size":{"type":"number","description":"Number of items per page"},"total":{"type":"number","description":"Total number of items available for this query"},"totalPages":{"type":"number","description":"Total number of pages for this query"}},"required":["page","size","total","totalPages"]}}},"paths":{"/api/v1/invoices":{"get":{"description":"Returns all invoices.","operationId":"InvoicesController_listInvoices","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Search by invoice reference","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter by invoice status","schema":{"type":"string","enum":["pending","partial","paid","expired"]}},{"name":"state","required":false,"in":"query","description":"Filter by invoice state","schema":{"type":"string","enum":["open","closed"]}},{"name":"currency","required":false,"in":"query","description":"Filter by currency","schema":{"type":"string"}},{"name":"startDate","required":false,"in":"query","description":"Filter invoices created from this date/time (ISO 8601)","schema":{"type":"string"}},{"name":"endDate","required":false,"in":"query","description":"Filter invoices created up to this date/time (ISO 8601)","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoicesResponseDto"}}}},"401":{"description":"Unauthorized"}},"summary":"List invoices","tags":["Invoices"]}}}}
```

## Create invoice

> Creates an invoice for a product/service.

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Invoices","description":"Create and manage invoices"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"schemas":{"CreateInvoiceDto":{"type":"object","properties":{"reference":{"type":"string","description":"Custom invoice reference. If not provided, auto-generated."},"items":{"description":"Invoice items. The invoice amount is computed as the sum of (quantity x unit price) across all items.","type":"array","items":{"$ref":"#/components/schemas/CreateInvoiceItemDto"}},"currency":{"type":"string","description":"Fiat currency for the invoice","enum":["NGN","USD"]},"description":{"type":"string","description":"Invoice description shown to the customer"},"expiresAt":{"type":"string","description":"Invoice expiry date in ISO 8601 format. Defaults to 1 day from creation, up to a maximum of 5 days."},"periodStart":{"type":"string","description":"Billing period start date (for subscription/recurring invoices)"},"periodEnd":{"type":"string","description":"Billing period end date (for subscription/recurring invoices)"},"metadata":{"type":"object","description":"custom metadata"},"successUrl":{"type":"string","description":"Custom success redirect URL for invoice"},"cancelUrl":{"type":"string","description":"Custom cancel redirect URL for invoice"},"webhookUrl":{"type":"string","description":"Optional URL to receive webhook notifications for this invoice (must be HTTPS). Overrides your dashboard webhook URL for this invoice only."},"asset":{"type":"string","description":"Cryptocurrency asset"},"chain":{"type":"string","description":"Blockchain network"},"customer":{"description":"Customer details","allOf":[{"$ref":"#/components/schemas/CreateInvoiceCustomerDto"}]}},"required":["items","currency","description","expiresAt","customer"]},"CreateInvoiceItemDto":{"type":"object","properties":{"name":{"type":"string","description":"Item name"},"description":{"type":"string","description":"Item description"},"unit":{"type":"string","description":"Unit of measure label"},"quantity":{"type":"string","description":"Quantity, as a numeric string with up to 8 decimal places"},"unitPrice":{"type":"string","description":"Price per unit, as a numeric string with up to 12 decimal places"}},"required":["name","quantity","unitPrice"]},"CreateInvoiceCustomerDto":{"type":"object","properties":{"email":{"type":"string","description":"Customer email"},"firstName":{"type":"string","description":"Customer name"},"lastName":{"type":"string","description":"Customer last name"},"phone":{"type":"string","description":"Customer phone number in international format (E.164)"},"telegramId":{"type":"string","description":"Customer Telegram ID"}},"required":["email","firstName"]},"InvoiceApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"description":"Response data","allOf":[{"$ref":"#/components/schemas/InvoiceResponseDto"}]}},"required":["success","message"]},"InvoiceResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Invoice ID"},"reference":{"type":"string","description":"Invoice reference"},"description":{"type":"string","description":"Invoice description"},"status":{"type":"string","description":"Invoice payment status (pending, partial, paid)","enum":["pending","partial","paid","expired"]},"state":{"type":"string","description":"Invoice state: open (accepting payment) or closed (finalized)","enum":["open","closed"]},"isRefunded":{"type":"boolean","description":"Whether this invoice has been refunded"},"isUnderpaymentAccepted":{"type":"boolean","description":"Whether the merchant accepted this partial payment"},"amount":{"type":"string","description":"Invoice amount (computed as the sum of all item totals)"},"amountPaid":{"type":"string","description":"Amount paid so far"},"currency":{"type":"string","description":"Invoice currency","enum":["NGN","USD"]},"items":{"description":"Invoice items","type":"array","items":{"$ref":"#/components/schemas/InvoiceItemResponseDto"}},"asset":{"type":"string","description":"Cryptocurrency asset","nullable":true},"chain":{"type":"string","description":"Blockchain network","nullable":true},"merchant":{"description":"Merchant information","allOf":[{"$ref":"#/components/schemas/MerchantInfoDto"}]},"customer":{"description":"Customer details","allOf":[{"$ref":"#/components/schemas/CustomerDto"}]},"url":{"type":"string","description":"Public URL to access this invoice"},"successUrl":{"type":"string","description":"Custom success redirect URL for invoice","nullable":true},"cancelUrl":{"type":"string","description":"Custom cancel redirect URL for invoice","nullable":true},"metadata":{"type":"object","description":"Invoice-level metadata","nullable":true},"periodStart":{"format":"date-time","type":"string","description":"Billing period start date (for subscription/recurring invoices)"},"periodEnd":{"format":"date-time","type":"string","description":"Billing period end date (for subscription/recurring invoices)"},"paidAt":{"format":"date-time","type":"string","description":"Invoice paid date (when status became paid)"},"expiresAt":{"format":"date-time","type":"string","description":"Invoice expiration date"},"createdAt":{"format":"date-time","type":"string","description":"Invoice creation date"}},"required":["id","reference","status","state","isRefunded","amount","amountPaid","currency","items","merchant","customer","url","createdAt"]},"InvoiceItemResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Item ID"},"name":{"type":"string","description":"Item name"},"description":{"type":"string","description":"Item description","nullable":true},"unit":{"type":"string","description":"Unit of measure label","nullable":true},"quantity":{"type":"string","description":"Quantity"},"unitPrice":{"type":"string","description":"Price per unit"},"lineTotal":{"type":"string","description":"Line total (quantity x unit price)"}},"required":["id","name","quantity","unitPrice","lineTotal"]},"MerchantInfoDto":{"type":"object","properties":{"businessName":{"type":"string","description":"Merchant business name"},"logoUrl":{"type":"string","description":"Merchant logo URL"}},"required":["businessName"]},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]}}},"paths":{"/api/v1/invoices":{"post":{"description":"Creates an invoice for a product/service.","operationId":"InvoicesController_createInvoice","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvoiceDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceApiResponseDto"}}}},"400":{"description":"Invalid input or expiration date exceeds 5 days"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"}},"summary":"Create invoice","tags":["Invoices"]}}}}
```

## Retrieve invoice by reference

> Returns the invoice for the given reference.

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Invoices","description":"Create and manage invoices"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"paths":{"/api/v1/invoices/reference/{reference}":{"get":{"description":"Returns the invoice for the given reference.","operationId":"InvoicesController_getInvoice","parameters":[{"name":"reference","required":true,"in":"path","description":"Invoice reference","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceApiResponseDto"}}}},"404":{"description":"Invoice not found"}},"summary":"Retrieve invoice by reference","tags":["Invoices"]}}},"components":{"schemas":{"InvoiceApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"description":"Response data","allOf":[{"$ref":"#/components/schemas/InvoiceResponseDto"}]}},"required":["success","message"]},"InvoiceResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Invoice ID"},"reference":{"type":"string","description":"Invoice reference"},"description":{"type":"string","description":"Invoice description"},"status":{"type":"string","description":"Invoice payment status (pending, partial, paid)","enum":["pending","partial","paid","expired"]},"state":{"type":"string","description":"Invoice state: open (accepting payment) or closed (finalized)","enum":["open","closed"]},"isRefunded":{"type":"boolean","description":"Whether this invoice has been refunded"},"isUnderpaymentAccepted":{"type":"boolean","description":"Whether the merchant accepted this partial payment"},"amount":{"type":"string","description":"Invoice amount (computed as the sum of all item totals)"},"amountPaid":{"type":"string","description":"Amount paid so far"},"currency":{"type":"string","description":"Invoice currency","enum":["NGN","USD"]},"items":{"description":"Invoice items","type":"array","items":{"$ref":"#/components/schemas/InvoiceItemResponseDto"}},"asset":{"type":"string","description":"Cryptocurrency asset","nullable":true},"chain":{"type":"string","description":"Blockchain network","nullable":true},"merchant":{"description":"Merchant information","allOf":[{"$ref":"#/components/schemas/MerchantInfoDto"}]},"customer":{"description":"Customer details","allOf":[{"$ref":"#/components/schemas/CustomerDto"}]},"url":{"type":"string","description":"Public URL to access this invoice"},"successUrl":{"type":"string","description":"Custom success redirect URL for invoice","nullable":true},"cancelUrl":{"type":"string","description":"Custom cancel redirect URL for invoice","nullable":true},"metadata":{"type":"object","description":"Invoice-level metadata","nullable":true},"periodStart":{"format":"date-time","type":"string","description":"Billing period start date (for subscription/recurring invoices)"},"periodEnd":{"format":"date-time","type":"string","description":"Billing period end date (for subscription/recurring invoices)"},"paidAt":{"format":"date-time","type":"string","description":"Invoice paid date (when status became paid)"},"expiresAt":{"format":"date-time","type":"string","description":"Invoice expiration date"},"createdAt":{"format":"date-time","type":"string","description":"Invoice creation date"}},"required":["id","reference","status","state","isRefunded","amount","amountPaid","currency","items","merchant","customer","url","createdAt"]},"InvoiceItemResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Item ID"},"name":{"type":"string","description":"Item name"},"description":{"type":"string","description":"Item description","nullable":true},"unit":{"type":"string","description":"Unit of measure label","nullable":true},"quantity":{"type":"string","description":"Quantity"},"unitPrice":{"type":"string","description":"Price per unit"},"lineTotal":{"type":"string","description":"Line total (quantity x unit price)"}},"required":["id","name","quantity","unitPrice","lineTotal"]},"MerchantInfoDto":{"type":"object","properties":{"businessName":{"type":"string","description":"Merchant business name"},"logoUrl":{"type":"string","description":"Merchant logo URL"}},"required":["businessName"]},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]}}}}
```
