Create a purchase invoice

POST

/v1/invoices

const url = 'https://api.trueproxies.com/v1/invoices';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"offer_key":"example","options":{"city":"example","gb":1},"promo_code":"example","request_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","service_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.trueproxies.com/v1/invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "offer_key": "example", "options": { "city": "example", "gb": 1 }, "promo_code": "example", "request_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "service_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'

Requires billing:write; reseller:purchase also permits this operation. Add customer_id to buy for an owned managed customer, which additionally requires reseller:purchase. Prices and discount are snapshotted; a floor conflict returns 409.

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.

Header Parameters

Idempotency-Key

string

<= 200 characters

Makes a retry safe. The first request carrying a given key is executed and its response recorded; repeating the same request with the same key replays that response, with Idempotency-Replayed: true, rather than buying or paying a second time. Reusing a key for a different request is refused with 409, as is a repeat that arrives while the first is still running. Keys are scoped to your account and to the endpoint. Successful and uncertain invoice commands are retained so that an old retry cannot create another invoice. Completed definite rejections are kept for at least 24 hours; after that, the same key may be evaluated again.

Request Body^required

application/json

object

offer_key

required

string

options

object

city

string

GB for top-ups; taken from the offer otherwise

integer

promo_code

string

>= 3 characters <= 40 characters /^[A-Za-z0-9][A-Za-z0-9-]{2,39}$/

request_id

Required when promo_code is present; keep stable only while retrying identical invoice content.

string format: uuid

service_id

Required for renewal and topup

string format: uuid

Example^generated

{
  "offer_key": "example",
  "options": {
    "city": "example",
    "gb": 1
  },
  "promo_code": "example",
  "request_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "service_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
}

Responses

201

Created

application/json

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

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 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

required

string format: uuid

provider

required

One of:

string
string

Payment provider identifier (stripe or cryptomus).

string

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

Example

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

400

Error

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

{
  "code": "BAD_REQUEST"
}

401

Error

application/json

object

code

required

string

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

application/json

object

code

required

string

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

application/json

object

code

required

string

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

application/json

object

code

required

string

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

application/json

object

code

required

string

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

application/json

object

code

required

string

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

application/json

object

code

required

string

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

Create a purchase invoice

Authorizations

Parameters

Query Parameters

Header Parameters

Request Bodyrequired

Examplegenerated

Responses

201

Example

400

Example

401

Example

403

Example

404

Example

409

Example

429

Example

500

Example

503

Example

Request Body^required

Example^generated