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.

List all invoices

Retrieve a paginated list of invoices with optional filters.

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

Filter by invoice status

partnerId
string
Example: partnerId=01HQWXYZ1234567890ABCDEF

Filter by partner ULID

dueDateFrom
string <date>
Example: dueDateFrom=2024-01-01

Filter invoices due from this date (inclusive)

dueDateTo
string <date>
Example: dueDateTo=2024-12-31

Filter invoices due up to this date (inclusive)

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

Page number for pagination

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

Number of items per page

Responses

Response samples

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

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

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"
}

Get an invoice

Retrieve a single invoice by its ULID. Includes line items.

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

Invoice ULID

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"
}

Settlements

Resource 'Settlements' operations.

List auto-settlement rules

Retrieve a paginated list of auto-settlement rules with optional filters.

Authorizations:
Bearer
query Parameters
partnerId
string

Filter by partner ID

page
integer >= 1
Default: 1

Page number

itemsPerPage
integer [ 1 .. 100 ]
Default: 25

Items per page

Responses

Response samples

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

Create auto-settlement rule

Create a rule for automatic settlement creation when charges arrive for a partner+scope combination.

Authorizations:
Bearer
Request Body schema:
required

The new AutoSettlementRule resource

partnerId
required
string <ulid>
scope
required
string <= 100 characters
basis
required
string
Enum: "period" "ad_hoc" "per_job" "on_demand"
currency
required
string = 3 characters
periodType
string or null
Enum: "weekly" "bi_weekly" "monthly"

Responses

Request samples

Content type
{
  • "partnerId": "string",
  • "scope": "string",
  • "basis": "period",
  • "currency": "str",
  • "periodType": "weekly"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "partnerId": "string",
  • "scope": "string",
  • "basis": "string",
  • "currency": "string",
  • "periodType": "string",
  • "createdAt": "string"
}

Delete auto-settlement rule

Delete an auto-settlement rule.

Authorizations:
Bearer
path Parameters
id
required
string

Rule ID

Responses

List settlement scopes

Retrieve all registered settlement scope definitions.

Authorizations:
Bearer
query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

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

List settlements

Retrieve a paginated list of partner settlements with optional filters.

Authorizations:
Bearer
query Parameters
partnerId
string

Filter by partner ID

status
string
Enum: "open" "locked" "under_review" "approved" "paid" "rejected"

Filter by settlement status

periodType
string
Enum: "weekly" "bi_weekly" "monthly"

Filter by period type

page
integer >= 1
Default: 1

Page number

itemsPerPage
integer [ 1 .. 100 ]
Default: 25

Items per page

Responses

Response samples

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

Create a settlement

Create a new settlement for a partner and period.

Authorizations:
Bearer
Request Body schema:
required

The new Settlement resource

partnerId
required
string <ulid>
basis
required
string
Enum: "period" "ad_hoc" "per_job" "on_demand"
currency
required
string = 3 characters
object or null
scopes
Array of strings

Responses

Request samples

Content type
{
  • "partnerId": "string",
  • "basis": "period",
  • "currency": "str",
  • "period": {
    },
  • "scopes": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "partnerId": "string",
  • "settlementNumber": "string",
  • "periodType": "string",
  • "periodStartDate": "string",
  • "periodEndDate": "string",
  • "currency": "string",
  • "status": "string",
  • "totalAmount": 0,
  • "totalCredits": 0,
  • "totalDebits": 0,
  • "lineItemCount": 0,
  • "lineItems": [
    ],
  • "createdAt": "string",
  • "approvedBy": "string",
  • "approvedAt": "string",
  • "approvalNotes": "string",
  • "rejectedBy": "string",
  • "rejectedAt": "string",
  • "rejectionReason": "string",
  • "paidAt": "string",
  • "paymentReference": "string",
  • "paymentMethod": "string"
}

Get a settlement

Retrieve settlement details including all line items.

Authorizations:
Bearer
path Parameters
id
required
string

Settlement identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "partnerId": "string",
  • "settlementNumber": "string",
  • "periodType": "string",
  • "periodStartDate": "string",
  • "periodEndDate": "string",
  • "currency": "string",
  • "status": "string",
  • "totalAmount": 0,
  • "totalCredits": 0,
  • "totalDebits": 0,
  • "lineItemCount": 0,
  • "lineItems": [
    ],
  • "createdAt": "string",
  • "approvedBy": "string",
  • "approvedAt": "string",
  • "approvalNotes": "string",
  • "rejectedBy": "string",
  • "rejectedAt": "string",
  • "rejectionReason": "string",
  • "paidAt": "string",
  • "paymentReference": "string",
  • "paymentMethod": "string"
}

Approve settlement

Approve a pending settlement for payment.

Authorizations:
Bearer
path Parameters
id
required
string

Settlement identifier

Request Body schema:
required

The new Settlement resource

notes
string or null <= 1000 characters

Responses

Request samples

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

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "partnerId": "string",
  • "settlementNumber": "string",
  • "periodType": "string",
  • "periodStartDate": "string",
  • "periodEndDate": "string",
  • "currency": "string",
  • "status": "string",
  • "totalAmount": 0,
  • "totalCredits": 0,
  • "totalDebits": 0,
  • "lineItemCount": 0,
  • "lineItems": [
    ],
  • "createdAt": "string",
  • "approvedBy": "string",
  • "approvedAt": "string",
  • "approvalNotes": "string",
  • "rejectedBy": "string",
  • "rejectedAt": "string",
  • "rejectionReason": "string",
  • "paidAt": "string",
  • "paymentReference": "string",
  • "paymentMethod": "string"
}

