# Reports and statements

> Reconcile each payout to your sellers, declare your commission, and hand each seller a yearly statement in your brand.

Your accountant matches each payout to your sellers with your bank or operator statement, and
declares your commission. Ask Wajub for a **report**, under **Sync, Reports** or with
`POST /sync/reports`: it is built in the background, usually within a minute or two, then

- `report.ready` reaches your endpoints;
- the member who asked in the Dashboard gets an e-mail, with a link to the Dashboard, never to the
  file;
- it is kept **30 days**, and downloaded through a link **signed for 15 minutes**.

## The five reports

| `type`                  | Formats       | Contains                                                                                                                                                                          |
| ----------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payout_reconciliation` | `csv`, `xlsx` | Every element of every payout to every seller, one row each                                                                                                                       |
| `seller_summary`        | `csv`, `xlsx` | Per seller and currency: sales, refunds, lost disputes, commission taken, returned and net, paid out; and, as it is built, what they are owed, what is withheld, their cover debt |
| `platform_commission`   | `csv`, `xlsx` | Your commission per month, seller and currency: taken, returned, net                                                                                                              |
| `relay_dues`            | `csv`, `xlsx` | Your Relay sellers' dues: their state, and the payout that paid them                                                                                                              |
| `seller_statement`      | `pdf`         | One Lite or Relay seller's statement for the period                                                                                                                               |

| Rule           |                                                                                                                                                                                  |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Period         | UTC days, from `period_start` at midnight to the end of `period_end`, **366 days at most**                                                                                       |
| Amounts        | Major units with their currency, as exact decimals with the currency's decimals (`19000.00`, `-286.50`). A negative amount stays a number                                        |
| Dates          | ISO 8601 UTC with offset (`2026-11-06T07:00:00+00:00`); a day alone as `YYYY-MM-DD`                                                                                              |
| Stable columns | `format_version` (today `1`) is in the report **and in the file's name**: `payout_reconciliation_v1_2026-11-01_2026-11-30.csv`. A column never changes meaning within a version  |
| Personal data  | The seller's name only. No e-mail address, no phone number, no identity document                                                                                                 |
| CSV            | UTF-8 with BOM, comma, RFC 4180 quoting, column names on the first line. A text cell starting with `=`, `+`, `-` or `@` gets a leading apostrophe, so it never runs as a formula |
| XLSX           | One sheet, "Report", bold frozen header; text as strings, never formulas; amounts and counts as numbers. Past 1 048 576 rows it fails with `too_many_rows`: ask for CSV          |
| Test key       | Built from test data (`rpt_test_…`), with `report.ready` in test                                                                                                                 |
| Waiting        | 5 reports at most at a time, being built or queued. A report still `pending` can be cancelled under **Sync, Reports**: it turns `failed` with `cancelled` and frees its place    |

## Ask for one

```bash title="November's payouts, as CSV"
curl https://api.wajub.com/sync/reports \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -d '{"type":"payout_reconciliation","format":"csv","period_start":"2026-11-01","period_end":"2026-11-30"}'
```

| Field                        |                                                                                                                                                           |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`                       | Required: one of the five above                                                                                                                           |
| `period_start`, `period_end` | Required, `YYYY-MM-DD`, UTC; `period_end` on or after `period_start`                                                                                      |
| `format`                     | `csv` or `xlsx` for an export, required; `pdf` for a statement, the default                                                                               |
| `account`                    | The seller's `acc_…`, required for `seller_statement`: a `lite` or `relay` account of yours, in the same environment                                      |
| `locale`                     | The language of a `seller_statement`: `en`, the default, or `fr`. Exports are the same in both: their columns never change. Any other value answers `422` |

The answer is `202` with the `report`, `pending`. Called with your own key, never with `X-Sync`.

| `error_code`              | Status | When                                                                             |
| ------------------------- | ------ | -------------------------------------------------------------------------------- |
| `format_not_available`    | `422`  | `pdf` for an export, `csv` or `xlsx` for a statement, or no format for an export |
| `period_too_long`         | `422`  | More than 366 days                                                               |
| `account_required`        | `422`  | `seller_statement` without `account`                                             |
| `statement_not_available` | `400`  | A statement for a `direct` account: they have their own Wajub reports            |
| `too_many_reports`        | `429`  | 5 reports already waiting                                                        |
|                           | `404`  | `account` unknown, another platform's, or of the other environment               |

## Download it

When `report.ready` arrives, `GET /sync/reports/{id}` returns the report with `url`, a link signed
for 15 minutes (`url_expires_at`). Call it again for a fresh one, and never store the link.

