Run wholesale billing for a month
Platform module
POST/wholesale-statements/runwholesaleStatements.run
Records the partner's statement for a month (app.run_wholesale_billing, org.billing.manage): every client org at its plan's list price less the agreed discount. A month is billed once (wholesale_statement_exists: 422); a partner without an agreement refuses (partner_agreement_missing: 422). Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.
- Requires the capability org.billing.manage.
- OAuth scopes: org.
- Send an Idempotency-Key header. A replay with the same key returns the original response.
- Error statuses: 400, 401, 409, 422, 429. Errors are RFC 9457 problem details.
Request body: WholesaleBillingRequest
| Field | Type | Required | Description |
|---|---|---|---|
| period_start | string (date) | Yes | First day of the month to bill. |
{
"period_start": "2026-10-08"
}Response 201: WholesaleStatement
| Field | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | Identifier of the wholesale statement. |
| org_id | string (uuid) | Yes | Identifier of the owning organization, derived from the parent row and never accepted from the caller. |
| created_at | string (date-time) | Yes | When the row was created. |
| created_by | string (uuid) | null | Yes | Identifier of the person who created the row. |
| updated_at | string (date-time) | Yes | When the row was last updated. |
| updated_by | string (uuid) | null | Yes | Identifier of the person who last updated the row. |
| period_start | string (date) | Yes | First day of the month billed. |
| currency_code | string | Yes | Currency of the partner agreement.Constraints: pattern ^[A-Z]{3}$ |
| wholesale_discount_bps | integer | Yes | Discount in basis points when the statement ran; agreements default to 3000, the 30 percent of ADR 0035.Constraints: range 0 to any |
| client_count | integer | Yes | Client orgs on the statement.Constraints: range 0 to any |
| list_total_minor | integer | null | Yes | Sum of priced list prices in minor units; null only while a statement has no priced line.Constraints: range 0 to any |
| wholesale_total_minor | integer | null | Yes | What the partner owes, in minor units; null only while a statement has no priced line.Constraints: range 0 to any |
| unpriced_count | integer | Yes | Lines whose plan is unpriced in the currency.Constraints: range 0 to any |
{
"id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
"org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
"created_at": "2026-10-08T14:30:00Z",
"created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
"updated_at": "2026-10-08T14:30:00Z",
"updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
"period_start": "2026-10-08",
"currency_code": "USD",
"wholesale_discount_bps": 3000,
"client_count": 3,
"list_total_minor": 44700,
"wholesale_total_minor": 31290,
"unpriced_count": 0
}Code samples
curl -X POST "$XOS_BASE_URL/wholesale-statements/run" \
-H "Authorization: Bearer $XOS_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"period_start":"2026-10-08"}'const { data } = await xos.wholesaleStatements.run({
"period_start": "2026-10-08"
});response = xos.wholesale_statements.run({"period_start": "2026-10-08"})xos wholesale-statements run --data '{"period_start":"2026-10-08"}'