ClocknextClocknextHelp
DocumentationAPI ReferenceMCP Tools
Dashboard

Get started

OverviewQuickstart

Good to know

Response formatHandling errorsPaginating resultsSending data reliablyYour own customer idsWebhooks

API reference

Signals

Record credit POSTRecord outcome POSTComplete outcome POSTRecord wallet POSTRecord unit POSTComplete composite POSTList raw signals GETRetry signals POSTList Customer Usage Log GETLook Up Usage Logs by ID GET

Deprecated

Record credit POSTRecord outcome POSTComplete outcome POSTRecord wallet POSTRecord unit POSTComplete composite POSTList raw signals GETRetry signals POST

Customers

List customers GETCreate a customer POSTGet a customer GETUpdate a customer PATCHDelete a customer DELETEGet a customer's balances GETGet a customer's wallet ledger GETSet a customer's low-balance alert for wallet PUTGet a customer's current plan GETChange a recurring grant PUTUpdate a customer's card POSTGet a customer's invoice balance GETAdjust a customer's invoice balance POST

Deprecated

List Customer Usage Log GETLook Up Usage Logs by ID GET

Manage

Manage a customer's credit balance POSTManage a customer's outcome balance POSTManage a customer's unit balance POSTManage a customer's composite balance POSTManage a customer's wallet balance POST

Members

List a customer's members GETAdd a member POSTUpdate a member PATCHRemove a member DELETE

Plans and Entitlements

PlansPackagesCreditsOutcomesUnitsComposites

Taxes

List taxes GETCreate a tax POSTGet a tax GETUpdate a tax PATCH

Purchases

List purchases GETCreate a purchase POSTGet a purchase GETUpdate a purchase's auto-payment setting PATCHCancel a purchase POST

Checkout

Create a checkout POST

Subscriptions

List subscriptions GETGet a subscription GETCancel a subscription POSTAdd packages to a subscription POSTRemove a package from a subscription POST

Plan changes

List plan changes GETPreview a plan change POSTChange a customer's plan POSTGet a plan change GET

Invoices

List invoices GETGet an invoice GETMint a hosted pay link GETRecord a payment POST

Credit notes

List credit notes GETCreate a credit note POSTGet a credit note GETVoid a credit note POST

Refunds

List refunds GETRefund to the card POSTGet a refund GET

Payments

List payments GETGet a payment GET

Webhooks

Customer Portal

Mint a customer-portal access token POST

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

POST
/invoices/{id}/pay

Authorization

apiKey
headerAuthorizationBearer <cnk_…>

Organisation-scoped key from Settings → API Keys.

Path Parameters

id*string

Invoice id.

Request Body

application/json
  1. body
  1. body
  2. …
mode*string

How the money arrived. Any payment method except STRIPE and PADDLE, which only the gateway records.

Value in"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?string

Your payment reference, such as a transfer or cheque number.

Lengthlength <= 200
notes?string

A note saved on the invoice as notes, in place of the one it had.

Lengthlength <= 300

Response Body

Invoice marked paid. The invoice as it is now, and the plan it descends from.

application/json
  1. response
  1. response
  2. …
statusCode*integer

