Commission periods

The commission operating cycle — provisional, objection, issue, and settlement, on your statement cadence.

If you sell in Retail (commission) mode, Linra rolls your commission earnings up into a commission period — a fixed calendar window in Saudi time (KSA) that follows your statement cadence, so every commission period ends on the same day as one of your statement periods. With the default cadence of 15 days that is the 1st–15th and the 16th–end-of-month; with a cadence of N days it is days 1–N, N+1–2N, …, with the last period of each month running to the month end (it is never a single day — a leftover last day joins the period before it). A period never crosses a month end. Each period moves through a strict lifecycle: Provisional → Issued → Settled.

The lifecycle

Provisional ──(objection window closes)──▶ Issued ──(you settle)──▶ Settled
     │
     └─(you object, before issueDate)──▶ stays Provisional until Linra resolves it

Provisional — generated automatically at the close of each window. The figures are a live snapshot of your Retail-mode orders for that window. You can object to a provisional period any time before its issueDate.
Issued — once the objection window passes (and any objection you raised has been resolved), the period’s figures are frozen permanently — re-queried live from your orders one last time, including a full-return exclusion for any order that was entirely returned by issue time. The period is issued on the day after it ends (18:00 Saudi time), and dueDate is stamped: your commission invoice is due the same day it is issued — by 24:00 Saudi time that day (dueDate is that exclusive end-of-day instant). From 00:00 the next day an unsettled period shows overdue: true. If an objection held the issue back, the period is due on the day it is actually issued.
Settled — a terminal, internal-only transition once Linra has recorded your commission invoice as received and settled it. You don’t drive this step yourself; it shows up as a status change.

1. List your commission periods

GET /api/v1/commission-periods?page=1&pageSize=20

{
  "state": "SUCCESS",
  "payload": {
    "items": [
      {
        "id": "33333333-3333-3333-3333-333333333333",
        "period": { "from": "2026-01-15T21:00:00Z", "to": "2026-01-31T21:00:00Z" },
        "issueDate": "2026-02-01T15:00:00Z",
        "dueDate": "2026-02-01T21:00:00Z",
        "currency": "SAR",
        "status": "Issued",
        "generatedAt": "2026-02-01T03:00:00Z",
        "isObjected": false,
        "objectedAt": null,
        "overdue": false,
        "netDue": 23.00,
        "totals": { "gross": 230.00, "net": 200.00, "vat": 30.00, "commission": 20.00, "commissionVat": 3.00 }
      }
    ],
    "pagination": { "page": 1, "pageSize": 20, "totalCount": 1, "totalPages": 1 }
  }
}

The list is lean — no per-order lines, so a page of periods stays small. totals reflects the period’s current authoritative document: the issued figures once issued, otherwise the still-provisional ones.

Filtering by status

status is a repeatable filter — pass it more than once to match any of several statuses:

GET /api/v1/commission-periods?status=Provisional&status=Issued

A single status value still works exactly as before. An unrecognized value (misspelled, or not one of Provisional/Issued/Settled) returns a 400 VALIDATION_INVALID_COMMISSION_PERIOD_STATUS rather than silently returning the unfiltered list.

2. Get one period, with the full ledger detail

By default, the by-id read returns the same summary shape as the list, plus objection/settlement detail — still no per-order lines:

GET /api/v1/commission-periods/{id}

Pass ?include=document to additionally embed the underlying document(s):

GET /api/v1/commission-periods/{id}?include=document

