Update a sales order or quote

PUT/v2/api/store/{team_slug}/v2/sales_order/{order_unique_key}

v2Operation ID v2_public_order_update

Changes an order's header fields. Send only the fields you change.

Use it for the name, number, customer PO number, notes, rush flag, status, Created By, addresses, brand profile and contact. Other changes have their own operation:

dates, payment term, pricing group, warehouse, customer, status with webhooks, conversion, cloning: Run an action (v2.public.order.single_action);
Client Note and production note alone: the note operations, which can also clear a note.

{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. The answer is the updated order.

Permission

Needs permission to edit this sales order or quote:

The team owner
A role with update_all_order
A role with update_self_order, when the order was created by or is assigned to the API key's user
The person who created a draft, with create_order

Quotes use the same sales order permissions.

Business rules

A different customer_id is refused: "Cannot change customer_id via update endpoint. Use change_customer single action."
On a draft, a different object_type or quote is refused: "Cannot change order identity via update endpoint. Use conversion single action." On a published order both fields are ignored.
status_id must be one of the team's statuses for this kind of order: "This status cannot be used for this sales order. Choose another status."
created_by must be a current team member; addresses must be current team addresses.
Shopify orders can't change status_id here (shopify_order_status_update_boundary): use the change_status action.
Shopify orders can't change their addresses or contact (shopify_order_snapshot_update_boundary) or their customer, and nothing changes once the order was deleted in Shopify (shopify_order_deleted_externally).
Deleted orders can't be updated: restore them first.
Fields not listed above are ignored.

Side effects

On a published order, a new status_id and changes to the number, customer PO number, notes and Created By are recorded in the order history.
Refreshes the order for people who have it open in the web app. On a published order, Customer Portal pages the order's customer has open refresh (a live update, not an email).

Path parameters

team_slugstringrequired
Your team slug, shown as Team ID next to your API key in Profile.
- Example your-team
order_unique_keystringrequired
The sales order's or quote's id (a hash id), or its unique_key (ord_…). The order number (scoped_id) does not work.
- Example V4keXwwxMQyXw7

Request body

application/json, required.

billing_address_idstring | null
The billing address id, or null or an empty string to clear it. It must be a current address of the team.
client_notestring
The Client Note (the customer sees it).
created_bystring
The team member shown as Created By. Must be a current member of the team.
customer_contact_idstring | null
The customer contact id, or empty to clear it.
customer_idstring
Only the current customer is accepted here. Change a draft's customer with the change_customer action.
customer_po_numberstring
The customer's purchase order number.
customer_profile_idstring | null
The customer brand profile id, or empty to clear it.
is_rushboolean
Marks the order as rush. Unlike the rush actions, this does not change the jobs or send a webhook.
namestring
The order's name.
object_typestring
Drafts only, and only the current value. Convert with the convert_to_quote or convert_to_sales_order action.
- One of: "sales_order", "quote"
prod_notestring
The production note (internal).
quoteboolean
Drafts only, and only the current value.
scoped_idstring
The order number.
shipping_address_idstring | null
The shipping address id, or null or an empty string to clear it. It must be a current address of the team.
status_idstring
A status id from the team's sales order (or quote) statuses. Prefer the change_status action, which also sends the status webhooks.

Response

200Successful response.

dataobjectrequired
A sales order or quote.
Child fields (110)
- idstringrequired
  The order's hash id: use it in every other call.
- internal_statusstringrequired
  draft until published.
  - One of: "draft", "published"
- object_typestringrequired
  - One of: "sales_order", "quote"
- scoped_idstringrequired
  The order number people see, SO and at least four digits (quotes too). Not an id.
- unique_keystringrequired
  The order's unique key (ord_…); accepted wherever {order_unique_key} is.
- approval_statusstring | null
  requested, sent-to-customer, viewed-by-customer, need-changes or approved; null without approvals.
- assigned_usersarray of objects
  The team members in the order's Assigned To list (always included).
  Fields of each item (5)
  - avatar_urlstring | null
  - emailstring
  - idstring
  - namestring
  - timezonestring | null
    IANA time zone, for example America/Chicago.
- auto_invoice_managedboolean
  true when YoPrint keeps one invoice in step with the order.
- auto_invoice_shipment_price_typestring | null
  DONOTMANAGE, NONE, MARKUP or MARGIN.
- auto_invoice_shipment_ratedecimal pair
  The 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 }. Read dp every time: it can differ between fields and records.
  - See Money and quantities.
- auto_invoice_typestring | null
  How the automatic invoice is built. Always single_invoice today.
