Skip to main content
POST
Record a manual (cash/external/comp) transaction against an order

Authorizations

x-api-key
string
header
required

API key minted in the MarketBox dashboard. Scope is restricted to the projects you select at creation time. Every route needs the key's standard API access (*) except POST /v1/projects/{projectId}/events, which needs events:write; a key without * is refused with 403 CAPABILITY_NOT_GRANTED.

Path Parameters

projectId
string
required

The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.

Minimum string length: 1
Example:

"prj_01kv60qgnef2kt3pvqgwmkbzfr"

orderId
string
required

The order — the commercial record. Order items are drawn down into bookings.

Minimum string length: 1
Example:

"ord_01kv8m92p4jcrywn14znp8cym0"

Body

application/json

Manual transaction data

kind
enum<string>
required
Available options:
PAYMENT,
ADJUSTMENT
source
enum<string>
required
Available options:
CASH,
EXTERNAL,
COMP
amount
object
required
clientId
string
Minimum string length: 1
note
string
Required string length: 1 - 500
reason
string

Why the charge was waived. REQUIRED when source is COMP.

Required string length: 1 - 500
Example:

"Service recovery — late supplier"

idempotencyKey
string

Replay guard. The same key on the same order returns the row the first call created instead of recording the money twice.

Required string length: 1 - 128
Example:

"9f8c0f7a-1f3f-4c8e-9a2b-6c7d8e9f0a1b"

Response

Replay of an earlier idempotencyKey — the original row, unchanged

data
object
required
replayed
enum<boolean>
required
Available options:
true