API docs by Redocly

4klyft API (1.0.0)

Download OpenAPI specification:

4klyft API Support: support@4klyft.com License: Proprietary

Logistics operations API for the 4klyft platform.

Overview

This API provides comprehensive endpoints for managing:

  • Routes & Execution: Create, manage, and execute delivery routes
  • Shipments & Loads: Track shipments from pickup to delivery
  • Fleet Management: Manage carriers, vehicles, and drivers
  • Proof of Delivery: Capture signatures, photos, and delivery confirmations
  • Settings: Configure system-wide and tenant-specific settings
  • Webhooks: Subscribe to real-time event notifications
  • Analytics: Access delivery performance metrics and reports

Authentication

All API endpoints (except /api/docs and /api/v1/iam/auth/*) require JWT Bearer token authentication. Include the token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Rate Limiting

API requests are rate-limited to ensure fair usage. Standard limits are:

  • 1000 requests per minute for read operations
  • 100 requests per minute for write operations

Error Handling

The API uses RFC 7807 Problem Details for error responses.

Billing - Credit Notes

Represents a credit note in the billing system.

List all credit notes

Retrieve a paginated list of credit notes with optional filters.

Authorizations:
Bearer
query Parameters
status
string
Enum: "draft" "issued" "applied" "cancelled"
Example: status=issued

Filter by credit note status

partnerId
string

Filter by partner ULID

invoiceId
string

Filter by invoice ULID

page
integer >= 1
Default: 1

Page number

itemsPerPage
integer [ 1 .. 100 ]
Default: 30

Items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Create a credit note

Create a new credit note for an invoice.

Authorizations:
Bearer
Request Body schema: application/json
required

Credit note data

invoiceId
required
string

Invoice ULID to credit

reason
required
string

Reason for the credit note

Array of objects

Line items to credit

issueImmediately
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "invoiceId": "string",
  • "reason": "string",
  • "lineItems": [
    ],
  • "issueImmediately": false
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "invoiceId": "string",
  • "invoiceNumber": "string",
  • "partnerId": "string",
  • "partnerName": "string",
  • "currencyCode": "string",
  • "status": "string",
  • "reason": "string",
  • "creditNoteNumber": "string",
  • "totalAmountCents": 0,
  • "totalAmountFormatted": "0.00",
  • "subtotalCents": 0,
  • "totalTaxCents": 0,
  • "grandTotalCents": 0,
  • "lineItemCount": 0,
  • "lineItems": [
    ],
  • "issuedAt": "string",
  • "appliedAt": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get a credit note

Retrieve a single credit note by its ULID.

Authorizations:
Bearer
path Parameters
id
required
string

CreditNote identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "invoiceId": "string",
  • "invoiceNumber": "string",
  • "partnerId": "string",
  • "partnerName": "string",
  • "currencyCode": "string",
  • "status": "string",
  • "reason": "string",
  • "creditNoteNumber": "string",
  • "totalAmountCents": 0,
  • "totalAmountFormatted": "0.00",
  • "subtotalCents": 0,
  • "totalTaxCents": 0,
  • "grandTotalCents": 0,
  • "lineItemCount": 0,
  • "lineItems": [
    ],
  • "issuedAt": "string",
  • "appliedAt": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Apply a credit note

Apply an issued credit note to the invoice.

Authorizations:
Bearer
path Parameters
id
required
string

CreditNote identifier

Request Body schema:
required

The new CreditNote resource

object (CreditNote.ApplyCreditNoteInput)

Represents a credit note in the billing system.

Responses

Request samples

Content type
{ }

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "invoiceId": "string",
  • "invoiceNumber": "string",
  • "partnerId": "string",
  • "partnerName": "string",
  • "currencyCode": "string",
  • "status": "string",
  • "reason": "string",
  • "creditNoteNumber": "string",
  • "totalAmountCents": 0,
  • "totalAmountFormatted": "0.00",
  • "subtotalCents": 0,
  • "totalTaxCents": 0,
  • "grandTotalCents": 0,
  • "lineItemCount": 0,
  • "lineItems": [
    ],
  • "issuedAt": "string",
  • "appliedAt": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Issue a credit note

Issue a draft credit note.

Authorizations:
Bearer
path Parameters
id
required
string

CreditNote identifier

Request Body schema:
required

The new CreditNote resource

creditNoteNumber
string or null <= 50 characters

Responses

Request samples

Content type
{
  • "creditNoteNumber": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "invoiceId": "string",
  • "invoiceNumber": "string",
  • "partnerId": "string",
  • "partnerName": "string",
  • "currencyCode": "string",
  • "status": "string",
  • "reason": "string",
  • "creditNoteNumber": "string",
  • "totalAmountCents": 0,
  • "totalAmountFormatted": "0.00",
  • "subtotalCents": 0,
  • "totalTaxCents": 0,
  • "grandTotalCents": 0,
  • "lineItemCount": 0,
  • "lineItems": [
    ],
  • "issuedAt": "string",
  • "appliedAt": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Billing - Invoices

Represents an invoice in the billing system.

Invoices track billing for partners with support for line items, issuing, payment tracking, and cancellation.

Generate an invoice

Generate a new draft invoice. Optionally include line items and issue immediately.

Authorizations:
Bearer
Request Body schema: application/json
required

Invoice generation data

partnerId
required
string

Partner ULID

currencyCode
string or null

ISO 4217 currency code. Optional — resolved from channel, tenant default, or country when omitted.

channelId
string or null

Originating sales channel ULID (consulted for per-channel default currency).

dueDate
required
string <date>

Due date for payment

notes
string or null

Additional notes

issueImmediately
boolean
Default: false

Whether to issue the invoice immediately

Array of objects or null

Line items to include

Responses

Request samples

Content type
application/json
{
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "currencyCode": "EUR",
  • "channelId": "01HQWXYZ1234567890ABCDEF",
  • "dueDate": "2024-07-15",
  • "notes": "string",
  • "issueImmediately": false,
  • "lineItems": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Corporation",
  • "currencyCode": "EUR",
  • "status": "draft",
  • "invoiceNumber": "INV-2024-001",
  • "dueDate": "2024-07-15",
  • "totalAmountCents": 15000,
  • "totalAmountFormatted": "150.00 EUR",
  • "subtotalCents": 10000,
  • "totalTaxCents": 2000,
  • "grandTotalCents": 12000,
  • "notes": "Payment terms: Net 30",
  • "lineItemCount": 5,
  • "lineItems": [
    ],
  • "issuedAt": "2024-06-15T09:00:00+00:00",
  • "paidAt": "2024-07-10T14:30:00+00:00",
  • "paymentReference": "TXN-12345",
  • "documentSubject": "billing/invoice/01HQWXYZ1234567890ABCDEF",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Get an invoice by number

Retrieve a single invoice by its invoice number.

Authorizations:
Bearer
path Parameters
invoiceNumber
required
string
Example: INV-2024-001

Invoice number

id
required
string

Invoice identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Corporation",
  • "currencyCode": "EUR",
  • "status": "draft",
  • "invoiceNumber": "INV-2024-001",
  • "dueDate": "2024-07-15",
  • "totalAmountCents": 15000,
  • "totalAmountFormatted": "150.00 EUR",
  • "subtotalCents": 10000,
  • "totalTaxCents": 2000,
  • "grandTotalCents": 12000,
  • "notes": "Payment terms: Net 30",
  • "lineItemCount": 5,
  • "lineItems": [
    ],
  • "issuedAt": "2024-06-15T09:00:00+00:00",
  • "paidAt": "2024-07-10T14:30:00+00:00",
  • "paymentReference": "TXN-12345",
  • "documentSubject": "billing/invoice/01HQWXYZ1234567890ABCDEF",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Cancel an invoice

Cancel an invoice. Only draft, issued, or overdue invoices can be cancelled.

Authorizations:
Bearer
path Parameters
id
required
string
Example: 01HQWXYZ1234567890ABCDEF

Invoice ULID

Request Body schema: application/json
required

Cancellation data

reason
required
string

Reason for cancellation

Responses

Request samples

Content type
application/json
{
  • "reason": "Duplicate invoice"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Corporation",
  • "currencyCode": "EUR",
  • "status": "draft",
  • "invoiceNumber": "INV-2024-001",
  • "dueDate": "2024-07-15",
  • "totalAmountCents": 15000,
  • "totalAmountFormatted": "150.00 EUR",
  • "subtotalCents": 10000,
  • "totalTaxCents": 2000,
  • "grandTotalCents": 12000,
  • "notes": "Payment terms: Net 30",
  • "lineItemCount": 5,
  • "lineItems": [
    ],
  • "issuedAt": "2024-06-15T09:00:00+00:00",
  • "paidAt": "2024-07-10T14:30:00+00:00",
  • "paymentReference": "TXN-12345",
  • "documentSubject": "billing/invoice/01HQWXYZ1234567890ABCDEF",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Generate the invoice PDF document

Render the invoice as a PDF via the Document module. Returns the generated Document resource; download it via GET /api/document/documents/{id}/download.

Authorizations:
Bearer
path Parameters
id
required
string
Example: 01HQWXYZ1234567890ABCDEF

Invoice ULID

Request Body schema: application/json
optional

Document generation options

includeDetails
boolean
Default: true

Whether to include line-item details in the document.

Responses

Request samples

Content type
application/json
{
  • "includeDetails": true
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "type": "string",
  • "subject": "string",
  • "status": "string",
  • "generatedBy": "string",
  • "createdAt": "string",
  • "number": "string",
  • "primaryFormat": "string",
  • "source": "string",
  • "sourceRef": "string",
  • "templateId": "string",
  • "templateVersion": 0,
  • "expiresAt": "string",
  • "finalizedAt": "string",
  • "voidedAt": "string",
  • "voidReason": "string",
  • "supersedes": "string",
  • "supersededBy": "string",
  • "storagePath": "string",
  • "fileSize": 0,
  • "failureReason": "string",
  • "updatedAt": "string",
  • "metadata": {
    },
  • "renditions": [
    ],
  • "attachments": [
    ],
  • "references": [
    ]
}

Issue an invoice

Issue a draft invoice. Assigns an invoice number and makes it payable.

Authorizations:
Bearer
path Parameters
id
required
string
Example: 01HQWXYZ1234567890ABCDEF

Invoice ULID

Request Body schema: application/json
optional

Issue invoice data

invoiceNumber
string or null

Custom invoice number. If not provided, one will be auto-generated.

Responses

Request samples

Content type
application/json
{
  • "invoiceNumber": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Corporation",
  • "currencyCode": "EUR",
  • "status": "draft",
  • "invoiceNumber": "INV-2024-001",
  • "dueDate": "2024-07-15",
  • "totalAmountCents": 15000,
  • "totalAmountFormatted": "150.00 EUR",
  • "subtotalCents": 10000,
  • "totalTaxCents": 2000,
  • "grandTotalCents": 12000,
  • "notes": "Payment terms: Net 30",
  • "lineItemCount": 5,
  • "lineItems": [
    ],
  • "issuedAt": "2024-06-15T09:00:00+00:00",
  • "paidAt": "2024-07-10T14:30:00+00:00",
  • "paymentReference": "TXN-12345",
  • "documentSubject": "billing/invoice/01HQWXYZ1234567890ABCDEF",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Mark invoice as paid

Mark an issued or overdue invoice as paid.

Authorizations:
Bearer
path Parameters
id
required
string
Example: 01HQWXYZ1234567890ABCDEF

Invoice ULID

Request Body schema: application/json
optional

Payment data

paymentReference
string or null

Payment reference or transaction ID

paidAt
string or null <date-time>

Payment date/time. Defaults to now if not provided.

Responses

Request samples

Content type
application/json
{
  • "paymentReference": "TXN-12345",
  • "paidAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Corporation",
  • "currencyCode": "EUR",
  • "status": "draft",
  • "invoiceNumber": "INV-2024-001",
  • "dueDate": "2024-07-15",
  • "totalAmountCents": 15000,
  • "totalAmountFormatted": "150.00 EUR",
  • "subtotalCents": 10000,
  • "totalTaxCents": 2000,
  • "grandTotalCents": 12000,
  • "notes": "Payment terms: Net 30",
  • "lineItemCount": 5,
  • "lineItems": [
    ],
  • "issuedAt": "2024-06-15T09:00:00+00:00",
  • "paidAt": "2024-07-10T14:30:00+00:00",
  • "paymentReference": "TXN-12345",
  • "documentSubject": "billing/invoice/01HQWXYZ1234567890ABCDEF",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Send an invoice to the customer

Deliver the issued invoice to the chosen recipients (To/CC/BCC) over the selected channel and format, optionally attaching documents. All fields are optional: an empty To list falls back to the partner billing contact, channel defaults to email, format to pdf, and attachments to the invoice's own document. The invoice must already be issued. Returns the invoice resource.

Authorizations:
Bearer
path Parameters
id
required
string
Example: 01HQWXYZ1234567890ABCDEF

Invoice ULID

Request Body schema:
required

The new Invoice resource

to
Array of strings

Primary (To) recipients. Empty = fall back to the partner billing contact.

cc
Array of strings
bcc
Array of strings
channel
string
Default: "email"
Enum: "email" "portal"
format
string
Default: "pdf"
Enum: "pdf" "html"
attachmentDocumentIds
Array of strings

Document IDs to attach. Empty = attach the invoice's own generated document.

Responses

Request samples

Content type
{
  • "to": [
    ],
  • "cc": [
    ],
  • "bcc": [
    ],
  • "channel": "email",
  • "format": "pdf",
  • "attachmentDocumentIds": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Corporation",
  • "currencyCode": "EUR",
  • "status": "draft",
  • "invoiceNumber": "INV-2024-001",
  • "dueDate": "2024-07-15",
  • "totalAmountCents": 15000,
  • "totalAmountFormatted": "150.00 EUR",
  • "subtotalCents": 10000,
  • "totalTaxCents": 2000,
  • "grandTotalCents": 12000,
  • "notes": "Payment terms: Net 30",
  • "lineItemCount": 5,
  • "lineItems": [
    ],
  • "issuedAt": "2024-06-15T09:00:00+00:00",
  • "paidAt": "2024-07-10T14:30:00+00:00",
  • "paymentReference": "TXN-12345",
  • "documentSubject": "billing/invoice/01HQWXYZ1234567890ABCDEF",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Billing - Recurring Invoices

Represents a recurring invoice profile — a billing cadence that automatically generates invoices for a partner.

List recurring invoice profiles

Retrieve a paginated list of recurring invoice profiles with optional filters.

Authorizations:
Bearer
query Parameters
status
string
Enum: "active" "paused" "ended"
Example: status=active

Filter by profile status

partnerId
string
Example: partnerId=01HQWXYZ1234567890ABCDEF

Filter by partner ULID

page
integer >= 1
Default: 1
Example: page=1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 20
Example: itemsPerPage=20

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Schedule a recurring invoice profile

Create a recurring invoice profile that auto-generates invoices on the given billing cadence.

Authorizations:
Bearer
Request Body schema: application/json
required

Recurring invoice profile data

partnerId
required
string

Partner ULID

currencyCode
required
string

ISO 4217 currency code (required)

cadence
required
string
Enum: "weekly" "monthly" "quarterly" "yearly"

Billing cadence

anchorDay
required
integer

Anchor day: ISO weekday (1..7) for weekly, day-of-month (1..31, clamped) otherwise

startAt
required
string <date>

First billing period start (UTC date)

endAt
string or null <date>

Optional end of the active window (exclusive)

dueDays
integer

Payment terms in days after each period start

autoIssue
boolean
Default: true

Whether generated invoices are issued immediately

notes
string or null

Notes copied onto every generated invoice

required
Array of objects

Line template copied verbatim onto every generated invoice

Responses

Request samples

Content type
application/json
{
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "currencyCode": "EUR",
  • "cadence": "monthly",
  • "anchorDay": 1,
  • "startAt": "2026-01-01",
  • "endAt": "2019-08-24",
  • "dueDays": 14,
  • "autoIssue": true,
  • "notes": "string",
  • "lines": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Corporation",
  • "currencyCode": "EUR",
  • "cadence": "weekly",
  • "anchorDay": 1,
  • "status": "active",
  • "dueDays": 14,
  • "startAt": "2026-01-01T00:00:00+00:00",
  • "endAt": "2026-12-31T00:00:00+00:00",
  • "nextInvoiceAt": "2026-02-01T00:00:00+00:00",
  • "lastInvoicedAt": "2026-01-01T00:00:00+00:00",
  • "createdAt": "2026-01-01T10:30:00+00:00",
  • "updatedAt": "2026-01-01T14:45:00+00:00"
}

Get a recurring invoice profile

Retrieve a single recurring invoice profile by its ULID.

Authorizations:
Bearer
path Parameters
id
required
string

RecurringInvoiceProfile identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Corporation",
  • "currencyCode": "EUR",
  • "cadence": "weekly",
  • "anchorDay": 1,
  • "status": "active",
  • "dueDays": 14,
  • "startAt": "2026-01-01T00:00:00+00:00",
  • "endAt": "2026-12-31T00:00:00+00:00",
  • "nextInvoiceAt": "2026-02-01T00:00:00+00:00",
  • "lastInvoicedAt": "2026-01-01T00:00:00+00:00",
  • "createdAt": "2026-01-01T10:30:00+00:00",
  • "updatedAt": "2026-01-01T14:45:00+00:00"
}

End a recurring invoice profile

End a profile permanently. Terminal — it never generates invoices again.

Authorizations:
Bearer
path Parameters
id
required
string

RecurringInvoiceProfile identifier

Request Body schema:
required

The new RecurringInvoiceProfile resource

id
string

Unique identifier (ULID)

partnerId
string

Partner ULID

partnerName
string or null

Partner name

currencyCode
string

ISO 4217 currency code

cadence
string
Enum: "weekly" "monthly" "quarterly" "yearly"
anchorDay
integer
Default: 1

Anchor day (weekday 1..7 for weekly, day-of-month 1..31 otherwise)

status
string
Enum: "active" "paused" "ended"
dueDays
integer
Default: 0

Payment terms in days after each period start

startAt
string

First billing period start (ISO 8601)

endAt
string or null

End of the active window (ISO 8601), if any

nextInvoiceAt
string

Next billing date (ISO 8601)

lastInvoicedAt
string or null

Last invoiced period start (ISO 8601), if any

createdAt
string

Timestamp when the profile was created (ISO 8601)

updatedAt
string

Timestamp when the profile was last updated (ISO 8601)

Responses

Request samples

Content type
{
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Corporation",
  • "currencyCode": "EUR",
  • "cadence": "weekly",
  • "anchorDay": 1,
  • "status": "active",
  • "dueDays": 14,
  • "startAt": "2026-01-01T00:00:00+00:00",
  • "endAt": "2026-12-31T00:00:00+00:00",
  • "nextInvoiceAt": "2026-02-01T00:00:00+00:00",
  • "lastInvoicedAt": "2026-01-01T00:00:00+00:00",
  • "createdAt": "2026-01-01T10:30:00+00:00",
  • "updatedAt": "2026-01-01T14:45:00+00:00"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Corporation",
  • "currencyCode": "EUR",
  • "cadence": "weekly",
  • "anchorDay": 1,
  • "status": "active",
  • "dueDays": 14,
  • "startAt": "2026-01-01T00:00:00+00:00",
  • "endAt": "2026-12-31T00:00:00+00:00",
  • "nextInvoiceAt": "2026-02-01T00:00:00+00:00",
  • "lastInvoicedAt": "2026-01-01T00:00:00+00:00",
  • "createdAt": "2026-01-01T10:30:00+00:00",
  • "updatedAt": "2026-01-01T14:45:00+00:00"
}

Pause a recurring invoice profile

Pause an active profile. It stops generating invoices until resumed.

Authorizations:
Bearer
path Parameters
id
required
string

RecurringInvoiceProfile identifier

Request Body schema:
required

The new RecurringInvoiceProfile resource

id
string

Unique identifier (ULID)

partnerId
string

Partner ULID

partnerName
string or null

Partner name

currencyCode
string

ISO 4217 currency code

cadence
string
Enum: "weekly" "monthly" "quarterly" "yearly"
anchorDay
integer
Default: 1

Anchor day (weekday 1..7 for weekly, day-of-month 1..31 otherwise)

status
string
Enum: "active" "paused" "ended"
dueDays
integer
Default: 0

Payment terms in days after each period start

startAt
string

First billing period start (ISO 8601)

endAt
string or null

End of the active window (ISO 8601), if any

nextInvoiceAt
string

Next billing date (ISO 8601)

lastInvoicedAt
string or null

Last invoiced period start (ISO 8601), if any

createdAt
string

Timestamp when the profile was created (ISO 8601)

updatedAt
string

Timestamp when the profile was last updated (ISO 8601)

Responses

Request samples

Content type
{
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Corporation",
  • "currencyCode": "EUR",
  • "cadence": "weekly",
  • "anchorDay": 1,
  • "status": "active",
  • "dueDays": 14,
  • "startAt": "2026-01-01T00:00:00+00:00",
  • "endAt": "2026-12-31T00:00:00+00:00",
  • "nextInvoiceAt": "2026-02-01T00:00:00+00:00",
  • "lastInvoicedAt": "2026-01-01T00:00:00+00:00",
  • "createdAt": "2026-01-01T10:30:00+00:00",
  • "updatedAt": "2026-01-01T14:45:00+00:00"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Corporation",
  • "currencyCode": "EUR",
  • "cadence": "weekly",
  • "anchorDay": 1,
  • "status": "active",
  • "dueDays": 14,
  • "startAt": "2026-01-01T00:00:00+00:00",
  • "endAt": "2026-12-31T00:00:00+00:00",
  • "nextInvoiceAt": "2026-02-01T00:00:00+00:00",
  • "lastInvoicedAt": "2026-01-01T00:00:00+00:00",
  • "createdAt": "2026-01-01T10:30:00+00:00",
  • "updatedAt": "2026-01-01T14:45:00+00:00"
}

Resume a recurring invoice profile

Resume a paused profile. The next billing date is advanced past any periods that elapsed while paused.

Authorizations:
Bearer
path Parameters
id
required
string

RecurringInvoiceProfile identifier

Request Body schema:
required

The new RecurringInvoiceProfile resource

id
string

Unique identifier (ULID)

partnerId
string

Partner ULID

partnerName
string or null

Partner name

currencyCode
string

ISO 4217 currency code

cadence
string
Enum: "weekly" "monthly" "quarterly" "yearly"
anchorDay
integer
Default: 1

Anchor day (weekday 1..7 for weekly, day-of-month 1..31 otherwise)

status
string
Enum: "active" "paused" "ended"
dueDays
integer
Default: 0

Payment terms in days after each period start

startAt
string

First billing period start (ISO 8601)

endAt
string or null

End of the active window (ISO 8601), if any

nextInvoiceAt
string

Next billing date (ISO 8601)

lastInvoicedAt
string or null

Last invoiced period start (ISO 8601), if any

createdAt
string

Timestamp when the profile was created (ISO 8601)

updatedAt
string

Timestamp when the profile was last updated (ISO 8601)

Responses

Request samples

Content type
{
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Corporation",
  • "currencyCode": "EUR",
  • "cadence": "weekly",
  • "anchorDay": 1,
  • "status": "active",
  • "dueDays": 14,
  • "startAt": "2026-01-01T00:00:00+00:00",
  • "endAt": "2026-12-31T00:00:00+00:00",
  • "nextInvoiceAt": "2026-02-01T00:00:00+00:00",
  • "lastInvoicedAt": "2026-01-01T00:00:00+00:00",
  • "createdAt": "2026-01-01T10:30:00+00:00",
  • "updatedAt": "2026-01-01T14:45:00+00:00"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Corporation",
  • "currencyCode": "EUR",
  • "cadence": "weekly",
  • "anchorDay": 1,
  • "status": "active",
  • "dueDays": 14,
  • "startAt": "2026-01-01T00:00:00+00:00",
  • "endAt": "2026-12-31T00:00:00+00:00",
  • "nextInvoiceAt": "2026-02-01T00:00:00+00:00",
  • "lastInvoicedAt": "2026-01-01T00:00:00+00:00",
  • "createdAt": "2026-01-01T10:30:00+00:00",
  • "updatedAt": "2026-01-01T14:45:00+00:00"
}

BillingInvoice

Resource 'BillingInvoice' operations.

Retrieves the collection of BillingInvoice resources.

Retrieves the collection of BillingInvoice resources.

Authorizations:
Bearer
query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Retrieves a BillingInvoice resource.

Retrieves a BillingInvoice resource.

Authorizations:
Bearer
path Parameters
id
required
string

BillingInvoice identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "number": "string",
  • "tenantId": "string",
  • "subscriptionId": "string",
  • "periodStartedAt": "string",
  • "periodEndsAt": "string",
  • "lineItems": [
    ],
  • "subtotalCents": 0,
  • "taxCents": 0,
  • "totalCents": 0,
  • "currency": "string",
  • "status": "string",
  • "issuedAt": "string",
  • "dueAt": "string",
  • "paidAt": "string",
  • "paymentMethod": "string",
  • "externalReference": "string",
  • "createdAt": "string"
}

BillingSubscription

Resource 'BillingSubscription' operations.

Retrieves a BillingSubscription resource.

Retrieves a BillingSubscription resource.

Authorizations:
Bearer

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "planId": "string",
  • "status": "string",
  • "trialEndsAt": "string",
  • "currentPeriodStartedAt": "string",
  • "currentPeriodEndsAt": "string",
  • "cancellationRequestedAt": "string",
  • "cancellationEffectiveAt": "string",
  • "paymentMethodRef": "string",
  • "createdAt": "string"
}

Creates a BillingSubscription resource.

Creates a BillingSubscription resource.

Authorizations:
Bearer
Request Body schema:
required

The new BillingSubscription resource

reason
string or null

Optional cancellation reason for audit purposes.

Responses

Request samples

Content type
{
  • "reason": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "planId": "string",
  • "status": "string",
  • "trialEndsAt": "string",
  • "currentPeriodStartedAt": "string",
  • "currentPeriodEndsAt": "string",
  • "cancellationRequestedAt": "string",
  • "cancellationEffectiveAt": "string",
  • "paymentMethodRef": "string",
  • "createdAt": "string"
}

Creates a BillingSubscription resource.

Creates a BillingSubscription resource.

Authorizations:
Bearer
Request Body schema:
required

The new BillingSubscription resource

planId
required
string

Responses

Request samples

Content type
{
  • "planId": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "planId": "string",
  • "status": "string",
  • "trialEndsAt": "string",
  • "currentPeriodStartedAt": "string",
  • "currentPeriodEndsAt": "string",
  • "cancellationRequestedAt": "string",
  • "cancellationEffectiveAt": "string",
  • "paymentMethodRef": "string",
  • "createdAt": "string"
}

BillingUsageReport

Resource 'BillingUsageReport' operations.

Retrieves a BillingUsageReport resource.

Retrieves a BillingUsageReport resource.

Authorizations:
Bearer

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "tenantId": "string",
  • "from": "string",
  • "to": "string",
  • "totals": [
    ]
}