- billing_addressobject | null
  An address, as the address operations return it.
  Child fields (8)
  - citystring | null
  - country_codestring | null
  - idstring
  - is_primaryboolean
  - labelstring | null
  - postcodestring | null
  - rolestring | null
    billing, shipping or a warehouse role.
  - state_codestring | null
- billing_address_idstring | null
- calc_deposit_totalinteger | number | string | null
  The 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 unless deposit_required. Thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.
- client_notestring | null
  The Client Note.
- created_atstring (date-time) | null
  Created. ISO 8601 with offset, or null.
- created_bystring | null
  Created By (a team member id).
- creator_namestring | null
- cust_due_datestring (date-time) | null
  Customer in-hands date. ISO 8601 with offset, or null.
- customerobject | null
  Always 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 | null
  - default_pricing_group_idstring | null
  - idstring
  - is_externalboolean
    true for a customer synced from an integration.
  - namestring
  - tax_exemptboolean
- customer_billing_contact_idstring | null
  The id of the contact on the order (the same contact as customer_contact_id), or null.
- customer_contact_idstring | null
- customer_has_emailboolean
- customer_idstring | null
- customer_po_numberstring | null
- customer_profile_idstring | null
  Brand profile.
- deposit_amount_duedecimal pair
  Deposit 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 }. Read dp every time: it can differ between fields and records.
  - See Money and quantities.
- deposit_duestring (date-time) | null
  Deposit due date. ISO 8601 with offset, or null.
- deposit_requiredboolean
- deposit_totalinteger | number | string | null
  The deposit as a percentage of the order. A percentage ×1000: 8250 is 8.25%. With X-Yoprint-Decimal-Format: exact-v1, a value that isn't a whole number comes back as a string.
- due_datestring (date-time) | null
  Production due. ISO 8601 with offset, or null.
- external_idsarray of objects
  The order's links to records in other systems. An empty list when there are none.
- external_typestring | null
  shopify for a Shopify order; null for YoPrint orders.
- from_legacyboolean
  true for an order that was moved over from the old format.
- full_amount_duestring (date-time) | null
  Full payment due date. ISO 8601 with offset, or null.
- grouped_pdfarray of objects
  PDF links, grouped: Main (only for roles with view_order_finance), Job (not on Shopify orders), Shipment and the team's templates.
  Fields of each item (2)
  - documentsarray of objects
  - labelstring
- has_external_integration_sync_errorboolean
  true when the last sync with an integration failed.
- has_invoiceboolean
  true when the order has at least one invoice, so a zero invoiced total can be told apart from no invoice.
- has_not_invoiced_itemsboolean
  true when some line items are not on an invoice yet.
- has_over_invoiced_itemsboolean
  true when some line items are invoiced for more than the order has.
- has_shipment_items_not_allocatedboolean
  true when some line items are not on a shipment yet.
- has_shipment_items_over_allocatedboolean
  true when some line items are on shipments for more than the order has.
- has_valid_invoiceboolean
  true when at least one of the order's invoices is in a valid state.
- has_valid_shipmentboolean
  true when at least one of the order's shipments is in a valid state.
- inventory_statusstring | null
  Stock status of the order's lines: not_committed, committed, partially_committed, not_applicable or pending.
- invoice_lock_versioninteger | string | null
  Changes whenever the order's invoices change.
- invoiced_discount_subtotaldecimal pair
  Discounts 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 }. Read dp every time: it can differ between fields and records.
  - See Money and quantities.
- invoiced_order_item_subtotaldecimal pair
  The lines and shipping fees the order's invoices bill (the sum of their cart_item_subtotal); 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 }. Read dp every time: it can differ between fields and records.
  - See Money and quantities.
- invoiced_shipment_subtotaldecimal pair
  The shipping fees in invoiced_order_item_subtotal; 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 }. Read dp every time: it can differ between fields and records.
  - See Money and quantities.
- invoiced_tax_subtotaldecimal pair
  Tax 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 }. Read dp every time: it can differ between fields and records.
  - See Money and quantities.
- invoiced_totaldecimal pair
  Total 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 }. Read dp every time: it can differ between fields and records.
  - See Money and quantities.
- is_client_note_editableboolean
  false for a Shopify order, whose client note comes from Shopify.
- is_externalboolean
  true for an order synced from an integration such as Shopify.
- is_legacyboolean
  true for an order made in the old format.
- is_rushboolean
- issue_datestring (date-time) | null
  Issue date. ISO 8601 with offset, or null.
- job_lock_versioninteger | string | null
  Changes whenever the order's jobs change.
- last_payment_request_datestring (date-time) | null
  When a payment reminder was last emailed for the order. ISO 8601 with offset, or null.
- lock_versioninteger | string | null
  Changes on every save.