Generate settlement document

Generate a settlement statement document (PDF or HTML) on-demand.

Authorizations:
Bearer
path Parameters
id
required
string

Settlement identifier

Request Body schema:
required

The new Settlement resource

format
string
Default: "pdf"
Enum: "pdf" "html"

Output format for the settlement statement.

Responses

Request samples

Content type
{
  • "format": "pdf"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "partnerId": "string",
  • "settlementNumber": "string",
  • "periodType": "string",
  • "periodStartDate": "string",
  • "periodEndDate": "string",
  • "currency": "string",
  • "status": "string",
  • "totalAmount": 0,
  • "totalCredits": 0,
  • "totalDebits": 0,
  • "lineItemCount": 0,
  • "lineItems": [
    ],
  • "createdAt": "string",
  • "approvedBy": "string",
  • "approvedAt": "string",
  • "approvalNotes": "string",
  • "rejectedBy": "string",
  • "rejectedAt": "string",
  • "rejectionReason": "string",
  • "paidAt": "string",
  • "paymentReference": "string",
  • "paymentMethod": "string"
}

Add line item

Add a credit, debit, or adjustment line item to the settlement.

Authorizations:
Bearer
path Parameters
id
required
string

Settlement identifier

Request Body schema:
required

The new Settlement resource

type
required
string
Enum: "credit" "debit" "adjustment"
description
required
string <= 500 characters
amount
required
number
currency
required
string = 3 characters
subject
string or null
chargeType
string or null
itemOccurredAt
string or null
object

Responses

Request samples

Content type
{
  • "type": "credit",
  • "description": "string",
  • "amount": 0,
  • "currency": "str",
  • "subject": "string",
  • "chargeType": "string",
  • "itemOccurredAt": "string",
  • "metadata": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "partnerId": "string",
  • "settlementNumber": "string",
  • "periodType": "string",
  • "periodStartDate": "string",
  • "periodEndDate": "string",
  • "currency": "string",
  • "status": "string",
  • "totalAmount": 0,
  • "totalCredits": 0,
  • "totalDebits": 0,
  • "lineItemCount": 0,
  • "lineItems": [
    ],
  • "createdAt": "string",
  • "approvedBy": "string",
  • "approvedAt": "string",
  • "approvalNotes": "string",
  • "rejectedBy": "string",
  • "rejectedAt": "string",
  • "rejectionReason": "string",
  • "paidAt": "string",
  • "paymentReference": "string",
  • "paymentMethod": "string"
}

Mark settlement as paid

Mark an approved settlement as paid.

Authorizations:
Bearer
path Parameters
id
required
string

Settlement identifier

Request Body schema:
required

The new Settlement resource

paymentReference
required
string <= 255 characters
paymentMethod
string or null
Enum: "bank_transfer" "check" "paypal" "other"

Responses

Request samples

Content type
{
  • "paymentReference": "string",
  • "paymentMethod": "bank_transfer"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "partnerId": "string",
  • "settlementNumber": "string",
  • "periodType": "string",
  • "periodStartDate": "string",
  • "periodEndDate": "string",
  • "currency": "string",
  • "status": "string",
  • "totalAmount": 0,
  • "totalCredits": 0,
  • "totalDebits": 0,
  • "lineItemCount": 0,
  • "lineItems": [
    ],
  • "createdAt": "string",
  • "approvedBy": "string",
  • "approvedAt": "string",
  • "approvalNotes": "string",
  • "rejectedBy": "string",
  • "rejectedAt": "string",
  • "rejectionReason": "string",
  • "paidAt": "string",
  • "paymentReference": "string",
  • "paymentMethod": "string"
}

Reject settlement

Reject a pending or approved settlement.

Authorizations:
Bearer
path Parameters
id
required
string

Settlement identifier

Request Body schema:
required

The new Settlement resource

reason
required
string <= 500 characters

Responses

Request samples

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

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "partnerId": "string",
  • "settlementNumber": "string",
  • "periodType": "string",
  • "periodStartDate": "string",
  • "periodEndDate": "string",
  • "currency": "string",
  • "status": "string",
  • "totalAmount": 0,
  • "totalCredits": 0,
  • "totalDebits": 0,
  • "lineItemCount": 0,
  • "lineItems": [
    ],
  • "createdAt": "string",
  • "approvedBy": "string",
  • "approvedAt": "string",
  • "approvalNotes": "string",
  • "rejectedBy": "string",
  • "rejectedAt": "string",
  • "rejectionReason": "string",
  • "paidAt": "string",
  • "paymentReference": "string",
  • "paymentMethod": "string"
}

Payables

Partner payables statement (AP subledger) — ONE entry per currency the partner transacts in. Balances are never summed across currencies.

Partner payables statement

Per-currency AP subledger for a partner: bills, settlements, credit notes and outgoing payments as signed ledger lines with a running balance and aging buckets (Current/1-30/31-60/61-90/90+ by due date).

Authorizations:
Bearer
path Parameters
partnerId
required
string

PartnerStatement identifier

query Parameters
currency
string

Restrict to a single ISO currency code

from
string <date-time>

ISO-8601 lower bound; earlier records roll into the opening balance

to
string <date-time>

ISO-8601 upper bound for the statement position

page
integer
Default: 1

The collection page number

Responses

