Record a payment
Records a payment received outside Clocknext (bank transfer, cash, UPI, …) and marks an OPEN invoice PAID; any other status is a 409. Paying the first invoice starts the purchase once its start date has come. No receipt email is sent. Stripe and Paddle payments come from the gateway only.
Base URL https://payments.clocknext.com/api/v1
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
id*stringInvoice id.
application/json- body
mode*stringHow the money arrived. Any payment method except STRIPE and PADDLE, which only the gateway records.
"MANUAL""CASH""BANK_TRANSFER""WIRE_TRANSFER""CARD""CHEQUE""OTHER""UPI""IMPS""NEFT""RTGS""ACH""INTERAC""FASTER_PAYMENTS""BACS""CHAPS""SEPA""IDEAL""BANCONTACT""SOFORT""BLIK""SWISH""MOBILEPAY""VIPPS""TWINT""PIX""BOLETO""SPEI""PSE""PAYID""BPAY""PAYNOW""FPX""DUITNOW""PROMPTPAY""QRIS""GCASH""KONBINI""ALIPAY""WECHAT_PAY""MPESA""OZOW""FAWRY""MADA""KNET"reference?stringYour payment reference, such as a transfer or cheque number.
length <= 200notes?stringA note saved on the invoice as notes, in place of the one it had.
length <= 300Invoice marked paid. The invoice as it is now, and the plan it descends from.
application/json- response
statusCode*integerThe HTTP status code of the response, repeated in the body.
statusDetail*The status of the request. status is SUCCESS, and message says what happened.
result*The paid invoice and the plan it comes from.
curl -X POST 'https://payments.clocknext.com/api/v1/invoices/inv_jkl012/pay' \ -H 'Content-Type: application/json' \ -d '{ "mode": "ACH", "reference": "ACH-20261020-4471"}'{ "statusCode": 200, "statusDetail": { "status": "SUCCESS", "message": "Invoice marked paid." }, "result": { "invoice": { "id": "cmvgvkn14002u08l2ct47s2a7", "invoiceNumber": "INV-0001", "paymentNumber": "PAY-001", "purchaseNumber": "PUR-001", "customerId": "cmvgva5po000c07iir1vtn8vl", "customerName": "Northwind Traders", "customerSlug": "northwind-traders", "customerParty": { "name": "Northwind Traders", "logoUrl": null, "legalName": "Northwind Traders Inc.", "email": "billing@northwindtraders.com", "phone": "+1 415 555 0142", "website": "https://northwindtraders.com", "taxId": "US-EIN 94-1234567", "addressLine1": "500 Market Street", "city": "San Francisco", "state": "CA", "country": "United States", "pincode": "94105" }, "orgParty": { "name": "Docs testing", "logoUrl": null, "legalName": null, "email": "josewin@clocknext.com", "phone": null, "website": null, "taxId": null, "addressLine1": null, "city": null, "state": null, "country": null, "pincode": null }, "purchaseId": "cmvgvkmxz002h08l2h2i1dnsr", "stream": "ADVANCE", "usageCycleIndex": null, "noteType": "NEW_PURCHASE", "planId": "cmvgvg2yq000s08l21gkr472h", "planName": "Pro", "planType": "BUNDLE", "plan": { "name": "Pro", "type": "BUNDLE", "hasWallet": true, "hasCredit": true, "hasOutcome": true, "hasUnit": true, "hasComposite": true, "kind": "FLAT_PRICE", "billingCycle": "MONTHLY", "cost": 535.18, "currencyCode": "USD", "spendingLimit": null, "seatScope": null, "billingDate": "2026-10-20T00:00:00.000Z", "status": "ACTIVE" }, "hasWallet": true, "hasCredit": true, "hasOutcome": true, "hasUnit": true, "hasComposite": true, "billingCycle": "MONTHLY", "cycleIndex": 0, "lineItems": [ { "kind": "wallet", "billingMode": "ADVANCE", "label": "Wallet top-up", "quantity": null, "unitPrice": null, "amount": 50 }, { "kind": "credit", "billingMode": "ADVANCE", "label": "Chat Message credits", "quantity": 5000, "unitPrice": 0.001197, "amount": 5.985 }, { "kind": "outcome", "billingMode": "ADVANCE", "label": "Resolved Support Ticket outcomes", "quantity": 500, "unitPrice": 0.1260225, "amount": 63.01125 }, { "kind": "unit", "billingMode": "ADVANCE", "label": "PDF Export units", "quantity": 200, "unitPrice": 0.25, "amount": 50 }, { "kind": "composite", "billingMode": "ADVANCE", "label": "Voice AI Call composites", "quantity": 100, "unitPrice": 1.75, "amount": 175 }, { "kind": "flat", "billingMode": "ADVANCE", "label": "Discount", "quantity": null, "unitPrice": null, "amount": -134.95875 } ], "amount": 535.18, "creditedUsd": 0, "balanceAppliedUsd": 0, "amountDueUsd": 0, "planChangeCredit": null, "adjustmentCreditedUsd": 0, "paidByCustomerUsd": 535.18, "subtotal": 499, "taxAmount": 36.18, "taxes": [ { "name": "California Sales Tax", "percentage": 7.25, "behavior": "EXCLUSIVE", "taxableAmount": 499, "amount": 36.18 } ], "currencyCode": "USD", "currencyRateUsd": 1, "status": "PAID", "issuedAt": "2026-10-20T00:00:00.000Z", "paidAt": "2026-10-20T16:06:35.286Z", "invoicePdfUrl": "https://payments.clocknext.com/api/documents/aW52b2ljZTppbnZfamtsMDEy.Qm9xV0x3c1N0a3B6bU1YdWNfR1J0dDBRZ1lQdmRqR3o", "receiptPdfUrl": "https://payments.clocknext.com/api/documents/cmVjZWlwdDppbnZfamtsMDEy.UjVrUXlCbmZ0VkRwYm1oV2NfbE5xN3dZcThPZ0pkS2E", "voidedAt": null, "paymentMode": "ACH", "paidWith": [ "ACH" ], "paymentReference": "ACH-20261020-4471", "stripePaymentIntentId": null, "autoPaid": false, "notes": "Annual kickoff — upgraded from Starter", "createdAt": "2026-10-20T16:05:52.408Z", "createdByName": "Josewin D D", "paidByName": "Josewin D D", "voidedByName": null }, "plan": { "id": "cmvgvg2yq000s08l21gkr472h", "name": "Pro" } }}Types
Every object type on this page, with its fields.
PayInvoiceInput
| Field | Type | Required | Description |
|---|---|---|---|
mode | "MANUAL" | "CASH" | "BANK_TRANSFER" | "WIRE_TRANSFER" | "CARD" | "CHEQUE" | "OTHER" | "UPI" | "IMPS" | "NEFT" | "RTGS" | "ACH" | "INTERAC" | "FASTER_PAYMENTS" | "BACS" | "CHAPS" | "SEPA" | "IDEAL" | "BANCONTACT" | "SOFORT" | "BLIK" | "SWISH" | "MOBILEPAY" | "VIPPS" | "TWINT" | "PIX" | "BOLETO" | "SPEI" | "PSE" | "PAYID" | "BPAY" | "PAYNOW" | "FPX" | "DUITNOW" | "PROMPTPAY" | "QRIS" | "GCASH" | "KONBINI" | "ALIPAY" | "WECHAT_PAY" | "MPESA" | "OZOW" | "FAWRY" | "MADA" | "KNET" | yes | How the money arrived. Any payment method except STRIPE and PADDLE, which only the gateway records. |
reference | string | no | Your payment reference, such as a transfer or cheque number. |
notes | string | no | A note saved on the invoice as notes, in place of the one it had. |
InvoiceWithPdfUrl
The invoice as GET /invoices/{id} and POST /invoices/{id}/pay return it: the Invoice object plus invoicePdfUrl and receiptPdfUrl.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The invoice's id. |
invoiceNumber | string | yes | The workspace's reference for the invoice, such as INV-0042. |
paymentNumber | string | null | no | The payment reference, such as PAY-0031. null while not paid. |
purchaseNumber | string | null | no | The reference of the purchase that raised it. null without one, or when it was deleted. |
customerId | string | yes | The id of the customer the invoice is for. |
customerName | string | yes | The customer's name. |
customerSlug | string | no | The customer's slug. |
customerParty | InvoiceParty | no | The customer's billing details, read from the customer as they are now. |
orgParty | InvoiceParty | no | Your workspace's billing details, read from the workspace as they are now. |
purchaseId | string | null | no | The id of the purchase that raised it. null without one, or when it was deleted. |
stream | "ADVANCE" | "ARREAR" | no | ADVANCE: the plan's price for a cycle, billed at its start. ARREAR: the usage of a cycle, billed after it. |
usageCycleIndex | integer | null | no | On a combined invoice: the index of the cycle whose usage it also bills (cycleIndex - 1). Else null. |
noteType | "NEW_PURCHASE" | "RENEWAL" | "MANUAL" | no | Why it was issued. NEW_PURCHASE: a purchase's first invoice. RENEWAL: a later one. MANUAL: no purchase. |
note | "New Purchase" | "Subscription Renewal" | "Manual Invoice" | no | The label of noteType, as the app shows it. |
planId | string | null | no | The plan behind the invoice's purchase. null when deleted or without a purchase. |
planName | string | yes | The plan's name, saved on the invoice when it was issued. |
planType | "WALLET" | "BUNDLE" | no | BUNDLE when the plan has credit, outcome or composite lines, else WALLET. Saved at issue. |
plan | InvoicePlanSnapshot | null | no | A summary of the plan, built from the values saved on the invoice. It does not change when the plan changes. |
billingCycle | "MONTHLY" | "QUARTERLY" | "SEMI_ANNUAL" | "YEARLY" | "FREE" | yes | The plan's billing cycle, saved on the invoice when it was issued. |
cycleIndex | integer | no | The billing cycle the invoice belongs to, counted from 0. 0 is the purchase's first cycle. |
lineItems | InvoiceLineItem[] | no | The billed lines, saved when the invoice was issued. Pay-in-advance lines come first, then usage lines. |
hasWallet | boolean | no | Whether the invoice has a wallet line. Always true on a WALLET plan. |
hasCredit | boolean | no | Whether the invoice has a credit line. |
hasOutcome | boolean | no | Whether the invoice has an outcome line. |
hasUnit | boolean | no | Whether the invoice has a unit line. |
hasComposite | boolean | no | Whether the invoice has a composite line. |
amount | number | yes | Total due in USD: subtotal plus any exclusive tax. |
creditedUsd | number | no | USD taken off by credit notes, tax included. |
balanceAppliedUsd | number | no | USD of it that the customer's invoice balance paid. |
amountDueUsd | number | no | USD still owed: the total less credit notes and the balance. 0 unless OPEN. |
planChangeCredit | object | null | no | Set on a plan change's first invoice, as an information-only line. null on every other invoice. |
adjustmentCreditedUsd | number | no | USD that credit notes made while the invoice was open took off it. Refunds after payment don't count. |
paidByCustomerUsd | number | no | USD the customer paid themselves, for a PAID invoice. 0 otherwise. A later refund does not change it. |
subtotal | number | no | Sum of the line items in USD, before exclusive tax. Inclusive taxes are already inside it. |
taxAmount | number | no | All tax on the invoice in USD, inclusive and exclusive. 0 when untaxed. |
taxes | InvoiceTaxLine[] | no | The taxes applied, frozen at issue; later tax edits don't change them. Empty when untaxed. |
currencyCode | string | yes | USD for every invoice issued since Clocknext stopped converting money (every invoice and charge is USD). An older invoice keeps the customer's currency it was issued with. |
currencyRateUsd | number | no | The exchange rate when the invoice was issued: 1 USD = this many units of currencyCode. 1 for USD. |
status | "OPEN" | "PAID" | "VOID" | "AUTO_CLOSED" | yes | OPEN, PAID, VOID or AUTO_CLOSED. |
issuedAt | string | yes | When the invoice was issued. |
paidAt | string | null | no | When the invoice was paid. null while it is not paid. |
voidedAt | string | null | no | When the invoice was voided. null when it is not voided. |
paymentMode | string | null | no | One of the server PaymentMode values (e.g. "CASH", "STRIPE"). |
paidWith | string[] | no | What paid the invoice, balance first, such as [INVOICE_BALANCE, GATEWAY_CARD]. Empty until it is paid. |
paymentReference | string | null | no | The Stripe or Paddle payment id, or the reference sent to POST /invoices/{id}/pay. null when none. |
stripePaymentIntentId | string | null | no | The Stripe PaymentIntent that took the money. null unless the invoice was paid through Stripe. |
autoPaid | boolean | no | true when auto-payment charged the saved card. false for every other payment, and while it is not paid. |
notes | string | null | no | A free note on the invoice. POST /invoices/{id}/pay with notes replaces it. null when there is none. |
createdAt | string | no | When the invoice record was created. |
createdByName | string | no | The member the invoice is recorded as created by: their name, or their email when no name is set. |
paidByName | string | null | no | Who paid: the payer's email for STRIPE or PADDLE when known, else the member who recorded it. |
voidedByName | string | null | no | The member who voided it. null when not voided, or voided automatically. |
invoicePdfUrl | string | null | yes | Signed link that downloads the invoice PDF, with no sign-in. null only while Invoices is locked. |
receiptPdfUrl | string | null | yes | Signed link that downloads the payment receipt PDF, with no sign-in. null unless PAID. |
InvoiceParty
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | The display name. |
logoUrl | string | null | no | The workspace's logo URL. Always null in customerParty. |
legalName | string | null | no | The registered legal name. Always null in orgParty. |
email | string | null | no | The billing email address. |
phone | string | null | no | The phone number. |
website | string | null | no | The website URL. |
taxId | string | null | no | The tax registration number. Always null in orgParty. |
addressLine1 | string | null | no | The street address. |
city | string | null | no | The city. |
state | string | null | no | The state or region. |
country | string | null | no | The country name. |
pincode | string | null | no | The postal code. |
InvoicePlanSnapshot
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | The plan's name, saved on the invoice when it was issued. |
type | "WALLET" | "BUNDLE" | yes | BUNDLE when the plan has credit, outcome or composite lines, else WALLET. Saved at issue. |
hasWallet | boolean | no | Whether the invoice has a wallet line. Always true on a WALLET plan. |
hasCredit | boolean | no | Whether the invoice has a credit line. |
hasOutcome | boolean | no | Whether the invoice has an outcome line. |
hasUnit | boolean | no | Whether the invoice has a unit line. |
hasComposite | boolean | no | Whether the invoice has a composite line. |
kind | "FLAT_PRICE" | "PAY_AS_YOU_GO" | "PAY_PER_SEAT" | yes | PAY_AS_YOU_GO on an ARREAR invoice, FLAT_PRICE on an ADVANCE one. Older ones: PAY_PER_SEAT. |
billingCycle | "MONTHLY" | "QUARTERLY" | "SEMI_ANNUAL" | "YEARLY" | "FREE" | yes | The plan's billing cycle, saved on the invoice when it was issued. |
cost | number | yes | The invoice's total in USD, the same value as the invoice's amount. It is not the plan's price. |
currencyCode | string | yes | USD for every invoice issued since Clocknext stopped converting money (every invoice and charge is USD). An older invoice keeps the customer's currency it was issued with. |
spendingLimit | number | null | no | The spending cap per cycle in USD, on older pay-as-you-go invoices. null on new invoices. |
seatScope | "CUSTOMER" | "MEMBER" | null | no | On older per-seat invoices, whether seats were counted per customer or per member. null on new invoices. |
billingDate | string | no | When the invoice was issued, the same value as the invoice's issuedAt. |
status | "SCHEDULED" | "ACTIVE" | no | Always ACTIVE on an invoice. |
InvoiceLineItem
One line of an invoice, saved when the invoice was issued.
| Field | Type | Required | Description |
|---|---|---|---|
kind | "wallet" | "credit" | "outcome" | "unit" | "flat" | "composite" | yes | What the line bills: wallet, credit, outcome, unit, flat fee or composite. |
billingMode | "ADVANCE" | "ARREAR" | yes | ADVANCE: a pay-in-advance charge for this cycle. ARREAR: metered usage. |
label | string | yes | The line's name as shown on the invoice, such as Deep Research credits. |
quantity | number | null | yes | Granted (pay-in-advance line) or used (usage line). null on a wallet or flat line. |
unitPrice | number | null | yes | The price of one item on this line. null when the line has no price per item. |
amount | number | yes | What this line costs, in the invoice's currency. |
InvoiceWithPdfUrl.planChangeCredit
The credit shown on the invoice.
| Field | Type | Required | Description |
|---|---|---|---|
amountUsd | number | yes | The credit in USD, tax included. |
creditNoteNumber | string | yes | The credit note that made it. |
InvoiceTaxLine
One tax applied to an invoice.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | The tax's name, saved on the invoice when it was issued. |
percentage | number | yes | The tax rate in percent, saved on the invoice when it was issued. |
behavior | "INCLUSIVE" | "EXCLUSIVE" | yes | INCLUSIVE — already inside the price. EXCLUSIVE — added on top. |
taxableAmount | number | yes | USD amount the tax was worked out on. |
amount | number | yes | The tax in USD. |
PlanRef
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Id of the plan that the invoice's purchase is for. |
name | string | yes | Name of the plan that the invoice's purchase is for. |
Mint a hosted pay link GET
Returns a hosted checkout URL. Fails with 409 when the invoice is not OPEN.
List credit notes GET
Newest first, paged with `limit` (at most 50) and `cursor` → `nextCursor` — see [Paginating results](/docs/api-reference/pagination). Filter by `invoiceId` and/or `customerId`. Any other query parameter is a `400`.