Cancel an unpaid invoice

POST

/v1/invoices/{id}/cancel

curl --request POST \
  --url https://api.trueproxies.com/v1/invoices/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/cancel \
  --header 'Authorization: Bearer <token>'

Requires billing:write; reseller:purchase also permits this operation. Cancels an open purchase or top-up invoice; nothing is owed afterwards. A renewal, a charge raised by staff, a paid invoice, or an invoice with a payment attempt still pending at a provider returns 409.

Authorizations

• customerAPIKey

Parameters

Path Parameters

id

required

string format: uuid

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.

Responses

200

Cancelled

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

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

Example

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