iotoms Docs

Create a sales order

POST
/api/v1/sales/orders

Books a new order with at least one line. Sending a clientOrderId makes retries safe: the same id returns the order already booked. Orders not from the field app, or with submit set, are created as submitted rather than draft. Booking an order does not move stock or post any accounting entry.

How to use it

  1. Pick the shop from List customer stores and the items from List items.
  2. Send customerStoreId, lines (item code and quantity; price defaults to the item's selling price) and a unique clientOrderId so retries are safe.
  3. Set submit to true to send it straight for review, or leave false to keep a draft and call Submit a sales order later. Orders keyed outside the field app are always submitted.
  4. The order gets an order number and server-computed totals; no stock moves and nothing is posted to accounts.

Authorization

BearerAuth
headerAuthorizationBearer <JWT>

Header Parameters

X-TenantID*string

Your merchant's tenant code — the value typed in the Domain field on the iotoms login screen. See Concepts.

Request Body

application/json
  1. body
customerStoreId?|

The customer's shop, from List customer stores. If the shop is not linked to a customer the order can be booked but not invoiced.

Formatint64
storeId?|

The merchant's own store booking the order, from List stores.

Formatint64
orderDate?|

Order date, YYYY-MM-DD. Defaults to today.

Formatdate
requestedDeliveryDate?|

Delivery date the customer asked for, YYYY-MM-DD.

Formatdate
routeId?|

The route the order is booked on, if any.

Formatint64
notes?|

Free-text notes.

clientOrderId?|

Your own unique id for this order. Resending the same id returns the order already booked instead of creating another.

source?|

Where the order came from: FIELD_APP (default), BACK_OFFICE, PHONE, PORTAL or IMPORT. Anything other than FIELD_APP needs back-office booking permission.

Value in"FIELD_APP""BACK_OFFICE""PHONE""PORTAL""IMPORT"null
bookedBy?|

Username of the salesperson to credit when someone else keys the order. Defaults to the caller.

submit*boolean

true to create the order as SUBMITTED (ready for review); false keeps it as DRAFT. Non-field-app orders are always created SUBMITTED.

lines*array<>

Order lines; at least one. Each needs an item code and a quantity above zero; price defaults to the item's selling price, tax is computed by the server.

Response Body

OK

*/*
  1. response
status*string

Outcome of the call: SUCCESS when the request was handled, ERROR otherwise.

message*string

Short human-readable message describing the outcome, e.g. which record was fetched or saved.

data?

The sales order.

Example Request
curl -X POST 'https://beta.iotoms.com/api/v1/sales/orders' \  -H 'X-TenantID: your-tenant-code' \  -H 'Content-Type: application/json' \  -d '{  "submit": true,  "lines": [    {      "itemId": "string",      "quantity": 0    }  ]}'
Example Response
{  "status": "string",  "message": "string",  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "orderNumber": "string",    "customerStoreId": 0,    "customerStoreName": "string",    "customerNumber": "string",    "customerNameSnapshot": "string",    "storeId": 0,    "status": "DRAFT",    "effectiveStatus": "DRAFT",    "orderDate": "2019-08-24",    "requestedDeliveryDate": "2019-08-24",    "bookedBy": "string",    "orderSource": "FIELD_APP",    "currency": "string",    "routeId": 0,    "subtotal": 0,    "discountTotal": 0,    "taxTotal": 0,    "grandTotal": 0,    "notes": "string",    "cancelReason": "string",    "overridePending": true,    "overrideApprovedBy": "string",    "overrideApprovedAt": "2019-08-24T14:15:22Z",    "invoiceId": "4f163819-178d-470c-a246-d6768476a6ec",    "invoiceNumber": "string",    "invoiceBlockedReason": "string",    "submittedAt": "2019-08-24T14:15:22Z",    "confirmedAt": "2019-08-24T14:15:22Z",    "cancelledAt": "2019-08-24T14:15:22Z",    "createdBy": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "lines": [      {        "id": 0,        "itemId": "string",        "description": "string",        "uomCode": "string",        "uomFactor": 0,        "quantity": 0,        "baseQuantity": 0,        "unitPrice": 0,        "discountAmount": 0,        "taxRate1": 0,        "taxRate2": 0,        "taxAmount": 0,        "lineTotal": 0,        "lineNumber": 0      }    ],    "revisions": [      {        "revisionNo": 0,        "changedBy": "string",        "changedAt": "2019-08-24T14:15:22Z",        "reason": "string",        "changes": "string"      }    ]  }}