List Sales Orders

Beta
GET/v1/sales/sales-orders

This endpoint is idempotent. Learn more

Returns a paginated list of sales orders for the current account, newest first.

A free-text search term (q) is matched as an exact value against the order number and the customer purchase order number, and still respects the other filters. Customer accounts calling this endpoint only ever see their own orders.

Permissions requiredValues:sales_orders:readcustomers:readsuppliers:read
The role behind your API key or agent must grant every one of these permissions.
cursoroptional string

Opaque cursor token identifying where the page of results starts.

Use the cursor value embedded in a previous response's next_page_url or previous_page_url to fetch the adjacent page. Omit to start from the first page.

limitoptional integer

Maximum number of results to return in a single page.

qoptional string

Free-text search term used to filter results.

Which fields are matched against the term varies by endpoint.

status_codes[]optional arrayenumValues:estimateissuedfulfilled

Restricts results to orders in any of these lifecycle statuses.

item_ids[]optional array

Restricts results to orders that have at least one line for any of these inventory items.

product_line_ids[]optional array

Restricts results to orders that have at least one line whose product belongs to any of these product lines.

customer_ids[]optional array

Restricts results to orders placed by any of these customers.

customer_group_ids[]optional array

Restricts results to orders placed by customers belonging to any of these account groups.

sales_rep_ids[]optional array

Restricts results to orders credited to any of these sales reps.

These are account user IDs, matching the sales_rep on the order.

starts_atoptional string

Earliest order creation date to include, in YYYY-MM-DD format.

ends_atoptional string

Latest order creation date to include, in YYYY-MM-DD format.

Compared against the creation timestamp at the start of that day, so orders created later on the end date itself are excluded; pass the following day to include them.

ship_by_afteroptional string

Earliest ship-by date to include, in YYYY-MM-DD format. Inclusive of the date itself.

ship_by_beforeoptional string

Latest ship-by date to include, in YYYY-MM-DD format. Inclusive of the date itself.

past_dueoptional boolean

Restricts results to orders that are, or are not, past their ship-by date.

An order is past due when it is still issued and its ship-by date has passed. A fulfilled order that shipped late is not past due — it is delivered, and how late it was is a delivery-performance question rather than a backlog one.

include[]optional arrayenumValues:customersales_repcreated_by

Sub-objects to expand in the response. When omitted, sub-objects are returned as null.

objectstringenumValues:list

Resource type identifier.

page_infoobject

Pagination metadata.

next_page_urlstringnullable

Relative URL that fetches the next page of results.

previous_page_urlstringnullable

Relative URL that fetches the previous page of results.

has_next_pageboolean

Whether more results exist after this page.

has_prev_pageboolean

Whether results exist before this page.

dataarray of sales_order

Resources in this page.

idstring

Sales order ID.

objectstringenumValues:sales_order

Resource type identifier.

numberstring

Human-readable order number, e.g. SO-001.

Assigned automatically when the order is created; unique within your account.

customer_purchase_order_numberstringnullable

The customer's own purchase order number, for cross-referencing.

Unique among this customer's orders.

notestringnullable

Free-form note about the order.

statusstringenumValues:estimateissuedfulfilled

Order 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:lownormalhigh

Fulfillment priority, used to rank orders on the shop floor.

payment_statusstringenumValues:unpaidpartially_paidpaid

Payment state of the order, derived from settlement allocations, invoices, and Stripe payments.

payment_intent_idsarray of string

Stripe payment intent IDs recorded against this order.

acknowledgment_statusstringenumValues:not_sentsent

Whether 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.

customercustomerExpandablenullable

The customer this order is for.

idstring

Customer ID.

objectstringenumValues:customer

Resource type identifier.

namestring

The customer's business name, as shown throughout the app and on documents.

numberstring

Human-readable customer number used to identify the account, distinct from the id.

Unique within your account.

statusstringenumValues:normalpreferredhold_shipment