The 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"}'
Example Response
{  "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

FieldTypeRequiredDescription
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"yesHow the money arrived. Any payment method except STRIPE and PADDLE, which only the gateway records.
referencestringnoYour payment reference, such as a transfer or cheque number.
notesstringnoA 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.

FieldTypeRequiredDescription
idstringyesThe invoice's id.
invoiceNumberstringyesThe workspace's reference for the invoice, such as INV-0042.
paymentNumberstring | nullnoThe payment reference, such as PAY-0031. null while not paid.
purchaseNumberstring | nullnoThe reference of the purchase that raised it. null without one, or when it was deleted.
customerIdstringyesThe id of the customer the invoice is for.
customerNamestringyesThe customer's name.
customerSlugstringnoThe customer's slug.
customerPartyInvoicePartynoThe customer's billing details, read from the customer as they are now.
orgPartyInvoicePartynoYour workspace's billing details, read from the workspace as they are now.
purchaseIdstring | nullnoThe id of the purchase that raised it. null without one, or when it was deleted.
stream"ADVANCE" | "ARREAR"noADVANCE: the plan's price for a cycle, billed at its start. ARREAR: the usage of a cycle, billed after it.
usageCycleIndexinteger | nullnoOn a combined invoice: the index of the cycle whose usage it also bills (cycleIndex - 1). Else null.
noteType"NEW_PURCHASE" | "RENEWAL" | "MANUAL"noWhy it was issued. NEW_PURCHASE: a purchase's first invoice. RENEWAL: a later one. MANUAL: no purchase.
note"New Purchase" | "Subscription Renewal" | "Manual Invoice"noThe label of noteType, as the app shows it.
planIdstring | nullnoThe plan behind the invoice's purchase. null when deleted or without a purchase.
planNamestringyesThe plan's name, saved on the invoice when it was issued.
planType"WALLET" | "BUNDLE"noBUNDLE when the plan has credit, outcome or composite lines, else WALLET. Saved at issue.
planInvoicePlanSnapshot | nullnoA 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"yesThe plan's billing cycle, saved on the invoice when it was issued.
cycleIndexintegernoThe billing cycle the invoice belongs to, counted from 0. 0 is the purchase's first cycle.
lineItemsInvoiceLineItem[]noThe billed lines, saved when the invoice was issued. Pay-in-advance lines come first, then usage lines.
hasWalletbooleannoWhether the invoice has a wallet line. Always true on a WALLET plan.
hasCreditbooleannoWhether the invoice has a credit line.
hasOutcomebooleannoWhether the invoice has an outcome line.
hasUnitbooleannoWhether the invoice has a unit line.
hasCompositebooleannoWhether the invoice has a composite line.
amountnumberyesTotal due in USD: subtotal plus any exclusive tax.
creditedUsdnumbernoUSD taken off by credit notes, tax included.
balanceAppliedUsdnumbernoUSD of it that the customer's invoice balance paid.
amountDueUsdnumbernoUSD still owed: the total less credit notes and the balance. 0 unless OPEN.
planChangeCreditobject | nullnoSet on a plan change's first invoice, as an information-only line. null on every other invoice.
adjustmentCreditedUsdnumbernoUSD that credit notes made while the invoice was open took off it. Refunds after payment don't count.
paidByCustomerUsdnumbernoUSD the customer paid themselves, for a PAID invoice. 0 otherwise. A later refund does not change it.
subtotalnumbernoSum of the line items in USD, before exclusive tax. Inclusive taxes are already inside it.
taxAmountnumbernoAll tax on the invoice in USD, inclusive and exclusive. 0 when untaxed.
taxesInvoiceTaxLine[]noThe taxes applied, frozen at issue; later tax edits don't change them. Empty when untaxed.
currencyCodestringyesUSD 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.
currencyRateUsdnumbernoThe exchange rate when the invoice was issued: 1 USD = this many units of currencyCode. 1 for USD.
status"OPEN" | "PAID" | "VOID" | "AUTO_CLOSED"yesOPEN, PAID, VOID or AUTO_CLOSED.
issuedAtstringyesWhen the invoice was issued.
paidAtstring | nullnoWhen the invoice was paid. null while it is not paid.
voidedAtstring | nullnoWhen the invoice was voided. null when it is not voided.
paymentModestring | nullnoOne of the server PaymentMode values (e.g. "CASH", "STRIPE").
paidWithstring[]noWhat paid the invoice, balance first, such as [INVOICE_BALANCE, GATEWAY_CARD]. Empty until it is paid.
paymentReferencestring | nullnoThe Stripe or Paddle payment id, or the reference sent to POST /invoices/{id}/pay. null when none.
stripePaymentIntentIdstring | nullnoThe Stripe PaymentIntent that took the money. null unless the invoice was paid through Stripe.
autoPaidbooleannotrue when auto-payment charged the saved card. false for every other payment, and while it is not paid.
notesstring | nullnoA free note on the invoice. POST /invoices/{id}/pay with notes replaces it. null when there is none.
createdAtstringnoWhen the invoice record was created.
createdByNamestringnoThe member the invoice is recorded as created by: their name, or their email when no name is set.
paidByNamestring | nullnoWho paid: the payer's email for STRIPE or PADDLE when known, else the member who recorded it.
voidedByNamestring | nullnoThe member who voided it. null when not voided, or voided automatically.
invoicePdfUrlstring | nullyesSigned link that downloads the invoice PDF, with no sign-in. null only while Invoices is locked.
receiptPdfUrlstring | nullyesSigned link that downloads the payment receipt PDF, with no sign-in. null unless PAID.

InvoiceParty

FieldTypeRequiredDescription
namestringyesThe display name.
logoUrlstring | nullnoThe workspace's logo URL. Always null in customerParty.
legalNamestring | nullnoThe registered legal name. Always null in orgParty.
emailstring | nullnoThe billing email address.
phonestring | nullnoThe phone number.
websitestring | nullnoThe website URL.
taxIdstring | nullnoThe tax registration number. Always null in orgParty.
addressLine1string | nullnoThe street address.
citystring | nullnoThe city.
statestring | nullnoThe state or region.
countrystring | nullnoThe country name.
pincodestring | nullnoThe postal code.

InvoicePlanSnapshot

FieldTypeRequiredDescription
namestringyesThe plan's name, saved on the invoice when it was issued.
type"WALLET" | "BUNDLE"yesBUNDLE when the plan has credit, outcome or composite lines, else WALLET. Saved at issue.
hasWalletbooleannoWhether the invoice has a wallet line. Always true on a WALLET plan.
hasCreditbooleannoWhether the invoice has a credit line.
hasOutcomebooleannoWhether the invoice has an outcome line.
hasUnitbooleannoWhether the invoice has a unit line.
hasCompositebooleannoWhether the invoice has a composite line.
kind"FLAT_PRICE" | "PAY_AS_YOU_GO" | "PAY_PER_SEAT"yesPAY_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"yesThe plan's billing cycle, saved on the invoice when it was issued.
costnumberyesThe invoice's total in USD, the same value as the invoice's amount. It is not the plan's price.
currencyCodestringyesUSD 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.
spendingLimitnumber | nullnoThe spending cap per cycle in USD, on older pay-as-you-go invoices. null on new invoices.
seatScope"CUSTOMER" | "MEMBER" | nullnoOn older per-seat invoices, whether seats were counted per customer or per member. null on new invoices.
billingDatestringnoWhen the invoice was issued, the same value as the invoice's issuedAt.
status"SCHEDULED" | "ACTIVE"noAlways ACTIVE on an invoice.

InvoiceLineItem

One line of an invoice, saved when the invoice was issued.

FieldTypeRequiredDescription
kind"wallet" | "credit" | "outcome" | "unit" | "flat" | "composite"yesWhat the line bills: wallet, credit, outcome, unit, flat fee or composite.
billingMode"ADVANCE" | "ARREAR"yesADVANCE: a pay-in-advance charge for this cycle. ARREAR: metered usage.
labelstringyesThe line's name as shown on the invoice, such as Deep Research credits.
quantitynumber | nullyesGranted (pay-in-advance line) or used (usage line). null on a wallet or flat line.
unitPricenumber | nullyesThe price of one item on this line. null when the line has no price per item.
amountnumberyesWhat this line costs, in the invoice's currency.

InvoiceWithPdfUrl.planChangeCredit

The credit shown on the invoice.

FieldTypeRequiredDescription
amountUsdnumberyesThe credit in USD, tax included.
creditNoteNumberstringyesThe credit note that made it.

InvoiceTaxLine

One tax applied to an invoice.

FieldTypeRequiredDescription
namestringyesThe tax's name, saved on the invoice when it was issued.
percentagenumberyesThe tax rate in percent, saved on the invoice when it was issued.
behavior"INCLUSIVE" | "EXCLUSIVE"yesINCLUSIVE — already inside the price. EXCLUSIVE — added on top.
taxableAmountnumberyesUSD amount the tax was worked out on.
amountnumberyesThe tax in USD.

PlanRef

FieldTypeRequiredDescription
idstringyesId of the plan that the invoice's purchase is for.
namestringyesName 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`.