Get store payouts and tax reports

A payout sends your store's payable balance to your organization, one currency at a time. We create payouts on your store's schedule, you can ask for one at any time, and our staff approve and send each one. The tax report lists the tax the Coritan companies charged on your sales, for your own accounts.

This page covers store payouts. The payouts for your organization's billing are on Track your payouts, and neither list shows the other's. The routes are under https://api.coritan.com/api/v1/orgs/{org_slug}/commerce/. The API reference lists the payout routes under Billing & Payouts, and the tax report under Commerce.

• Reading payouts and tax reports takes an organization API key with the commerce.finance:read scope, or a member's token with the Billing role or above.
• Asking for a payout takes an owner's or admin's token. No API key can ask for one.
• We pay out only once we have approved your merchant profile, and never while the store is suspended.
• We send the money by the payout method set for your organization: paypal, stripe_connect, or manual, which means we send it by hand. Ask support to change it.

A payout pays every row of the ledger in one currency that is available and not yet paid: your sales and shipping, less refunds, our commission and chargebacks. It takes off any reserve that is still held, and pays a reserve back once its release date has passed. The result is the payable amount that GET /commerce/balance shows. Test orders never count.

Tax is never paid out, because the Coritan company that sold the order owes it. The money for a gift card sold is not paid out either: it becomes yours as part of the sale when a shopper spends the card.

We make no payout in a currency, and the balance carries over, when:

• The payable amount is zero or less, because refunds and chargebacks outweigh sales. Later sales cover the debt first.
• It is below the currency's minimum: 10 in the currency's main unit, such as €10.00, unless we set another.
• A payout in the currency is still open.
• Payouts are held, because the store is suspended or the merchant profile is not approved.

Amounts are in minor units of the payout's currency_code:

We create payouts on the store's payout_schedule, which is daily, weekly or monthly. Weekly is the default. The periods follow UTC: a day, a week from Monday, or a calendar month. In each period, we create one payout for each currency as soon as its payable amount reaches the minimum.

curl -X PATCH "https://api.coritan.com/api/v1/orgs/acme/commerce/store" \
  -H "X-API-Key: $ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"settings": {"payout_schedule": "monthly"}}'

Changing it takes commerce.store:write or the Admin role, and another word answers 422. A payout you ask for counts as the period's payout for its currency, so the schedule creates the next one in the next period.

POST /commerce/payouts asks for the payable balance in one currency now, instead of waiting for the schedule:

curl -X POST "https://api.coritan.com/api/v1/orgs/acme/commerce/payouts" \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Idempotency-Key: payout-eur-2026-09-26" \
  -H "Content-Type: application/json" \
  -d '{"currency_code": "EUR"}'

The answer is 201 with the payout, which is awaiting_approval. When there is nothing to pay, the answer is 409, with the reason as its error: nothing_payable, below_minimum, payout_open or held. It also gives the currency_code, the payable amount and the minimum, and your balance stays as it is.

The organization can ask 10 times an hour, retries included. Beyond that, the answer is 429 with rate_limited and a Retry-After of 3,600 seconds.

An optional Idempotency-Key header of up to 128 characters makes a retry safe. A retry with the same key within 24 hours gets the first answer back and creates nothing, and the same key with another currency answers 409 with idempotency_key_reused. A refused request keeps no key, so you can ask again later with the same one.

GET /commerce/payouts lists the store's payouts newest first, with count, filtered by status and currency_code. status=open finds both open statuses. A page holds up to 200 payouts, and 50 by default.

Each payout also has its payout_method, the trigger that created it (schedule, merchant for you, or staff), and period_start and period_end, which are the time of its oldest row and the time we created it. released_at says when a declined or cancelled payout gave its rows back.

The list's summary shows your schedule, and in balances, what each currency could pay now:

{
  "schedule": "weekly",
  "balances": [
    {"currency_code": "EUR", "payable": 184250, "minimum": 1000, "open_payout_id": null}
  ]
}

open_payout_id names a payout in the currency that is still open.

GET /commerce/payouts/{payout_id} answers the payout with the ledger entries it holds, oldest first, and entries_count. A page holds 100 entries by default and up to 200, set with limit and offset.

The entries are the rows the payout pays, each now paid_out with the payout's ID in payout_id, and a payout row of minus the net_amount, described as Payout #88. A declined or cancelled payout holds only its two payout rows, which cancel out: the second one gave the money back to your balance. GET /commerce/ledger shows the same rows.

data holds the payout's id, currency_code, amount, platform_fee, net_amount, status, payout_method and entry_count. livemode is always true, because test orders are never paid out. The payouts for your organization's billing send payout.created instead, without the commerce. prefix.

GET /commerce/tax-reports totals the tax the Coritan companies charged on your store's sales, from the invoices and credit notes they issued. The company that sold each order accounts for its tax, and the report shows what each one charged, for your own accounts.

curl "https://api.coritan.com/api/v1/orgs/acme/commerce/tax-reports?from=2026-07-01&to=2026-10-01&bucket=quarter&format=csv" \
  -H "X-API-Key: $ORG_API_KEY" \
  -o tax-report.csv

Dates are in UTC, and a report covers up to 400 days. Each invoice and credit note counts in the period it was issued in: an invoice adds to the tax charged, and a credit note to the tax credited. Test orders never count.

Each row is one Coritan company, period, place, tax code, rate and currency. The place is where the tax is owed: a country, a state or province, and a postal prefix. Sales that owed no tax appear too, placed at the order's shipping address, or at its billing address when it has none. A line taxed by two places, such as a state and a county, counts under each.

The JSON answer has the rows, their columns in order, and totals for each Coritan company and currency. A total counts each taxed amount once, however many places taxed it, and its tax is the sum of its rows. Amounts are in minor units, and we never convert them or add them across currencies.

With format=csv, the answer is a file named like tax-report-acme-2026-07-01-2026-10-01.csv. It has a header line and one line per row, without the totals, and its amounts are in the currency's main unit, such as 19.99. We put a ' in front of any text that a spreadsheet would read as a formula.

Each payout appears in GET /commerce/payouts, and the rows it pays in GET /commerce/payouts/{payout_id}. Once our staff have sent it, it is completed, and commerce.payout.paid reaches your webhooks.

409 with nothing_payable

Refunds and chargebacks have taken the balance to zero or below, or no sale has become available yet. Later sales cover the debt first.

409 with below_minimum

The payable amount is below the minimum for the currency. Ask again once more sales have become available.

409 with payout_open

A payout in this currency is waiting to be sent. The list's summary names it in open_payout_id.

409 with held

The store is suspended, or its merchant profile is not approved. GET /commerce/store shows the store's status and the profile's status under merchant.

409 with too_large

The payout is larger than one payout can hold, and our staff split it by hand. Ask support.

403 with people_only

No API key can ask for a payout. Ask with an owner's or admin's token.

429 with rate_limited

The organization asked for more than 10 payouts in an hour. Wait for the time in Retry-After.

422 from the tax report

from or to is missing or is not a date, to does not come after from, or the report is longer than 400 days. The message says which.

A payout stays processing with outcome_unknown

The provider did not answer when we sent it. Our staff check with the provider, then complete the payout, or cancel it and return its rows to your balance.

• Sell with the Commerce API
• Answer disputes on store orders
• Track your payouts
• Receive organization webhooks