Read the marketplace's balances
Per currency: buyers' money you are holding, what each seller is owed, your fees, disputes you absorbed, and what the payment provider has yet to settle — plus the books' own cross-check, which is zero when everything balances. Requires marketplace.read.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Read the marketplace's balances › Responses
OK
List the transfers owed to your sellers
Every transfer prepared against a finalized statement, newest first, with the statement it settles and who is being paid. Filter by seller and by state to find the ones still waiting to go out. Requires marketplace.read.
query Parameters
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
sortOrdering: created_at with an optional :asc/:desc suffix (default created_at:desc). An unknown value is rejected. Cursors are bound to the ordering that issued them, so changing sort mid-walk needs a fresh first page.
statusKeep only payouts in these states, comma-separated: prepared, submitted, reconciled, returned, paid. Absent keeps all.
seller_customer_idKeep only what is owed to this seller.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List the transfers owed to your sellers › Responses
OK
Record that you transferred a payout
Says the money left your bank, clears what the seller was owed and marks the statement paid. The bank's own reference is required — it is the only evidence the transfer happened. Only a transfer that is still waiting can be marked: one already paid, or one in a bank batch, is refused rather than paid a second time. Requires marketplace.payouts.manage.
path Parameters
idThe payout you transferred.
Headers
Idempotency-KeyRequired on this money route. Reuse the same key to retry safely.
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Record that you transferred a payout › Request Body
bank_referenceThe bank's own reference for the transfer you made. Required: it is what the payment is evidenced by.
Record that you transferred a payout › Responses
OK
List sales on your marketplace
Newest first. Filter by state, by who sold, by who bought, and by when they were agreed. Requires marketplace.read.
query Parameters
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
sortOrdering: agreed_at with an optional :asc/:desc suffix (default agreed_at:desc). An unknown value is rejected. Cursors are bound to the ordering that issued them, so changing sort mid-walk needs a fresh first page.
statusKeep only sales in these states, comma-separated: agreed, funded, completed, cancelled, refunded. Absent keeps all.
seller_customer_idKeep only what this customer sold.
buyer_customer_idKeep only what this customer bought.
agreed_fromKeep only sales agreed at or after this instant (RFC3339).
agreed_toKeep only sales agreed BEFORE this instant (RFC3339). The period is half-open, as every period in this API is, so consecutive ranges neither overlap nor gap.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List sales on your marketplace › Responses
OK
Agree a sale between two of your customers
Records that one customer is selling to another, works out who supplies it for tax purposes and what your fee is, and freezes both onto the sale — so a document issued months later still says who supplied and why. The seller must be verified and must have a bank account on file. Who supplies is decided here and cannot be chosen. Requires marketplace.manage.
Headers
Idempotency-KeyRequired on this money route. Reuse the same key to retry safely; a new key creates a new sale.
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Agree a sale between two of your customers › Request Body
What the buyer pays, with its currency. The seller must have a bank account on file to be paid in.
buyer_customer_idThe customer that is buying. It cannot be the seller.
listing_referenceYour own reference for what is being sold — the storefront's id for the listing. Required: this package never parses or resolves it, so it is the only thing tying the sale back to what was on offer.
seller_customer_idThe customer that is selling. It must already be a verified seller.
whatWhat is being sold: a digital service delivered electronically, another kind of service, a right, or goods. Required — there is no default, because who supplies for tax purposes depends on it.
commission_product_idCharge the fee from this product instead of the one your settings name. Omit to use the setting.
supplied_byState who you believe supplies, and the request is refused if that is not the answer. Omit it — this is decided from what is sold and where the parties are, never chosen.
Agree a sale between two of your customers › Responses
Created
Read one sale
The sale's state, who supplied it and on what ground, the amounts, the documents it produced and when each step happened. Requires marketplace.read.
path Parameters
idThe sale.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Read one sale › Responses
OK
Cancel a sale before it is delivered
Unwinds the sale and refunds the buyer if it has already paid. Safe to retry: the refund is tied to the sale, so it is issued once however many times you call. Refused once the sale is delivered — refund it instead. Requires marketplace.manage.
path Parameters
idThe sale.
Headers
Idempotency-KeyRequired on this money route.
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Cancel a sale before it is delivered › Responses
OK
Change who bears a lost dispute
Moves a lost dispute between the seller and this organization. The books are corrected by recording the move, never by editing what was recorded before, so the decision and its date stay visible. Requires marketplace.manage.
path Parameters
idThe sale whose chargeback is being reassigned.
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Change who bears a lost dispute › Request Body
bearerWho should bear it: the seller, whose balance is debited, or this organization, which absorbs it. It must be the one that is NOT bearing it today; asking for the current bearer is refused rather than silently doing nothing.
dispute_idThe dispute being reassigned. It must be one this sale has a chargeback recorded under — read the sale's postings to find it.
Change who bears a lost dispute › Responses
OK
Charge the buyer for a sale
Takes the sale's full amount from the buyer's saved payment method. The sale is not marked paid here — it becomes funded on its own once the payment goes through, so what comes back is the payment to follow rather than the sale. Only a sale still waiting for payment can be charged, and a buyer with nothing saved to charge is refused rather than sent to a payment page. Safe to retry with the same Idempotency-Key: repeats land on the same payment instead of taking the money twice. Requires marketplace.manage.
path Parameters
idThe sale to charge the buyer for.
Headers
Idempotency-KeyRequired on this money route.
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Charge the buyer for a sale › Request Body
return_urlWhere to send the buyer back to after it completes a bank challenge. Omit it if your surface finishes the challenge without leaving the page.
Charge the buyer for a sale › Responses
Created
Mark a sale delivered
Call this once you have delivered. It credits the seller with the sale less your fee, issues the buyer's document in whoever supplied's name, and invoices the seller for the fee — all or nothing, so a failure leaves the sale unchanged and you can retry with the same Idempotency-Key. Refused once the deadline for completing has passed, because the sale is then cancelled automatically and the buyer refunded. Requires marketplace.manage.
path Parameters
idThe sale.
Headers
Idempotency-KeyRequired on this money route.
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Mark a sale delivered › Responses
OK
Read what money moved on one sale
Every movement this sale caused, newest first, with both sides of each. The sale says what was agreed and this says what actually moved, which is why it is worth reading separately. Requires marketplace.read.
path Parameters
idThe sale.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Read what money moved on one sale › Responses
OK
Refund a delivered sale, in whole or in part
Gives the buyer back what you say, takes it out of what the seller is owed, and issues a credit note. Your fee follows it back or is kept, according to what the sale was agreed under. Can be called again until the whole amount has gone back, at which point the sale is final. Requires marketplace.manage.
path Parameters
idThe sale to refund.
Headers
Idempotency-KeyRequired on this money route.
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Refund a delivered sale, in whole or in part › Request Body
How much to give back, with its currency, which must be the sale's. It can be less than the gross, and it can be asked for again until the whole gross has gone back.
Refund a delivered sale, in whole or in part › Responses
OK
List the sellers on your marketplace
Every customer that has been given the seller role, newest first. Filter by state to find the ones waiting to be verified. Requires marketplace.read.
query Parameters
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
sortOrdering: created_at with an optional :asc/:desc suffix (default created_at:desc). An unknown value is rejected. Cursors are bound to the ordering that issued them, so changing sort mid-walk needs a fresh first page.
statusKeep only sellers in these states, comma-separated: pending, verified, suspended, closed. Absent keeps all.
customer_idKeep only the seller role of this customer, which is how to answer "is this customer already a seller" without knowing the seller id.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List the sellers on your marketplace › Responses
OK
Give a customer the seller role
Makes an existing customer a seller and runs whatever check your verification setting asks for, so the seller may come back already verified or waiting. One seller per customer: a second request is a conflict rather than an update. Requires marketplace.manage.
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Give a customer the seller role › Request Body
customer_idThe customer to give the seller role to. One seller per customer; a second request is a conflict.
series_code_prefixThe prefix the seller's own document numbers are built from: 1-16 characters of A-Z, 0-9 and '-'. It must not be used by another seller, and must not be one your organization already numbers its own documents from: document numbers are unique across your whole organization whoever issued them, so a shared prefix would stop the seller's first document being numbered.
countryWhere the seller is established, ISO 3166-1 alpha-2. Omit to take it from the customer's billing address; a customer with no address must be given one here.
in_businessWhether the seller trades as a business. Omit to take it from the customer's classification.
mandate_agreed_atWhen the seller agreed to let this organization sell on its behalf.
natural_personWhether the seller is a private individual. Defaults to false.
Where the seller is paid. It can be supplied later.
self_billing_agreed_atWhen the seller agreed to let this organization raise documents in the seller's name.
small_business_schemeThe national small-business exemption the seller declares, e.g. DE_19. Omit for none.
tax_regimeThe VAT regime the seller declares. Defaults to STANDARD.
Give a customer the seller role › Responses
Created
Read one seller
The seller's state, tax posture, document-number prefix, agreements and masked payout account. Its name, address and tax identifiers are the customer's and are read there. Requires marketplace.read.
path Parameters
idThe seller.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Read one seller › Responses
OK
Change a seller's posture, payout account or agreements
Changes what the seller declares about itself and where it is paid. It applies to future sales only — a sale already agreed keeps the posture it was agreed under. The seller's state is not changed here. Requires marketplace.manage.
path Parameters
idThe seller to change.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Change a seller's posture, payout account or agreements › Request Body
mandate_agreed_atWhen the seller agreed to let this organization sell on its behalf; null withdraws the agreement; omit to leave it alone.
payout_accountWhere the seller is paid; null removes the account; omit it to leave it alone.
The seller's tax posture, replaced as a whole. Omit to leave it alone. A change applies to future sales only — a sale already agreed keeps the posture it was agreed under.
self_billing_agreed_atWhen the seller agreed to let this organization raise documents in its name; null withdraws the agreement; omit to leave it alone.
series_code_prefixA new document-number prefix. Omit to leave it alone.
Change a seller's posture, payout account or agreements › Responses
OK
Close a seller
Final: the customer stops being a seller and cannot become one again. Refused while any of its sales is unfinished or while anything is still owed in either direction, because a buyer who has paid must still be able to receive or be refunded. Requires marketplace.manage.
path Parameters
idThe seller.
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Close a seller › Responses
OK
Reinstate a suspended seller
Lifts a suspension. The verification check runs again, so a seller whose VAT ID lapsed while it was suspended is not reinstated into selling. Requires marketplace.manage.
path Parameters
idThe seller.
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Reinstate a suspended seller › Responses
OK
Suspend a seller
Stops the seller starting new sales. Sales the buyer has already paid for still complete, and statements still run, so nobody is stranded. Reversible. Requires marketplace.manage.
path Parameters
idThe seller.
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Suspend a seller › Responses
OK
Verify a seller
Lets the seller start selling. What is checked depends on your verification setting; a seller that is already verified is left as it is rather than refused, so this is safe to retry. A seller established in a country where invoices must be issued through the tax authority's own system cannot be verified. Requires marketplace.manage.
path Parameters
idThe seller.
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Verify a seller › Responses
OK
List your sellers' statements
What each seller was owed for each period, most recent period first. Filter by seller, by state, by currency and by when the period ended. The individual movements are not listed here — read one statement for those. Requires marketplace.read.
query Parameters
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
sortOrdering: period_end with an optional :asc/:desc suffix (default period_end:desc). An unknown value is rejected. Cursors are bound to the ordering that issued them, so changing sort mid-walk needs a fresh first page.
statusKeep only statements in these states, comma-separated: draft, finalized, paid. Absent keeps all.
seller_customer_idKeep only this seller's statements.
currencyKeep only statements in this currency, ISO 4217. A statement has exactly one.
period_fromKeep only statements whose period ENDS at or after this instant (RFC3339).
period_toKeep only statements whose period ends BEFORE this instant (RFC3339). Half-open, as every period in this API is, so consecutive ranges neither overlap nor gap.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List your sellers' statements › Responses
OK
Read one statement
The period, what it came to, and every movement behind the totals — the sales that credited the seller, your fee, what went back to buyers, disputes the seller bore, and the balance brought forward from last time. Requires marketplace.read.
path Parameters
idThe statement.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Read one statement › Responses
OK
Download a statement as a PDF
The document the seller was sent, exactly as it was sent. A statement that is still being rendered is not found yet; ask again. Requires marketplace.read.
path Parameters
idThe statement.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Download a statement as a PDF › Responses
PDF file