The 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:enableddisabled

Whether EDI (Electronic Data Interchange) is enabled for exchanging orders and documents with this customer.

relationship_typestringenumValues:standaloneparentchild

The customer's position in the account hierarchy.

  • standalone: no parent or child accounts.
  • parent: has one or more child accounts (see child_accounts).
  • child: belongs to a parent account (see parent_account).
commission_policystringenumValues:commission_appliedcommission_exempt

How 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.

notestringnullable

Free-form note about the customer.

credit_limitquantitynullable

Maximum 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.

Always returned as null in this endpoint.
contact_infocustomer_contact_infonullable

General contact details for the customer's business.

Always returned as null in this endpoint.
freight_preferencescustomer_freight_preferencesnullable

Freight and carrier preferences applied to this customer's shipments.

Always returned as null in this endpoint.
defaultscustomer_defaultsnullable

Default settings applied to new orders for this customer.

Always returned as null in this endpoint.
notification_preferencescustomer_notification_preferencesnullable

Which document emails this customer is set up to receive.

Always returned as null in this endpoint.
bill_to_addressaddressnullable

Default billing address.

Always returned as null in this endpoint.
ship_to_addressaddressnullable

Default shipping address.

Always returned as null in this endpoint.
typeaccount_groupnullable

The account group of type type_group that categorizes this customer (for example "Distributors").

Always returned as null in this endpoint.
price_groupslistnullable

Account groups of type pricing_group that this customer belongs to, used to apply pricing rules.

Always returned as null in this endpoint.
parent_accountcustomernullable

The customer this account belongs to, when it is a child account.

Always returned as null in this endpoint.
child_accountslistnullable

The customers belonging to this account, when it is a parent account.

Always returned as null in this endpoint.
created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

sales_repactorExpandablenullable

The 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.

idstring

Unique identifier of the actor.

objectstringenumValues:actor

Resource type identifier.

typestringenumValues:userapi_keyagent

Actor 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.
namestringnullable

The actor's display name.

handlestringnullable

Human-readable handle identifying the actor.

  • For user actors: the user's email address.
  • For api_key actors: the redacted key value.

Other actor types carry no handle.

avatar_urlstringnullable

URL of the actor's profile photo, if one is set.

Only populated for user actors.

rolerolenullable

The role the actor holds in the account, which determines what it is permitted to do.

Always returned as null in this endpoint.
created_bycreated_byExpandablenullable

Who created this order, and their relation (internal/customer/system).

objectstringenumValues:created_by

Resource type identifier.

relationstringenumValues:internalcustomersystem

The creator's relationship to the account that owns the resource.

  • internal: created by a user of the owning account.
  • customer: created by a customer of the owning account.
  • system: created automatically with no human actor (e.g. an EDI import).
actoractornullable

The actor who created the resource.

Absent when relation is system, since no human or programmatic actor performed the action.

Always returned as null in this endpoint.
bill_to_addressaddressExpandablenullable

Address the order is billed to.

idstring

Address ID.

objectstringenumValues:address

Resource type identifier.

namestring

Display name of the address.

phonestringnullable

Phone number associated with the address.

emailstringnullable

Email address associated with the address.

typestringenumValues:standarddrop_ship

How 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_idstringnullable

The 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.

geolocationgeolocationnullable

Street-level location details for the address.

Always returned as null in this endpoint.
created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

ship_to_addressaddressExpandablenullable

Address the order ships to.

idstring

Address ID.

objectstringenumValues:address

Resource type identifier.

namestring

Display name of the address.

phonestringnullable

Phone number associated with the address.

emailstringnullable

Email address associated with the address.

typestringenumValues:standarddrop_ship

How 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_idstringnullable

The 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.

geolocationgeolocationnullable

Street-level location details for the address.

Always returned as null in this endpoint.
created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

freightfreightExpandablenullable

Carrier selection and freight billing for this order.