Response samples

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

List bills

Retrieve a paginated list of received bills with optional filters.

Authorizations:
Bearer
query Parameters
partnerId
string

Filter by partner ID

status
string
Enum: "received" "under_review" "approved" "scheduled" "paid" "disputed" "cancelled"

Filter by bill status

page
integer >= 1
Default: 1

Page number

itemsPerPage
integer [ 1 .. 100 ]
Default: 25

Items per page

Responses

Response samples

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

Receive a bill

Record a new bill received from a partner.

Authorizations:
Bearer
Request Body schema:
required

The new Bill resource

partnerId
required
string <ulid>
billNumber
required
string <= 255 characters
currency
required
string = 3 characters
totalAmountInCents
required
integer > 0
subtotalInCents
integer or null >= 0

Net (tax-exclusive) amount the vendor charged, in minor units. Optional — omit for a gross-only bill. When both this and {@see $totalTaxInCents} are supplied they must reconcile to {@see $totalAmountInCents} (net + tax = gross).

totalTaxInCents
integer or null >= 0

Input VAT the vendor charged, in minor units. Optional — captured verbatim from the vendor's bill, never recomputed via the tax engine (compliance).

subject
string or null
issuedAt
required
string
dueAt
required
string

Responses

Request samples

Content type
{
  • "partnerId": "string",
  • "billNumber": "string",
  • "currency": "str",
  • "totalAmountInCents": 0,
  • "subtotalInCents": 0,
  • "totalTaxInCents": 0,
  • "subject": "string",
  • "issuedAt": "string",
  • "dueAt": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "partnerId": "string",
  • "partnerName": "string",
  • "billNumber": "string",
  • "currency": "string",
  • "totalAmount": 0,
  • "subtotalCents": 0,
  • "totalTaxCents": 0,
  • "subject": "string",
  • "selfBilled": false,
  • "status": "string",
  • "issuedAt": "string",
  • "dueAt": "string",
  • "reviewedBy": "string",
  • "reviewedAt": "string",
  • "approvedBy": "string",
  • "approvedAt": "string",
  • "approvalNotes": "string",
  • "scheduledPaymentDate": "string",
  • "paidAt": "string",
  • "paymentReference": "string",
  • "paymentMethod": "string",
  • "disputedBy": "string",
  • "disputedAt": "string",
  • "disputeReason": "string",
  • "cancellationReason": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get a bill

Retrieve bill details.

Authorizations:
Bearer
path Parameters
id
required
string

Bill identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "partnerId": "string",
  • "partnerName": "string",
  • "billNumber": "string",
  • "currency": "string",
  • "totalAmount": 0,
  • "subtotalCents": 0,
  • "totalTaxCents": 0,
  • "subject": "string",
  • "selfBilled": false,
  • "status": "string",
  • "issuedAt": "string",
  • "dueAt": "string",
  • "reviewedBy": "string",
  • "reviewedAt": "string",
  • "approvedBy": "string",
  • "approvedAt": "string",
  • "approvalNotes": "string",
  • "scheduledPaymentDate": "string",
  • "paidAt": "string",
  • "paymentReference": "string",
  • "paymentMethod": "string",
  • "disputedBy": "string",
  • "disputedAt": "string",
  • "disputeReason": "string",
  • "cancellationReason": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Approve bill

Approve a bill for payment.

Authorizations:
Bearer
path Parameters
id
required
string

Bill identifier

Request Body schema:
required

The new Bill resource

notes
string or null <= 500 characters

Responses

Request samples

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

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "partnerId": "string",
  • "partnerName": "string",
  • "billNumber": "string",
  • "currency": "string",
  • "totalAmount": 0,
  • "subtotalCents": 0,
  • "totalTaxCents": 0,
  • "subject": "string",
  • "selfBilled": false,
  • "status": "string",
  • "issuedAt": "string",
  • "dueAt": "string",
  • "reviewedBy": "string",
  • "reviewedAt": "string",
  • "approvedBy": "string",
  • "approvedAt": "string",
  • "approvalNotes": "string",
  • "scheduledPaymentDate": "string",
  • "paidAt": "string",
  • "paymentReference": "string",
  • "paymentMethod": "string",
  • "disputedBy": "string",
  • "disputedAt": "string",
  • "disputeReason": "string",
  • "cancellationReason": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Cancel bill

Cancel a bill.

Authorizations:
Bearer
path Parameters
id
required
string

Bill identifier

Request Body schema:
required

The new Bill resource

reason
required
string <= 500 characters

Responses

Request samples

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

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "partnerId": "string",
  • "partnerName": "string",
  • "billNumber": "string",
  • "currency": "string",
  • "totalAmount": 0,
  • "subtotalCents": 0,
  • "totalTaxCents": 0,
  • "subject": "string",
  • "selfBilled": false,
  • "status": "string",
  • "issuedAt": "string",
  • "dueAt": "string",
  • "reviewedBy": "string",
  • "reviewedAt": "string",
  • "approvedBy": "string",
  • "approvedAt": "string",
  • "approvalNotes": "string",
  • "scheduledPaymentDate": "string",
  • "paidAt": "string",
  • "paymentReference": "string",
  • "paymentMethod": "string",
  • "disputedBy": "string",
  • "disputedAt": "string",
  • "disputeReason": "string",
  • "cancellationReason": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Dispute bill

Dispute a bill under review or approved.

Authorizations:
Bearer
path Parameters
id
required
string

Bill identifier

Request Body schema:
required

The new Bill resource

reason
required
string <= 500 characters

Responses

Request samples

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

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "partnerId": "string",
  • "partnerName": "string",
  • "billNumber": "string",
  • "currency": "string",
  • "totalAmount": 0,
  • "subtotalCents": 0,
  • "totalTaxCents": 0,
  • "subject": "string",
  • "selfBilled": false,
  • "status": "string",
  • "issuedAt": "string",
  • "dueAt": "string",
  • "reviewedBy": "string",
  • "reviewedAt": "string",
  • "approvedBy": "string",
  • "approvedAt": "string",
  • "approvalNotes": "string",
  • "scheduledPaymentDate": "string",
  • "paidAt": "string",
  • "paymentReference": "string",
  • "paymentMethod": "string",
  • "disputedBy": "string",
  • "disputedAt": "string",
  • "disputeReason": "string",
  • "cancellationReason": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Mark bill as paid

Record payment for a scheduled bill.

Authorizations:
Bearer
path Parameters
id
required
string

Bill identifier

Request Body schema:
required

The new Bill resource

paymentReference
required
string <= 255 characters
paymentMethod
string or null
Enum: "bank_transfer" "check" "paypal" "other"
paidAmountInCents
required
integer > 0
currency
required
string = 3 characters

Responses

Request samples

Content type
{
  • "paymentReference": "string",
  • "paymentMethod": "bank_transfer",
  • "paidAmountInCents": 0,
  • "currency": "str"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "partnerId": "string",
  • "partnerName": "string",
  • "billNumber": "string",
  • "currency": "string",
  • "totalAmount": 0,
  • "subtotalCents": 0,
  • "totalTaxCents": 0,
  • "subject": "string",
  • "selfBilled": false,
  • "status": "string",
  • "issuedAt": "string",
  • "dueAt": "string",
  • "reviewedBy": "string",
  • "reviewedAt": "string",
  • "approvedBy": "string",
  • "approvedAt": "string",
  • "approvalNotes": "string",
  • "scheduledPaymentDate": "string",
  • "paidAt": "string",
  • "paymentReference": "string",
  • "paymentMethod": "string",
  • "disputedBy": "string",
  • "disputedAt": "string",
  • "disputeReason": "string",
  • "cancellationReason": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Start bill review

Start reviewing a received bill.

Authorizations:
Bearer
path Parameters
id
required
string

Bill identifier

Request Body schema:
required

The new Bill resource

id
string
tenantId
string
partnerId
string
partnerName
string or null

Denormalized partner display name

billNumber
string
currency
string
totalAmount
number
subtotalCents
integer or null

Net (tax-exclusive) amount the vendor charged, in minor units; null on a gross-only bill

totalTaxCents
integer or null

Input VAT the vendor charged, in minor units; captured verbatim, never recomputed; null on a gross-only bill

subject
string or null
selfBilled
boolean
Default: false

True when we raised this bill on the supplier's behalf (self-billed / ERS); its bill number is our issuer number, not the vendor's invoice number

status
string
issuedAt
string
dueAt
string
reviewedBy
string or null
reviewedAt
string or null
approvedBy
string or null
approvedAt
string or null
approvalNotes
string or null
scheduledPaymentDate
string or null
paidAt
string or null
paymentReference
string or null
paymentMethod
string or null
disputedBy
string or null
disputedAt
string or null
disputeReason
string or null
cancellationReason
string or null
createdAt
string
updatedAt
string

Responses

Request samples

Content type
{
  • "id": "string",
  • "tenantId": "string",
  • "partnerId": "string",
  • "partnerName": "string",
  • "billNumber": "string",
  • "currency": "string",
  • "totalAmount": 0,
  • "subtotalCents": 0,
  • "totalTaxCents": 0,
  • "subject": "string",
  • "selfBilled": false,
  • "status": "string",
  • "issuedAt": "string",
  • "dueAt": "string",
  • "reviewedBy": "string",
  • "reviewedAt": "string",
  • "approvedBy": "string",
  • "approvedAt": "string",
  • "approvalNotes": "string",
  • "scheduledPaymentDate": "string",
  • "paidAt": "string",
  • "paymentReference": "string",
  • "paymentMethod": "string",
  • "disputedBy": "string",
  • "disputedAt": "string",
  • "disputeReason": "string",
  • "cancellationReason": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "partnerId": "string",
  • "partnerName": "string",
  • "billNumber": "string",
  • "currency": "string",
  • "totalAmount": 0,
  • "subtotalCents": 0,
  • "totalTaxCents": 0,
  • "subject": "string",
  • "selfBilled": false,
  • "status": "string",
  • "issuedAt": "string",
  • "dueAt": "string",
  • "reviewedBy": "string",
  • "reviewedAt": "string",
  • "approvedBy": "string",
  • "approvedAt": "string",
  • "approvalNotes": "string",
  • "scheduledPaymentDate": "string",
  • "paidAt": "string",
  • "paymentReference": "string",
  • "paymentMethod": "string",
  • "disputedBy": "string",
  • "disputedAt": "string",
  • "disputeReason": "string",
  • "cancellationReason": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Schedule bill payment

Schedule a payment date for an approved bill.

Authorizations:
Bearer
path Parameters
id
required
string

Bill identifier

Request Body schema:
required

The new Bill resource

scheduledPaymentDate
required

Responses

Request samples

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

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "partnerId": "string",
  • "partnerName": "string",
  • "billNumber": "string",
  • "currency": "string",
  • "totalAmount": 0,
  • "subtotalCents": 0,
  • "totalTaxCents": 0,
  • "subject": "string",
  • "selfBilled": false,
  • "status": "string",
  • "issuedAt": "string",
  • "dueAt": "string",
  • "reviewedBy": "string",
  • "reviewedAt": "string",
  • "approvedBy": "string",
  • "approvedAt": "string",
  • "approvalNotes": "string",
  • "scheduledPaymentDate": "string",
  • "paidAt": "string",
  • "paymentReference": "string",
  • "paymentMethod": "string",
  • "disputedBy": "string",
  • "disputedAt": "string",
  • "disputeReason": "string",
  • "cancellationReason": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Finance Payments

Unified standalone Payment (In/Out) API resource.

List payments

Retrieve a paginated list of standalone payments with optional filters.

Authorizations:
Bearer
query Parameters
direction
string
Enum: "inbound" "outbound"

Filter by direction (inbound/outbound)

status
string
Enum: "pending" "processing" "completed" "failed" "refunded" "partially_refunded" "cancelled"

Filter by payment status

subject
string

Filter by subject ResourceUri

counterparty
string

Filter by counterparty (partner) id

page
integer >= 1
Default: 1

Page number

itemsPerPage
integer [ 1 .. 100 ]
Default: 25

Items per page

Responses

Response samples

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

Record a payment

Record a new standalone payment (In/Out) with optional links.

Authorizations:
Bearer
Request Body schema:
required

The new Payment resource

direction
required
string
Enum: "inbound" "outbound"
amountInCents
required
integer > 0
currency
required
string = 3 characters
paymentMethodId
required
string <ulid>
subject
string or null
counterpartyId
string or null <ulid>
externalReference
string or null
Array of objects
notes
string or null

Responses

Request samples

Content type
{
  • "direction": "inbound",
  • "amountInCents": 0,
  • "currency": "str",
  • "paymentMethodId": "string",
  • "subject": "string",
  • "counterpartyId": "string",
  • "externalReference": "string",
  • "links": [
    ],
  • "notes": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "direction": "string",
  • "amount": 0,
  • "refundedAmount": 0,
  • "currency": "string",
  • "paymentMethodId": "string",
  • "gateway": "string",
  • "status": "string",
  • "counterpartyId": "string",
  • "subject": "string",
  • "externalReference": "string",
  • "number": "string",
  • "notes": "string",
  • "recordedBy": "string",
  • "failureReason": "string",
  • "failureCode": "string",
  • "links": [
    ],
  • "paidAt": "string",
  • "completedAt": "string",
  • "reconciledAt": "string",
  • "failedAt": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get a payment

Retrieve payment details, including its links.

Authorizations:
Bearer
path Parameters
id
required
string

Payment identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "direction": "string",
  • "amount": 0,
  • "refundedAmount": 0,
  • "currency": "string",
  • "paymentMethodId": "string",
  • "gateway": "string",
  • "status": "string",
  • "counterpartyId": "string",
  • "subject": "string",
  • "externalReference": "string",
  • "number": "string",
  • "notes": "string",
  • "recordedBy": "string",
  • "failureReason": "string",
  • "failureCode": "string",
  • "links": [
    ],
  • "paidAt": "string",
  • "completedAt": "string",
  • "reconciledAt": "string",
  • "failedAt": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Cancel a payment

Cancel a pending payment.

Authorizations:
Bearer
path Parameters
id
required
string

Payment identifier

Request Body schema:
required

The new Payment resource

reason
string or null

Responses

Request samples

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

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "direction": "string",
  • "amount": 0,
  • "refundedAmount": 0,
  • "currency": "string",
  • "paymentMethodId": "string",
  • "gateway": "string",
  • "status": "string",
  • "counterpartyId": "string",
  • "subject": "string",
  • "externalReference": "string",
  • "number": "string",
  • "notes": "string",
  • "recordedBy": "string",
  • "failureReason": "string",
  • "failureCode": "string",
  • "links": [
    ],
  • "paidAt": "string",
  • "completedAt": "string",
  • "reconciledAt": "string",
  • "failedAt": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Complete a payment

Mark a payment as completed.

Authorizations:
Bearer
path Parameters
id
required
string

Payment identifier

Request Body schema:
required

The new Payment resource

externalReference
string or null

Responses

Request samples

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

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "direction": "string",
  • "amount": 0,
  • "refundedAmount": 0,
  • "currency": "string",
  • "paymentMethodId": "string",
  • "gateway": "string",
  • "status": "string",
  • "counterpartyId": "string",
  • "subject": "string",
  • "externalReference": "string",
  • "number": "string",
  • "notes": "string",
  • "recordedBy": "string",
  • "failureReason": "string",
  • "failureCode": "string",
  • "links": [
    ],
  • "paidAt": "string",
  • "completedAt": "string",
  • "reconciledAt": "string",
  • "failedAt": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Fail a payment

Mark a payment as failed with a reason.

Authorizations:
Bearer
path Parameters
id
required
string

Payment identifier

Request Body schema:
required

The new Payment resource

reason
required
string
failureCode
string or null

Responses

Request samples

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

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "direction": "string",
  • "amount": 0,
  • "refundedAmount": 0,
  • "currency": "string",
  • "paymentMethodId": "string",
  • "gateway": "string",
  • "status": "string",
  • "counterpartyId": "string",
  • "subject": "string",
  • "externalReference": "string",
  • "number": "string",
  • "notes": "string",
  • "recordedBy": "string",
  • "failureReason": "string",
  • "failureCode": "string",
  • "links": [
    ],
  • "paidAt": "string",
  • "completedAt": "string",
  • "reconciledAt": "string",
  • "failedAt": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Refund a payment

Refund a completed payment (full or partial).

Authorizations:
Bearer
path Parameters
id
required
string

Payment identifier

Request Body schema:
required

The new Payment resource

amountInCents
required
integer > 0
currency
required
string = 3 characters
reason
required
string

Responses

Request samples

Content type
{
  • "amountInCents": 0,
  • "currency": "str",
  • "reason": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "direction": "string",
  • "amount": 0,
  • "refundedAmount": 0,
  • "currency": "string",
  • "paymentMethodId": "string",
  • "gateway": "string",
  • "status": "string",
  • "counterpartyId": "string",
  • "subject": "string",
  • "externalReference": "string",
  • "number": "string",
  • "notes": "string",
  • "recordedBy": "string",
  • "failureReason": "string",
  • "failureCode": "string",
  • "links": [
    ],
  • "paidAt": "string",
  • "completedAt": "string",
  • "reconciledAt": "string",
  • "failedAt": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Finance Payment Methods

PaymentMethod API resource (finance/payment-methods).

List payment method groups

Retrieve the tenant's payment method display groups.

Authorizations:
Bearer
query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

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

Create a payment method group

Create a payment method group

Authorizations:
Bearer
Request Body schema:
required

The new PaymentMethodGroup resource

name
required
string
sortOrder
integer >= 0
Default: 0

Responses

Request samples

Content type
{
  • "name": "string",
  • "sortOrder": 0
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "name": "string",
  • "sortOrder": 0,
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get a payment method group

Get a payment method group

Authorizations:
Bearer
path Parameters
id
required
string

PaymentMethodGroup identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "name": "string",
  • "sortOrder": 0,
  • "createdAt": "string",
  • "updatedAt": "string"
}

Rename a payment method group

Rename a payment method group

Authorizations:
Bearer
path Parameters
id
required
string

PaymentMethodGroup identifier

Request Body schema:
required

The new PaymentMethodGroup resource

name
required
string
sortOrder
integer or null >= 0

Responses

Request samples

Content type
{
  • "name": "string",
  • "sortOrder": 0
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "name": "string",
  • "sortOrder": 0,
  • "createdAt": "string",
  • "updatedAt": "string"
}

List payment methods

Retrieve a paginated list of the tenant's configured payment methods.

Authorizations:
Bearer
query Parameters
gateway
string

Filter by gateway

status
string
Enum: "active" "inactive"

Filter by status (active/inactive)

groupId
string

Filter by group id

page
integer >= 1
Default: 1

Page number

itemsPerPage
integer [ 1 .. 100 ]
Default: 25

Items per page

Responses

Response samples

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

Create a payment method

Configure a new payment method for the tenant.

Authorizations:
Bearer
Request Body schema:
required

The new PaymentMethod resource

name
required
string
gateway
required
string
Enum: "manual" "cash" "bank_transfer" "card" "stripe" "paypal" "wallet" "cash_on_delivery" "other"
sortOrder
integer >= 0
Default: 0
icon
string or null
groupId
string or null <ulid>

Responses

Request samples

Content type
{
  • "name": "string",
  • "gateway": "manual",
  • "sortOrder": 0,
  • "icon": "string",
  • "groupId": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "name": "string",
  • "gateway": "string",
  • "canProcess": true,
  • "status": "string",
  • "isSystemProvisioned": true,
  • "sortOrder": 0,
  • "icon": "string",
  • "groupId": "string",
  • "aliases": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get a payment method

Retrieve a payment method, including its cross-channel aliases.

Authorizations:
Bearer
path Parameters
id
required
string

PaymentMethod identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "name": "string",
  • "gateway": "string",
  • "canProcess": true,
  • "status": "string",
  • "isSystemProvisioned": true,
  • "sortOrder": 0,
  • "icon": "string",
  • "groupId": "string",
  • "aliases": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Activate a payment method

Activate a payment method

Authorizations:
Bearer
path Parameters
id
required
string

PaymentMethod identifier

Request Body schema:
required

The new PaymentMethod resource

object (PaymentMethod.PaymentMethodActionInput)

PaymentMethod API resource (finance/payment-methods).

Responses

Request samples

Content type
{ }

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "name": "string",
  • "gateway": "string",
  • "canProcess": true,
  • "status": "string",
  • "isSystemProvisioned": true,
  • "sortOrder": 0,
  • "icon": "string",
  • "groupId": "string",
  • "aliases": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Attach a cross-channel alias

Attach a cross-channel alias

Authorizations:
Bearer
path Parameters
id
required
string

PaymentMethod identifier

Request Body schema:
required

The new PaymentMethod resource

externalCode
required
string
channelRef
string or null
channelType
string or null
externalLabel
string or null

Responses

Request samples

Content type
{
  • "externalCode": "string",
  • "channelRef": "string",
  • "channelType": "string",
  • "externalLabel": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "name": "string",
  • "gateway": "string",
  • "canProcess": true,
  • "status": "string",
  • "isSystemProvisioned": true,
  • "sortOrder": 0,
  • "icon": "string",
  • "groupId": "string",
  • "aliases": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Deactivate a payment method

Deactivate a payment method

Authorizations:
Bearer
path Parameters
id
required
string

PaymentMethod identifier

Request Body schema:
required

The new PaymentMethod resource

object (PaymentMethod.PaymentMethodActionInput)

PaymentMethod API resource (finance/payment-methods).

Responses

Request samples

Content type
{ }

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "name": "string",
  • "gateway": "string",
  • "canProcess": true,
  • "status": "string",
  • "isSystemProvisioned": true,
  • "sortOrder": 0,
  • "icon": "string",
  • "groupId": "string",
  • "aliases": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Detach a cross-channel alias

Detach a cross-channel alias

Authorizations:
Bearer
path Parameters
id
required
string

PaymentMethod identifier

Request Body schema:
required

The new PaymentMethod resource

externalCode
required
string
channelRef
string or null

Responses

Request samples

Content type
{
  • "externalCode": "string",
  • "channelRef": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "name": "string",
  • "gateway": "string",
  • "canProcess": true,
  • "status": "string",
  • "isSystemProvisioned": true,
  • "sortOrder": 0,
  • "icon": "string",
  • "groupId": "string",
  • "aliases": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Move a payment method into a group

Move a payment method into a group

Authorizations:
Bearer
path Parameters
id
required
string

PaymentMethod identifier

Request Body schema:
required

The new PaymentMethod resource

groupId
string or null <ulid>

Responses

Request samples

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

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "name": "string",
  • "gateway": "string",
  • "canProcess": true,
  • "status": "string",
  • "isSystemProvisioned": true,
  • "sortOrder": 0,
  • "icon": "string",
  • "groupId": "string",
  • "aliases": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Rename a payment method

Rename a payment method

Authorizations:
Bearer
path Parameters
id
required
string

PaymentMethod identifier

Request Body schema:
required

The new PaymentMethod resource

name
required
string

Responses

Request samples

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

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "tenantId": "string",
  • "name": "string",
  • "gateway": "string",
  • "canProcess": true,
  • "status": "string",
  • "isSystemProvisioned": true,
  • "sortOrder": 0,
  • "icon": "string",
  • "groupId": "string",
  • "aliases": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Finance - Tax Categories

Read-only tenant view of tax categories.

List all tax categories

Retrieve a paginated list of tax categories with optional search.

Authorizations:
Bearer
query Parameters
search
string

Search by name or code

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": [
    ]
}

Finance - Tax Rules

Read-only tenant view of tax rules.

List all tax rules

Retrieve a paginated list of tax rules with optional filters.

Authorizations:
Bearer
query Parameters
zoneCode
string

Filter by zone code

isActive
boolean

Filter by active status

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": [
    ]
}

Finance - Tax Rates

Read-only tenant view of tax rates.

List all tax rates

Retrieve a paginated list of tax rates with optional filters.

Authorizations:
Bearer
query Parameters
type
string
Enum: "percentage" "fixed_amount"

Filter by tax type

countryCode
string

Filter by country code

isActive
boolean

Filter by active status

isDefault
boolean

Filter by default status

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": [
    ]
}

Finance - Exchange Rates

Operator-maintained FX rate: 1 unit of baseCurrency = rate units of quoteCurrency, as of effectiveAt. rate stays a decimal string so precision is preserved.

List exchange rates

Retrieve a paginated list of FX rates with optional currency filters.

Authorizations:
Bearer
query Parameters
baseCurrency
string

Filter by base (source) currency ISO-4217 code

quoteCurrency
string

Filter by quote (target) currency ISO-4217 code

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 an exchange rate

Create a new FX rate. 1 unit of baseCurrency = rate units of quoteCurrency.

Authorizations:
Bearer
Request Body schema: application/json
required

Exchange rate data

baseCurrency
required
string

Source currency ISO-4217 code

quoteCurrency
required
string

Target currency ISO-4217 code

rate
required
string

Units of quoteCurrency per 1 baseCurrency (decimal string)

effectiveAt
required
string <date-time>

When this rate takes effect

Responses

Request samples

Content type
application/json
{
  • "baseCurrency": "USD",
  • "quoteCurrency": "NGN",
  • "rate": "1650.5",
  • "effectiveAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "baseCurrency": "string",
  • "quoteCurrency": "string",
  • "rate": "string",
  • "effectiveAt": "string",
  • "createdBy": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get an exchange rate

Retrieve a single FX rate by its ULID.

Authorizations:
Bearer
path Parameters
id
required
string

ExchangeRate identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "baseCurrency": "string",
  • "quoteCurrency": "string",
  • "rate": "string",
  • "effectiveAt": "string",
  • "createdBy": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Delete an exchange rate

Delete an FX rate.

Authorizations:
Bearer
path Parameters
id
required
string

ExchangeRate identifier

Responses

Update an exchange rate

Update the rate and/or effective date of an existing FX rate.

Authorizations:
Bearer
path Parameters
id
required
string

ExchangeRate identifier

Request Body schema: application/merge-patch+json
required

The updated ExchangeRate resource

rate
string or null^(\d+(\.\d+)?)$
effectiveAt
string or null

Responses

Request samples

Content type
application/merge-patch+json
{
  • "rate": "string",
  • "effectiveAt": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "baseCurrency": "string",
  • "quoteCurrency": "string",
  • "rate": "string",
  • "effectiveAt": "string",
  • "createdBy": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Finance

Purchase price variance summary over a period, bucketed by granularity and split by currency. Read from finance_price_variances.

COGS over a period

Cost of goods sold aggregated over a period into day/week/month buckets, split by currency, with a per-currency total.

Authorizations:
Bearer
query Parameters
startDate
string <date>

Period start (YYYY-MM-DD). Defaults to 30 days ago.

endDate
string <date>

Period end (YYYY-MM-DD). Defaults to today.

granularity
string
Default: "day"
Enum: "day" "week" "month"

Bucket size.

currency
string

Restrict to a single ISO 4217 currency.

warehouse
string

Restrict to a single warehouse (ULID).

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "cogs",
  • "startDate": "",
  • "endDate": "",
  • "granularity": "day",
  • "points": [
    ],
  • "totals": [
    ],
  • "generatedAt": ""
}

GRNI aging

Open GRNI balances by subject, bucketed by age as of a reporting date and split by currency.

Authorizations:
Bearer
query Parameters
asOf
string <date>

Reporting date (YYYY-MM-DD). Defaults to today.

currency
string

Restrict to a single ISO 4217 currency.

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "grni-aging",
  • "asOf": "",
  • "buckets": [
    ],
  • "subjects": [
    ],
  • "generatedAt": ""
}

Inventory valuation by warehouse

On-hand stock value aggregated by warehouse and currency, with a per-currency grand total.

Authorizations:
Bearer
query Parameters
warehouse
string

Restrict to a single warehouse (ULID).

currency
string
Example: currency=USD

Restrict to a single ISO 4217 currency.

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "inventory-value",
  • "warehouses": [
    ],
  • "totals": [
    ],
  • "generatedAt": ""
}

Three-way-match exceptions worklist

Paginated list of GRNI three-way-match exceptions awaiting operator attention, newest update first.

Authorizations:
Bearer
query Parameters
currency
string

Filter by ISO 4217 currency.

page
integer
Default: 1

Page number.

itemsPerPage
integer
Default: 25

Items per page.

Responses

Response samples

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

Purchase price variance summary

Purchase price variance aggregated over a period into day/week/month buckets, split by currency, with a per-currency total.

Authorizations:
Bearer
query Parameters
startDate
string <date>

Period start (YYYY-MM-DD). Defaults to 30 days ago.

endDate
string <date>

Period end (YYYY-MM-DD). Defaults to today.

granularity
string
Default: "month"
Enum: "day" "week" "month"

Bucket size.

currency
string

Restrict to a single ISO 4217 currency.

warehouse
string

Restrict to a single warehouse (ULID).

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "price-variance",
  • "startDate": "",
  • "endDate": "",
  • "granularity": "month",
  • "points": [
    ],
  • "totals": [
    ],
  • "generatedAt": ""
}