{
  "state": "SUCCESS",
  "payload": {
    "id": "33333333-3333-3333-3333-333333333333",
    "period": { "from": "2026-01-15T21:00:00Z", "to": "2026-01-31T21:00:00Z" },
    "issueDate": "2026-02-01T15:00:00Z",
    "dueDate": "2026-02-01T21:00:00Z",
    "currency": "SAR",
    "status": "Issued",
    "generatedAt": "2026-02-01T03:00:00Z",
    "isObjected": false,
    "objectedAt": null,
    "overdue": false,
    "netDue": 23.00,
    "totals": { "gross": 230.00, "net": 200.00, "vat": 30.00, "commission": 20.00, "commissionVat": 3.00 },
    "objection": { "isObjected": false, "reason": null, "objectedAt": null, "resolvedAt": null, "resolutionNote": null },
    "settlement": { "expectedInvoiceTotal": 23.00, "invoiceReceivedAt": null, "settledAt": null, "netDue": 23.00, "overdue": false },
    "provisionalDocument": {
      "isProvisional": true,
      "period": { "from": "2026-01-15T21:00:00Z", "to": "2026-01-31T21:00:00Z" },
      "generatedAt": "2026-02-01T03:00:00Z",
      "currency": "SAR",
      "totals": { "gross": 230.00, "net": 200.00, "vat": 30.00, "commission": 20.00, "commissionVat": 3.00 },
      "lines": [
        {
          "date": "2026-01-20T10:00:00Z",
          "orderNumber": "EXT-REF-0001",
          "retailInclVat": 230.00,
          "net": 200.00,
          "vat": 30.00,
          "commission": 20.00,
          "commissionVat": 3.00,
          "fullyReturnedExcluded": false
        }
      ],
      "deltaNote": null
    },
    "issuedDocument": {
      "isProvisional": false,
      "period": { "from": "2026-01-15T21:00:00Z", "to": "2026-01-31T21:00:00Z" },
      "generatedAt": "2026-01-31T22:00:00Z",
      "currency": "SAR",
      "totals": { "gross": 230.00, "net": 200.00, "vat": 30.00, "commission": 20.00, "commissionVat": 3.00 },
      "lines": [ "..." ],
      "deltaNote": null
    }
  }
}

Without ?include=document, provisionalDocument/issuedDocument are omitted entirely from the response — not sent as null. issuedDocument is only ever present once the period has actually been issued, even when ?include=document is passed on a still-provisional period.

A commission period belonging to another partner, or an unknown ID, returns a plain 404 NOT_FOUND_COMMISSION_PERIOD — never a 403, so you can’t tell the difference between “not yours” and “doesn’t exist.”

The document line shape

Each lines[] entry is one order’s contribution — date (the order’s tax point), orderNumber (your own externalReference, not an internal id), and the five money figures: retailInclVat, net, vat, commission, commissionVat. fullyReturnedExcluded is only meaningful on the issued document — true means every commission-bearing line on that order was fully returned by issue time, so it’s excluded from the issued totals even though it’s still listed here (not hidden). A partially-returned order is never excluded.

deltaNote (issued document only) is a plain-English explanation whenever the issued totals differ from the provisional ones — most commonly because one or more orders were excluded at issue time per the rule above.

3. Objecting to a provisional period

If a provisional period’s figures look wrong, object to it before its issueDate:

POST /api/v1/commission-periods/{id}/objection
Content-Type: application/json

{ "reason": "Order EXT-REF-0001's commission looks miscalculated." }

{
  "state": "SUCCESS",
  "payload": {
    "id": "33333333-3333-3333-3333-333333333333",
    "status": "Provisional",
    "isObjected": true,
    "objectedAt": "2026-02-01T12:00:00Z",
    "objection": {
      "isObjected": true,
      "reason": "Order EXT-REF-0001's commission looks miscalculated.",
      "objectedAt": "2026-02-01T12:00:00Z",
      "resolvedAt": null,
      "resolutionNote": null
    }
  }
}

reason is required, 1–1000 characters. Objecting pauses the period at Provisional — it will not become Issued until Linra resolves the objection, so a genuine dispute never silently gets frozen out from under you. The response is a write confirmation, not a document read — it never embeds a document, regardless of any query parameter; fetch the by-id read with ?include=document if you need the ledger detail.

Objection conflicts

Code	HTTP	When
`CONFLICT_COMMISSION_PERIOD_ALREADY_OBJECTED`	409	You already objected to this period.
`CONFLICT_COMMISSION_PERIOD_NOT_PROVISIONAL`	409	The period is already Issued or Settled — objecting only makes sense before issuance.
`CONFLICT_COMMISSION_PERIOD_PAST_ISSUE_DATE`	409	The objection window has already closed.

Not a financial ledger event by itself

A commission period is a commercial reporting layer over your Retail-mode orders — every order still posts its own ledger rows (see Billing statements) independent of this cycle. Objecting to a period doesn’t move any money by itself; it’s a hold on the period’s own Issued/Settled progression while the figures are reviewed.