# List invoices > List invoices: TrueProxies customer API reference with the required scope, parameters, responses and code samples. Source: https://docs.trueproxies.com/api/operations/get_v1_invoices/ `GET /v1/invoices` **Fetch** ```js const url = 'https://api.trueproxies.com/v1/invoices?limit=25&status=open&kind=wallet_topup'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` **cURL** ```sh curl --request GET \ --url 'https://api.trueproxies.com/v1/invoices?limit=25&status=open&kind=wallet_topup' \ --header 'Authorization: Bearer ' ``` Invoice amounts are integer cents in the specified currency. Supports cursor pagination and an optional service\_id filter. Creating and paying invoices requires billing:write or reseller:purchase; billing:read alone cannot spend money. ## Authorizations - **[customerAPIKey](https://docs.trueproxies.com/api/#customerapikey)** ## Parameters ### Query Parameters - **customer\_id** string format: uuid Owned sub-customer UUID. Resellers only; reads require reseller:read and writes reseller:purchase in addition to the operation scope. X-Customer-Id header is an alternative. Not allowed for me, wallet, trial, API keys, or reseller-management routes. - **cursor** string - **limit** integer default: 25 >= 1 <= 100 - **service\_id** string format: uuid Only invoices linked to this service and owned by the signed-in customer - **status** string Allowed values: open paid cancelled Filter before pagination and counting - **kind** string Allowed values: wallet\_topup purchase renewal topup custom white\_label Filter before pagination and counting ## Responses ### 200 Ok Media type: `application/json` object - **items** required Array\ object - **activated\_at** When this invoice’s service activation, top-up, renewal, or charge-only processing committed. Payment receipt and an already-active service do not establish this outcome. string format: date-time - **activation\_failed\_at** Automatic fulfillment stopped and needs operator attention. Payment remains received; this does not mean a refund completed or previously purchased service was revoked. string format: date-time - **amount\_cents** required integer - **bill\_to** Who the invoice is issued to, copied from the account’s billing details when the invoice was created. Absent when the account had no billing details then; saving details later does not change it. object - **address** string - **company** string - **country** string - **name** string - **vat\_id** string - **created\_at** required string format: date-time - **currency** required string - **discount\_bp** integer - **display\_name** required string - **due\_at** required string format: date-time - **expired** True when a cancelled invoice closed because it was not paid by due\_at. Invoices cancelled before this field existed report false. boolean - **id** required Internal API identifier. Use reference for customer-facing display. string format: uuid - **kind** required string Allowed values: wallet\_topup purchase renewal topup custom white\_label - **list\_amount\_cents** integer - **offer\_key** required string - **options** object - **city** string - **gb** GB for top-ups; taken from the offer otherwise integer - **paid\_at** string format: date-time - **payments** required Array\ object - **amount\_received\_cents** integer - **attempt** required integer - **checkout\_url** Present only while the invoice is payable and the pending checkout has not reached its known expiry string - **created\_at** required string format: date-time - **expires\_at** string format: date-time - **failure\_reason** Staff views only. Why the checkout ended unpaid, as the provider reports it: not\_attempted (no payment submitted), not\_completed (started, never confirmed), or the card issuer’s code such as card\_declined/insufficient\_funds. string - **id** required string format: uuid - **provider** required One of: **string** Payment provider identifier (stripe or cryptomus). string **string** string Allowed values: manual - **refund\_amount\_cents** integer \>= 1 - **refund\_amount\_unknown** A provider refund was reported without a trustworthy amount. Reconciliation is required before any additional refund. boolean - **refund\_completed\_at** string format: date-time - **refund\_reason** string - **refund\_reference** string - **refund\_retryable** The recorded request can be retried unchanged within the provider idempotency window. boolean - **refund\_status** string Allowed values: processing uncertain manual\_required submitted failed refunded - **refunded\_at** Refund request recorded at; not proof of completion string format: date-time - **status** required string Allowed values: pending paid expired failed paid\_unapplied paid\_duplicate - **promo\_code** string - **promo\_discount\_cents** integer format: int64 - **reference** required Stable, unique customer-facing reference. string /^INV-\[0-9]{6,}$/ - **service\_id** string format: uuid - **status** required string Allowed values: open paid cancelled - **limit** required integer - **next\_cursor** string - **total** required integer ##### Example ```json { "items": [ { "kind": "wallet_topup", "payments": [ { "provider": "manual", "refund_status": "processing", "status": "pending" } ], "reference": "INV-001001", "status": "open" } ] } ``` ### 400 Error Media type: `application/json` object - **code** required string Allowed values: BAD\_REQUEST UNAUTHENTICATED FORBIDDEN NOT\_FOUND CONFLICT RATE\_LIMITED SERVICE\_UNAVAILABLE OFFER\_UNAVAILABLE CITY\_UNAVAILABLE CAPACITY\_UNAVAILABLE INVOICE\_NOT\_PAYABLE PROVIDER\_ERROR PIPE\_UNAVAILABLE TRIAL\_NOT\_ELIGIBLE EMAIL\_UNVERIFIED INTERNAL - **details** What a client needs to act on the error (ids, flags), never display text. object - ***key*** additional properties any - **message** required string ##### Example ```json { "code": "BAD_REQUEST" } ``` ### 401 Error Media type: `application/json` object - **code** required string Allowed values: BAD\_REQUEST UNAUTHENTICATED FORBIDDEN NOT\_FOUND CONFLICT RATE\_LIMITED SERVICE\_UNAVAILABLE OFFER\_UNAVAILABLE CITY\_UNAVAILABLE CAPACITY\_UNAVAILABLE INVOICE\_NOT\_PAYABLE PROVIDER\_ERROR PIPE\_UNAVAILABLE TRIAL\_NOT\_ELIGIBLE EMAIL\_UNVERIFIED INTERNAL - **details** What a client needs to act on the error (ids, flags), never display text. object - ***key*** additional properties any - **message** required string ##### Example ```json { "code": "BAD_REQUEST" } ``` ### 403 Error Media type: `application/json` object - **code** required string Allowed values: BAD\_REQUEST UNAUTHENTICATED FORBIDDEN NOT\_FOUND CONFLICT RATE\_LIMITED SERVICE\_UNAVAILABLE OFFER\_UNAVAILABLE CITY\_UNAVAILABLE CAPACITY\_UNAVAILABLE INVOICE\_NOT\_PAYABLE PROVIDER\_ERROR PIPE\_UNAVAILABLE TRIAL\_NOT\_ELIGIBLE EMAIL\_UNVERIFIED INTERNAL - **details** What a client needs to act on the error (ids, flags), never display text. object - ***key*** additional properties any - **message** required string ##### Example ```json { "code": "BAD_REQUEST" } ``` ### 404 Error Media type: `application/json` object - **code** required string Allowed values: BAD\_REQUEST UNAUTHENTICATED FORBIDDEN NOT\_FOUND CONFLICT RATE\_LIMITED SERVICE\_UNAVAILABLE OFFER\_UNAVAILABLE CITY\_UNAVAILABLE CAPACITY\_UNAVAILABLE INVOICE\_NOT\_PAYABLE PROVIDER\_ERROR PIPE\_UNAVAILABLE TRIAL\_NOT\_ELIGIBLE EMAIL\_UNVERIFIED INTERNAL - **details** What a client needs to act on the error (ids, flags), never display text. object - ***key*** additional properties any - **message** required string ##### Example ```json { "code": "BAD_REQUEST" } ``` ### 409 Error Media type: `application/json` object - **code** required string Allowed values: BAD\_REQUEST UNAUTHENTICATED FORBIDDEN NOT\_FOUND CONFLICT RATE\_LIMITED SERVICE\_UNAVAILABLE OFFER\_UNAVAILABLE CITY\_UNAVAILABLE CAPACITY\_UNAVAILABLE INVOICE\_NOT\_PAYABLE PROVIDER\_ERROR PIPE\_UNAVAILABLE TRIAL\_NOT\_ELIGIBLE EMAIL\_UNVERIFIED INTERNAL - **details** What a client needs to act on the error (ids, flags), never display text. object - ***key*** additional properties any - **message** required string ##### Example ```json { "code": "BAD_REQUEST" } ``` ### 429 Error Media type: `application/json` object - **code** required string Allowed values: BAD\_REQUEST UNAUTHENTICATED FORBIDDEN NOT\_FOUND CONFLICT RATE\_LIMITED SERVICE\_UNAVAILABLE OFFER\_UNAVAILABLE CITY\_UNAVAILABLE CAPACITY\_UNAVAILABLE INVOICE\_NOT\_PAYABLE PROVIDER\_ERROR PIPE\_UNAVAILABLE TRIAL\_NOT\_ELIGIBLE EMAIL\_UNVERIFIED INTERNAL - **details** What a client needs to act on the error (ids, flags), never display text. object - ***key*** additional properties any - **message** required string ##### Example ```json { "code": "BAD_REQUEST" } ``` ### 500 Error Media type: `application/json` object - **code** required string Allowed values: BAD\_REQUEST UNAUTHENTICATED FORBIDDEN NOT\_FOUND CONFLICT RATE\_LIMITED SERVICE\_UNAVAILABLE OFFER\_UNAVAILABLE CITY\_UNAVAILABLE CAPACITY\_UNAVAILABLE INVOICE\_NOT\_PAYABLE PROVIDER\_ERROR PIPE\_UNAVAILABLE TRIAL\_NOT\_ELIGIBLE EMAIL\_UNVERIFIED INTERNAL - **details** What a client needs to act on the error (ids, flags), never display text. object - ***key*** additional properties any - **message** required string ##### Example ```json { "code": "BAD_REQUEST" } ``` ### 503 Error Media type: `application/json` object - **code** required string Allowed values: BAD\_REQUEST UNAUTHENTICATED FORBIDDEN NOT\_FOUND CONFLICT RATE\_LIMITED SERVICE\_UNAVAILABLE OFFER\_UNAVAILABLE CITY\_UNAVAILABLE CAPACITY\_UNAVAILABLE INVOICE\_NOT\_PAYABLE PROVIDER\_ERROR PIPE\_UNAVAILABLE TRIAL\_NOT\_ELIGIBLE EMAIL\_UNVERIFIED INTERNAL - **details** What a client needs to act on the error (ids, flags), never display text. object - ***key*** additional properties any - **message** required string ##### Example ```json { "code": "BAD_REQUEST" } ```