- modestring
  Older flag: create for a draft, view once published.
  - One of: "create", "view", "edit"
- namestring | null
- order_balance_duedecimal pair
  Invoiced 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 }. Read dp every time: it can differ between fields and records.
  - See Money and quantities.
- order_item_cart_totaldecimal pair
  The 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 }. Read dp every time: it can differ between fields and records.
  - See Money and quantities.
- order_item_lock_versioninteger | string | null
  Changes whenever the order's line items change.
- order_margin_percentagedecimal pair
  Margin, 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 }. Read dp every time: it can differ between fields and records.
  - See Money and quantities.
- order_markup_percentagedecimal pair
  Markup, 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 }. Read dp every time: it can differ between fields and records.
  - See Money and quantities.
- order_profitdecimal pair
  Profit. 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 }. Read dp every time: it can differ between fields and records.
  - See Money and quantities.
- paid_amountinteger | number | string | null
  Paid so far. Thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.
- payment_lock_versioninteger | string | null
  Changes whenever the order's payments change.
- payment_term_idstring | null
- pricing_group_idstring | null
- pricing_strategystring | null
  job_separately, job_together or service_loc_together.
- prod_notestring | null
  The production note.
- producible_item_countnumber | integer | string | null
  Quantity to produce.
- quickbook_disable_syncboolean
  true when QuickBooks sync is off for this order.
- quickbook_disable_sync_atstring (date-time) | null
  When the switch was last changed. ISO 8601 with offset, or null.
- quickbook_disable_sync_bystring | null
  The team member who last changed the switch, or null.
- quickbook_disable_sync_reasonstring | null
  The 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) | null
  When a QuickBooks sync of the order last failed. ISO 8601 with offset, or null.
- quickbook_last_success_syncstring (date-time) | null
  When QuickBooks last accepted the order. ISO 8601 with offset, or null.
- quickbooks_holdobject | null
  Set when YoPrint holds back a QuickBooks payment covering this order: code is changed, deleted or rejected (the payment was changed or deleted in QuickBooks, or QuickBooks refused a change), and detail is already_deposited (the payment is in a QuickBooks bank deposit) or null. Null when nothing is held.
  Child fields (2)
  - codestring
    One of: "changed", "deleted", "rejected"
  - detailstring | null
- quoteboolean
  Older flag: true for a quote.
- ship_due_datestring (date-time) | null
  Ship due date. ISO 8601 with offset, or null.
- shipment_billable_fee_invoice_statusstring | null
  Whether those shipping fees are on an invoice. Null when there is nothing to bill.
- shipment_billable_fee_totaldecimal pair
  The 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 }. Read dp every time: it can differ between fields and records.
  - See Money and quantities.
- shipment_cost_totaldecimal pair
  Shipping 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 }. Read dp every time: it can differ between fields and records.
  - See Money and quantities.
- shipment_lock_versioninteger | string | null
  Changes whenever the order's shipments change.
- shipping_addressobject | null
  An address, as the address operations return it.
  - Same fields as data.billing_address.
- shipping_address_idstring | null
- shopify_last_error_syncstring (date-time) | null
  When a Shopify sync of the order last failed. Shopify orders only. ISO 8601 with offset, or null.
- shopify_last_success_syncstring (date-time) | null
  When Shopify last accepted the order. Shopify orders only. ISO 8601 with offset, or null.
- shopify_terminal_topicstring | null
  Shopify 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) | null
  Production start. ISO 8601 with offset, or null.
- statusobject | null
  The order's status (always included).
  Child fields (9)
  - colorstringrequired
    A hex color, such as #2196f3.
  - customer_labelstringrequired
    What customers see in the customer portal. When none is set: Pending for start, In Progress for in_progress and pre_production, Completed for end.
  - idstringrequired
  - labelstringrequired
    The status name people see.
  - positionintegerrequired
    Sort order within its list, lowest first.
  - rolestringrequired
    Which list the status belongs to: order, quote, job, shipment, purchase_order, pipeline or customer_message.
  - trashedbooleanrequired
    true for a deleted status.
  - typestringrequired
    start is the first status of its list and end the last; pre_production and in_progress are the ones in between.
    One of: "start", "pre_production", "in_progress", "end"
  - pipeline_idstring
    The task preset, for pipeline statuses only; absent for other roles.
- status_completion_datestring (date-time) | null
  When the order's status last moved to an end status. ISO 8601 with offset, or null.
- status_idstring
  The order's status (from the team's sales order or quote statuses).
- status_last_change_datestring (date-time) | null
  Last status change. ISO 8601 with offset, or null.
- tagsarray of objects
  Fields of each item (3)
  - color_hexstring | null
    Tag color, for example #E53935.
  - idstring
  - namestring
