Run wholesale billing for a month
Módulo Platform
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`.
- Requiere la capacidad org.billing.manage.
- Alcances de OAuth: org.
- Envía el encabezado Idempotency-Key. Una repetición con la misma clave devuelve la respuesta original.
- Estados de error: 400, 401, 409, 422, 429. Los errores son detalles de problema RFC 9457.
Cuerpo de la solicitud: WholesaleBillingRequest
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| period_start | string (date) | Sí | First day of the month to bill. |
{
"period_start": "2026-10-08"
}Respuesta 201: WholesaleStatement
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| id | string (uuid) | Sí | Identifier of the wholesale statement. |
| org_id | string (uuid) | Sí | Identifier of the owning organization, derived from the parent row and never accepted from the caller. |
| created_at | string (date-time) | Sí | When the row was created. |
| created_by | string (uuid) | null | Sí | Identifier of the person who created the row. |
| updated_at | string (date-time) | Sí | When the row was last updated. |
| updated_by | string (uuid) | null | Sí | Identifier of the person who last updated the row. |
| period_start | string (date) | Sí | First day of the month billed. |
| currency_code | string | Sí | Currency of the partner agreement.Restricciones: pattern ^[A-Z]{3}$ |
| wholesale_discount_bps | integer | Sí | Discount in basis points when the statement ran; agreements default to 3000, the 30 percent of ADR 0035.Restricciones: range 0 to any |
| client_count | integer | Sí | Client orgs on the statement.Restricciones: range 0 to any |
| list_total_minor | integer | null | Sí | Sum of priced list prices in minor units; null only while a statement has no priced line.Restricciones: range 0 to any |
| wholesale_total_minor | integer | null | Sí | What the partner owes, in minor units; null only while a statement has no priced line.Restricciones: range 0 to any |
| unpriced_count | integer | Sí | Lines whose plan is unpriced in the currency.Restricciones: 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
}Ejemplos de código
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"}'