List invoices

GET

/v1/invoices

curl --request GET \
  --url 'https://api.trueproxies.com/v1/invoices?limit=25&status=open&kind=wallet_topup' \
  --header 'Authorization: Bearer <token>'

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

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 typeapplication/json

object

items

required

Array<object>

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>

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

{
  "items": [
    {
      "kind": "wallet_topup",
      "payments": [
        {
          "provider": "manual",
          "refund_status": "processing",
          "status": "pending"
        }
      ],
      "reference": "INV-001001",
      "status": "open"
    }
  ]
}

400

Error

Media typeapplication/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

{
  "code": "BAD_REQUEST"
}

401

Error

Media typeapplication/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

{
  "code": "BAD_REQUEST"
}

403

Error

Media typeapplication/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

{
  "code": "BAD_REQUEST"
}

404

Error

Media typeapplication/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

{
  "code": "BAD_REQUEST"
}

409

Error

Media typeapplication/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

{
  "code": "BAD_REQUEST"
}

429

Error

Media typeapplication/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

{
  "code": "BAD_REQUEST"
}

500

Error

Media typeapplication/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

{
  "code": "BAD_REQUEST"
}

503

Error

Media typeapplication/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

{
  "code": "BAD_REQUEST"
}