Deliveries and warehouses

A delivery records goods leaving a warehouse for a destination. It has a sequential number within your organization (DEL-000001), line items and a status, and it can fulfil a sales order or relate to a tender. Warehouses and destinations are saved places you reuse, not a stock ledger: the platform does not track quantities in a warehouse.

How deliveries move a sales order forward, and how differences from the order are shown, is explained in Orders. The sales order tools themselves are in Sales and purchase orders.

Warehouses

A warehouse is a place deliveries leave from. A delivery copies its warehouse's details when it is created, so editing the warehouse later never changes older delivery records.

warehouses_list

Lists your organization's warehouses, newest first. Deactivated warehouses are left out unless you ask for them with include_inactive.

Read-only · scope logistics.read · roles: owner, admin, sales, purchasing, viewer, viewer (no pricing) · Pro and Enterprise plans

Returns: A page of warehouses in data, with total, page, page_size and total_pages.

warehouses_get

Fetches one warehouse by its ID: its name, address, contact person and whether it is active.

Read-only · scope logistics.read · roles: owner, admin, sales, purchasing, viewer, viewer (no pricing) · Pro and Enterprise plans

Returns: The warehouse record, in warehouse.

warehouses_create

Creates a warehouse that deliveries can ship from. Only the name is required, and a new warehouse is active.

Changes data · scope logistics.write · roles: owner, admin · Pro and Enterprise plans

{
  "name": "Riyadh Central Warehouse",
  "address": "Industrial City, Second Phase",
  "city": "Riyadh",
  "contact_name": "Khalid Al-Otaibi",
  "contact_phone": "+966 11 555 0142"
}

Returns: The warehouse that was created, in warehouse.

warehouses_update

Changes a warehouse's details, or hides it from pickers by sending is_active as false (true brings it back). Only what you send changes, and at least one field is required.

Changes data · scope logistics.write · roles: owner, admin · Pro and Enterprise plans

{
  "id": 3,
  "contact_name": "Faisal Al-Harbi",
  "contact_phone": "+966 11 555 0177"
}

Returns: The warehouse after the change, in warehouse.

• Deliveries already created keep the details they copied, so the edit does not change them.

warehouses_delete

Deletes a warehouse. When any delivery refers to it, the warehouse is deactivated instead of deleted so those delivery records stay meaningful, and the reply says which happened.

Deletes or overwrites data · scope logistics.write · roles: owner, admin · Pro and Enterprise plans

Returns: ok and deactivated: true means the warehouse was kept and deactivated, false means it was deleted.

• A deactivated warehouse comes back with warehouses_update and is_active set to true. A deleted one cannot be recovered.

Destinations

A destination is a receiving party you deliver to repeatedly, such as a hospital or a branch, saved so you can copy its details into deliveries. A delivery is not linked to a saved destination: you read its details and put them in the destination_* parameters when you create the delivery.

destinations_list

Lists your organization's saved destinations, newest first. Deactivated ones are left out unless you ask for them with include_inactive.

Read-only · scope logistics.read · roles: owner, admin, sales, purchasing, viewer, viewer (no pricing) · Pro and Enterprise plans

Returns: A page of destinations in data, with total, page, page_size and total_pages.

destinations_get

Fetches one saved destination by its ID: its name, address and contact person.

Read-only · scope logistics.read · roles: owner, admin, sales, purchasing, viewer, viewer (no pricing) · Pro and Enterprise plans

Returns: The destination record, in destination.

destinations_create

Saves a delivery destination for reuse. Only the name is required, and a new destination is active.

Changes data · scope logistics.write · roles: owner, admin · Pro and Enterprise plans

{
  "name": "King Fahd Hospital, Pharmacy Store",
  "address": "Al Olaya Street",
  "city": "Riyadh",
  "contact_name": "Nora Al-Qahtani",
  "contact_phone": "+966 11 555 0188"
}

Returns: The destination that was saved, in destination.

destinations_update

Changes a saved destination's details, or hides it from pickers by sending is_active as false (true brings it back). Only what you send changes, and at least one field is required.

Changes data · scope logistics.write · roles: owner, admin · Pro and Enterprise plans

{
  "id": 12,
  "is_active": false
}

Returns: The destination after the change, in destination.

• Deliveries already created keep their own copy of the destination details, so the edit does not change them.

destinations_delete

Deletes a saved destination for good. No delivery is affected, because each delivery carries its own copy of the destination details. This cannot be undone.

Deletes or overwrites data · scope logistics.write · roles: owner, admin · Pro and Enterprise plans

Returns: A confirmation of the deletion, in ok.

• To hide a destination but keep it, use destinations_update with is_active set to false instead of deleting.

Deliveries