Valuation

Purchase price variance summary over a period, bucketed by granularity and split by currency. Read from finance_price_variances.

COGS over a period

Cost of goods sold aggregated over a period into day/week/month buckets, split by currency, with a per-currency total.

Authorizations:
Bearer
query Parameters
startDate
string <date>

Period start (YYYY-MM-DD). Defaults to 30 days ago.

endDate
string <date>

Period end (YYYY-MM-DD). Defaults to today.

granularity
string
Default: "day"
Enum: "day" "week" "month"

Bucket size.

currency
string

Restrict to a single ISO 4217 currency.

warehouse
string

Restrict to a single warehouse (ULID).

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "cogs",
  • "startDate": "",
  • "endDate": "",
  • "granularity": "day",
  • "points": [
    ],
  • "totals": [
    ],
  • "generatedAt": ""
}

GRNI aging

Open GRNI balances by subject, bucketed by age as of a reporting date and split by currency.

Authorizations:
Bearer
query Parameters
asOf
string <date>

Reporting date (YYYY-MM-DD). Defaults to today.

currency
string

Restrict to a single ISO 4217 currency.

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "grni-aging",
  • "asOf": "",
  • "buckets": [
    ],
  • "subjects": [
    ],
  • "generatedAt": ""
}

Inventory valuation by warehouse

