Skip to content

Run an action on a sales order or quote

Open .md

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

v2Operation ID v2_public_order_single_action

Runs one named action on an order. Put the action's name in the path ({action_name}) and its fields in the body.

The send_order_detail, send_payment_reminder and send_approval_reminder actions email the customer. Email limit: if your team makes more than 60 of these calls in a minute, or goes over the daily email limit for its plan, YoPrint blocks email sending for your whole team until YoPrint support lifts the block. Never call this in a loop.

action_name Body Draft Published
change_status value: status id no yes
change_customer value: customer id yes no
change_issue_date value: date; also moves the order's other dates, its jobs and invoices by the same amount yes yes
change_customer_due_date, change_ship_due_date value: date or null, not before the issue date yes yes
change_deposit_due, change_full_amount_due value: date or null; deposit due can't be after full payment due yes yes
change_start_end_date_date start_date, due_date: both dates or both null yes yes
change_payment_term payment_term_id, deposit_due, full_amount_due, optional deposit_total (a percentage) yes yes
change_pricing_group pricing_group_id yes yes
change_pricing_strategy pricing_strategy yes yes
change_warehouse warehouse_id yes yes
clone_order is_time_shift, cloned_anchor_date, item_choices, optional pricing_group_id yes yes
convert_to_quote, convert_to_sales_order optional status_id and pricing_group_id yes yes
bulk_change_invoice_address, bulk_change_shipment_address address flags and ids yes yes
configure_order_auto_invoice_managed the three auto-invoice fields yes yes
mark_order_as_rush, mark_order_as_not_rush, mark_all_job_as_rush, mark_all_job_as_not_rush {} yes yes
send_order_detail, send_payment_reminder, send_approval_reminder {} no yes

Dates are ISO 8601, such as 2026-11-05. An action that is not allowed for the order's state (draft or published) fails with object_action_error "Action not found".

The answer is the order after the action (for clone_order the new draft copy; for convert_to_quote and convert_to_sales_order the converted document, with the same id). change_customer adds customer_profile and participants; change_pricing_group and change_pricing_strategy add items and participants. Three actions answer differently: bulk_change_invoice_address returns the order's invoices with their lines (as List the invoices of a sales order), bulk_change_shipment_address returns the order's shipments with their lines, estimates and packages (as List the shipments of a sales order), and configure_order_auto_invoice_managed returns data: null.

These email the customer: send_order_detail (the order or quote detail template; nothing is sent if the team has no such template), send_payment_reminder (only when the order is not fully paid; otherwise nothing is sent) and send_approval_reminder (needs an open approval and a recipient with an email address).

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

Permission

Most actions need permission to edit this order (update_all_order, or update_self_order for orders the user created or is assigned to; the creator of a draft with create_order). clone_order needs create_order and permission to view the order. The send_* actions need permission to message the order's customer (message_all_order, or message_self_order for own and assigned orders). The team owner can do all of them.

