> 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"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.coincircuit.io/invoices.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.