On-hand stock value aggregated by warehouse and currency, with a per-currency grand total.

Authorizations:
Bearer
query Parameters
warehouse
string

Restrict to a single warehouse (ULID).

currency
string
Example: currency=USD

Restrict to a single ISO 4217 currency.

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "inventory-value",
  • "warehouses": [
    ],
  • "totals": [
    ],
  • "generatedAt": ""
}

Three-way-match exceptions worklist

Paginated list of GRNI three-way-match exceptions awaiting operator attention, newest update first.

Authorizations:
Bearer
query Parameters
currency
string

Filter by ISO 4217 currency.

page
integer
Default: 1

Page number.

itemsPerPage
integer
Default: 25

Items per page.

Responses

Response samples

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

Purchase price variance summary

Purchase price variance aggregated over a period into day/week/month buckets, split by currency, with a per-currency total.

Authorizations:
Bearer
query Parameters
startDate
string <date>

Period start (YYYY-MM-DD). Defaults to 30 days ago.

endDate
string <date>

Period end (YYYY-MM-DD). Defaults to today.

granularity
string
Default: "month"
Enum: "day" "week" "month"

Bucket size.

currency
string

Restrict to a single ISO 4217 currency.

warehouse
string

Restrict to a single warehouse (ULID).

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "price-variance",
  • "startDate": "",
  • "endDate": "",
  • "granularity": "month",
  • "points": [
    ],
  • "totals": [
    ],
  • "generatedAt": ""
}