Business rules

  • On an order synced from an integration (Shopify), only change_status, change_customer_due_date, change_ship_due_date, change_start_end_date_date and send_order_detail work; every other action fails with 422 validation_error "Cannot update external object from API." A Shopify order deleted in Shopify fails every action with 422 shopify_order_deleted_externally.
  • change_customer works on drafts only. It is refused if the draft has any of the following: a payment, a payment link, a sent message, or linked stock. Shopify orders and Shopify customers are also refused. Sending the current customer changes nothing.
  • change_customer resets the order using the new customer's settings:

    • Brand profile, addresses, contact: the customer's primary brand profile, primary billing and shipping addresses, and primary (or first) contact replace the order's (or are cleared if none exist). Message participants are replaced by that contact.
    • Payment term: uses the customer's default payment term (or the team's default). The deposit percentage, deposit requirement, and due dates (counted from today) update from it. If there is no default term, only the term is cleared.
    • Warehouse: sets the customer's default warehouse, if configured.
    • Pricing group: sets the customer's default pricing group (or the team's default if none exists or theirs was removed). The order is repriced if the pricing group changes.
    • Invoices and shipments: every invoice receives the new customer and new addresses, and its tax is recalculated (manually entered tax is kept). Shipments receive the new customer but keep their existing addresses.
  • change_status works on published orders only; the status must belong to the team and to this kind of order.
  • change_customer_due_date and change_ship_due_date can't be before the issue date: "Input date should be after order issue date."
  • change_deposit_due can't be after the full payment due date, and change_full_amount_due can't be before the deposit due date.
  • change_start_end_date_date needs both dates or neither, and the due date not before the start date.
  • change_payment_term: deposit_due and full_amount_due must be present (null allowed); a deposit is required when deposit_due is set; deposit_total.dp must be 3.
  • clone_order needs a choice in item_choices for every line on a phased-out or deleted product, size or color (clone_needs_choices), and refuses choices that are not needed (clone_choice_not_needed), unknown lines (clone_choice_unknown_line) and bad replacements (clone_replacement_invalid). Shopify orders can't be cloned.
  • clone_order, convert_to_quote and convert_to_sales_order keep the order's pricing group unless you send pricing_group_id. When that group was removed they are refused with 422 clone_needs_pricing_group ("<name> was removed. Choose a pricing group."): error.pricing_group names the removed group and error.suggested_pricing_group the customer's default or else the team's ({ id, name, removed, disabled }, or null). Send pricing_group_id, for example the suggested one, and try again. When a clone_order also has lines that need item_choices, the refusal is clone_needs_choices instead: it lists those lines and carries pricing_group_needed: true with the same two groups.
  • A pricing_group_id you send (in change_pricing_group, clone_order or a conversion) must be one of the team's published groups: a removed group is refused with 422 pricing_group_removed ("<name> was removed. Choose another pricing group.", error.pricing_group names it); a group that is turned off with 422 pricing_group_disabled unless it is already the order's (or, for a copy or conversion, the customer's default); a draft or another team's group with 404 pricing_group_not_found.
  • Conversions refuse deleted orders ("A deleted order cannot be converted. Restore it first."), Shopify orders and orders whose customer is a Shopify customer, converting to the same kind, an order whose current status is not one of its kind's statuses, and teams without a starting status for the target kind; each is 422 object_action_error. A status_id must be a status of the target kind (else 404).
  • MARKUP rates can't be below -100; MARGIN rates must be 0 or more and below 100.
  • The send_* actions count toward the team's daily email limit (60 a day on the free plan, and on a trial only once YoPrint support has turned email on for it; on paid plans 280 in the first 6 days of the subscription or the team, 800 once the subscription is over 3 months old, 380 otherwise). Every call counts, even one that ends up sending nothing. Going over it blocks the team's email until YoPrint support lifts the block. A trial without email turned on, or a team without an active plan, gets 422 email_feature_not_enabled_in_trial.

Side effects

  • change_status sends sales_order.status_changed (or quote.status_changed) and order.status_changed webhooks and records the change in the history, only when the status really changes.
  • convert_to_sales_order sends quote.converted_to_sales_order; convert_to_quote sends order.converted_to_quote and releases the order's stock reservations.
  • mark_order_as_rush and mark_order_as_not_rush change the order and all its jobs and send order.marked_as_rush or order.marked_as_not_rush when the order's flag changes; the mark_all_job_* actions change only the jobs. No job rush webhooks are sent.
  • configure_order_auto_invoice_managed turned on creates or updates the order's one managed invoice (DONOTMANAGE removes its managed shipping lines); turned off, the invoices and their lines stay but are no longer managed.
  • bulk_change_invoice_address redoes Auto Tax for the new addresses.
  • change_deposit_due changes only the date: whether a deposit is required and its amount stay as they are (use change_payment_term for those).
  • change_pricing_group and change_pricing_strategy recalculate prices, totals and auto-managed invoices. change_payment_term recalculates only the deposit (and the customer's totals on a published sales order).
  • change_issue_date moves the other dates of the order, its jobs, and its invoices by the same number of days.
  • The send_* actions email the customer; clone_order creates a new draft. On a copy whose invoices are recalculated (for example when a line is left out), the deposit amount is recalculated too.
  • 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
  • action_namestringrequired

    The action to run. See the table for each one's body and when it is allowed.

    • One of: "change_status", "change_customer", "change_issue_date", "change_customer_due_date", "change_ship_due_date", "change_deposit_due", "change_full_amount_due", "change_start_end_date_date", "change_payment_term", "change_pricing_group", "change_pricing_strategy", "change_warehouse", "clone_order", "convert_to_quote", "convert_to_sales_order", "bulk_change_invoice_address", "bulk_change_shipment_address", "configure_order_auto_invoice_managed", "mark_order_as_rush", "mark_order_as_not_rush", "mark_all_job_as_rush", "mark_all_job_as_not_rush", "send_order_detail", "send_payment_reminder", "send_approval_reminder"
    • Example change_status

Request body

application/json, required.

Which action?

Send any of these 25 bodies.

change_status

Published orders only. Moves the order to another status.

  • valuestringrequired

    A status id from the team's sales order statuses (or quote statuses for a quote).

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/action/change_status' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "value": "52CuV8sWcDZLPm"  }'

change_customer

Drafts only. Sets another customer and resets order defaults (brand profile, addresses, contact, payment term, warehouse, pricing group, and invoices).

  • valuestringrequired

    The new customer's id.

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/action/change_customer' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "value": "GI8C9GWswRirDL"  }'

change_issue_date

Sets the issue date and moves the other dates by the same number of days (including its jobs and invoices).

  • valuestring (date)required

    The new issue date (ISO 8601).

  • Accepted and ignored: the other dates, jobs, and invoices always move by the same number of days with the issue date.

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/action/change_issue_date' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "value": "2026-11-05"  }'

change_customer_due_date

Sets the in-hands date; not before the issue date.

  • valuestring (date) | null

    The new date (ISO 8601), or null (or an empty string) to clear it. Leaving value out also clears it.

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/action/change_customer_due_date' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "value": "2026-11-20"  }'

change_ship_due_date

Sets the ship due date; not before the issue date.

  • valuestring (date) | null

    The new date (ISO 8601), or null (or an empty string) to clear it. Leaving value out also clears it.

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/action/change_ship_due_date' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "value": "2026-11-18"  }'

change_deposit_due

Sets the deposit due date; not after the full payment due date.

  • valuestring (date) | null

    The new date (ISO 8601), or null (or an empty string) to clear it. Leaving value out also clears it.

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/action/change_deposit_due' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "value": "2026-11-08"  }'

change_full_amount_due

Sets the full payment due date; not before the deposit due date.

  • valuestring (date) | null

    The new date (ISO 8601), or null (or an empty string) to clear it. Leaving value out also clears it.

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/action/change_full_amount_due' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "value": "2026-11-30"  }'

change_start_end_date_date

Sets both production dates, or clears both with null.

  • due_datestring (date) | nullrequired

    Production due date, or null.

  • start_datestring (date) | nullrequired

    Production start date, or null.

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/action/change_start_end_date_date' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "due_date": "2026-11-14",    "start_date": "2026-11-10"  }'

change_payment_term

Sets the payment term, the deposit percentage and the due dates.

  • deposit_duestring (date) | nullrequired

    Deposit due date, or null for no deposit. Required (may be null).

  • full_amount_duestring (date) | nullrequired

    Full payment due date, or null. Required (may be null).

  • payment_term_idstringrequired

    A payment term id from the team's payment terms.

  • Ignored: a deposit is required exactly when deposit_due is set.

  • deposit_totaldecimal pair

    Optional deposit percentage. Sent as a percentage ×1000 inside a decimal pair with dp exactly 3: 50000 with dp 3 is 50% ({ "value": 50000, "dp": 3 }). YoPrint works out the deposit amount (calc_deposit_total) from it. Leave it out to keep the current percentage.

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/action/change_payment_term' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "deposit_due": "2026-11-08",    "deposit_total": {      "dp": 3,      "value": 50000    },    "full_amount_due": "2026-11-30",    "payment_term_id": "w57OrAv5fu6FoG"  }'

change_pricing_group

Changes the pricing group and reprices every line. A removed group is refused, and so is a turned-off group unless the order is already on it.

  • pricing_group_idstringrequired

    A pricing group id. Pricing groups are not listed on the public API: copy pricing_group_id from a sales order or quote that uses the group (Get a sales order or quote), or default_pricing_group_id from a customer that has it (Get a customer).

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/action/change_pricing_group' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "pricing_group_id": "PvlX5QRtc6cV6V"  }'

change_pricing_strategy

Changes how decoration is priced and reprices the order.

  • pricing_strategystringrequired

    How decoration quantity breaks are counted: per job, across jobs, or across jobs per print location.

    • One of: "job_separately", "job_together", "service_loc_together"

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/action/change_pricing_strategy' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "pricing_strategy": "job_together"  }'

change_warehouse

Changes the warehouse the order ships and takes stock from. On a published order that already has stock allocated, or a pending or in-progress stock flow, nothing changes (the answer still shows the old warehouse).

  • warehouse_idstringrequired

    A current store location of the team.

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/action/change_warehouse' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "warehouse_id": "HjfVkHROYx8Xnu"  }'

clone_order

Copies the order into a new draft with a new number and the starting status. Answers with the new draft.

  • is_time_shiftbooleanrequired

    true to move all dates so the copy's issue date is cloned_anchor_date; false to keep the original dates.

  • cloned_anchor_datestring (date)

    The copy's issue date. Required when is_time_shift is true. A date-time with an offset is taken as that moment (stored in UTC).

  • item_choicesarray of objects

    Required for each line on a phased-out or deleted product, size or color, and only for those: leave it out, or replace it with another size or color of the same product.

    Fields of each item (3)
    • actionstringrequired
      • One of: "leave_out", "replace"
    • idstringrequired

      The source line's id.

    • With replace: the size or color (variant) to use instead. Simple products can only be left out.

  • Optional: the pricing group for the copy, which is repriced with it. Required when the order's own group was removed (clone_needs_pricing_group).

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/action/clone_order' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "is_time_shift": false  }'

convert_to_quote

Turns a sales order into a quote.

  • Optional: another pricing group for the converted document, which is repriced with it. Required when the document's own group was removed (clone_needs_pricing_group).

  • status_idstring

    Optional: the status to give the converted document. Default: the team's starting status.

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/action/convert_to_quote' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{}'

convert_to_sales_order

Turns a quote into a sales order.

  • Optional: another pricing group for the converted document, which is repriced with it. Required when the document's own group was removed (clone_needs_pricing_group).

  • status_idstring

    Optional: the status to give the converted document. Default: the team's starting status.

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/action/convert_to_sales_order' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{}'

bulk_change_invoice_address

Sets the billing and/or shipping address on every invoice of the order and redoes Auto Tax for the new addresses. Answers with the order's invoices, not the order.

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/action/bulk_change_invoice_address' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "billing_address_id": "wvwxl8XfNRzRhC",    "update_billing_address": true,    "update_shipping_address": false  }'

bulk_change_shipment_address

Sets the shipping address on every shipment of the order except pick-up shipments. Answers with the order's shipments, not the order.

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/action/bulk_change_shipment_address' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "shipping_address_id": "RNG2OuYC20YzXs",    "update_shipping_address": true  }'

configure_order_auto_invoice_managed

Turns the automatic invoice on or off; here, shipping at a 20% markup. Answers with data: null.

  • auto_invoice_managedbooleanrequired

    true to keep one invoice in step with the order automatically.

  • Shipping on that invoice: DONOTMANAGE adds none, NONE charges the shipping cost, MARKUP adds rate percent to it (at least -100), MARGIN prices it for a rate percent margin (0 to under 100).

    • One of: "DONOTMANAGE", "NONE", "MARKUP", "MARGIN"
  • auto_invoice_shipment_ratedecimal pairrequired

    The percentage for MARKUP or MARGIN, as a { value, dp } pair; dp 0 to 16. Send 0 for the other types.

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/action/configure_order_auto_invoice_managed' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "auto_invoice_managed": true,    "auto_invoice_shipment_price_type": "MARKUP",    "auto_invoice_shipment_rate": {      "dp": 0,      "value": 20    }  }'

mark_order_as_rush

No fields: send {}.

This variant sends no fields.

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/action/mark_order_as_rush' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{}'

mark_order_as_not_rush

No fields: send {}.

This variant sends no fields.

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/action/mark_order_as_not_rush' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{}'

mark_all_job_as_rush

No fields: send {}.

This variant sends no fields.

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/action/mark_all_job_as_rush' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{}'

mark_all_job_as_not_rush

No fields: send {}.

This variant sends no fields.

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/action/mark_all_job_as_not_rush' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{}'

send_order_detail

No fields: send {}.

This variant sends no fields.

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/action/send_order_detail' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{}'

send_payment_reminder

No fields: send {}.

This variant sends no fields.

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/action/send_payment_reminder' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{}'

send_approval_reminder

No fields: send {}.

This variant sends no fields.

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/action/send_approval_reminder' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{}'

Response

200Successful response.

  • dataobject | array of objects | nullrequired

    Depends on the action: see the description.

    Child fields (113)
    • 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)
    • true when YoPrint keeps one invoice in step with the order.

    • DONOTMANAGE, NONE, MARKUP or MARGIN.

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

    • 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)
    • 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)
    • The id of the contact on the order (the same contact as customer_contact_id), or null.

    • customer_contact_idstring | null
    • customer_idstring | null
    • customer_po_numberstring | null
    • customer_profileobject | null

      change_customer only: the brand profile after the change, or 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.

    • deposit_duestring (date-time) | null

      Deposit due date. ISO 8601 with offset, or null.

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

    • 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)
    • true when the last sync with an integration failed.

    • true when the order has at least one invoice, so a zero invoiced total can be told apart from no invoice.

    • true when some line items are not on an invoice yet.

    • true 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.

    • true when at least one of the order's invoices is in a valid state.

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

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

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

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

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

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

    • false for a Shopify order, whose client note comes from Shopify.

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

    • itemsarray of objects

      change_pricing_group and change_pricing_strategy only: the repriced lines.

      Fields of each item (16)
      • _metaobject

        The line's own values again (id, type, order_id, unit_price, subtotal and so on). Always an object.

      • idstring
      • inventory_statusstring | null

        Stock status of the line.

      • jobobject
      • lock_versioninteger | null

        The line's own lock version (a microsecond timestamp).

      • order_idstring
      • The order's unique_key. The line's own unique_key is not in the answer: use id.

      • positioninteger
      • pricingobject
      • The 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)
        • afterstring

          Full summary only: the price after the rule, as a decimal string.

        • after_totaldecimal pair

          The 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). Read dp every time: it can differ between fields and records.

        • basestring

          Full summary only: that starting price, as a decimal string with at least 2 decimal places.

        • base_typestring

          Full 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"
        • normal_pricestring | null

          Full 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 pair

          The 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). Read dp every time: it can differ between fields and records.

        • pricing_group_idstring | null

          The pricing group whose rule applied.

        • pricing_group_namestring | null

          Full summary only: the group's name now.

        • pricing_group_removedboolean | null

          Full summary only: true when the group was removed since. The line keeps its price.

        • pricing_rule_idstring | null

          The rule that applied.

        • ruleobject | null

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

          Child fields (3)
        • typestring

          product on a line.

      • productobject
      • quantityobject

        The quantity, trailing zeros dropped: 10 is { "value": 10, "dp": 0 }.

      • subtotaldecimal pair

        unit_price times the quantity. 4 decimal places: 125.00 is { "value": 1250000, "dp": 4 }. A decimal pair: the amount is value ÷ 10^dp ({ "value": 1250, "dp": 2 } is 12.50). Read dp every time: it can differ between fields and records.

      • trashedboolean

        true when the line was deleted.

      • typestring

        The kind of line: db_catalog, user_simple, db_variant, custom or fee.

      • unit_pricedecimal pair

        The 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 is value ÷ 10^dp ({ "value": 1250, "dp": 2 } is 12.50). Read dp every time: it can differ between fields and records.

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

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

    • order_item_lock_versioninteger | string | null

      Changes whenever the order's line items change.

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

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

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

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

    • participantsarray of objects

      change_customer, change_pricing_group and change_pricing_strategy only: who receives the order's messages.

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

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

    • The team member who last changed the switch, or 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.

    • Whether those shipping fees are on an invoice. Null when there is nothing to bill.

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

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

    • shipment_lock_versioninteger | string | null

      Changes whenever the order's shipments change.

    • shipping_addressobject | null

      An address, as the address operations return it.

    • 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 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"
      • 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)
    • 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 lacks the permission the action needs (user_is_not_authorized).
    Fix
    Ask the team owner for the 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, status (for change_status or a conversion's status_id), customer, payment term, warehouse or address in this team (error.code null, "No query results for …").
    Fix
    Use ids from the team's own lists.
    When
    The pricing_group_id is not one of the team's published groups (pricing_group_not_found, "This pricing group doesn't exist or was removed.").
    Fix
    Copy pricing_group_id from an order or customer that uses the group.
  • 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
    The action name is unknown, or not allowed for a draft or published order: "Action not found" (object_action_error).
    Fix
    Check the table: some actions are drafts-only or published-only.
    When
    The body breaks a rule above: field rules and MARKUP/MARGIN limits (validation_failed, with error.fields); dates out of order, a customer that can't change, an address or warehouse that can't be used, or an action an integration-synced order doesn't allow (validation_error); production dates not both set, or due before start (job_validation_error); clone choices (clone_needs_choices, clone_choice_not_needed, clone_choice_unknown_line, clone_replacement_invalid); a conversion that isn't possible (object_action_error).
    Fix
    Read error.code, error.message and error.fields.
    When
    A pricing group that can't be used: removed (pricing_group_removed), turned off (pricing_group_disabled), or the order's own group was removed and a copy or conversion needs another (clone_needs_pricing_group, with error.suggested_pricing_group).
    Fix
    Send another pricing_group_id.
    When
    send_approval_reminder with no open approval (approval_reminder_no_open_approval) or nobody who can receive email (approval_email_no_recipient).
    Fix
    Create an approval first, or add a contact with an email address.
    When
    The team can't send email: a trial without email turned on (email_feature_not_enabled_in_trial), or over the daily limit ("You are sending too many emails ...", validation_error).
    Fix
    Ask YoPrint support to turn email on, or lift the block.

Notes

  • The path parameter {action_name} is the action's name, not an id.
  • Get status ids from the team's sales order and quote status lists.
  • Ask before calling the send_* actions on someone's behalf: they email the customer.