SalesOrders

Creates a sales order, optionally with its lines (the app's New Sales Order page plus its item modal).

Requires ManageSalesOrders and an Idempotency-Key header. Body: { "customerId": 42, "customerPONumber": "PO-7781", "lines": [ { "itemId": 5, "quantity": 10, "unitPrice": 125.00 } ] }. Same code path and defaults as the app: the order is created Pending with the next SO{yy}{MM}{nnnn} number; taxRate omitted or 0 → the organization's default rate, and 0 for a tax-exempt customer; paymentTerms omitted → the organization's default terms; orderDate omitted → now. The customer must exist in this organization and not be marked Difficult, deliveryAddressId must be one of its addresses and each line's itemId a non-deleted catalog item — everything is checked before anything is written. Lines are added as the app adds them: two lines for the same item become one line (quantities add up; a later non-zero price or cost wins), line total = quantity × unit price, then subTotal, taxAmount and totalAmount are computed. The order's history records "Sales order created (via API key '…')". Creating reserves no stock; call POST /api/v1/sales-orders/{id}/fulfill to start fulfilment.

post/api/v1/sales-orders

Request

  • Base URL: https://app.flexonthejob.com
  • URL: https://app.flexonthejob.com/api/v1/sales-orders
  • Auth: HTTP bearer

Request body

customerIdinteger

Customer the order is for (see /api/v1/customers); must be an existing customer of this organization that is not marked Difficult. Example: 42.

customerPONumberstring nullable

The customer's own purchase-order reference, up to 100 characters. Example: PO-7781.

deliveryAddressIdinteger nullable

Id of one of the customer's addresses to deliver to (/api/v1/customers/{id}/locations); omit for none. Example: 77.

orderDatestring date-time nullable

Order date, an organization-local calendar date (yyyy-MM-dd; no UTC offset). Defaults to today's date (server clock), like the New Sales Order page's pre-filled value. Example: 2026-09-23.

requestedDeliveryDatestring date-time nullable

Requested delivery date, an organization-local calendar date (yyyy-MM-dd). Example: 2026-09-30.

paymentTermsstring nullable

Payment terms text, up to 100 characters. Defaults to the organization's default payment terms (else Due on Receipt). Example: Net 30.

taxRatenumber double nullable

Tax rate in percent, 0–100 (8.25 = 8.25 %). Omit or send 0 for the organization's default tax rate; a tax-exempt customer always gets 0. Example: 8.25.

notesstring nullable

Free-text notes on the order. Example: Leave at loading dock.

Response

Created; body is the order as GET /api/v1/sales-orders/{id} returns it, Location points at it.

idinteger

Numeric id used in /api/v1/sales-orders/{id}. Unique within this organization. Example: 318.

syncIdstring uuid

Stable cross-device identifier (GUID) — also the pagination cursor value. Example: 7b1e2c3d-4f5a-4b6c-9d8e-0f1a2b3c4d5e.

orderNumberstring

Order number assigned by the app, SO + two-digit year + two-digit month + a four-digit sequence per month. Example: SO26090007.

statusstring

Order status. One of Pending (created, lines can be added, fulfilment not started or not covering every line), Picking (a pick transfer covers every line and items are being picked), Packed (everything picked), Shipped (every transfer has shipping info), Delivered (every transfer completed), Complete (terminal: marked complete, or delivered and fully invoiced and paid) and Cancelled (terminal). Legacy rows may still say the deprecated Confirmed. Over the API /fulfill starts fulfilment and the later statuses follow from /pick, /complete-pick, /ship and /deliver, as in the app.

paymentStatusstring nullable

Payment status: Pending, Partial, Paid, Overdue, Refunded, Invoiced or Cancelled. Example: Pending. Null on some legacy rows.

fulfillmentStatusstring nullable

Aggregate status of the order's transfers (the earliest one wins): None (no transfer yet), Draft, Pending, InTransit, AtWaypoint, InTransitToWaypoint, InTransitToDestination, Completed, Cancelled, Failed. Example: Pending.

customerIdinteger

Customer id (see /api/v1/customers/{id}). Example: 42.

customerNamestring nullable

Customer name at read time. Example: Acme Plumbing.

customerPONumberstring nullable

The customer's own purchase-order reference; null when none. Example: PO-7781.

orderDatestring date-time

Order date as entered in the app: the organization's local calendar date with no UTC offset (not an instant; do not convert it between time zones). Example: 2026-09-23T00:00:00.

requestedDeliveryDatestring date-time nullable

Requested delivery date, same organization-local calendar-date format as orderDate; null when none. Example: 2026-09-30T00:00:00.

subTotalnumber double

Sum of the line totals, in the organization's currency. Example: 1250.00.

taxRatenumber double

Tax rate in percent (8.25 = 8.25 %). 0 for a tax-exempt customer. Example: 8.25.

taxAmountnumber double

Tax, subTotal × taxRate / 100, in the organization's currency. Example: 103.13.

shippingCostnumber double

Shipping charged on the order, in the organization's currency. Example: 25.00.

totalAmountnumber double

Order total, subTotal + taxAmount + shippingCost, in the organization's currency. Example: 1378.13.

amountPaidnumber double

Amount paid so far, in the organization's currency. Example: 500.00.

balanceDuenumber double

Still owed: totalAmount − amountPaid − store credit applied, in the organization's currency. Example: 878.13.

lineCountinteger

Number of lines on the order (removed lines excluded). Example: 3.

createdAtstring date-time

Creation time, ISO-8601 UTC. Example: 2026-09-23T14:05:00Z.

updatedAtstring date-time nullable

Last recorded modification (header or line edits, lines added or removed, status change, fulfilment and pick progress, fulfillmentStatus change), ISO-8601 UTC; null when never modified since creation. Payments do not move it (paymentStatus / amountPaid / balanceDue can change without it). Example: 2026-09-23T15:12:00Z.

deliveryAddressIdinteger nullable

Id of the customer address the order is delivered to; null when none. Example: 77.

paymentTermsstring nullable

Payment terms text. Example: Net 30. Null when none.

notesstring nullable

Free-text notes on the order. Example: Leave at loading dock. Null when none.

Changes

No recorded changes to this operation across all 1 revision of this API.