Create a purchase invoice

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 discount never goes below an offer's minimum price. API keys must send an Idempotency-Key header.

post/v1/invoices

Request

  • Base URL: https://api.trueproxies.com
  • URL: https://api.trueproxies.com/v1/invoices
  • Auth: HTTP bearer

Query parameters

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

Headers

Idempotency-Keystring

Required for API-key requests; optional for dashboard sessions. 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

offer_keystring required
promo_codestring
request_idstring uuid

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

service_idstring uuid

required for renewal, topup and plan upgrade

Response

created

activated_atstring date-time

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.

activation_failed_atstring date-time

Automatic fulfillment stopped and needs operator attention. Payment remains received; this does not mean a refund completed or previously purchased service was revoked.

amount_centsinteger required
created_atstring date-time required
currencystring required
discount_bpinteger
display_namestring required
due_atstring date-time required
expiredboolean

True when a cancelled invoice closed because it was not paid by due_at. Invoices cancelled before this field existed report false.

idstring uuid required

Internal API identifier. Use reference for customer-facing display.

kind'wallet_topup' | 'purchase' | 'renewal' | 'topup' | 'upgrade' | 'custom' | 'white_label' required
list_amount_centsinteger
offer_keystring required
paid_atstring date-time
promo_codestring
promo_discount_centsinteger
referencestring required

Stable, unique customer-facing reference.

service_idstring uuid
status'open' | 'paid' | 'cancelled' required
upgrade_credit_centsinteger

Plan upgrades only. Credit for unused time on the previous plan.

upgrade_price_centsinteger

Plan upgrades only. The new plan's price; amount_cents is this minus upgrade_credit_cents.

Example response

{
  "reference": "INV-001001"
}

Changes

No recorded changes to this operation across all 1 revision of this API.