Record a payment to the vendor (deposit, balance, payment or refund)

The balance due is what the purchase order costs in the end (payableTotal: its total; what was received plus its charges once it is closed short; 0 once it is cancelled) minus what was paid (a refund subtracts); the financial status becomes paid (what was paid covers a payableTotal above 0), partly-paid or unbilled. A purchase order that did not track payments starts tracking with this one. A payment above what is owed is accepted: the balance due is then below zero and says by how much. A refund returns money that was paid, so one above what was paid (refunds already recorded taken off) is 422 totals_mismatch, and the message names that amount. A cancelled purchase order takes only a refund: any other kind is 409. More payments than the limit is 409; an archived purchase order is read-only (409).

Scope: outgoing-purchase-orders:write, channel:write or admin. A permission group made before the Channel API scopes existed grants it as inventory:manage or supply-chain:manage.

Idempotency: send Idempotency-Key; a retry with the same key replays the first answer.

Rate limit: write class, 1,200 requests per minute per tenant by default (read class 6,000). Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a refusal is 429 rate_limited with Retry-After.

Path Params
string
required
length between 1 and 64

The purchase order's uuid or 24-hex id.

Body Params
required
length ≤ 24
^[0-9]{1,14}(\.[0-9]{1,8})?$

A non-negative decimal amount in currency units ("12.50"); numbers are accepted.

enum
^[0-9]{4}-[0-9]{2}-[0-9]{2}$

YYYY-MM-DD (anchored at 12:00 UTC) or an ISO-8601 timestamp.


A date: stored at 12:00 UTC.

string
length ≤ 50

Wire, card, check, ...

string
length ≤ 100
string
length ≤ 500
Headers
string
length between 7 and 50

Any string of 7 to 50 characters that identifies this request (an order number, a webhook id). A retry with the same key and the same body answers the first result with Idempotent-Replayed: true; the same key with a different body is 422 idempotency_key_reused; a concurrent request with the same key is 409 in_progress with Retry-After. Recommended on every write.

Responses

Language
Credentials
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json