{"openapi":"3.1.0","info":{"title":"AffiliateLauncher Public API","version":"1.0.0","description":"# Public API\r\n\r\nMachine-to-machine REST at **`/api/v1`**. Requires **Plus** or **MLM** (`Starter` returns 403). Get your company **API key** under **Settings → Company Config → API & integrations** (platform admins: **Client Listing**). Rotating the key invalidates the previous one immediately.\r\n\r\nThe same API key works for **REST** and **MCP** (Streamable HTTP at **`/mcp`**). Company Config shows **API Base URL** and **MCP URL** on paid tiers. Example Cursor MCP config: `docs/mcp-cursor-example.json` in the repo.\r\n\r\n## Authentication\r\n\r\nBearer token on every request:\r\n\r\n```http\r\nAuthorization: Bearer YOUR_API_KEY\r\n```\r\n\r\n## Response format\r\n\r\n**Success:** `{ \"data\": ..., \"meta\": { \"page\", \"pageSize\", \"totalRows\" } }`  \r\n**Errors:** `{ \"errors\": [{ \"code\", \"message\", \"field?\" }] }` — 401 (bad key), 403 (inactive or wrong tier), 422 (validation), 429 (`rate_limited` — too many requests; see Rate limits).\r\n\r\n**Tax ID:** never on GET; check `hasTaxIdOnFile`. Set via **`PUT /api/v1/distributors/{id}/tax-id`** only.\r\n\r\n## Rate limits\r\n\r\nShared across **REST** (`/api/v1`) and **MCP** (`/mcp`) for the same company API key:\r\n\r\n- **~600 requests per 60 seconds** per company (after successful auth).\r\n- Failed auth attempts are limited by client IP (**~60 per 60 seconds**).\r\n\r\nWhen exceeded, the API returns **429** with `Retry-After: 60` and `{ \"errors\": [{ \"code\": \"rate_limited\", \"message\": \"...\" }] }` (MCP uses `{ \"error\": \"...\" }` with the same status and header).\r\n\r\n## Paging\r\n\r\n- **Lists** (distributors, sales, ledger, etc.): `page` + `pageSize` query params; `meta.totalRows` in the response.\r\n- **Commission run results** (MLM): cursor-based — pass `cursor` from `meta.nextCursor` (default `pageSize` 500, max 2000).\r\n\r\n## Access by tier\r\n\r\n**Plus:** distributors, sales, ledger, real-time commission plans. **MLM:** same plus ranks (read-only) and commission runs. Per-route requirements are in the operations below.\r\n\r\n## Commission run workflow (MLM only)\r\n\r\n1. `POST /api/v1/commission-runs` — `{ \"period\": 202606, \"runType\": \"monthly\" }` (YYYYMM; YYYYMMDD for rebate) → `{ \"runId\" }`\r\n2. Poll `GET .../{runId}/status` while `isRunning` (use `nextPollAfterSeconds`)\r\n3. Page results: `GET .../results/detail|history|orders-paid|returns-processed` with `cursor`\r\n4. Optional CSV: `GET .../exports/commission-detail` (see OpenAPI for other keys)\r\n5. `POST .../{runId}/finalize` — post earnings to ledger\r\n6. `POST .../{runId}/rollback` — when the period allows\r\n\r\n## Resources\r\n\r\n- `GET/POST/PUT /api/v1/distributors` — affiliates; `PUT …/tax-id` for tax id only\r\n- `GET/PUT/DELETE /api/v1/sales` — orders\r\n- `GET/POST/PUT /api/v1/commission-plans` — real-time plans (Plus)\r\n- `GET /api/v1/ranks` — MLM rank codes (read-only)\r\n- `GET/POST /api/v1/commission-runs` + status, results, exports, finalize, rollback (MLM)\r\n- `GET/POST /api/v1/ledger/entries` — search and manual adjustments\r\n\r\n## Scope notes\r\n\r\n- Validation and side effects match the admin UI (accrual, registration email, audit log).\r\n- Deactivating a real-time plan fails while distributors are assigned.\r\n- Rank definitions are edited in the MLM plan editor, not via API.\r\n\r\n## MCP (supplementary)\r\n\r\nREST (`/api/v1`) is the canonical contract — use **`GET /api/v1/openapi.json`** for full schemas. MCP at **`/mcp`** uses the same Bearer API key and is optional for agent clients (e.g. Cursor):\r\n\r\n- **get_company_context** — company name, tier, capabilities, discovery URLs (call first)\r\n- **find_distributor** — resolve affiliate by id, email, or name\r\n- **list_distributors** — paged affiliate roster\r\n- **get_sale** — order/sale summary by order number or sale id\r\n- **get_commission_overview** — Plus plans or MLM run status\r\n- **get_distributor_earnings** — ledger balance and recent entries\r\n- **explain_workflow** — safe step-by-step guidance (`commission_run`, `payout`, `enroll_affiliate`, `create_distributor_via_api`)\r\n- **search_help** / **get_help_topic** — product Help Center (client-scoped terminology)\r\n\r\nContract: `GET /api/v1/openapi.json` · AI index: `GET /api/v1/llms.txt` · Site index: `GET /llms.txt`\r\n\r\n## Agent signup (no Shopify, no browser)\r\n\r\nWhen Stripe SaaS is enabled on the deployment, agents can create a company without the UI:\r\n\r\n1. `POST /BillingSaas/CreateTenant` with `email`, `password`, `clientName` (optional `planId`: `core` or `network`) → `apiKey`, `clientId`\r\n2. Pay via `POST /BillingSaas/MachinePay` with a Stripe Machine Payments Shared Payment Token (or open the returned Checkout URL as a human)\r\n3. Call `/api/v1` and `/mcp` with `Authorization: Bearer <apiKey>`\r\n\r\nUnpaid / Starter companies cannot use the Public API or MCP. See live **`GET /llms.txt`** for the curl-level sequence."},"servers":[{"url":"/api/v1"}],"tags":[{"name":"Commission plans","description":"**Real-time commission plans** for **Plus** companies (real-time commission) — **not** MLM commission plans. **MLM** companies use **Commission runs** for monthly/rebate processing instead; the MLM plan editor is not exposed via API."},{"name":"Ranks","description":"Read-only rank codes from the live **MLM** commission plan. Rank definitions are edited in the plan editor, not via API."},{"name":"Commission runs","description":"Monthly and rebate commission processing for **MLM** companies. **Plus** and **Starter** receive 403 on these routes."},{"name":"Distributors","description":"Affiliate (distributor) list, CRUD, tax ID, terminate, and reactivate. Available on **Plus** and **MLM**."},{"name":"Sales","description":"Order and sale records. Available on **Plus** and **MLM**."},{"name":"Ledger","description":"Commission ledger search and manual adjustments. Available on **Plus** and **MLM**."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Company API key (GUID). Obtain or rotate under Company settings → API Key. Not a user JWT."}},"schemas":{"CommissionPlan":{"type":"object","properties":{"planId":{"type":"string","description":"Plan GUID.","example":"550e8400-e29b-41d4-a716-446655440000"},"clientId":{"type":"integer","description":"CaaS client id."},"name":{"type":"string","description":"Plan display name.","example":"Standard 25%"},"percentRate":{"type":"number","description":"Commission percent (e.g. 25 for 25%)."},"basisType":{"type":"string","enum":["TotalPrice","TotalVolume","TotalQualifyingVolume"],"description":"Volume/price basis for the plan."},"isActive":{"type":"boolean","description":"Whether the plan can be assigned."},"isDefault":{"type":"boolean","description":"Default plan for new affiliates."},"createdAtUtc":{"type":"string","description":"Created timestamp (UTC ISO)."}},"required":["planId","name","percentRate","basisType","isActive"],"additionalProperties":false},"ErrorItem":{"type":"object","properties":{"code":{"type":"string","description":"Machine code, e.g. validation, unauthorized, forbidden."},"message":{"type":"string","description":"Human-readable message (aligned with admin UI errors)."},"field":{"type":"string","description":"Optional field name related to the error."}},"required":["code","message"],"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorItem"}}},"required":["errors"],"additionalProperties":false},"CommissionPlanWriteBody":{"type":"object","properties":{"planId":{"type":"string","format":"uuid","description":"Plan id; omit on POST to generate a new GUID."},"planName":{"type":"string","description":"Plan name (alias of name)."},"name":{"type":"string","description":"Plan name."},"basisPercent":{"type":"number","description":"Commission percent (alias of percentRate)."},"percentRate":{"type":"number","description":"Commission percent."},"basisType":{"type":"string","enum":["TotalPrice","TotalVolume","TotalQualifyingVolume"],"description":"Basis type."},"isActive":{"type":"boolean","description":"Active flag."}},"additionalProperties":false},"DeactivatedPlan":{"type":"object","properties":{"deactivated":{"type":"boolean","enum":[true],"description":"Plan was deactivated."}},"required":["deactivated"],"additionalProperties":false},"SetDefaultPlan":{"type":"object","properties":{"setDefault":{"type":"boolean","enum":[true],"description":"Plan was set as default."}},"required":["setDefault"],"additionalProperties":false},"Rank":{"type":"object","properties":{"rankCode":{"type":"string","description":"Rank code (unique per client).","example":"10"},"rankDesc":{"type":"string","description":"Rank display name.","example":"Consultant"},"isBreakawayTitle":{"type":"boolean","description":"Breakaway title flag (network clients)."},"ordering":{"type":"integer","description":"Sort order (lower = earlier)."}},"required":["rankCode","rankDesc"],"additionalProperties":false},"DistributorListItem":{"type":"object","properties":{"id":{"type":"string","description":"Affiliate id.","example":"1001"},"name":{"type":"string","description":"Display name (person or business).","example":"Jane Doe"},"email":{"type":"string","description":"Primary email.","example":"jane@example.com"},"phone":{"type":"string","description":"Phone number."},"isActive":{"type":"boolean","description":"Whether the affiliate is active."},"sponsor":{"type":["string","null"],"description":"Sponsor affiliate id (network clients)."},"enroller":{"type":["string","null"],"description":"Enroller affiliate id (network clients)."},"rankCode":{"type":["string","null"],"description":"Current rank code."},"rankName":{"type":["string","null"],"description":"Formatted rank label."},"appDate":{"type":"string","description":"Application date (UTC ISO)."},"appDateFormatted":{"type":"string","description":"Application date (US display)."}},"required":["id","name","email","isActive"],"additionalProperties":false},"ListMeta":{"type":"object","properties":{"page":{"type":"integer","description":"Current page (1-based).","example":1},"pageSize":{"type":"integer","description":"Rows per page.","example":20},"hasNextPage":{"type":"boolean","description":"True when another page of results exists.","example":false},"totalRows":{"type":"integer","description":"Deprecated. Omitted when using has-next pagination.","example":42}},"required":["page","pageSize","hasNextPage"],"additionalProperties":false},"DistributorDetail":{"type":"object","properties":{"clientId":{"type":"integer","description":"CaaS client id."},"distributorId":{"type":"string","description":"Affiliate id.","example":"1001"},"sponsor":{"type":"string","description":"Sponsor affiliate id."},"enroller":{"type":"string","description":"Enroller affiliate id."},"rankCode":{"type":"string","description":"Rank code."},"appDate":{"type":["string","null"],"description":"Application date (UTC)."},"isActive":{"type":"boolean","description":"Active flag."},"isSuspended":{"type":"boolean","description":"Suspended flag."},"firstName":{"type":"string","description":"First name (individual)."},"lastName":{"type":"string","description":"Last name (individual)."},"corpEntity":{"type":"boolean","description":"True when the affiliate is a business entity."},"businessName":{"type":"string","description":"Business name when corpEntity is true."},"zip":{"type":"string","description":"Postal code."},"email":{"type":"string","description":"Primary email."},"street1":{"type":"string","description":"Address line 1."},"street2":{"type":"string","description":"Address line 2."},"city":{"type":"string","description":"City."},"stateProvince":{"type":"string","description":"State or province."},"country":{"type":"string","description":"ISO country code."},"phone":{"type":"string","description":"Phone number."},"replicatedSiteName":{"type":"string","description":"Replicated site / URL slug."},"dateOfBirth":{"type":["string","null"],"description":"Date of birth (UTC)."},"payPalId":{"type":"string","description":"PayPal payout recipient id."},"greeting":{"type":"string","description":"Public greeting text."},"simpleCommPlanId":{"type":["string","null"],"description":"Assigned commission plan id."},"simpleCommPlanName":{"type":["string","null"],"description":"Assigned commission plan name."},"hasTaxIdOnFile":{"type":"boolean","description":"True when a tax id is stored. The value is never returned; use PUT …/tax-id to set."},"distributorName":{"type":"string","description":"Resolved display name."}},"required":["distributorId","email"],"additionalProperties":false},"DistributorWriteBody":{"type":"object","properties":{"distributorId":{"type":"string","description":"Affiliate id (optional on create)."},"firstName":{"type":"string","description":"First name."},"lastName":{"type":"string","description":"Last name."},"corpEntity":{"type":"boolean","description":"Business entity flag."},"businessName":{"type":"string","description":"Business name."},"email":{"type":"string","description":"Email address."},"street1":{"type":"string","description":"Address line 1."},"street2":{"type":"string","description":"Address line 2."},"city":{"type":"string","description":"City."},"stateProvince":{"type":"string","description":"State or province."},"country":{"type":"string","description":"Country code."},"zip":{"type":"string","description":"Postal code."},"phone":{"type":"string","description":"Phone."},"sponsor":{"type":"string","description":"Sponsor id."},"enroller":{"type":"string","description":"Enroller id."},"rankCode":{"type":"string","description":"Rank code."},"appDate":{"type":"string","description":"Application date."},"dateOfBirth":{"type":["string","null"],"description":"Date of birth."},"replicatedSiteName":{"type":"string","description":"Replicated site name."},"simpleCommPlanId":{"type":["string","null"],"description":"Simple commission plan id."},"payPalId":{"type":"string","description":"PayPal recipient id."},"greeting":{"type":"string","description":"Greeting."}},"additionalProperties":false},"DistributorPatchBody":{"type":"object","properties":{"distributorId":{"type":"string","description":"Affiliate id (optional on create)."},"firstName":{"type":"string","description":"First name."},"lastName":{"type":"string","description":"Last name."},"corpEntity":{"type":"boolean","description":"Business entity flag."},"businessName":{"type":"string","description":"Business name."},"email":{"type":"string","description":"Email address."},"street1":{"type":"string","description":"Address line 1."},"street2":{"type":"string","description":"Address line 2."},"city":{"type":"string","description":"City."},"stateProvince":{"type":"string","description":"State or province."},"country":{"type":"string","description":"Country code."},"zip":{"type":"string","description":"Postal code."},"phone":{"type":"string","description":"Phone."},"sponsor":{"type":"string","description":"Sponsor id."},"enroller":{"type":"string","description":"Enroller id."},"rankCode":{"type":"string","description":"Rank code."},"appDate":{"type":"string","description":"Application date."},"dateOfBirth":{"type":["string","null"],"description":"Date of birth."},"replicatedSiteName":{"type":"string","description":"Replicated site name."},"simpleCommPlanId":{"type":["string","null"],"description":"Simple commission plan id."},"payPalId":{"type":"string","description":"PayPal recipient id."},"greeting":{"type":"string","description":"Greeting."}},"additionalProperties":false},"PublicOperationResult":{"type":"object","properties":{"updated":{"type":"boolean","description":"True when the operation completed."},"errorMessage":{"type":"string","description":"Non-empty when the operation failed."}},"additionalProperties":false},"DistributorTaxIdBody":{"type":"object","properties":{"taxId":{"type":"string","description":"Tax identifier (write-only; stored encrypted; never returned on GET).","example":"123456789"}},"required":["taxId"],"additionalProperties":false},"SaleListItem":{"type":"object","properties":{"resultingOrdno":{"type":"string","description":"Human-facing display order number (Shopify: integration prefix stripped, e.g. `1040`). Not the path/lookup key."},"createdAt":{"type":"string","description":"Order created timestamp."},"processedDate":{"type":["string","null"],"description":"Last processed timestamp."},"integrationOrderId":{"type":"string","description":"Canonical sale id. For Shopify: `{integrationId}-{shopifyNumericId}` (e.g. `7-18695943029040`). Same value as path `saleId` / detail `orderNumber`."},"alternateOrderNumber":{"type":"string","description":"Prefixed readable Shopify order number: `{integrationId}-{order_number|name}` (e.g. `7-1040`). Prefer `resultingOrdno` for display."},"integrationType":{"type":"string","description":"Source integration (e.g. Shopify)."},"distributorId":{"type":"string","description":"Affiliate id on the order."},"distributorName":{"type":"string","description":"Affiliate display name."},"email":{"type":"string","description":"Customer email on the order."},"name":{"type":"string","description":"Customer name on the order."},"totalVolume":{"type":"number","description":"Commission volume."},"totalQualifyingVolume":{"type":"number","description":"Net qualifying volume."},"orderTotalQualifyingVolume":{"type":"number","description":"Gross order qualifying volume."},"simpleCommPlanId":{"type":"string","description":"Applied Simple plan id."},"simpleCommPlanName":{"type":"string","description":"Applied Simple plan name."},"simpleCommIsPaid":{"type":"boolean","description":"Commission paid flag."},"simpleCommCommissionAmount":{"type":"number","description":"Commission amount."},"canRepull":{"type":"boolean","description":"Whether the order can be repulled from integration."},"canDelete":{"type":"boolean","description":"Whether the order can be removed."}},"additionalProperties":false},"SaleOrderItem":{"type":"object","properties":{"productCode":{"type":"string","description":"Product or SKU code."},"description":{"type":"string","description":"Line description."},"qty":{"type":"number","description":"Quantity."},"priceEach":{"type":"number","description":"Unit price."},"volumeEach":{"type":"number","description":"Unit commission volume."},"qualifyingVolumeEach":{"type":"number","description":"Unit qualifying volume."}},"additionalProperties":false},"SaleReturn":{"type":"object","properties":{"returnCode":{"type":"string","description":"Return identifier."},"qualifyingVolume":{"type":"number","description":"Return qualifying volume."},"volume":{"type":"number","description":"Return volume."},"returnDateUtc":{"type":"string","description":"Return date (UTC)."}},"additionalProperties":false},"SaleDetail":{"type":"object","properties":{"orderNumber":{"type":"string","description":"Canonical sale id (same as `integrationOrderId` and path `saleId`). For Shopify: `{integrationId}-{shopifyNumericId}` e.g. `7-18695943029040`."},"integrationOrderId":{"type":"string","description":"Canonical sale id (same as `orderNumber`). For Shopify: `{integrationId}-{shopifyNumericId}` e.g. `7-18695943029040`."},"displayOrderNumber":{"type":["string","null"],"description":"Human-facing display order number (Shopify: integration prefix stripped, e.g. `1040`). Same role as list `resultingOrdno`."},"alternateOrderNumber":{"type":["string","null"],"description":"Prefixed readable Shopify order number: `{integrationId}-{order_number|name}` (e.g. `7-1040`). Prefer `displayOrderNumber` for display."},"distributorId":{"type":"string","description":"Affiliate id."},"distributorName":{"type":"string","description":"Affiliate name."},"orderDateUtc":{"type":"string","description":"Order date (UTC)."},"updateDateUtc":{"type":"string","description":"Last update (UTC)."},"totalPrice":{"type":"number","description":"Order total price."},"totalVolume":{"type":"number","description":"Total commission volume."},"totalQualifyingVolume":{"type":"number","description":"Total qualifying volume."},"orderType":{"type":["string","null"],"description":"Order type label."},"email":{"type":["string","null"],"description":"Customer email."},"nameOnOrder":{"type":["string","null"],"description":"Customer name."},"integrationType":{"type":"string","description":"Integration source."},"simpleCommPlanId":{"type":["string","null"],"description":"Simple plan id."},"simpleCommIsPaid":{"type":"boolean","description":"Commission paid."},"simpleCommCommissionAmount":{"type":["number","null"],"description":"Commission amount."},"simpleCommPlanName":{"type":["string","null"],"description":"Simple plan name."},"orderItems":{"type":"array","items":{"$ref":"#/components/schemas/SaleOrderItem"},"description":"Line items."},"returns":{"type":"array","items":{"$ref":"#/components/schemas/SaleReturn"},"description":"Returns on the order."}},"additionalProperties":false},"SaleReturnWrite":{"type":"object","properties":{"returnCode":{"type":"string","description":"Return identifier. When omitted on create, the server generates one."},"qualifyingVolume":{"type":"number","description":"Return qualifying volume."},"volume":{"type":"number","description":"Return volume."},"returnDateUtc":{"type":"string","description":"Return date (UTC)."},"markedForDeletion":{"type":"boolean","description":"When true, delete this return (requires returnCode)."}},"additionalProperties":false},"SaleWriteBody":{"type":"object","properties":{"isNew":{"type":"boolean","description":"True when creating a new order."},"distributorId":{"type":"string","description":"Affiliate id owning the order."},"simpleCommPlanId":{"type":["string","null"],"description":"Simple plan id."},"createdAt":{"type":"string","description":"Created timestamp."},"orderDateUtc":{"type":"string","description":"Order date (UTC)."},"nameOnOrder":{"type":"string","description":"Customer name."},"name":{"type":"string","description":"Customer name (alias)."},"email":{"type":"string","description":"Customer email."},"totalPrice":{"type":"number","description":"Order total."},"totalVolume":{"type":"number","description":"Commission volume."},"totalQualifyingVolume":{"type":"number","description":"Qualifying volume."},"orderItems":{"type":"array","items":{"$ref":"#/components/schemas/SaleOrderItem"}},"returns":{"type":"array","items":{"$ref":"#/components/schemas/SaleReturnWrite"},"description":"Returns to upsert or delete on the order. Omit returnCode to create; set markedForDeletion to remove."}},"required":["distributorId"],"additionalProperties":false},"RemovedSale":{"type":"object","properties":{"removed":{"type":"boolean","enum":[true],"description":"Sale was removed."}},"required":["removed"],"additionalProperties":false},"LedgerEntry":{"type":"object","properties":{"transactionDate":{"type":"string","description":"Transaction date/time (display or UTC)."},"transactionType":{"type":"string","description":"Ledger event type.","example":"Adjustment"},"amount":{"type":"number","description":"Amount (positive = credit, negative = debit)."},"transactionDescription":{"type":"string","description":"Description text."},"rowLookupId":{"type":"string","description":"Stable row identifier."},"lastKnownStatus":{"type":"string","description":"Payout or processing status."},"payoutType":{"type":"string","description":"Payout channel when applicable."},"paymentIsLocked":{"type":"boolean","description":"True when payment is locked."},"simpleCommIsPaid":{"type":"boolean","description":"Simple commission paid flag."}},"required":["transactionType","amount"],"additionalProperties":false},"LedgerEntryCreateBody":{"type":"object","properties":{"distributorId":{"type":"string","description":"Affiliate id.","example":"1001"},"amount":{"type":"number","description":"Adjustment amount.","example":25},"transactionType":{"type":"string","default":"Adjustment","description":"Transaction type.","example":"Adjustment"},"transactionDescription":{"type":"string","description":"Optional description.","example":"Manual bonus"}},"required":["distributorId","amount"],"additionalProperties":false},"CommissionRunStartResult":{"type":"object","properties":{"runId":{"type":"string","description":"Created run id.","example":"a1b2c3d4-..."}},"required":["runId"],"additionalProperties":false},"CommissionRunStartBody":{"type":"object","properties":{"period":{"type":"integer","description":"Period to process: YYYYMM for monthly runs, YYYYMMDD for rebate runs.","example":202606},"runType":{"type":"string","enum":["monthly","rebate"],"description":"Commission run type.","example":"monthly"}},"required":["period","runType"],"additionalProperties":false},"CommissionRun":{"type":"object","properties":{"runId":{"type":"string","description":"Run id.","example":"a1b2c3d4-..."},"runType":{"type":"string","enum":["monthly","rebate"],"description":"Commission run type.","example":"monthly"},"period":{"type":"integer","description":"Period as YYYYMM (monthly) or YYYYMMDD (rebate).","example":202606},"periodLabel":{"type":"string","description":"Human-readable period label."},"foresightStatus":{"type":"string","description":"Run status (Ready, Processing, Errored, Processing Complete, Finalized)."},"runDateUtc":{"type":"string","description":"When the run was created (UTC ISO)."},"isRunning":{"type":"boolean","description":"True when workflow is still processing."},"payoutsMade":{"type":"boolean","description":"True when payouts have been recorded."},"lastRunStateMessage":{"type":"string","description":"Last progress message."}},"required":["runId","runType","period","foresightStatus"],"additionalProperties":false},"ActiveCommissionRun":{"type":"object","properties":{"isRunning":{"type":"boolean","description":"True when any commission run is active."},"runId":{"type":"string","description":"Active run id when isRunning is true."},"runType":{"type":"string","enum":["monthly","rebate"],"description":"Commission run type.","example":"monthly"}},"required":["isRunning"],"additionalProperties":false},"CommissionRunStatus":{"type":"object","properties":{"runId":{"type":"string","description":"Run id."},"isRunning":{"type":"boolean","description":"True while the run is processing."},"isComplete":{"type":"boolean","description":"True when processing has finished."},"isInvalidRunId":{"type":"boolean","description":"True when run id was not found."},"percentComplete":{"type":"integer","description":"Progress 0–100.","example":45},"statusMessage":{"type":"string","description":"Current status text."},"errorMessage":{"type":"string","description":"Error message when failed."},"nextPollAfterSeconds":{"type":"integer","description":"Suggested seconds before polling again (5 while running, 0 when done).","example":5},"period":{"type":"integer","description":"Run period (YYYYMM or YYYYMMDD)."},"runType":{"type":"string","enum":["monthly","rebate"],"description":"Commission run type.","example":"monthly"}},"required":["isRunning","isComplete","percentComplete","nextPollAfterSeconds"],"additionalProperties":false},"CommissionDetailRow":{"type":"object","properties":{"distributorId":{"type":"string","description":"Affiliate id receiving commission."},"period":{"type":"integer","description":"YYYYMM or YYYYMMDD."},"amount":{"type":"number","description":"Commission amount."},"payCode":{"type":"string","description":"Pay code."},"rankCode":{"type":"string","description":"Rank code."},"volume":{"type":"number","description":"Volume."},"percentage":{"type":"number","description":"Percentage."},"level":{"type":"integer","description":"Genealogy level."},"fromDistributorId":{"type":"string","description":"Source affiliate id."},"fromOrderNumber":{"type":"string","description":"Source order number."},"returnCode":{"type":"string","description":"Return code when applicable."},"reasonCode":{"type":"string","description":"Reason code."},"customAccount":{"type":"string","description":"Custom account."},"isStatic":{"type":"boolean","description":"Static row flag."}},"required":["distributorId"],"additionalProperties":false},"CursorListMeta":{"type":"object","properties":{"pageSize":{"type":"integer","description":"Rows returned per page.","example":500},"nextCursor":{"type":"string","description":"Pass as cursor to fetch the next page."},"hasNextPage":{"type":"boolean","description":"True when more rows exist.","example":false}},"required":["pageSize","hasNextPage"],"additionalProperties":false},"CommissionHistoryRow":{"type":"object","properties":{"distributorId":{"type":"string","description":"Affiliate id."},"period":{"type":"integer","description":"YYYYMM or YYYYMMDD."},"orderByLevel":{"type":"integer","description":"Sort level."},"isActive":{"type":"boolean","description":"Period active state."},"mainActive":{"type":"boolean","description":"Organization active state."},"applicationDate":{"type":"string","description":"Application date."},"sponsor":{"type":"string","description":"Sponsor id."},"enroller":{"type":"string","description":"Enroller id."},"startRank":{"type":"string","description":"Start rank code."},"currentRank":{"type":"string","description":"Current rank code."},"rankPaidAt":{"type":"string","description":"Rank paid at."},"vol":{"type":"number","description":"Volume."},"qvol":{"type":"number","description":"Qualifying volume."},"amount":{"type":"number","description":"Total amount."},"numbers":{"type":"object","additionalProperties":{"type":"number","description":"Dynamic numeric stat value."},"description":"Dynamic numeric stats."},"strings":{"type":"object","additionalProperties":{"type":"string","description":"Dynamic string stat value."},"description":"Dynamic string stats."},"dates":{"type":"object","additionalProperties":{"type":"string","description":"Dynamic date stat value."},"description":"Dynamic date stats."}},"required":["distributorId"],"additionalProperties":false},"OrderPaidRow":{"type":"object","properties":{"orderNumber":{"type":"string","description":"Order number processed in this run."}},"required":["orderNumber"],"additionalProperties":false},"ReturnProcessedRow":{"type":"object","properties":{"returnCode":{"type":"string","description":"Return code processed in this run."}},"required":["returnCode"],"additionalProperties":false}},"parameters":{}},"paths":{"/commission-plans":{"get":{"operationId":"listCommissionPlans","tags":["Commission plans"],"summary":"List commission plans","description":"Real-time (simple) commission plans for Plus tier. Not available on the MLM tier — use monthly commission processing instead. MLM/advanced commission plan editor is not exposed via API.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Plans","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionPlan"}}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"operationId":"createCommissionPlan","tags":["Commission plans"],"summary":"Create commission plan","description":"Real-time (simple) commission plans for Plus tier. Not available on the MLM tier — use monthly commission processing instead. MLM/advanced commission plan editor is not exposed via API.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionPlanWriteBody"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CommissionPlan"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — MLM tier or Starter tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/commission-plans/{planId}":{"put":{"operationId":"updateCommissionPlan","tags":["Commission plans"],"summary":"Update commission plan","description":"Real-time (simple) commission plans for Plus tier. Not available on the MLM tier — use monthly commission processing instead. MLM/advanced commission plan editor is not exposed via API.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Commission plan GUID.","example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"planId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionPlanWriteBody"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CommissionPlan"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — MLM tier or Starter tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/commission-plans/{planId}/deactivate":{"post":{"operationId":"deactivateCommissionPlan","tags":["Commission plans"],"summary":"Deactivate plan","description":"Real-time (simple) commission plans for Plus tier. Not available on the MLM tier — use monthly commission processing instead. MLM/advanced commission plan editor is not exposed via API. Fails with 422 if distributors are still assigned to the plan.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Commission plan GUID.","example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"planId","in":"path"}],"responses":{"200":{"description":"Deactivated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeactivatedPlan"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — MLM tier or Starter tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/commission-plans/{planId}/set-default":{"post":{"operationId":"setDefaultCommissionPlan","tags":["Commission plans"],"summary":"Set default plan","description":"Real-time (simple) commission plans for Plus tier. Not available on the MLM tier — use monthly commission processing instead. MLM/advanced commission plan editor is not exposed via API.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Commission plan GUID.","example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"planId","in":"path"}],"responses":{"200":{"description":"Default set","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SetDefaultPlan"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — MLM tier or Starter tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/ranks":{"get":{"operationId":"listRanks","tags":["Ranks"],"summary":"List ranks","description":"Read-only rank codes from the live MLM tier commission plan. Requires MLM subscription. Rank definitions are edited in the plan editor, not via API.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Ranks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Rank"}}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — requires MLM tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/distributors":{"get":{"operationId":"listDistributors","tags":["Distributors"],"summary":"List affiliates","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["true","false","1","0"],"description":"Filter to active affiliates."},"required":false,"name":"activeOnly","in":"query"},{"schema":{"type":"string","description":"Search text (id, name, email, etc.)."},"required":false,"name":"filter","in":"query"},{"schema":{"type":["integer","null"],"description":"Page number (1-based).","example":1},"required":false,"name":"page","in":"query"},{"schema":{"type":["integer","null"],"description":"Page size (max 250).","example":20},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Return all rows (ignore paging)."},"required":false,"name":"includeAllRows","in":"query"}],"responses":{"200":{"description":"Paged list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DistributorListItem"}},"meta":{"$ref":"#/components/schemas/ListMeta"}},"required":["data","meta"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"operationId":"createDistributor","tags":["Distributors"],"summary":"Create affiliate","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DistributorWriteBody"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DistributorDetail"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/distributors/{distributorId}":{"get":{"operationId":"getDistributor","tags":["Distributors"],"summary":"Get affiliate","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Affiliate id.","example":"1001"},"required":true,"name":"distributorId","in":"path"}],"responses":{"200":{"description":"Affiliate detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DistributorDetail"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"operationId":"updateDistributor","tags":["Distributors"],"summary":"Update affiliate","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Affiliate id.","example":"1001"},"required":true,"name":"distributorId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DistributorPatchBody"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DistributorDetail"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/distributors/{distributorId}/tax-id":{"put":{"operationId":"updateDistributorTaxId","tags":["Distributors"],"summary":"Update tax ID","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Affiliate id.","example":"1001"},"required":true,"name":"distributorId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DistributorTaxIdBody"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicOperationResult"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/distributors/{distributorId}/terminate":{"post":{"operationId":"terminateDistributor","tags":["Distributors"],"summary":"Terminate affiliate","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Affiliate id.","example":"1001"},"required":true,"name":"distributorId","in":"path"}],"responses":{"200":{"description":"Terminated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicOperationResult"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/distributors/{distributorId}/reactivate":{"post":{"operationId":"reactivateDistributor","tags":["Distributors"],"summary":"Reactivate affiliate","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Affiliate id.","example":"1001"},"required":true,"name":"distributorId","in":"path"}],"responses":{"200":{"description":"Reactivated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicOperationResult"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/sales":{"get":{"operationId":"listSales","tags":["Sales"],"summary":"List sales","description":"Paged order list. When beginDate and endDate are both omitted, defaults to the last 90 days.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":["integer","null"],"description":"Start date YYYYMMDD. When omitted with endDate, the server defaults to the last 90 days.","example":20260101},"required":false,"name":"beginDate","in":"query"},{"schema":{"type":["integer","null"],"description":"End date YYYYMMDD. When omitted with beginDate, the server defaults to the last 90 days.","example":20260131},"required":false,"name":"endDate","in":"query"},{"schema":{"type":"string","description":"Filter by affiliate id."},"required":false,"name":"distributorId","in":"query"},{"schema":{"type":["integer","null"],"example":1},"required":false,"name":"page","in":"query"},{"schema":{"type":["integer","null"],"example":20},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Lookup a single order."},"required":false,"name":"specificOrder","in":"query"},{"schema":{"type":"string","description":"Canonical sale id when specificOrder=true (same as path `saleId`; Shopify e.g. `7-18695943029040`)."},"required":false,"name":"orderNumber","in":"query"},{"schema":{"type":"string","description":"Alias for orderNumber (canonical sale id)."},"required":false,"name":"saleId","in":"query"}],"responses":{"200":{"description":"Paged sales","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SaleListItem"}},"meta":{"$ref":"#/components/schemas/ListMeta"}},"required":["data","meta"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/sales/{saleId}":{"get":{"operationId":"getSale","tags":["Sales"],"summary":"Get sale detail","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Canonical sale id. For Shopify: `{integrationId}-{shopifyNumericId}` (e.g. `7-18695943029040`). Not the display number (`1040`).","example":"7-18695943029040"},"required":true,"name":"saleId","in":"path"}],"responses":{"200":{"description":"Sale detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SaleDetail"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"operationId":"updateSale","tags":["Sales"],"summary":"Save sale changes","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Canonical sale id. For Shopify: `{integrationId}-{shopifyNumericId}` (e.g. `7-18695943029040`). Not the display number (`1040`).","example":"7-18695943029040"},"required":true,"name":"saleId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaleWriteBody"}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SaleDetail"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"operationId":"deleteSale","tags":["Sales"],"summary":"Remove unpaid sale","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Canonical sale id. For Shopify: `{integrationId}-{shopifyNumericId}` (e.g. `7-18695943029040`). Not the display number (`1040`).","example":"7-18695943029040"},"required":true,"name":"saleId","in":"path"}],"responses":{"200":{"description":"Removed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RemovedSale"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/ledger/entries":{"get":{"operationId":"listLedgerEntries","tags":["Ledger"],"summary":"Search ledger entries","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Required affiliate id.","example":"1001"},"required":true,"name":"distributorId","in":"query"},{"schema":{"type":["integer","null"],"description":"Start date YYYYMMDD."},"required":false,"name":"startDate","in":"query"},{"schema":{"type":["integer","null"],"description":"End date YYYYMMDD."},"required":false,"name":"endDate","in":"query"},{"schema":{"type":"string","description":"Text filter on description/type."},"required":false,"name":"filter","in":"query"},{"schema":{"type":["integer","null"],"example":1},"required":false,"name":"page","in":"query"},{"schema":{"type":["integer","null"],"example":20},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Return all rows (ignore paging)."},"required":false,"name":"includeAllRows","in":"query"}],"responses":{"200":{"description":"Ledger rows","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LedgerEntry"}},"meta":{"$ref":"#/components/schemas/ListMeta"}},"required":["data","meta"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"operationId":"createLedgerEntry","tags":["Ledger"],"summary":"Create manual ledger adjustment","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LedgerEntryCreateBody"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicOperationResult"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/commission-runs":{"post":{"operationId":"startCommissionRun","tags":["Commission runs"],"summary":"Start commission run","description":"Monthly and rebate commission processing for the MLM tier. Requires MLM subscription (Plus and Starter receive 403). Trigger a run, poll status, download paged JSON results or CSV exports, rollback, or finalize. One-step create and start (body: period + runType).","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRunStartBody"}}}},"responses":{"201":{"description":"Run started","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CommissionRunStartResult"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Requires MLM tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"operationId":"listCommissionRuns","tags":["Commission runs"],"summary":"List commission runs","description":"Monthly and rebate commission processing for the MLM tier. Requires MLM subscription (Plus and Starter receive 403). Trigger a run, poll status, download paged JSON results or CSV exports, rollback, or finalize.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["monthly","rebate"],"description":"Commission run type.","example":"monthly"},"required":false,"name":"runType","in":"query"},{"schema":{"type":["integer","null"],"description":"Filter by YYYYMM or YYYYMMDD."},"required":false,"name":"period","in":"query"},{"schema":{"type":"string","description":"Filter by foresight status (Ready, Processing, Errored, Processing Complete, Finalized)."},"required":false,"name":"status","in":"query"},{"schema":{"type":["integer","null"],"example":1},"required":false,"name":"page","in":"query"},{"schema":{"type":["integer","null"],"example":20},"required":false,"name":"pageSize","in":"query"}],"responses":{"200":{"description":"Runs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionRun"}},"meta":{"$ref":"#/components/schemas/ListMeta"}},"required":["data","meta"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Requires MLM tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/commission-runs/active":{"get":{"operationId":"getActiveCommissionRun","tags":["Commission runs"],"summary":"Get active commission run","description":"Monthly and rebate commission processing for the MLM tier. Requires MLM subscription (Plus and Starter receive 403). Trigger a run, poll status, download paged JSON results or CSV exports, rollback, or finalize.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Active run if any","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ActiveCommissionRun"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Requires MLM tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/commission-runs/{runId}":{"get":{"operationId":"getCommissionRun","tags":["Commission runs"],"summary":"Get commission run","description":"Monthly and rebate commission processing for the MLM tier. Requires MLM subscription (Plus and Starter receive 403). Trigger a run, poll status, download paged JSON results or CSV exports, rollback, or finalize.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Commission run id (GUID).","example":"a1b2c3d4-..."},"required":true,"name":"runId","in":"path"}],"responses":{"200":{"description":"Run metadata","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CommissionRun"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Requires MLM tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/commission-runs/{runId}/status":{"get":{"operationId":"getCommissionRunStatus","tags":["Commission runs"],"summary":"Poll commission run status","description":"Monthly and rebate commission processing for the MLM tier. Requires MLM subscription (Plus and Starter receive 403). Trigger a run, poll status, download paged JSON results or CSV exports, rollback, or finalize. Poll every 3–5 seconds while isRunning; use nextPollAfterSeconds.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Commission run id (GUID).","example":"a1b2c3d4-..."},"required":true,"name":"runId","in":"path"}],"responses":{"200":{"description":"Status","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CommissionRunStatus"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Requires MLM tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/commission-runs/{runId}/rollback":{"post":{"operationId":"rollbackCommissionRun","tags":["Commission runs"],"summary":"Rollback commission run","description":"Monthly and rebate commission processing for the MLM tier. Requires MLM subscription (Plus and Starter receive 403). Trigger a run, poll status, download paged JSON results or CSV exports, rollback, or finalize.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Commission run id (GUID).","example":"a1b2c3d4-..."},"required":true,"name":"runId","in":"path"}],"responses":{"200":{"description":"Rollback started","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CommissionRunStartResult"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Requires MLM tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/commission-runs/{runId}/finalize":{"post":{"operationId":"finalizeCommissionRun","tags":["Commission runs"],"summary":"Finalize commission run","description":"Monthly and rebate commission processing for the MLM tier. Requires MLM subscription (Plus and Starter receive 403). Trigger a run, poll status, download paged JSON results or CSV exports, rollback, or finalize. Posts period earnings to the ledger.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Commission run id (GUID).","example":"a1b2c3d4-..."},"required":true,"name":"runId","in":"path"}],"responses":{"200":{"description":"Finalized","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicOperationResult"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Requires MLM tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/commission-runs/{runId}/results/detail":{"get":{"operationId":"getCommissionRunDetailResults","tags":["Commission runs"],"summary":"Page commission detail results","description":"Monthly and rebate commission processing for the MLM tier. Requires MLM subscription (Plus and Starter receive 403). Trigger a run, poll status, download paged JSON results or CSV exports, rollback, or finalize.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Commission run id (GUID).","example":"a1b2c3d4-..."},"required":true,"name":"runId","in":"path"},{"schema":{"type":"string","description":"Opaque cursor from a previous page (tloc)."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"],"description":"Rows per page (default 500, max 2000).","example":500},"required":false,"name":"pageSize","in":"query"}],"responses":{"200":{"description":"Detail rows","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionDetailRow"}},"meta":{"$ref":"#/components/schemas/CursorListMeta"}},"required":["data","meta"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Requires MLM tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Results not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/commission-runs/{runId}/results/history":{"get":{"operationId":"getCommissionRunHistoryResults","tags":["Commission runs"],"summary":"Page commission history results","description":"Monthly and rebate commission processing for the MLM tier. Requires MLM subscription (Plus and Starter receive 403). Trigger a run, poll status, download paged JSON results or CSV exports, rollback, or finalize.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Commission run id (GUID).","example":"a1b2c3d4-..."},"required":true,"name":"runId","in":"path"},{"schema":{"type":"string","description":"Opaque cursor from a previous page (tloc)."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"],"description":"Rows per page (default 500, max 2000).","example":500},"required":false,"name":"pageSize","in":"query"}],"responses":{"200":{"description":"History rows","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionHistoryRow"}},"meta":{"$ref":"#/components/schemas/CursorListMeta"}},"required":["data","meta"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Requires MLM tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Results not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/commission-runs/{runId}/results/orders-paid":{"get":{"operationId":"getCommissionRunOrdersPaidResults","tags":["Commission runs"],"summary":"Page orders paid in run","description":"Monthly and rebate commission processing for the MLM tier. Requires MLM subscription (Plus and Starter receive 403). Trigger a run, poll status, download paged JSON results or CSV exports, rollback, or finalize.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Commission run id (GUID).","example":"a1b2c3d4-..."},"required":true,"name":"runId","in":"path"},{"schema":{"type":"string","description":"Opaque cursor from a previous page (tloc)."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"],"description":"Rows per page (default 500, max 2000).","example":500},"required":false,"name":"pageSize","in":"query"}],"responses":{"200":{"description":"Order numbers","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrderPaidRow"}},"meta":{"$ref":"#/components/schemas/CursorListMeta"}},"required":["data","meta"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Requires MLM tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Results not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/commission-runs/{runId}/results/returns-processed":{"get":{"operationId":"getCommissionRunReturnsProcessedResults","tags":["Commission runs"],"summary":"Page returns processed in run","description":"Monthly and rebate commission processing for the MLM tier. Requires MLM subscription (Plus and Starter receive 403). Trigger a run, poll status, download paged JSON results or CSV exports, rollback, or finalize.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Commission run id (GUID).","example":"a1b2c3d4-..."},"required":true,"name":"runId","in":"path"},{"schema":{"type":"string","description":"Opaque cursor from a previous page (tloc)."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"],"description":"Rows per page (default 500, max 2000).","example":500},"required":false,"name":"pageSize","in":"query"}],"responses":{"200":{"description":"Return codes","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ReturnProcessedRow"}},"meta":{"$ref":"#/components/schemas/CursorListMeta"}},"required":["data","meta"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Requires MLM tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Results not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/commission-runs/{runId}/exports/{exportKey}":{"get":{"operationId":"exportCommissionRunCsv","tags":["Commission runs"],"summary":"Download commission run CSV export","description":"Monthly and rebate commission processing for the MLM tier. Requires MLM subscription (Plus and Starter receive 403). Trigger a run, poll status, download paged JSON results or CSV exports, rollback, or finalize. Monthly keys include commission-detail, commission-summary, earnings, etc. Rebate keys include rebate-detail, actual-payouts.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Commission run id (GUID)."},"required":true,"name":"runId","in":"path"},{"schema":{"type":"string","minLength":1,"description":"CSV export key (e.g. commission-detail, commission-summary, earnings, rebate-detail, actual-payouts).","example":"commission-detail"},"required":true,"name":"exportKey","in":"path"}],"responses":{"200":{"description":"CSV file","content":{"text/csv":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Requires MLM tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Invalid export","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"webhooks":{}}