Create Sales Order
Beta/v1/sales/sales-ordersIdempotent with Idempotency-Key header. Learn more
Creates a sales order in estimate status.
The order number is assigned automatically, and a sales rep is auto-assigned when none is provided. Line prices and costs are resolved server-side from each product. A shipping line carrying the estimated freight charge is added to the order, plus a negative-priced discount line when an order discount is supplied. The order is not committed for fulfillment until it is issued.
include[]optional arrayenumValues:customersales_repbill_to_addressSub-objects to expand in the response. When omitted, sub-objects are returned as null.
buyer_account_idstringID of the customer account the order is for.
customer_purchase_order_numberoptional stringThe customer's own purchase order number, for cross-referencing.
Must be unique among your orders for this customer.
noteoptional stringFree-form note about the order.
carrier_idoptional stringID of the carrier that will ship the order.
Falls back to the customer's default carrier; the order is rejected when neither is available.
service_level_idoptional stringID of the carrier service level the order ships on.
Falls back to the customer's default service level, but only when carrier_id is also omitted — supplying a carrier without a service level leaves the service level unset.
carrier_billing_typeoptional stringenumValues:senderthird_partyWho is billed for freight.
sender: the sender pays for shipping.third_party: a third party pays for shipping, using the carrier billing account number.
carrier_billing_account_numberoptional stringCarrier billing account number charged when carrier_billing_type is third_party.
priority_codestringenumValues:lownormalhighFulfillment priority used to rank the order on the shop floor.
sales_rep_idoptional stringID of the account user to credit as the order's sales rep.
When omitted, a rep is assigned automatically: the customer's default sales rep first, then the sales territory matching the ship-to postal code, then the ship-to state. No rep is assigned when the customer is commission-exempt or every ordered product belongs to a commission-exempt product line.
shipping_term_idoptional stringID of the shipping terms for the order.
Falls back to the customer's default shipping term; the order is rejected when neither is available.
payment_term_idoptional stringID of the payment terms for the order.
Falls back to the customer's default payment term; the order is rejected when neither is available.
order_discount_idoptional stringThe order-level discount to apply, given as either its ID or its unique code.
The discount is realized as an extra negative-priced line on the order rather than as a separate total.
promised_atoptional string (date-time)Date delivery is promised to the customer.
The order's ship-by date is worked back from this: the goods have to reach the customer on a day they receive, so transit and both operating calendars are subtracted from it. Mutually exclusive with lead_time_override_days and ship_by_override_date.
lead_time_override_daysoptional integerDays between this order being issued and it being due to ship, replacing the customer's standing lead time for this order alone.
Already a ship lead time, so no carrier transit is subtracted from it. Mutually exclusive with promised_at and ship_by_override_date.
ship_by_override_dateoptional string (date-time)The exact date the order is due to ship, bypassing transit and the customer's receiving days.
Still moved back to the nearest earlier day the plant ships on, since a date nobody can ship on is not a deadline. Mutually exclusive with promised_at and lead_time_override_days.
bill_to_address_idstringBill-to address ID.
Must reference an existing address on the order's owner or buyer account.
ship_to_address_idstringShip-to address ID.
Must reference an existing address on the order's owner or buyer account.
linesarray of objectThe line items to put on the order.
The freight line, and the discount line when order_discount_id is supplied, are added on top of these automatically.
product_idstringID of the product being ordered.
quantityobjectQuantity ordered.
valuestring (decimal)Decimal value, as a string to preserve precision.
unit_idstringID of the unit of measure for the value.
product_skuoptional stringSKU recorded on the line.
Defaults to the product's SKU when omitted.
product_descriptionoptional stringDescription recorded on the line.
Defaults to the product's description when omitted.
unit_priceoptional objectUnit price override.
Honored only for internal users; for customer accounts it is ignored and the price is calculated server-side.
valuestring (decimal)Decimal value of the rate, expressed as the amount of the numerator unit per one denominator unit.
numerator_unit_idstringID of the unit for the rate's numerator (e.g. the currency of a price).
denominator_unit_idstringID of the unit for the rate's denominator (the per-unit basis).
acknowledgement_email_contactsoptional array of objectUsers who should receive order acknowledgement emails for this order.
Each must be a user on the customer's account.
account_user_idstringID of the account user who should receive the notification.
invoice_email_contactsoptional array of objectUsers who should receive invoice emails for this order.
Each must be a user on the customer's account.
account_user_idstringID of the account user who should receive the notification.
idstringSales order ID.
objectstringenumValues:sales_orderResource type identifier.
numberstringHuman-readable order number, e.g. SO-001.
Assigned automatically when the order is created; unique within your account.
customer_purchase_order_numberstringnullableThe customer's own purchase order number, for cross-referencing.
Unique among this customer's orders.
notestringnullableFree-form note about the order.
statusstringenumValues:estimateissuedfulfilledOrder lifecycle status.
estimate: a draft quote that has not yet been committed; not counted as a real order.issued: the order has been issued and is being fulfilled.fulfilled: the order has been completed and closed.
Status changes are made through the issue, unissue, close, and reopen action endpoints rather than by updating this field.
prioritystringenumValues:lownormalhighFulfillment priority, used to rank orders on the shop floor.
payment_statusstringenumValues:unpaidpartially_paidpaidPayment state of the order, derived from settlement allocations, invoices, and Stripe payments.
payment_intent_idsarray of stringStripe payment intent IDs recorded against this order.
acknowledgment_statusstringenumValues:not_sentsentWhether an order acknowledgment has been sent to the customer.
Becomes sent when the order is issued with customer notification requested and the order has acknowledgement contacts to send to. It can also be set directly when an acknowledgement was sent outside OpenMRP.
The customer this order is for.
idstringCustomer ID.
objectstringenumValues:customerResource type identifier.
namestringThe customer's business name, as shown throughout the app and on documents.
numberstringHuman-readable customer number used to identify the account, distinct from the id.
Unique within your account.
statusstringenumValues:normalpreferredhold_shipmentThe customer's account standing.
normal: standard account with no restrictions.preferred: account flagged for prioritized handling.hold_shipment: the customer's shipments should be held, typically over a credit problem, while orders can still be placed.hold_all: all activity for the customer should be held.
The hold statuses are advisory: OpenMRP flags the customer's orders as being on credit hold, but requests to create orders or shipments for the customer are not rejected.
edi_statusstringenumValues:enableddisabledWhether EDI (Electronic Data Interchange) is enabled for exchanging orders and documents with this customer.
relationship_typestringenumValues:standaloneparentchildThe customer's position in the account hierarchy.
standalone: no parent or child accounts.parent: has one or more child accounts (seechild_accounts).child: belongs to a parent account (seeparent_account).
commission_policystringenumValues:commission_appliedcommission_exemptHow sales commission applies to this customer's orders.
commission_exempt: this customer's orders are exempt from sales commission.commission_applied: sales commission is calculated on this customer's orders.
The customer counts as exempt if this field, its type group, or any of its price_groups is commission_exempt. Exempt customers never have a sales rep assigned automatically when an order is created without one.
notestringnullableFree-form note about the customer.
credit_limitquantitynullableMaximum credit extended to this customer.
Used to flag orders once the customer's outstanding balance approaches or passes the limit; orders that exceed it are not rejected.
null in this endpoint.contact_infocustomer_contact_infonullableGeneral contact details for the customer's business.
null in this endpoint.freight_preferencescustomer_freight_preferencesnullableFreight and carrier preferences applied to this customer's shipments.
null in this endpoint.defaultscustomer_defaultsnullableDefault settings applied to new orders for this customer.
null in this endpoint.notification_preferencescustomer_notification_preferencesnullableWhich document emails this customer is set up to receive.
null in this endpoint.Default billing address.
null in this endpoint.Default shipping address.
null in this endpoint.The account group of type type_group that categorizes this customer (for example "Distributors").
null in this endpoint.Account groups of type pricing_group that this customer belongs to, used to apply pricing rules.
null in this endpoint.The customer this account belongs to, when it is a child account.
null in this endpoint.The customers belonging to this account, when it is a parent account.
null in this endpoint.created_atstring (date-time)Creation timestamp.
updated_atstring (date-time)Last updated timestamp.
sales_repactorExpandablenullableThe sales representative credited with the order.
Chosen automatically at creation when none is supplied, from the customer's default rep or the sales territory covering the ship-to address.
idstringUnique identifier of the actor.
objectstringenumValues:actorResource type identifier.
typestringenumValues:userapi_keyagentActor type.
user: a human user account.api_key: a programmatic caller authenticating with an API key.agent: an automated agent acting on the account's behalf.group: a shared group identity, such as a "Customer Service" persona, rather than a single individual.
namestringnullableThe actor's display name.
handlestringnullableHuman-readable handle identifying the actor.
- For
useractors: the user's email address. - For
api_keyactors: the redacted key value.
Other actor types carry no handle.
avatar_urlstringnullableURL of the actor's profile photo, if one is set.
Only populated for user actors.
The role the actor holds in the account, which determines what it is permitted to do.
null in this endpoint.created_bycreated_bynullableWho created this order, and their relation (internal/customer/system).
Address the order is billed to.
idstringAddress ID.
objectstringenumValues:addressResource type identifier.
namestringDisplay name of the address.
phonestringnullablePhone number associated with the address.
emailstringnullableEmail address associated with the address.
typestringenumValues:standarddrop_shipHow the address is used.
standard: a normal shipping or billing address.drop_ship: an address an order is shipped to directly, typically a third party or end customer rather than the account itself.
receive_calendar_idstringnullableThe operating calendar naming the days this dock accepts freight.
The most specific link in the receiving chain: set it when one of a customer's sites keeps different days from the rest. Null falls through to the customer, then their group, then the account default.
geolocationgeolocationnullableStreet-level location details for the address.
null in this endpoint.created_atstring (date-time)Creation timestamp.
updated_atstring (date-time)Last updated timestamp.
Address the order ships to.
idstringAddress ID.
objectstringenumValues:addressResource type identifier.
namestringDisplay name of the address.
phonestringnullablePhone number associated with the address.
emailstringnullableEmail address associated with the address.
typestringenumValues:standarddrop_shipHow the address is used.
standard: a normal shipping or billing address.drop_ship: an address an order is shipped to directly, typically a third party or end customer rather than the account itself.
receive_calendar_idstringnullableThe operating calendar naming the days this dock accepts freight.
The most specific link in the receiving chain: set it when one of a customer's sites keeps different days from the rest. Null falls through to the customer, then their group, then the account default.
geolocationgeolocationnullableStreet-level location details for the address.
null in this endpoint.created_atstring (date-time)Creation timestamp.
updated_atstring (date-time)Last updated timestamp.
freightfreightExpandablenullableCarrier selection and freight billing for this order.
The freight charge itself is carried as a line on the order, not on this object.
objectstringenumValues:freightResource type identifier.
policystringnullableenumValues:free_freightbilled_freightHow freight is arranged and billed for the record.
free_freight: no shipping cost to the buyer.billed_freight: freight is billed to the buyer.
Sales orders, purchase orders, and shipments do not carry a policy of their own. Freight on those records is waived when the customer's freight preferences, the customer's type group, any of its pricing groups, the customer's shipping term, or any product line on the order is free_freight.
The shipping carrier selected to fulfill the shipment.
null in this endpoint.The carrier service level selected for the shipment (e.g. ground, overnight).
null in this endpoint.billing_typestringnullableenumValues:senderthird_partyWhich party the carrier bills for the shipment.
sender: the shipper (your account) is billed.third_party: a third party is billed viabilling_account_number.
billing_account_numberstringnullableCarrier account number to bill, used when billing_type is third_party.
Payment terms agreed for this order.
idstringPayment term ID.
objectstringenumValues:payment_termResource type identifier.
namestringDisplay name (e.g. Net 30), unique among the payment terms visible to your account.
statusstringenumValues:activeinactiveWhether this payment term is still in active use.
Payment terms created through the API are always active, and no endpoint changes a term's status. List Payment Terms returns inactive terms alongside active ones, so filter them out yourself if you only want the ones still on offer.
ownerownernullableProvenance of this payment term.
System-owned payment terms are platform-provided defaults shared across all accounts and cannot be updated or deleted; account-owned payment terms are custom to your account.
null in this endpoint.created_atstring (date-time)Creation timestamp.
updated_atstring (date-time)Last-updated timestamp.
Shipping terms agreed for this order.
idstringShipping term ID.
objectstringenumValues:shipping_termResource type identifier.
namestringHuman-readable name for the shipping term, used to identify it when assigning shipping terms to customers and orders.
typestringenumValues:free_freightflat_rate_freightcarrier_rate_freightFreight pricing model applied by this shipping term.
free_freight: the buyer is never charged for shipping.flat_rate_freight: the buyer is charged the fixed amount inflat_rate, regardless of what the carrier would have charged.carrier_rate_freight: the buyer is charged the rate the carrier quotes for the order's carrier and service level.
ownerownernullableProvenance of this shipping term.
System-owned shipping terms are platform-provided defaults shared across all accounts and cannot be updated or deleted; account-owned shipping terms are custom to your account.
null in this endpoint.flat_ratequantitynullableFixed shipping charge applied to the order.
Used only when type is flat_rate_freight; ignored for other freight pricing models. A flat_rate_freight term with no flat rate falls through to the carrier's quoted rate.
null in this endpoint.minimum_order_valuequantitynullableOrder total a buyer must exceed for this term's free-shipping rules to apply.
Above this total, freight is free for the service levels in free_shipping_service_levels.
null in this endpoint.Service levels that ship for free once an order exceeds minimum_order_value.
When this list is empty, every service level ships free above the threshold. When it is not empty, an order that picks a service level outside the list is not shipped free even above the threshold.
null in this endpoint.created_atstring (date-time)When this shipping term was created.
updated_atstring (date-time)When this shipping term was last updated.
Order-level discount applied to this order.
The discount is charged through a negative-priced line on the order, so it is already reflected in the order totals.
idstringOrder discount ID.
objectstringenumValues:order_discountResource type identifier.
namestringDisplay name of the discount.
codestringThe code a buyer enters to apply this discount to an order.
Codes are unique within your account and are matched without regard to letter case.
percentagestring (decimal)The fraction of the order total taken off, as a decimal string.
This is a multiplier, not a whole percent: 0.1 takes 10% off. Only read when discount_type is percentage.
amountstring (decimal)The flat amount taken off the order total, as a decimal string.
Only read when discount_type is amount.
discount_typestringenumValues:percentageamountHow the discount is calculated.
percentage: the order total is reduced by the fraction inpercentage.amount: the order total is reduced by the flat amount inamount.
order_countintegerHow many sales orders this discount has been applied to, across all buyers.
created_atstring (date-time)Creation timestamp.
updated_atstring (date-time)Last updated timestamp.
The order's lines, including the automatically generated freight and discount lines.
objectstringenumValues:listResource type identifier.
page_infoobjectPagination metadata.
next_page_urlstringnullableRelative URL that fetches the next page of results.
previous_page_urlstringnullableRelative URL that fetches the previous page of results.
has_next_pagebooleanWhether more results exist after this page.
has_prev_pagebooleanWhether results exist before this page.
dataarray of sales_order_lineResources in this page.
idstringSales order line ID.
objectstringenumValues:sales_order_lineResource type identifier.
line_item_numberintegerPosition of the line on the order.
Assigned automatically in sequence, starting at 1. Product lines are numbered first and the automatically generated freight and discount lines always sit at the bottom; removing a line renumbers the rest so the sequence stays contiguous.
product_skustringSKU recorded on this line.
Taken from the product unless the line supplies its own, and editable afterwards, so it preserves what was sold even if the product's SKU later changes.
product_descriptionstringnullableDescription recorded on this line, taken from the product unless the line supplies its own.
The item this line sells, identified by the SKU recorded when the line was created.
null in this endpoint.The product being sold on this line.
The product's type tells you what kind of line this is: the freight and discount lines an order generates for itself reference the account's built-in shipping and credit products, so their type is shipping or credit rather than sale.
null in this endpoint.quantity_orderedquantitynullableQuantity ordered.
null in this endpoint.unit_priceratenullablePrice charged per unit.
null in this endpoint.unit_costratenullableInternal cost per unit.
Reflects what the business pays for the item, not what the customer is charged, and is used to derive line profitability.
null in this endpoint.totalssales_order_totalsnullableDerived monetary totals for this line.
null in this endpoint.created_atstring (date-time)Creation timestamp.
updated_atstring (date-time)Last updated timestamp.
line_countintegerNumber of lines on this order.
totalssales_order_totalsExpandablenullableDerived monetary totals and per-stage fulfillment progress.
objectstringenumValues:sales_order_totalsResource type identifier.
orderedstring (decimal)Total ordered amount as a decimal string (unit price x quantity ordered).
This is the baseline the stage completions are measured against.
pickedsales_order_stage_totalPicked amount and completion.
null in this endpoint.packedsales_order_stage_totalPacked amount and completion.
null in this endpoint.invoicedsales_order_stage_totalInvoiced amount and completion.
null in this endpoint.relatedsales_order_relatednullableFulfillment records produced from this order.
objectstringenumValues:sales_order_relatedResource type identifier.
pickrecordExpandablenullableThe pick created when the order was issued.
idstringUnique identifier for the record.
objectstringenumValues:recordResource type identifier.
typestringenumValues:sales_orderpurchase_orderreceiving_orderThe kind of business record referenced.
Determines how to resolve the record and which status and metadata keys may appear.
sales_order: a customer order.purchase_order: an order placed with a supplier.receiving_order: an inbound order being received into inventory.pick: a warehouse pick task.shipment: an outbound shipment.delivery: a delivery of one or more shipments to a destination.production_run: a manufacturing production run.invoice: a customer invoice.transaction: a payment or financial transaction.settlement: a settlement reconciling transactions against invoices.
numberstringnullableHuman-readable record number, when the record has one.
statusstringnullableType-specific status code, when applicable.
metadataobjectType-specific metadata.
The set of keys varies by record type.
production_runrecordExpandablenullableThe production run created for this order, if one was started.
idstringUnique identifier for the record.
objectstringenumValues:recordResource type identifier.
typestringenumValues:sales_orderpurchase_orderreceiving_orderThe kind of business record referenced.
Determines how to resolve the record and which status and metadata keys may appear.
sales_order: a customer order.purchase_order: an order placed with a supplier.receiving_order: an inbound order being received into inventory.pick: a warehouse pick task.shipment: an outbound shipment.delivery: a delivery of one or more shipments to a destination.production_run: a manufacturing production run.invoice: a customer invoice.transaction: a payment or financial transaction.settlement: a settlement reconciling transactions against invoices.
numberstringnullableHuman-readable record number, when the record has one.
statusstringnullableType-specific status code, when applicable.
metadataobjectType-specific metadata.
The set of keys varies by record type.
Shipments made against this order.
objectstringenumValues:listResource type identifier.
page_infoobjectPagination metadata.
next_page_urlstringnullableRelative URL that fetches the next page of results.
previous_page_urlstringnullableRelative URL that fetches the previous page of results.
has_next_pagebooleanWhether more results exist after this page.
has_prev_pagebooleanWhether results exist before this page.
dataarray of recordResources in this page.
idstringUnique identifier for the record.
objectstringenumValues:recordResource type identifier.
typestringenumValues:sales_orderpurchase_orderreceiving_orderThe kind of business record referenced.
Determines how to resolve the record and which status and metadata keys may appear.
sales_order: a customer order.purchase_order: an order placed with a supplier.receiving_order: an inbound order being received into inventory.pick: a warehouse pick task.shipment: an outbound shipment.delivery: a delivery of one or more shipments to a destination.production_run: a manufacturing production run.invoice: a customer invoice.transaction: a payment or financial transaction.settlement: a settlement reconciling transactions against invoices.
numberstringnullableHuman-readable record number, when the record has one.
statusstringnullableType-specific status code, when applicable.
metadataobjectType-specific metadata.
The set of keys varies by record type.
Invoices raised against this order.
objectstringenumValues:listResource type identifier.
page_infoobjectPagination metadata.
next_page_urlstringnullableRelative URL that fetches the next page of results.
previous_page_urlstringnullableRelative URL that fetches the previous page of results.
has_next_pagebooleanWhether more results exist after this page.
has_prev_pagebooleanWhether results exist before this page.
dataarray of recordResources in this page.
idstringUnique identifier for the record.
objectstringenumValues:recordResource type identifier.
typestringenumValues:sales_orderpurchase_orderreceiving_orderThe kind of business record referenced.
Determines how to resolve the record and which status and metadata keys may appear.
sales_order: a customer order.purchase_order: an order placed with a supplier.receiving_order: an inbound order being received into inventory.pick: a warehouse pick task.shipment: an outbound shipment.delivery: a delivery of one or more shipments to a destination.production_run: a manufacturing production run.invoice: a customer invoice.transaction: a payment or financial transaction.settlement: a settlement reconciling transactions against invoices.
numberstringnullableHuman-readable record number, when the record has one.
statusstringnullableType-specific status code, when applicable.
metadataobjectType-specific metadata.
The set of keys varies by record type.
contactsorder_contactExpandablenullableEmail recipients grouped by notification purpose.
objectstringenumValues:order_contactResource type identifier.
invoicearray of stringEmail addresses that receive invoices for this order.
acknowledgementarray of stringEmail addresses that receive order acknowledgements for this order.
issued_atstring (date-time)nullableWhen the order was issued (moved out of estimate).
completed_atstring (date-time)nullableWhen the order was fulfilled and closed.
first_ship_atstring (date-time)nullableWhen the first shipment against this order went out.
expired_atstring (date-time)nullableWhen this estimate expires, if an expiration was set.
promised_atstring (date-time)nullableDate promised to the customer for delivery, if one was committed.
lead_time_override_daysintegernullableDays between issue and the ship-by date, set on this order alone in place of the customer's standing lead time.
ship_by_override_datestring (date-time)nullableThe ship date pinned on this order, bypassing transit and the customer's receiving days.
ship_by_datestring (date-time)nullableDate this order is contractually due to ship.
Stamped when the order is issued. With a promised delivery date, this is that date less the carrier's transit for the order's lane and less any day the customer cannot receive on — the day the order has to leave to arrive when promised. Otherwise it comes from a lead time, whether this order's own or the one on the customer, its parent account, its account group, or the account.
Always a day the plant actually ships on, whichever rule produced it.
It is not recomputed afterwards, so neither renegotiating a customer's lead time, nor a later carrier estimate, nor a holiday added to a calendar moves commitments already made. Cleared if the order is unissued.
ship_by_cutoff_atstring (date-time)nullableThe ship-by date at the plant's pickup cutoff — the moment freight has to be tendered by, not just the day.
Only set when the account's shipping calendar carries a cutoff time.
calendar_adjustment_daysintegernullableDays the customer's receiving calendar and the plant's shipping calendar pulled the ship-by date back, beyond what carrier transit accounted for.
Zero means every date along the way already fell on an open day. This is what explains a ship-by date that is earlier than transit alone would suggest.
lead_time_daysintegernullableCalendar days between issue and the ship-by date.
lead_time_sourcestringnullableenumValues:customerparent_customeraccount_groupWhich rule produced the ship-by date.
transit_daysintegernullableBusiness days the carrier needs to cover this order's lane, subtracted from the promised delivery date to reach the ship-by date.
Only set when a delivery date was promised and the lane could be priced. Without it the ship-by date falls back to the promised date itself.
transit_sourcestringnullableenumValues:carrier_laneservice_levelWhere the transit estimate came from.
created_atstring (date-time)Creation timestamp.
updated_atstring (date-time)Last updated timestamp.
Responses
Successful response for Create Sales Order