Changelog

How the API changes#

The apps are released on their own schedule, so the API keeps a simple promise:

• Additive only. An existing /api/v1 response never loses, renames or retypes a key. New data arrives as new keys or new endpoints, so an app must ignore keys it does not know.
• Money stays decimal SAR in JSON, even where the server stores halalas. The one exception is the payment attempt's amount, which is in halalas because Moyasar expects it (see Payments).
• Invalid requests may start to be refused. When the server accepted something it should not have — a skipped order status, an unsuitable driver — a fix can turn that request into a 422. The response shape does not change, and every such fix is listed below with what to send instead.

Check this page before each app release.

2026-10-18#

Changed: a store must be authorized for invoicing before it can sell#

Tote now issues customer invoices in the store's name, so checkout answers 422 with code: store_unavailable at a store whose legal identity and signed invoicing agreement are not verified yet. The response is the one an inactive store already gets.

What to change: nothing in the customer app. In the merchant app, owners can read and propose their store's legal identity through the new stores/{store}/legal-identity endpoints; see Stores & staff.

Added: tax documents and VAT reports in the accounting API#

accounting/tax-documents lists every issued tax document from every issuer, and accounting/vat-report gives a store's or Tote's VAT figures for a period, built only from those documents. Store owners get their own figures from stores/{store}/vat-report. See Accounting API.

Added: store owners download their tax and settlement documents#

New owner-only endpoints list and download the store's customer invoices and credit notes, Tote's monthly commission invoices and notes, and the settlement statement of each transfer: stores/{store}/documents. See Stores & staff.

Changed: invoices are in the store's name#

The order's invoice and credit notes are now the store's documents, issued by Tote on its behalf: the seller on them is the store, and their number comes from the store's own sequence, for example 12-INV-000001 and 12-CN-000002 instead of INV-000123. Keys and types in orders/{order}/documents are unchanged.

What to change: nothing, unless an app parses the number; treat it as an opaque string.

Changed: refunds and returns split the sale from Tote's commission#

A refunded Return or refund now writes the full refunded value back from the store (return_reversal / refund_reversal) and a separate negative commission_credit for Tote's commission and its VAT. When the store or its driver is at fault, a store fault fee (return_commission_charge / new store_fault_fee) is added. What the store bears is unchanged. When the platform is at fault there are no entries at all: Tote pays the refund as a platform compensation. New type values on accounting/commission-adjustments: commission_credit, store_fault_fee.

Added: manual ledger entries say what they are#

Every manual entry on accounting/commission-adjustments now carries manual_kind: tote_service_charge, commission_correction or settlement_correction (null on automatic entries). A service charge or commission correction includes its 15% VAT in amount, with vat_amount set.

Added: commission VAT in the accounting API#

Tote's commission is now taken on the order total before VAT, and Tote charges the store 15% VAT on it. For example, on a 1,150.00 order at 10%, the commission is 100.00 plus 15.00 VAT, and the store keeps 1,035.00 before the card fee. New keys, none changed:

• accounting/orders: commission_vat_amount, also on each line with include=items. commission_rate is now the blended percent of the total before VAT, and net_store_amount also subtracts the commission VAT.
• accounting/commission-adjustments and the Return ledger rows: vat_amount, the VAT inside amount.
• accounting/payouts with include=items: commission_vat on each line.

The mobile apps see no change.

2026-10-01#

Changed: login is rate limited#

The customer, driver and merchant login endpoints now return 429 with Retry-After after 5 attempts a minute for one phone from one address, or 60 a minute from one address.

What to change: handle 429 on the login screen by showing the wait; never retry a login automatically.

Changed: a rejected friend request can be sent again#

friendships/request used to return 409 for a pair whose request had been rejected. Either customer can now ask again: the existing friendship becomes a new pending request from the one asking, with the same id, and the receiver is pushed friend_request. A blocked pair is still refused with 403.

Changed: order status moves one step at a time#

PUT orders/{order}/status in the merchant and driver apps used to accept any status. It now accepts only the next step in the lifecycle, or cancelled on an order that is not finished. Anything else returns 422 with a translated message.

• Drivers may only send out_for_delivery, delivered or cancelled.
• Cancelling a delivered order is refused, as cancelling a cancelled one already was.

What to change: send the next status only; see Order lifecycle.

Changed: assigning a driver checks the driver and the order#

assign-driver now returns 422 when:

• the order is not accepted or preparing — accept the order first;
• the driver is not an active, approved member of the store's team (message under errors.driver_id) — pick from drivers.

Fixed: store opening hours use Riyadh time#

is_closed compared working_hours against UTC, so stores showed as open or closed three hours off. Hours are now read on the Riyadh clock, as merchants enter them. No app change is needed.

Added: the notification list is filled#

The profile/notifications endpoints of every app always returned an empty list. Every push is now also stored there, with its title, body and data payload. See Push notifications.

Added: developer guides#

These guides, at /docs/guides, next to the API reference.

2026-09-28#

Added: Returns#

New endpoints for customers, merchants and accounting, plus new keys on store, order and accounting payloads. No existing key changed. See Returns, which lists every addition under "Changes to existing endpoints".