Share an invoice with the counterparty

post

https://api.bitwave.io/v1/invoices/{invoiceId}:share

Distributes the invoice to the counterparty over a channel (relationship — a Bitwave org-to-org connection — or email).

:share is a superset of :issue: if the invoice is still a draft, it is committed (lifecycle: issued) first, then shared. Idempotent: re-sharing on the same channel succeeds with no change.

Precondition (otherwise 409 precondition_failed): the invoice must have at least one paymentAccountIds entry, so the payor has somewhere to pay (find candidates with GET /v1/payment-accounts?enabledForAR=true). A voided or deleted invoice cannot be shared. Send the current version; a stale value is refused with 409 version_mismatch.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

invoiceId

string

required

The invoice id.

Body Params

Body for :share. Carries the version you last read via GET (a stale value is refused with 409 version_mismatch) and the channel to distribute over.

version

int64

required

≥ 0

The invoice version you last read (via GET).

channel

string

enum

required

Channel over which an invoice is distributed to the counterparty. Extensible enum — tolerate unknown values.

relationship — delivered through a Bitwave org-to-org connection (appears as
the counterparty's AP bill).
email — delivered as an InvoiceShare link by email.

Allowed:

Headers

Idempotency-Key

string

length ≤ 255

Optional idempotency key (a UUID is ideal). Retrying a command with the same key applies the action at most once and returns the original result, so a network retry can't double-apply. Complements version (which guards concurrent writes).

Responses

200The invoice, now shared (and issued if it was a draft), with its incremented version.

400Invalid request (code: invalid_request).

401Missing, expired, or invalid bearer token (code: unauthorized). The response carries WWW-Authenticate: Bearer error="invalid_token". Re-authenticate to obtain a fresh token.

403The token is valid but lacks the required scope (code: forbidden).

404No such resource for your organization (code: not_found). Also returned when a resource exists but belongs to a different organization.

429Too many requests (code: rate_limited). Wait for Retry-After seconds, then retry.

500Unexpected server error (code: internal_error).