| `status`              |                                                                                                                                                                                                                             |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pending`, `building` | On its way. A year of a large platform can stay `building` a few minutes: you still get one file, and one `report.ready`                                                                                                    |
| `ready`               | `url`, `row_count` (exports, header not counted), `file_name`, `file_size` in bytes, `completed_at`, `expires_at`                                                                                                           |
| `failed`              | `failure_reason`: `too_many_rows` (an XLSX past Excel's last row, ask for CSV), `build_failed` (three attempts failed, ask again) or `cancelled` (cancelled in the Dashboard). A failed report no longer counts among the 5 |
| `expired`             | The file was deleted after 30 days                                                                                                                                                                                          |

`report.ready` is sent once per report. It is a [Sync lifecycle delivery](https://docs.wajub.com/developer-tools/webhooks/events#sync-lifecycle-deliveries):
list it by name. Its body is `event`, `sandbox`, `timestamp` and the `report`, without a link. A
report that failed sends nothing: read it with `GET`.

## The columns of `payout_reconciliation`

One row per **element** of each payout Wajub made to your sellers. A payout is in the period by its
**value date**, or, not paid yet, by its creation. &#x2A;*The `amount` of a payout's rows add up to its
`payout_amount`, to the centime.** The payouts follow each other in that same order, by value date
(or creation), then payout by payout, and a payout's rows keep their order (`line`).

| Column                                             |                                                                              |
| -------------------------------------------------- | ---------------------------------------------------------------------------- |
| `payout_id`, `payout_status`                       | `po_…`; `pending`, `processing`, `succeeded`, `failed` or `cancelled`        |
| `payout_created_at`, `payout_value_date`           | Creation; value date, empty until it succeeded                               |
| `operator_reference`                               | The operator's reference, the one on your statement                          |
| `payout_amount`, `currency`                        | What the payout paid                                                         |
| `account`, `account_type`, `seller_name`           | The seller                                                                   |
| `line`, `element`, `amount`                        | The row's rank in the payout, what it is, and its signed share of the payout |
| `payment`, `refund`, `dispute`                     | The public ids concerned                                                     |
| `occurred_at`                                      | When the element happened                                                    |
| `escrow_amount`, `hold_status`, `hold_released_at` | The [hold until delivery](https://docs.wajub.com/sync/holds) of the sale concerned                 |

| `element`                                            | Sign  |                                                                                                                            |
| ---------------------------------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------- |
| `sale`, `share`                                      | +     | A sale, or a part of a shared payment, gross                                                                               |
| `wajub_fee`                                          | −     | Wajub's fee on it                                                                                                          |
| `commission`                                         | −     | Your commission                                                                                                            |
| `refund`, `dispute`                                  | −     | What a refund or a lost dispute took back                                                                                  |
| `commission_returned`                                | +     | Your commission given back with it                                                                                         |
| `cover`, `recovery`                                  | + / − | What you covered for the seller, and what you took back                                                                    |
| `debt`                                               | −     | A Relay seller's debt, netted                                                                                              |
| `payout_fee`                                         | −     | The payout's own fee                                                                                                       |
| `reserve_brought_forward`, `balance_brought_forward` | +     | What the previous payout left                                                                                              |
| `reserve_held`, `balance_carried_forward`            | −     | What this payout leaves for later                                                                                          |
| `adjustment`                                         | ±     | A balance movement no other element explains                                                                               |
| `rounding`                                           | ±     | A centime's difference between gross, fees, commission and what was paid                                                   |
| `escrow_released`                                    | 0     | A held Lite sale released since the previous payout, paid through `balance_brought_forward`; `escrow_amount` says how much |
| `unreported`                                         | +     | A payout whose detail was never written: one row of its whole amount                                                       |

The other exports list their columns in the same way, in the file's header: `seller_summary`
(`balance_due`, `withheld` and `cover_debt` are as the report is built, `as_of`, and empty for a
`direct` seller; its last column, `card_reserve`, is what the seller's card sales keep against
chargebacks, included in `withheld`), `platform_commission` (one row per month, seller and currency) and `relay_dues`
(one due per row, `outstanding` as `GET /accounts/{id}/dues` reads it).

## Your sellers' statements

A `seller_statement` is a PDF for one Lite or Relay seller, **in your brand**: per currency, what was
collected for them, refunded, lost to disputes, kept as your commission and paid to them, then month
by month. It says it is a record for their accounts, not a tax return; Wajub's fees are in each
payout's detail. Through the API it is in English unless you ask for `locale: fr`; from the
Dashboard, in the language of the member who asks.

A dispute the merchant accepted is counted once, among the lost disputes, never also among the
refunds: in the statement, in `seller_summary` and in the seller's figures. Ordinary refunds stay
under refunds.

| Who                                   | Where                                                                                                                                     |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| You                                   | The seller's page in **Sync, Accounts**, one button per year since they connected; or `POST /sync/reports` with any period up to 366 days |
| A Lite seller                         | Their portal, under Payouts                                                                                                               |
| A Lite or Relay seller, in your pages | The `payouts` [component](https://docs.wajub.com/sync/embedded-components) shows their statements by year                                                       |

- [Analytics](https://docs.wajub.com/sync/analytics): The same ledger, as figures over a period.
- [What a payout settles](https://docs.wajub.com/sync/payouts#what-a-payout-settles): The lines of each payout, in the API.
- [Ask for a report](https://docs.wajub.com/api/subaccounts/create-report): The endpoint specification.
