Skip to content
Docsv2 preview

List invoices

GET/v1/invoices

Newest first. Every filter narrows the list, with one exception: status and outcome_flags given together match an invoice that has one of the statuses or carries one of the flags.

Authorization

Section titled “Authorization”

Send your API key as a bearer token in the Authorization header. Secret API key: Authorization: Bearer ctp_live_sk_…. A publishable key (ctp_…_pk_…) is accepted by these operations only, which serve reference data: getRate, listAssets, listNetworks (each marked x-publishable-key: true). Every other operation refuses it with 403 publishable_key_not_allowed, whatever Origin the request carries: that header binds browsers, not other clients, and nothing on this API relies on it.

Query parameters

Section titled “Query parameters”
Name Type Description
limit integer Number of items to return (1 to 100). Default 50. Minimum 1, maximum 100.
starting_after string Return items after this id: pass next_cursor of the previous page. At most 100 characters.
status string Invoices in this status. One of open, pending, underpaid, paid, expired, canceled, refunded, or several separated by commas. At most 256 characters.
outcome_flags string Invoices that carry this outcome flag. One of overpaid, late, underpaid_accepted, partially_refunded, or several separated by commas. At most 256 characters.
order_id string Exactly this order_id. At most 128 characters.
network string Network slug, e.g. bsc, or several separated by commas. Matches the network of the option the payer chose; while none is chosen, any network the invoice offers. At most 528 characters.
created_after string (date-time) Created at or after this moment.
created_before string (date-time) Created at or before this moment.
q string Free text, matched literally and without regard to letter case: part of the order id, of the description or of the customer’s email, or the whole invoice number (42, INV-0042) or id. At most 128 characters.

Example request

Section titled “Example request”
Terminal window
curl "https://api.ctpeway.com/v1/invoices" \
  -H "Authorization: Bearer $CTPEWAY_API_KEY"

Response

Section titled “Response”

200 OK

Section titled “200 OK”
Field Type Description
data array of objects
data[].id string
data[].number integer
data[].status string One of open, pending, underpaid, paid, expired, canceled, refunded.
data[].outcome_flags array of strings Values: overpaid, late, underpaid_accepted, partially_refunded.
data[].kind string One of fiat, crypto.
data[].price optional object
data[].price.currency string
data[].price.amount string A decimal number written as a string, with up to 8 decimal places.
data[].options array of objects
data[].options[].id string
data[].options[].network string
data[].options[].asset string
data[].options[].asset_id string
data[].options[].contract optional string
data[].options[].decimals integer
data[].options[].amount_due optional string Set once the option is selected (fiat invoices). A quoted amount is rounded up to display_decimals, so the amount shown to the payer is exactly the amount that pays the invoice. A whole number written as a string of digits.
data[].options[].display_decimals optional integer Present with amount_due: the decimals it is stated with. amount_due is a whole number of 10^(decimals − display_decimals) base units; equal to decimals when the amount is exact to the base unit (crypto invoices).
data[].options[].rate optional string Price of one unit of the asset in the invoice currency at lock time. A decimal number written as a string, with up to 8 decimal places.
data[].options[].quote_expires_at optional string (date-time) Until when amount_due holds. Afterwards the payer takes a new quote; the invoice lives on.
data[].options[].address optional string
data[].options[].token_account optional string Solana tokens: the address’s associated token account, where the token is held.
data[].options[].selected_at optional string (date-time)
data[].options[].amount_paid string Sum of confirmed payments to this option. A whole number written as a string of digits.
data[].options[].amount_detected string Sum of detected, unconfirmed payments to this option. A whole number written as a string of digits.
data[].selected_option_id optional string
data[].paid_option_id optional string
data[].tolerance_bps integer
data[].order_id optional string
data[].customer_email optional string The customer the merchant named when creating the invoice.
data[].description optional string
data[].metadata optional map of string to string
data[].expires_at string (date-time)
data[].pre_selection_expires_at string (date-time)
data[].created_at string (date-time)
data[].paid_at optional string (date-time)
data[].expired_at optional string (date-time)
data[].canceled_at optional string (date-time)
data[].refunded_at optional string (date-time) When the invoice became refunded.
data[].livemode boolean false for objects of the test environment.
data[].checkout_url string The hosted checkout page of this invoice. Send the payer here.
has_more boolean Whether more items exist after this page.
next_cursor string or null Pass as starting_after to get the next page; null on the last page. 
{
  "data": [
    {
      "id": "string",
      "number": 0,
      "status": "open",
      "outcome_flags": [
        "overpaid"
      ],
      "kind": "fiat",
      "price": {
        "currency": "string",
        "amount": "10.00"
      },
      "options": [
        {
          "id": "string",
          "network": "string",
          "asset": "string",
          "asset_id": "string",
          "contract": "string",
          "decimals": 0,
          "amount_due": "1000000",
          "display_decimals": 0,
          "rate": "10.00",
          "quote_expires_at": "2026-01-01T00:00:00.000Z",
          "address": "string",
          "token_account": "string",
          "selected_at": "2026-01-01T00:00:00.000Z",
          "amount_paid": "1000000",
          "amount_detected": "1000000"
        }
      ],
      "selected_option_id": "string",
      "paid_option_id": "string",
      "tolerance_bps": 0,
      "order_id": "string",
      "customer_email": "string",
      "description": "string",
      "metadata": {},
      "expires_at": "2026-01-01T00:00:00.000Z",
      "pre_selection_expires_at": "2026-01-01T00:00:00.000Z",
      "created_at": "2026-01-01T00:00:00.000Z",
      "paid_at": "2026-01-01T00:00:00.000Z",
      "expired_at": "2026-01-01T00:00:00.000Z",
      "canceled_at": "2026-01-01T00:00:00.000Z",
      "refunded_at": "2026-01-01T00:00:00.000Z",
      "livemode": true,
      "checkout_url": "string"
    }
  ],
  "has_more": true,
  "next_cursor": "string"
}

The values are placeholders generated from the schema. They show the shape, not real data.

Errors

Section titled “Errors”

A failed request answers with the error format described under Errors.

Besides the codes any endpoint can return, this endpoint can answer with these code values: