Finalize invoice by ID

Finalizes a draft invoice by ID. The invoice must be valid, not soft-deleted, and belong to the merchant account resolved from the secret key. Request body — autoAdvance: Optional. If omitted, treated as true. This controls the immediate finalize path only (when autoFinalizeAt is omitted): when true, GETTRX may open the invoice and schedule automatic collection according to the invoice collectionMethod. When false, the invoice is opened and numbered without scheduling automatic collection or recurring-engine follow-up (currentRecurringEngineProcess cleared). Request body — autoFinalizeAt: Optional. Unix timestamp (seconds) for when the recurring engine should run the finalize step. Cannot be used with autoAdvance = false. When autoFinalizeAt is provided, the platform does not apply the immediate autoAdvance = true finalize rules below (no open transition, no invoice number allocation, no nextPaymentAttempt / autoSendInvoiceAt / PAY_INVOICE / SEND_INVOICE from this call). It updates only these fields on the invoice (the invoice remains draft until the engine finalizes it): - autoAdvance = true - autoFinalizeAt = the Unix timestamp sent in the request - currentRecurringEngineProcess = FINALIZE_INVOICE - lastUpdated = current server time (NOW()) When autoFinalizeAt is omitted — autoAdvance = true (default): - collectionMethod = charge_automatically: autoAdvance = true, status = open, finalizedOn = now, autoFinalizeAt = null, invoiceNumber generated, nextPaymentAttempt set per platform automatic-collection policy, autoSendInvoiceAt = null, currentRecurringEngineProcess = PAY_INVOICE. - collectionMethod = send_invoice: autoAdvance = true, status = open, finalizedOn = now, autoFinalizeAt = null, nextPaymentAttempt = null, autoSendInvoiceAt set per platform invoice-send policy, invoiceNumber generated, currentRecurringEngineProcess = SEND_INVOICE. autoAdvance = false (only when autoFinalizeAt is omitted): autoAdvance = false, status = open, finalizedOn = now, autoFinalizeAt = null, nextPaymentAttempt = null, autoSendInvoiceAt = null, invoiceNumber generated, currentRecurringEngineProcess = null. Response data matches the invoice-by-id shape. Line-item price, accountDiscounts, and accountFees follow the same expand pattern as GET invoice when expand is supported.

Path Params
string
required
length between 10 and 128

Invoice ID (e.g. inv_a11YYufWQzNY63zpQ6QSNRQhkUpVph4WRmzW0zWJO2znZKdVujZ0N0S22u). Must be valid, not soft deleted, and belong to the merchant account.

Body Params

Optional body for finalize; omit or send {} to use default autoAdvance behavior for the immediate path when autoFinalizeAt is not sent. When autoFinalizeAt is set, do not set autoAdvance to false (mutually exclusive).

boolean

When true (default if omitted), perform automatic collection per collectionMethod on the immediate finalize path (when autoFinalizeAt is omitted). When false, open and number the invoice without automatic payment scheduling or invoice send scheduling. Must not be false when autoFinalizeAt is provided.

int64

Unix timestamp (seconds) when the invoice is expected to be finalized by the recurring engine. Cannot be used with autoAdvance = false. When this field is present, the platform updates only the following fields (invoice stays draft; the immediate autoAdvance finalize behaviour is not applied): - Set autoAdvance = true - Set autoFinalizeAt = the Unix timestamp passed in this field - Set currentRecurringEngineProcess = FINALIZE_INVOICE - Set lastUpdated = current server time (NOW())

Headers
string
required

Secret key associated to the partner's account (e.g. sk_age14sf40sSwfchDsaetaqsgh3001e4gf2ed).

string

(Optional) AccountId of the merchant that will own the site (e.g. acm_********). Conditionally required when secretKey belongs to an "entity" account.

string

Unique Key String refNumber

string

Unique key generated by the partner (e.g. 490ff93e-8a73-4aa4-a02b-9d9251f91243)

Responses

Language
Credentials
Header
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json