The freight charge itself is carried as a line on the order, not on this object.

objectstringenumValues:freight

Resource type identifier.

policystringnullableenumValues:free_freightbilled_freight

How 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.

carriercarriernullable

The shipping carrier selected to fulfill the shipment.

Always returned as null in this endpoint.
service_levelservice_levelnullable

The carrier service level selected for the shipment (e.g. ground, overnight).

Always returned as null in this endpoint.
billing_typestringnullableenumValues:senderthird_party

Which party the carrier bills for the shipment.

  • sender: the shipper (your account) is billed.
  • third_party: a third party is billed via billing_account_number.
billing_account_numberstringnullable

Carrier account number to bill, used when billing_type is third_party.

payment_termpayment_termExpandablenullable

Payment terms agreed for this order.

idstring

Payment term ID.

objectstringenumValues:payment_term

Resource type identifier.

namestring

Display name (e.g. Net 30), unique among the payment terms visible to your account.

statusstringenumValues:activeinactive

Whether 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.

ownerownernullable

Provenance 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.

Always returned as null in this endpoint.
created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last-updated timestamp.

shipping_termshipping_termExpandablenullable

Shipping terms agreed for this order.

idstring

Shipping term ID.

objectstringenumValues:shipping_term

Resource type identifier.

namestring

Human-readable name for the shipping term, used to identify it when assigning shipping terms to customers and orders.

typestringenumValues:free_freightflat_rate_freightcarrier_rate_freight

Freight 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 in flat_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.
ownerownernullable

Provenance 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.

Always returned as null in this endpoint.
flat_ratequantitynullable

Fixed 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.

Always returned as null in this endpoint.
minimum_order_valuequantitynullable

Order 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.

Always returned as null in this endpoint.
free_shipping_service_levelslistnullable

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.

Always returned as 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_discountorder_discountExpandablenullable

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.

idstring

Order discount ID.

objectstringenumValues:order_discount

Resource type identifier.

namestring

Display name of the discount.

codestring

The 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:percentageamount

How the discount is calculated.

  • percentage: the order total is reduced by the fraction in percentage.
  • amount: the order total is reduced by the flat amount in amount.
order_countinteger

How 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.

lineslistExpandablenullable

The order's lines, including the automatically generated freight and discount lines.

objectstringenumValues:list

Resource type identifier.

page_infoobject

Pagination metadata.

next_page_urlstringnullable

Relative URL that fetches the next page of results.

previous_page_urlstringnullable

Relative URL that fetches the previous page of results.

has_next_pageboolean

Whether more results exist after this page.

has_prev_pageboolean

Whether results exist before this page.

dataarray of sales_order_line

Resources in this page.

idstring

Sales order line ID.

objectstringenumValues:sales_order_line

Resource type identifier.

line_item_numberinteger

Position 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_skustring

SKU 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_descriptionstringnullable

Description recorded on this line, taken from the product unless the line supplies its own.

itemitemnullable

The item this line sells, identified by the SKU recorded when the line was created.

Always returned as null in this endpoint.
productproductnullable

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.

Always returned as null in this endpoint.
quantity_orderedquantitynullable

Quantity ordered.

Always returned as null in this endpoint.
unit_priceratenullable

Price charged per unit.

Always returned as null in this endpoint.
unit_costratenullable

Internal cost per unit.

Reflects what the business pays for the item, not what the customer is charged, and is used to derive line profitability.

Always returned as null in this endpoint.
totalssales_order_totalsnullable

Derived monetary totals for this line.

Always returned as null in this endpoint.
created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

line_countinteger

Number of lines on this order.

totalssales_order_totalsExpandablenullable

Derived monetary totals and per-stage fulfillment progress.

objectstringenumValues:sales_order_totals

Resource 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_total

Picked amount and completion.

Always returned as null in this endpoint.
packedsales_order_stage_total

Packed amount and completion.