- total_qty_need_orderingstring
  Quantity still to buy, as a decimal string with 8 decimal places ("24.00000000").
- trashedboolean
  true when the order is deleted.
- typestring
  Older name for object_type.
  - One of: "order", "quote"
- unallocated_amountinteger | number | string | null
  Payments not yet allocated to an invoice. Thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.
- updated_atstring (date-time) | null
  Last changed. ISO 8601 with offset, or null.
- versioninteger | string | null
  The order format version.
- wallet_currency_isostring | null
  The order's currency code (USD and so on), or null on older orders without one.
- warehouse_idstring | null
- calc_discountinteger | number | string | nulldeprecated
  Deprecated: use invoiced_discount_subtotal, the same amount. Thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.
- calc_subtotalinteger | number | string | nulldeprecated
  Deprecated: use invoiced_order_item_subtotal, which already includes billed shipping. This older field adds invoiced_shipment_subtotal to it once more. Thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.
- calc_taxinteger | number | string | nulldeprecated
  Deprecated: use invoiced_tax_subtotal, the same amount. Thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.
- calc_totalinteger | number | string | nulldeprecated
  Deprecated: use invoiced_total, the same amount. Thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.
statusintegerrequired
successbooleanrequired

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, with unauthorized or user_is_not_authorized.
When
The API key's role can't edit this order.
Fix
Ask the team owner for sales order edit permission.
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.
When
No such order in this team, or it is deleted.
Fix
Check the id; restore a deleted order first.
422The request was refused and changed nothing. validation_failed lists what to fix in error.fields; other codes name a business rule, explained in error.message. A few checks answer with only {"message": "..."}. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer connect_timeout ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.
When
A field breaks one of the rules above: validation_error with the message (error.fields names status_id, created_by or customer_id for those), or validation_failed for a value of the wrong type.
Fix
Use the matching action, or a value from the team's own lists.

PUTRun an action on a sales order or quote/v2/api/store/{team_slug}/v2/sales_order/{order_unique_key}/action/{action_name}
PUTSet the Client Note of a sales order or quote/v2/api/store/{team_slug}/v2/sales_order/{order_unique_key}/customer_note
PUTSet the production note of a sales order or quote/v2/api/store/{team_slug}/v2/sales_order/{order_unique_key}/production_note

Example request

curl

curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "customer_po_number": "PO-1190",    "is_rush": true,    "name": "Spring team shirts"  }'

Example response 200

{
  "data": {
    "assigned_users": [],
    "calc_deposit_total": 67500,
    "customer": {
      "id": "63KcENAAsKuipY",
      "is_external": false,
      "name": "Northwind Apparel",
      "tax_exempt": false
    },
    "customer_id": "63KcENAAsKuipY",
    "customer_po_number": "PO-1190",
    "deposit_amount_due": {
      "dp": 4,
      "value": 175000
    },
    "deposit_required": true,
    "deposit_total": 50000,
    "due_date": "2026-11-14T00:00:00+00:00",
    "id": "V4keXwwxMQyXw7",
    "internal_status": "published",
    "invoiced_discount_subtotal": {
      "dp": 4,
      "value": 0
    },
    "invoiced_order_item_subtotal": {
      "dp": 4,
      "value": 1250000
    },
    "invoiced_shipment_subtotal": {
      "dp": 4,
      "value": 0
    },
    "invoiced_tax_subtotal": {
      "dp": 4,
      "value": 100000
    },
    "invoiced_total": {
      "dp": 4,
      "value": 1350000
    },
    "is_rush": true,
    "issue_date": "2026-11-03T00:00:00+00:00",
    "mode": "view",
    "name": "Spring team shirts",
    "object_type": "sales_order",
    "order_balance_due": {
      "dp": 4,
      "value": 850000
    },
    "order_item_cart_total": {
      "dp": 4,
      "value": 1250000
    },
    "paid_amount": 50000,
    "quote": false,
    "scoped_id": "SO1001",
    "status": {
      "color": "#2196f3",
      "customer_label": "In Progress",
      "id": "52CuV8sWcDZLPm",
      "label": "In production",
      "position": 2,
      "role": "order",
      "trashed": false,
      "type": "in_progress"
    },
    "status_id": "52CuV8sWcDZLPm",
    "total_qty_need_ordering": "0.00000000",
    "trashed": false,
    "type": "order",
    "unique_key": "ord_EXAMPLEuniqueKey"
  },
  "status": 200,
  "success": true
}

AI agents: read /llms.txt; add .md to any page URL for its Markdown. Guides and concepts in one file: /llms-full.txt.

Download the OpenAPI spec Support: support@yoprint.com yoprint.com