API Documentation

Update an invoice

patch
https://api.bitwave.io/v1/invoices/

Updates an invoice. Editing is allowed only while the invoice is a draft — once it is committed (lifecycle: issued or beyond) its terms are frozen and any edit is refused with 409 precondition_failed; change a committed invoice by :void + re-issue instead. Uses JSON Merge Patch (RFC 7396), so the request content type is application/merge-patch+json:

  • A field present with a value sets that value.

  • A field present and null clears it (nullable fields only; null on a
    non-nullable field is 400 invalid_request).

  • A field absent is left unchanged.

  • The lines array, when present, REPLACES all line items — send the
    full list, including a line's id to keep/modify it, omitting id for a
    new line. lines: [] clears all lines; omit the field to leave lines
    unchanged.

Lifecycle and settlement are not editable here — move the invoice with the lifecycle commands (:issue / :share / :sync / :void / :delete); settlement is derived from payments.

Concurrency: read the invoice's version, then send it in the body; a stale value is refused with 409 version_mismatch. On success the invoice is returned with an incremented version.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
string
required

The invoice id.

Body Params

Body for updating an invoice. JSON Merge Patch (RFC 7396): a field present sets it; a field present and null clears it (nullable fields only); a field absent is unchanged; lines, when present, replaces the full set of line items.

int64
required
≥ 0

The invoice version you last read (via GET). A stale value is refused with 409 version_mismatch.

string

Change the customer. Discover via GET /v1/customers.

paymentAccountIds
array of strings | null

Set/change the receiving payment accounts (discover via GET /v1/payment-accounts?enabledForAR=true), one per settlement rail. When present, replaces the full set; [] or null clears it; absent leaves it unchanged. At least one is required before the invoice can be shared.

paymentAccountIds
string

Human-facing invoice number.

string | null

Invoice title. Send null to clear.

string

Invoice description.

string
enum

How the invoice's line amounts are denominated. Extensible enum — tolerate unknown values.

  • fiat — lines are priced in a fiat currency (type: fiat); the payor
    settles on one of the invoice's paymentOptions rails, converted to the
    denomination currency at payment time.

  • token — lines are priced directly in on-chain tokens; the invoice carries
    one total per distinct token currency among the lines.

Allowed:
paymentOptions
array of objects | null

The settlement rails the payor may pay on, each a {ticker, network} currency. When present, replaces the full set; [] or null clears it; absent leaves it unchanged.

paymentOptions
date-time | null

Date the invoice is issued. Send null to clear.

date-time

Date the invoice is due.

lines
array of objects

Full replacement set of line items. When present, replaces all existing lines — include a line's id to preserve/modify it, omit id for a new one. [] clears all lines. Omit the field to leave lines unchanged.

lines
Responses

Updated about 1 hour ago

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

Updated about 1 hour ago