Accounting API

The accounting system reads Tote's money from five export endpoints. They are read-only and are not for the mobile apps.

Authentication#

Send the shared secret in the X-Accounting-Token header on every request. A missing or wrong token returns 401. The token is issued by Tote; keep it on the server side of the accounting integration only.

GET /api/v1/accounting/orders?start_date=2026-09-01&end_date=2026-09-30&per_page=200
X-Accounting-Token: …
Accept: application/json

Responses have data and a meta block (current_page, last_page, per_page, total). per_page goes up to 200; walk ?page= until last_page.

How a store gets paid#

flowchart TD
    order["Order paid and delivered<br/>(or cancelled)"]
    hold["Waits the hold period"]
    ledger["Ledger adjustments<br/>(charges and credits)"]
    payout["Payout: one bank transfer to the store"]
    order --> hold --> payout
    ledger --> payout

• Every order belongs to a settlement batch: {store_id}-{YYYYMMDD}, the store and the sale day in Riyadh time, for example 12-20260915.
• A finished order becomes payable once a hold period set by Tote has passed.
• Ledger adjustments are charges and credits outside the order itself: store fault fees (merchant_fault_charge for a cancellation, return_commission_charge for a Return, store_fault_fee for another refund), manual adjustments, and the entries a refund or Return writes — the sale given back (refund_reversal, return_reversal) and Tote's commission given back (commission_credit, negative). They are payable at once.
• A payout is one bank transfer that bundles payable orders and adjustments. Once a row is in a payout it is locked there; settled_at is set when that payout is paid.

All amounts are SAR.

Orders#

GET accounting/orders — one row per order:

Key	Meaning
total_order_amount	What the customer paid
commission_amount, commission_rate	The basic commission the store owes Tote, taken on the order total before VAT (commission_rate is its blended percent of that base). 0 for a cancelled order; null for orders from before commissions existed
commission_vat_amount	The VAT Tote charges the store on its commission (15%). 0 for a cancelled order
commission_adjustments_amount	The order's active ledger entries
gateway_fee	The card processing fee as Moyasar charged it, its VAT included, passed on to the store
net_store_amount	Total less commission, commission VAT, adjustments and gateway fee: what the store keeps
payment_status	paid, unpaid or refunded. Only fully refunded orders are refunded; a partial refund stays paid with refunded_amount set
settlement_batch_id, settlement_date	The batch and Riyadh sale day
payout_id, payout_reference, settled_at	The payout the order is locked into, and when it was paid

Filters: store_id, settlement_batch_id, status (paid, unpaid, refunded), settled (true/false; false includes orders in a pending or failed payout), start_date/end_date (creation), settlement_date_from/settlement_date_to (Riyadh sale day). Add include=items for per-line prices, commissions and commission_vat_amount.

A bare end_date like 2026-09-30 covers the whole day.

Ledger adjustments#

GET accounting/commission-adjustments — newest first. amount is signed: positive means the store owes Tote, negative is a credit to the store. vat_amount is the part of amount that is VAT on a Tote charge — the commission VAT on a store fault fee, or on a commission credit (negative) — and 0 on any other entry. manual_kind says what a manual entry is: tote_service_charge (a taxable service, VAT inside amount), commission_correction (changes one order's commission, with its VAT) or settlement_correction (money only); null on automatic entries. Voided entries are left out unless include_voided=true, except a voided entry already locked into a payout, which stays next to the entry that reverses it. Same settled filter as orders.

Payouts#

GET accounting/payouts — one row per bank transfer, newest first.

• lines_total sums the payout's lines and can be negative. Then transfer_amount is 0 and the shortfall carries forward as a ledger entry.
• status is pending, paid, failed or voided. Voided payouts appear only with status=voided.
• start_date/end_date filter on the transfer date. include=items lists the lines: an order line carries order_id, a ledger line commission_adjustment_id; each line has gross, commission, commission_vat, gateway_fee and net.

Tax documents#

GET accounting/tax-documents — one row per issued tax document, newest first, from every issuer:

type	issuer	What it is
customer_invoice, customer_credit_note	store	The customer's invoice and credit notes, issued by Tote in the store's name
commission_invoice, commission_credit_note, commission_debit_note	tote	Tote's monthly commission invoice to the store and its notes

Each row has number, issued_at (Riyadh), before_vat, vat, after_vat (SAR, positive on credit notes too), and the links order_id, order_return_id, payout_id and corrects_number (the invoice a note corrects). Filters: issuer, store_id, type, start_date / end_date (Riyadh issue date).

VAT report#

GET accounting/vat-report with start_date and end_date (Riyadh days), built only from issued documents:

• with store_id: the store's sales (customer invoices less credit notes: before VAT, VAT, after VAT) and its input VAT on Tote's charges (commission invoices and debit notes less credit notes);
• without: Tote's output VAT on all commission documents, per store (stores), and the platform_compensation it paid in the period (no VAT).

Returns#

GET accounting/returns — one row per Return with its refund, fault party and the ledger rows it wrote. Details are in Returns.

Products#

GET accounting/products — the shared catalog, paginated.