Always returned as null in this endpoint.
invoicedsales_order_stage_total

Invoiced amount and completion.

Always returned as null in this endpoint.
relatedsales_order_relatednullable

Fulfillment records produced from this order.

objectstringenumValues:sales_order_related

Resource type identifier.

pickrecordExpandablenullable

The pick created when the order was issued.

idstring

Unique identifier for the record.

objectstringenumValues:record

Resource type identifier.

typestringenumValues:sales_orderpurchase_orderreceiving_order

The 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.
numberstringnullable

Human-readable record number, when the record has one.

statusstringnullable

Type-specific status code, when applicable.

metadataobject

Type-specific metadata.

The set of keys varies by record type.

production_runrecordExpandablenullable

The production run created for this order, if one was started.

idstring

Unique identifier for the record.

objectstringenumValues:record

Resource type identifier.

typestringenumValues:sales_orderpurchase_orderreceiving_order

The 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.
numberstringnullable

Human-readable record number, when the record has one.

statusstringnullable

Type-specific status code, when applicable.

metadataobject

Type-specific metadata.

The set of keys varies by record type.

shipmentslistExpandablenullable

Shipments made against this order.

objectstringenumValues:list

Resource type identifier.

page_infoobject

Pagination metadata.

next_page_urlstringnullable

Relative URL that fetches the next page of results.

previous_page_urlstringnullable

Relative URL that fetches the previous page of results.

has_next_pageboolean

Whether more results exist after this page.

has_prev_pageboolean

Whether results exist before this page.

dataarray of record

Resources in this page.

idstring

Unique identifier for the record.

objectstringenumValues:record

Resource type identifier.

typestringenumValues:sales_orderpurchase_orderreceiving_order

The 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.
numberstringnullable

Human-readable record number, when the record has one.

statusstringnullable

Type-specific status code, when applicable.

metadataobject

Type-specific metadata.

The set of keys varies by record type.

invoiceslistExpandablenullable

Invoices raised against this order.

objectstringenumValues:list

Resource type identifier.

page_infoobject

Pagination metadata.

next_page_urlstringnullable

Relative URL that fetches the next page of results.

previous_page_urlstringnullable

Relative URL that fetches the previous page of results.

has_next_pageboolean

Whether more results exist after this page.

has_prev_pageboolean

Whether results exist before this page.

dataarray of record

Resources in this page.

idstring

Unique identifier for the record.

objectstringenumValues:record

Resource type identifier.

typestringenumValues:sales_orderpurchase_orderreceiving_order

The 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.
numberstringnullable

Human-readable record number, when the record has one.

statusstringnullable

Type-specific status code, when applicable.

metadataobject

Type-specific metadata.

The set of keys varies by record type.

contactsorder_contactExpandablenullable

Email recipients grouped by notification purpose.

objectstringenumValues:order_contact

Resource type identifier.

invoicearray of string

Email addresses that receive invoices for this order.

acknowledgementarray of string

Email addresses that receive order acknowledgements for this order.

issued_atstring (date-time)nullable

When the order was issued (moved out of estimate).

completed_atstring (date-time)nullable

When the order was fulfilled and closed.

first_ship_atstring (date-time)nullable

When the first shipment against this order went out.

expired_atstring (date-time)nullable

When this estimate expires, if an expiration was set.

promised_atstring (date-time)nullable

Date promised to the customer for delivery, if one was committed.

lead_time_override_daysintegernullable

Days 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)nullable

The ship date pinned on this order, bypassing transit and the customer's receiving days.

ship_by_datestring (date-time)nullable

Date 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)nullable

The 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_daysintegernullable

Days 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_daysintegernullable

Calendar days between issue and the ship-by date.

lead_time_sourcestringnullableenumValues:customerparent_customeraccount_group

Which rule produced the ship-by date.

transit_daysintegernullable

Business 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_level

Where the transit estimate came from.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

Responses

200

Successful response for List Sales Orders