Get a sales order or quote
AI agents: read /llms.txt; add .md to any page URL. This page as Markdown: /reference/sales-orders/v2-order-show.md. Index of every page and the rules for every call: /llms.txt. Guides and concepts in one file: /llms-full.txt. OpenAPI: /openapi.json.
GET/
Returns one sales order or quote with its line items (items), customer and message participants.
{order_unique_key} is the sales order or quote id (for example V4keXwwxMQyXw7) or its unique_key (it starts with ord_). The order number people see, such as SO1001, is not accepted here. Deleted orders are returned too (trashed: true).
The answer is the order: its id and unique_key, scoped_id (the number people see), name, object_type (sales_order or quote), internal_status (draft until published), status_id and status, the customer and addresses, dates, notes, is_rush, pricing settings and totals. The value of the order's lines is order_item_cart_total. invoiced_total, invoiced_order_item_subtotal, invoiced_shipment_subtotal, invoiced_tax_subtotal and invoiced_discount_subtotal count only what has been invoiced (0 until the order has an invoice). They are decimal pairs ({ "value": 850000, "dp": 4 } is 85.00; always read dp). paid_amount, calc_deposit_total and unallocated_amount are in thousandths (135000 is 135.00). deposit_total is a percentage ×1000 (50000 is 50%). calc_subtotal, calc_discount, calc_tax and calc_total are deprecated thousandths copies of the invoiced totals: they still return, but use the decimal pair fields instead.
Path parameters
Your team slug, shown as Team ID next to your API key in Profile.
- Example
your-team
- Example
The sales order's or quote's
id(a hash id), or itsunique_key(ord_…). The order number (scoped_id) does not work.- Example
V4keXwwxMQyXw7
- Example
Request body
This operation takes no request body.
Response
200Successful response.
A sales order or quote.
Child fields (112)
The order's hash id: use it in every other call.
draftuntil published.- One of:
"draft","published"
- One of:
- One of:
"sales_order","quote"
- One of:
The order number people see,
SOand at least four digits (quotes too). Not an id.The order's unique key (
ord_…); accepted wherever{order_unique_key}is.approval_statusstring | nullrequested,sent-to-customer,viewed-by-customer,need-changesorapproved; null without approvals.assigned_usersarray of objectsThe team members in the order's Assigned To list (always included).
Fields of each item (5)
avatar_urlstring | nullemailstringidstringnamestringtimezonestring | nullIANA time zone, for example
America/Chicago.
auto_invoice_managedbooleantrue when YoPrint keeps one invoice in step with the order.
auto_invoice_shipment_price_typestring | nullDONOTMANAGE,NONE,MARKUPorMARGIN.auto_invoice_shipment_ratedecimal pairThe MARKUP or MARGIN percentage. A decimal pair: the amount is
value÷ 10^dp({ "value": 12500000, "dp": 6 }is 12.50). Kept with 6 decimal places; an amount never set can come as{ "value": 0, "dp": 0 }. Readdpevery time: it can differ between fields and records.- See Money and quantities.
auto_invoice_typestring | nullHow the automatic invoice is built. Always
single_invoicetoday.billing_addressobject | nullAn address, as the address operations return it.
Child fields (8)
citystring | nullcountry_codestring | nullidstringis_primarybooleanlabelstring | nullpostcodestring | nullrolestring | nullbilling,shippingor a warehouse role.state_codestring | null
billing_address_idstring | nullcalc_deposit_totalinteger | number | string | nullThe deposit amount, rounded to 2 decimal places: the percentage of
order_item_cart_total, or of the invoiced total once every line is invoiced (or the invoiced total reaches the order's); 0 unlessdeposit_required. Thousandths, an older encoding:12500is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5is 1.2345), or as a string ("1234.5") when you sendX-Yoprint-Decimal-Format: exact-v1. See Money and quantities.client_notestring | nullThe Client Note.
created_atstring (date-time) | nullCreated. ISO 8601 with offset, or null.
created_bystring | nullCreated By (a team member id).
creator_namestring | nullcust_due_datestring (date-time) | nullCustomer in-hands date. ISO 8601 with offset, or null.
customerobject | nullAlways present on order answers, lists included: the customer record, or null when the order has none. Get a sales order also nests the customer's contacts, addresses, brand profiles, tags, files and assigned users in it.
Child fields (6)
default_payment_term_idstring | nulldefault_pricing_group_idstring | nullidstringis_externalbooleantrue for a customer synced from an integration.
namestringtax_exemptboolean
customer_billing_contact_idstring | nullThe id of the contact on the order (the same contact as
customer_contact_id), or null.customer_contact_idstring | nullcustomer_has_emailbooleancustomer_idstring | nullcustomer_po_numberstring | nullcustomer_profile_idstring | nullBrand profile.
deposit_amount_duedecimal pairDeposit still to pay (negative once overpaid). A decimal pair: the amount is
value÷ 10^dp({ "value": 125000, "dp": 4 }is 12.50). Kept with 4 decimal places; an amount never set can come as{ "value": 0, "dp": 0 }. Readdpevery time: it can differ between fields and records.- See Money and quantities.
deposit_duestring (date-time) | nullDeposit due date. ISO 8601 with offset, or null.
deposit_requiredbooleandeposit_totalinteger | number | string | nullThe deposit as a percentage of the order. A percentage ×1000:
8250is 8.25%. WithX-Yoprint-Decimal-Format: exact-v1, a value that isn't a whole number comes back as a string.due_datestring (date-time) | nullProduction due. ISO 8601 with offset, or null.
external_idsarray of objectsThe order's links to records in other systems. An empty list when there are none.
external_typestring | nullshopifyfor a Shopify order; null for YoPrint orders.from_legacybooleantrue for an order that was moved over from the old format.
full_amount_duestring (date-time) | nullFull payment due date. ISO 8601 with offset, or null.
grouped_pdfarray of objectsPDF links, grouped:
Main(only for roles withview_order_finance),Job(not on Shopify orders),Shipmentand the team's templates.true when the last sync with an integration failed.
has_invoicebooleantrue when the order has at least one invoice, so a zero invoiced total can be told apart from no invoice.
has_not_invoiced_itemsbooleantrue when some line items are not on an invoice yet.
has_over_invoiced_itemsbooleantrue when some line items are invoiced for more than the order has.
true when some line items are not on a shipment yet.
true when some line items are on shipments for more than the order has.
has_valid_invoicebooleantrue when at least one of the order's invoices is in a valid state.
has_valid_shipmentbooleantrue when at least one of the order's shipments is in a valid state.
inventory_statusstring | nullStock status of the order's lines:
not_committed,committed,partially_committed,not_applicableorpending.invoice_lock_versioninteger | string | nullChanges whenever the order's invoices change.
invoiced_discount_subtotaldecimal pairDiscounts on the order's invoices; 0 until invoiced. A decimal pair: the amount is
value÷ 10^dp({ "value": 125000, "dp": 4 }is 12.50). Kept with 4 decimal places; an amount never set can come as{ "value": 0, "dp": 0 }. Readdpevery time: it can differ between fields and records.- See Money and quantities.
invoiced_order_item_subtotaldecimal pairThe lines and shipping fees the order's invoices bill (the sum of their
cart_item_subtotal); 0 until invoiced. A decimal pair: the amount isvalue÷ 10^dp({ "value": 125000, "dp": 4 }is 12.50). Kept with 4 decimal places; an amount never set can come as{ "value": 0, "dp": 0 }. Readdpevery time: it can differ between fields and records.- See Money and quantities.
invoiced_shipment_subtotaldecimal pairThe shipping fees in
invoiced_order_item_subtotal; 0 until invoiced. A decimal pair: the amount isvalue÷ 10^dp({ "value": 125000, "dp": 4 }is 12.50). Kept with 4 decimal places; an amount never set can come as{ "value": 0, "dp": 0 }. Readdpevery time: it can differ between fields and records.- See Money and quantities.
invoiced_tax_subtotaldecimal pairTax on the order's invoices; 0 until invoiced. A decimal pair: the amount is
value÷ 10^dp({ "value": 125000, "dp": 4 }is 12.50). Kept with 4 decimal places; an amount never set can come as{ "value": 0, "dp": 0 }. Readdpevery time: it can differ between fields and records.- See Money and quantities.
invoiced_totaldecimal pairTotal of the order's invoices. A decimal pair: the amount is
value÷ 10^dp({ "value": 125000, "dp": 4 }is 12.50). Kept with 4 decimal places; an amount never set can come as{ "value": 0, "dp": 0 }. Readdpevery time: it can differ between fields and records.- See Money and quantities.
is_client_note_editablebooleanfalse for a Shopify order, whose client note comes from Shopify.
is_externalbooleantrue for an order synced from an integration such as Shopify.
is_legacybooleantrue for an order made in the old format.
is_rushbooleanissue_datestring (date-time) | nullIssue date. ISO 8601 with offset, or null.
itemsarray of objectsThe order's lines (Get only).
Fields of each item (16)
_metaobjectThe line's own values again (
id,type,order_id,unit_price,subtotaland so on). Always an object.idstringinventory_statusstring | nullStock status of the line.
jobobjectlock_versioninteger | nullThe line's own lock version (a microsecond timestamp).
order_idstringorder_unique_keystringThe order's
unique_key. The line's ownunique_keyis not in the answer: useid.positionintegerpricingobjectpricing_rule_appliedobject | nullThe pricing rule that set the line's product price, or null when no rule did. List the line items, Get one line item and the bulk save answer with the full summary below. Other answers carry only
type, the two ids and the two totals.Child fields (12)
afterstringFull summary only: the price after the rule, as a decimal string.
after_totaldecimal pairThe product price per unit after the rule. 6 decimal places. A decimal pair: the amount is
value÷ 10^dp({ "value": 1250, "dp": 2 }is 12.50). Readdpevery time: it can differ between fields and records.- See Money and quantities.
basestringFull summary only: that starting price, as a decimal string with at least 2 decimal places.
base_typestringFull summary only: what the rule started from: the supplier price for catalog lines, the product's own price for other lines.
- One of:
"supplier_price","base_price"
- One of:
normal_pricestring | nullFull summary only: what the line would cost with no rule. For catalog lines the supplier price plus the group's catalog markup as it is now; otherwise the same as
base.original_totaldecimal pairThe product price per unit before the rule. 6 decimal places. A decimal pair: the amount is
value÷ 10^dp({ "value": 1250, "dp": 2 }is 12.50). Readdpevery time: it can differ between fields and records.- See Money and quantities.
pricing_group_idstring | nullThe pricing group whose rule applied.
pricing_group_namestring | nullFull summary only: the group's name now.
pricing_group_removedboolean | nullFull summary only: true when the group was removed since. The line keeps its price.
pricing_rule_idstring | nullThe rule that applied.
ruleobject | nullFull summary only: the rule as the group holds it now, with its current name and position (1 is the first rule checked). Null when the rule no longer exists.
typestringproducton a line.
productobjectquantityobjectThe quantity, trailing zeros dropped: 10 is
{ "value": 10, "dp": 0 }.subtotaldecimal pairunit_pricetimes the quantity. 4 decimal places: 125.00 is{ "value": 1250000, "dp": 4 }. A decimal pair: the amount isvalue÷ 10^dp({ "value": 1250, "dp": 2 }is 12.50). Readdpevery time: it can differ between fields and records.- See Money and quantities.
trashedbooleantrue when the line was deleted.
typestringThe kind of line: db_catalog, user_simple, db_variant, custom or fee.
unit_pricedecimal pairThe price of one unit: the product price plus the decoration price. 6 decimal places: 12.50 is
{ "value": 12500000, "dp": 6 }. A decimal pair: the amount isvalue÷ 10^dp({ "value": 1250, "dp": 2 }is 12.50). Readdpevery time: it can differ between fields and records.- See Money and quantities.
job_lock_versioninteger | string | nullChanges whenever the order's jobs change.
last_payment_request_datestring (date-time) | nullWhen a payment reminder was last emailed for the order. ISO 8601 with offset, or null.
lock_versioninteger | string | nullChanges on every save.
modestringOlder flag:
createfor a draft,viewonce published.- One of:
"create","view","edit"
- One of:
namestring | nullorder_balance_duedecimal pairInvoiced total minus paid. A decimal pair: the amount is
value÷ 10^dp({ "value": 125000, "dp": 4 }is 12.50). Kept with 4 decimal places; an amount never set can come as{ "value": 0, "dp": 0 }. Readdpevery time: it can differ between fields and records.- See Money and quantities.
order_item_cart_totaldecimal pairThe value of the order's lines: the order's own total before invoicing. A decimal pair: the amount is
value÷ 10^dp({ "value": 125000, "dp": 4 }is 12.50). Kept with 4 decimal places; an amount never set can come as{ "value": 0, "dp": 0 }. Readdpevery time: it can differ between fields and records.- See Money and quantities.
order_item_lock_versioninteger | string | nullChanges whenever the order's line items change.
order_margin_percentagedecimal pairMargin, in percent. A decimal pair: the amount is
value÷ 10^dp({ "value": 1250, "dp": 2 }is 12.50). Kept with 2 decimal places; an amount never set can come as{ "value": 0, "dp": 0 }. Readdpevery time: it can differ between fields and records.- See Money and quantities.
order_markup_percentagedecimal pairMarkup, in percent. A decimal pair: the amount is
value÷ 10^dp({ "value": 1250, "dp": 2 }is 12.50). Kept with 2 decimal places; an amount never set can come as{ "value": 0, "dp": 0 }. Readdpevery time: it can differ between fields and records.- See Money and quantities.
order_profitdecimal pairProfit. A decimal pair: the amount is
value÷ 10^dp({ "value": 1250, "dp": 2 }is 12.50). Kept with 2 decimal places; an amount never set can come as{ "value": 0, "dp": 0 }. Readdpevery time: it can differ between fields and records.- See Money and quantities.
paid_amountinteger | number | string | nullPaid so far. Thousandths, an older encoding:
12500is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5is 1.2345), or as a string ("1234.5") when you sendX-Yoprint-Decimal-Format: exact-v1. See Money and quantities.participantsarray of objectsWho receives the order's messages (Get only).
payment_lock_versioninteger | string | nullChanges whenever the order's payments change.
payment_term_idstring | nullpricing_group_idstring | nullpricing_strategystring | nulljob_separately,job_togetherorservice_loc_together.prod_notestring | nullThe production note.
producible_item_countnumber | integer | string | nullQuantity to produce.
quickbook_disable_syncbooleantrue when QuickBooks sync is off for this order.
quickbook_disable_sync_atstring (date-time) | nullWhen the switch was last changed. ISO 8601 with offset, or null.
quickbook_disable_sync_bystring | nullThe team member who last changed the switch, or null.
quickbook_disable_sync_reasonstring | nullThe note given at the last change of the order's QuickBooks sync switch (off or back on), at most 500 characters, or null.
quickbook_last_error_syncstring (date-time) | nullWhen a QuickBooks sync of the order last failed. ISO 8601 with offset, or null.
quickbook_last_success_syncstring (date-time) | nullWhen QuickBooks last accepted the order. ISO 8601 with offset, or null.
quickbooks_holdobject | nullSet when YoPrint holds back a QuickBooks payment covering this order:
codeischanged,deletedorrejected(the payment was changed or deleted in QuickBooks, or QuickBooks refused a change), anddetailisalready_deposited(the payment is in a QuickBooks bank deposit) or null. Null when nothing is held.quotebooleanOlder flag: true for a quote.
ship_due_datestring (date-time) | nullShip due date. ISO 8601 with offset, or null.
shipment_billable_fee_invoice_statusstring | nullWhether those shipping fees are on an invoice. Null when there is nothing to bill.
shipment_billable_fee_totaldecimal pairThe shipping fees you bill the customer on the order's shipments. A decimal pair: the amount is
value÷ 10^dp({ "value": 125000, "dp": 4 }is 12.50). Kept with 4 decimal places; an amount never set can come as{ "value": 0, "dp": 0 }. Readdpevery time: it can differ between fields and records.- See Money and quantities.
shipment_cost_totaldecimal pairShipping cost incurred. A decimal pair: the amount is
value÷ 10^dp({ "value": 125000, "dp": 4 }is 12.50). Kept with 4 decimal places; an amount never set can come as{ "value": 0, "dp": 0 }. Readdpevery time: it can differ between fields and records.- See Money and quantities.
shipment_lock_versioninteger | string | nullChanges whenever the order's shipments change.
shipping_addressobject | nullAn address, as the address operations return it.
- Same fields as
data.billing_address.
- Same fields as
shipping_address_idstring | nullshopify_last_error_syncstring (date-time) | nullWhen a Shopify sync of the order last failed. Shopify orders only. ISO 8601 with offset, or null.
shopify_last_success_syncstring (date-time) | nullWhen Shopify last accepted the order. Shopify orders only. ISO 8601 with offset, or null.
shopify_terminal_topicstring | nullShopify orders only: the Shopify event name behind the order's final state there. Null on YoPrint orders. The answer can also hold more
shopify_*fields (shopify_admin_url,shopify_compliance_deletion,shopify_finance_notices,shopify_has_fulfillment_conflict,shopify_last_fulfillment_conflict_at): they are null or empty on YoPrint orders.start_datestring (date-time) | nullProduction start. ISO 8601 with offset, or null.
statusobject | nullThe order's status (always included).
Child fields (9)
A hex color, such as
#2196f3.What customers see in the customer portal. When none is set:
Pendingforstart,In Progressforin_progressandpre_production,Completedforend.The status name people see.
Sort order within its list, lowest first.
Which list the status belongs to:
order,quote,job,shipment,purchase_order,pipelineorcustomer_message.true for a deleted status.
startis the first status of its list andendthe last;pre_productionandin_progressare the ones in between.- One of:
"start","pre_production","in_progress","end"
- One of:
pipeline_idstringThe task preset, for
pipelinestatuses only; absent for other roles.
status_completion_datestring (date-time) | nullWhen the order's status last moved to an end status. ISO 8601 with offset, or null.
status_idstringThe order's status (from the team's sales order or quote statuses).
status_last_change_datestring (date-time) | nullLast status change. ISO 8601 with offset, or null.
tagsarray of objectstotal_qty_need_orderingstringQuantity still to buy, as a decimal string with 8 decimal places (
"24.00000000").trashedbooleantrue when the order is deleted.
typestringOlder name for
object_type.- One of:
"order","quote"
- One of:
unallocated_amountinteger | number | string | nullPayments not yet allocated to an invoice. Thousandths, an older encoding:
12500is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5is 1.2345), or as a string ("1234.5") when you sendX-Yoprint-Decimal-Format: exact-v1. See Money and quantities.updated_atstring (date-time) | nullLast changed. ISO 8601 with offset, or null.
versioninteger | string | nullThe order format version.
wallet_currency_isostring | nullThe order's currency code (
USDand so on), or null on older orders without one.warehouse_idstring | nullDeprecated: use
invoiced_discount_subtotal, the same amount. Thousandths, an older encoding:12500is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5is 1.2345), or as a string ("1234.5") when you sendX-Yoprint-Decimal-Format: exact-v1. See Money and quantities.Deprecated: use
invoiced_order_item_subtotal, which already includes billed shipping. This older field addsinvoiced_shipment_subtotalto it once more. Thousandths, an older encoding:12500is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5is 1.2345), or as a string ("1234.5") when you sendX-Yoprint-Decimal-Format: exact-v1. See Money and quantities.Deprecated: use
invoiced_tax_subtotal, the same amount. Thousandths, an older encoding:12500is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5is 1.2345), or as a string ("1234.5") when you sendX-Yoprint-Decimal-Format: exact-v1. See Money and quantities.Deprecated: use
invoiced_total, the same amount. Thousandths, an older encoding:12500is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5is 1.2345), or as a string ("1234.5") when you sendX-Yoprint-Decimal-Format: exact-v1. See Money and quantities.
Errors
401The API key is missing or wrong (
unauthenticated).403You are not allowed to do this.
api_access_not_in_plan: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only{"message": "Insufficient Permission"}. Other refusals use the error envelope, withunauthorizedoruser_is_not_authorized.404Not found.
page_not_found: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's.code: null, with a message that starts "No query results for": there is no record with that id.
Notes
- To find an order by its number, use search; to list a customer's orders, use the sales order or quote filter with
customer_id. - Line items here use the same shape as List the line items.
Related
- POSTList sales orders
/v2/ api/ store/ {team_slug}/ v2/ sales_order/ filter - POSTList quotes
/v2/ api/ store/ {team_slug}/ v2/ quote/ filter - GETList the line items of a sales order or quote
/v2/ api/ store/ {team_slug}/ v2/ sales_order/ {order_unique_key}/ order_item - GETList the history of a sales order or quote
/v2/ api/ store/ {team_slug}/ v2/ sales_order/ {order_unique_key}/ history