The usual order of statuses is draft, scheduled, in_transit and delivered, plus cancelled for a delivery that will not happen. Every delivery starts as a draft, and its status is changed with deliveries_set_status, not by editing it.

deliveries_list

Lists your organization's deliveries, newest first, each with the names of its tender, sales order and warehouse. Filter by status, tender, sales order or warehouse.

Read-only · scope logistics.read · roles: owner, admin, sales, purchasing, viewer, viewer (no pricing) · Pro and Enterprise plans

Returns: A page of deliveries in data, with total, page, page_size and total_pages. Each delivery has id, delivery_number, status, scheduled_at, delivered_at, the destination name and city, the warehouse_snapshot, and a short summary of its tender, sales order and current warehouse.

• Line items are not in the list. Use deliveries_get to read them.

deliveries_get

Fetches one delivery in full: its header, its lines, and the tender, sales order and current warehouse it is linked to.

Read-only · scope logistics.read · roles: owner, admin, sales, purchasing, viewer, viewer (no pricing) · Pro and Enterprise plans

Returns: delivery (the header, with warehouse_snapshot), items (the lines in order), and tender, warehouse and sales_order, each null when there is none.

• warehouse_snapshot is what was copied when the delivery was created and never changes. warehouse is the warehouse's current record, which may have changed since.

deliveries_create

Creates a delivery with at least one line. The platform gives it a sequential number, it starts as a draft, and the warehouse's details are copied onto it when you give warehouse_id.

Changes data · scope logistics.write · roles: owner, admin · Pro and Enterprise plans

{
  "tender_id": 48213,
  "sales_order_id": 77,
  "warehouse_id": 3,
  "destination_name": "King Fahd Hospital, Pharmacy Store",
  "destination_address": "Al Olaya Street",
  "destination_city": "Riyadh",
  "destination_contact_name": "Nora Al-Qahtani",
  "destination_contact_phone": "+966 11 555 0188",
  "scheduled_at": "2026-10-12T09:00:00+03:00",
  "notes": "Deliver to the pharmacy store, gate 2",
  "items": [
    {
      "product_id": 1204,
      "sales_order_item_id": 311,
      "description": "Syringe 5 ml, Luer lock, sterile",
      "quantity": 200,
      "unit": "box"
    },
    {
      "description": "Examination gloves, nitrile, size M",
      "quantity": 80,
      "unit": "box"
    }
  ]
}

Returns: delivery_id and the number given to the delivery, in delivery_number.

• The number follows your organization's sequence, such as DEL-000014, and never changes afterwards.
• The tender must be visible to your organization, and the warehouse and sales order must belong to it, or the call is refused. A line with a sales_order_item_id needs sales_order_id and must be a line of that order, or the call is refused as well.
• A delivery records what actually shipped, so a line with more than the ordered quantity is accepted. The difference shows on the sales order page as a deviation from the order.

deliveries_update

Changes a delivery's destination, schedule, notes, links or lines. Only what you send changes; the status is changed with a separate tool.

Changes data · scope logistics.write · roles: owner, admin · Pro and Enterprise plans

{
  "id": 412,
  "scheduled_at": "2026-10-14T10:30:00+03:00",
  "notes": "Moved at the hospital's request"
}

Returns: delivery_id of the delivery after the change.

• items replaces the whole list: a line you leave out is removed, and a line you keep that belongs to an order line needs its sales_order_item_id sent again. Leave items out and the lines stay as they are.
• If you change or clear sales_order_id without sending items, the delivery's lines are unlinked from the old order's lines and stop counting toward it.
• The delivery number and the stored warehouse copy cannot be edited. The status is changed with deliveries_set_status.
• After saving, the linked sales order's status is reviewed again, moving forward only.

deliveries_delete

Deletes a delivery together with its lines. This cannot be undone, and the linked sales order keeps whatever status it has reached.

Deletes or overwrites data · scope logistics.write · roles: owner, admin · Pro and Enterprise plans

Returns: A confirmation of the deletion, in ok.

• To stop a delivery without erasing it, move it to cancelled with deliveries_set_status: a cancelled delivery counts for nothing toward any order.

deliveries_set_status

Moves a delivery to a new status. Any move between statuses is allowed, so a mistake is fixed by moving back, and the linked sales order's status is worked out again afterwards.

Changes data · scope logistics.write · roles: owner, admin · Pro and Enterprise plans

{
  "id": 412,
  "status": "delivered"
}

Returns: ok and status, the status the delivery is now in.

• delivered_at is stamped when the delivery enters delivered and cleared when it leaves that status.
• The sales order only moves forward: a delivery becoming delivered can take it to in_progress and then fulfilled, but moving the delivery back never moves the order back. The order has its own status tool for that.