# Run an action on a sales order or quote

```http
PUT https://secure.yoprint.com/v2/api/store/{team_slug}/v2/sales_order/{order_unique_key}/action/{action_name}
```

- API version: v2
- Operation ID: `v2_public_order_single_action`
- Section: Sales › [Sales orders](https://developer.yoprint.com/reference/sales-orders.md)
- Web page: https://developer.yoprint.com/reference/sales-orders/v2-order-single-action/
- Authentication: `Authorization: Bearer YOUR_API_KEY`

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_slug` (string, required): Your team slug, shown as Team ID next to your API key in Profile. Example `your-team`.
- `order_unique_key` (string, required): 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_name` (string, required): 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

Content type `application/json`, required.

Which action? Send any of these 25 bodies: **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**.

### change_status

Variant 1 of 25. Sent with `action_name` `change_status` in the path. On the web page: https://developer.yoprint.com/reference/sales-orders/v2-order-single-action/#variant-change-status

Published orders only. Moves the order to another status.

Fields:

- `value` (string, required): A status id from the team's sales order statuses (or quote statuses for a quote).

Example request (change_status):

```bash
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

Variant 2 of 25. Sent with `action_name` `change_customer` in the path. On the web page: https://developer.yoprint.com/reference/sales-orders/v2-order-single-action/#variant-change-customer

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

Fields:

- `value` (string, required): The new customer's `id`.

Example request (change_customer):

```bash
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

Variant 3 of 25. Sent with `action_name` `change_issue_date` in the path. On the web page: https://developer.yoprint.com/reference/sales-orders/v2-order-single-action/#variant-change-issue-date

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

Fields:

- `value` (string (date), required): The new issue date (ISO 8601).
- `shift_other_date` (boolean, optional): Accepted and ignored: the other dates, jobs, and invoices always move by the same number of days with the issue date.

Example request (change_issue_date):

```bash
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

Variant 4 of 25. Sent with `action_name` `change_customer_due_date` in the path. On the web page: https://developer.yoprint.com/reference/sales-orders/v2-order-single-action/#variant-change-customer-due-date

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

Fields:

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

Example request (change_customer_due_date):

```bash
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

Variant 5 of 25. Sent with `action_name` `change_ship_due_date` in the path. On the web page: https://developer.yoprint.com/reference/sales-orders/v2-order-single-action/#variant-change-ship-due-date

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

Fields:

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

Example request (change_ship_due_date):

```bash
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

Variant 6 of 25. Sent with `action_name` `change_deposit_due` in the path. On the web page: https://developer.yoprint.com/reference/sales-orders/v2-order-single-action/#variant-change-deposit-due

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

Fields:

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

Example request (change_deposit_due):

```bash
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

Variant 7 of 25. Sent with `action_name` `change_full_amount_due` in the path. On the web page: https://developer.yoprint.com/reference/sales-orders/v2-order-single-action/#variant-change-full-amount-due

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

Fields:

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

Example request (change_full_amount_due):

```bash
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

Variant 8 of 25. Sent with `action_name` `change_start_end_date_date` in the path. On the web page: https://developer.yoprint.com/reference/sales-orders/v2-order-single-action/#variant-change-start-end-date-date

Sets both production dates, or clears both with null.

Fields:

- `due_date` (string (date) | null, required): Production due date, or null.
- `start_date` (string (date) | null, required): Production start date, or null.

Example request (change_start_end_date_date):

```bash
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

Variant 9 of 25. Sent with `action_name` `change_payment_term` in the path. On the web page: https://developer.yoprint.com/reference/sales-orders/v2-order-single-action/#variant-change-payment-term

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

Fields:

- `deposit_due` (string (date) | null, required): Deposit due date, or null for no deposit. Required (may be null).
- `full_amount_due` (string (date) | null, required): Full payment due date, or null. Required (may be null).
- `payment_term_id` (string, required): A payment term id from the team's payment terms.
- `deposit_required` (boolean, optional): Ignored: a deposit is required exactly when `deposit_due` is set.
- `deposit_total` (decimal pair, optional): 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. See https://developer.yoprint.com/concepts/money-and-quantities.md.

Example request (change_payment_term):

```bash
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

Variant 10 of 25. Sent with `action_name` `change_pricing_group` in the path. On the web page: https://developer.yoprint.com/reference/sales-orders/v2-order-single-action/#variant-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.

Fields:

- `pricing_group_id` (string, required): 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 (change_pricing_group):

```bash
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

Variant 11 of 25. Sent with `action_name` `change_pricing_strategy` in the path. On the web page: https://developer.yoprint.com/reference/sales-orders/v2-order-single-action/#variant-change-pricing-strategy

Changes how decoration is priced and reprices the order.

Fields:

- `pricing_strategy` (string, required): 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 (change_pricing_strategy):

```bash
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

Variant 12 of 25. Sent with `action_name` `change_warehouse` in the path. On the web page: https://developer.yoprint.com/reference/sales-orders/v2-order-single-action/#variant-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).

Fields:

- `warehouse_id` (string, required): A current store location of the team.

Example request (change_warehouse):

```bash
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

Variant 13 of 25. Sent with `action_name` `clone_order` in the path. On the web page: https://developer.yoprint.com/reference/sales-orders/v2-order-single-action/#variant-clone-order

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

Fields:

- `is_time_shift` (boolean, required): true to move all dates so the copy's issue date is `cloned_anchor_date`; false to keep the original dates.
- `cloned_anchor_date` (string (date), optional): 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_choices` (array of objects, optional): 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.
  - Each item:
    - `action` (string, required): One of: `"leave_out"`, `"replace"`.
    - `id` (string, required): The source line's id.
    - `replacement_id` (string, optional): With `replace`: the size or color (variant) to use instead. Simple products can only be left out.
- `pricing_group_id` (string, optional): 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 (clone_order):

```bash
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

Variant 14 of 25. Sent with `action_name` `convert_to_quote` in the path. On the web page: https://developer.yoprint.com/reference/sales-orders/v2-order-single-action/#variant-convert-to-quote

Turns a sales order into a quote.

Fields:

- `pricing_group_id` (string, optional): 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_id` (string, optional): Optional: the status to give the converted document. Default: the team's starting status.

Example request (convert_to_quote):

```bash
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

Variant 15 of 25. Sent with `action_name` `convert_to_sales_order` in the path. On the web page: https://developer.yoprint.com/reference/sales-orders/v2-order-single-action/#variant-convert-to-sales-order

Turns a quote into a sales order.

Fields:

- `pricing_group_id` (string, optional): 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_id` (string, optional): Optional: the status to give the converted document. Default: the team's starting status.

Example request (convert_to_sales_order):

```bash
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

Variant 16 of 25. Sent with `action_name` `bulk_change_invoice_address` in the path. On the web page: https://developer.yoprint.com/reference/sales-orders/v2-order-single-action/#variant-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.

Fields:

- `update_billing_address` (boolean, required)
- `update_shipping_address` (boolean, required)
- `billing_address_id` (string | null, optional): Required (may be null) when `update_billing_address` is true.
- `shipping_address_id` (string | null, optional): Required (may be null) when `update_shipping_address` is true.

Example request (bulk_change_invoice_address):

```bash
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

Variant 17 of 25. Sent with `action_name` `bulk_change_shipment_address` in the path. On the web page: https://developer.yoprint.com/reference/sales-orders/v2-order-single-action/#variant-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.

Fields:

- `update_shipping_address` (boolean, required)
- `shipping_address_id` (string | null, optional): Required (may be null) when `update_shipping_address` is true.

Example request (bulk_change_shipment_address):

```bash
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

Variant 18 of 25. Sent with `action_name` `configure_order_auto_invoice_managed` in the path. On the web page: https://developer.yoprint.com/reference/sales-orders/v2-order-single-action/#variant-configure-order-auto-invoice-managed

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

Fields:

- `auto_invoice_managed` (boolean, required): true to keep one invoice in step with the order automatically.
- `auto_invoice_shipment_price_type` (string, required): 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_rate` (decimal pair, required): The percentage for MARKUP or MARGIN, as a `{ value, dp }` pair; `dp` 0 to 16. Send 0 for the other types. See https://developer.yoprint.com/concepts/money-and-quantities.md.

Example request (configure_order_auto_invoice_managed):

```bash
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

Variant 19 of 25. Sent with `action_name` `mark_order_as_rush` in the path. On the web page: https://developer.yoprint.com/reference/sales-orders/v2-order-single-action/#variant-mark-order-as-rush

No fields: send `{}`.

Fields:

- None: this variant sends no fields.

Example request (mark_order_as_rush):

```bash
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

Variant 20 of 25. Sent with `action_name` `mark_order_as_not_rush` in the path. On the web page: https://developer.yoprint.com/reference/sales-orders/v2-order-single-action/#variant-mark-order-as-not-rush

No fields: send `{}`.

Fields:

- None: this variant sends no fields.

Example request (mark_order_as_not_rush):

```bash
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

Variant 21 of 25. Sent with `action_name` `mark_all_job_as_rush` in the path. On the web page: https://developer.yoprint.com/reference/sales-orders/v2-order-single-action/#variant-mark-all-job-as-rush

No fields: send `{}`.

Fields:

- None: this variant sends no fields.

Example request (mark_all_job_as_rush):

```bash
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

Variant 22 of 25. Sent with `action_name` `mark_all_job_as_not_rush` in the path. On the web page: https://developer.yoprint.com/reference/sales-orders/v2-order-single-action/#variant-mark-all-job-as-not-rush

No fields: send `{}`.

Fields:

- None: this variant sends no fields.

Example request (mark_all_job_as_not_rush):

```bash
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

Variant 23 of 25. Sent with `action_name` `send_order_detail` in the path. On the web page: https://developer.yoprint.com/reference/sales-orders/v2-order-single-action/#variant-send-order-detail

No fields: send `{}`.

Fields:

- None: this variant sends no fields.

Example request (send_order_detail):

```bash
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

Variant 24 of 25. Sent with `action_name` `send_payment_reminder` in the path. On the web page: https://developer.yoprint.com/reference/sales-orders/v2-order-single-action/#variant-send-payment-reminder

No fields: send `{}`.

Fields:

- None: this variant sends no fields.

Example request (send_payment_reminder):

```bash
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

Variant 25 of 25. Sent with `action_name` `send_approval_reminder` in the path. On the web page: https://developer.yoprint.com/reference/sales-orders/v2-order-single-action/#variant-send-approval-reminder

No fields: send `{}`.

Fields:

- None: this variant sends no fields.

Example request (send_approval_reminder):

```bash
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

`200` Successful response.

Fields:

- `data` (object | array of objects | null, required): Depends on the action: see the description.
  - `id` (string, required): The order's hash id: use it in every other call.
  - `internal_status` (string, required): `draft` until published. One of: `"draft"`, `"published"`.
  - `object_type` (string, required): One of: `"sales_order"`, `"quote"`.
  - `scoped_id` (string, required): The order number people see, `SO` and at least four digits (quotes too). Not an id.
  - `unique_key` (string, required): The order's unique key (`ord_…`); accepted wherever `{order_unique_key}` is.
  - `approval_status` (string | null, optional): `requested`, `sent-to-customer`, `viewed-by-customer`, `need-changes` or `approved`; null without approvals.
  - `assigned_users` (array of objects, optional): The team members in the order's Assigned To list (always included).
    - Each item:
      - `avatar_url` (string | null, optional)
      - `email` (string, optional)
      - `id` (string, optional)
      - `name` (string, optional)
      - `timezone` (string | null, optional): IANA time zone, for example `America/Chicago`.
  - `auto_invoice_managed` (boolean, optional): true when YoPrint keeps one invoice in step with the order.
  - `auto_invoice_shipment_price_type` (string | null, optional): `DONOTMANAGE`, `NONE`, `MARKUP` or `MARGIN`.
  - `auto_invoice_shipment_rate` (decimal pair, optional): 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 https://developer.yoprint.com/concepts/money-and-quantities.md.
  - `auto_invoice_type` (string | null, optional): How the automatic invoice is built. Always `single_invoice` today.
  - `billing_address` (object | null, optional): An address, as the address operations return it.
    - `city` (string | null, optional)
    - `country_code` (string | null, optional)
    - `id` (string, optional)
    - `is_primary` (boolean, optional)
    - `label` (string | null, optional)
    - `postcode` (string | null, optional)
    - `role` (string | null, optional): `billing`, `shipping` or a warehouse role.
    - `state_code` (string | null, optional)
  - `billing_address_id` (string | null, optional)
  - `calc_deposit_total` (integer | number | string | null, optional): 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](/concepts/money-and-quantities/).
  - `client_note` (string | null, optional): The Client Note.
  - `created_at` (string (date-time) | null, optional): Created. ISO 8601 with offset, or null.
  - `created_by` (string | null, optional): Created By (a team member id).
  - `creator_name` (string | null, optional)
  - `cust_due_date` (string (date-time) | null, optional): Customer in-hands date. ISO 8601 with offset, or null.
  - `customer` (object | null, optional): 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.
    - `default_payment_term_id` (string | null, optional)
    - `default_pricing_group_id` (string | null, optional)
    - `id` (string, optional)
    - `is_external` (boolean, optional): true for a customer synced from an integration.
    - `name` (string, optional)
    - `tax_exempt` (boolean, optional)
  - `customer_billing_contact_id` (string | null, optional): The id of the contact on the order (the same contact as `customer_contact_id`), or null.
  - `customer_contact_id` (string | null, optional)
  - `customer_has_email` (boolean, optional)
  - `customer_id` (string | null, optional)
  - `customer_po_number` (string | null, optional)
  - `customer_profile` (object | null, optional): `change_customer` only: the brand profile after the change, or null.
  - `customer_profile_id` (string | null, optional): Brand profile.
  - `deposit_amount_due` (decimal pair, optional): 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 https://developer.yoprint.com/concepts/money-and-quantities.md.
  - `deposit_due` (string (date-time) | null, optional): Deposit due date. ISO 8601 with offset, or null.
  - `deposit_required` (boolean, optional)
  - `deposit_total` (integer | number | string | null, optional): 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_date` (string (date-time) | null, optional): Production due. ISO 8601 with offset, or null.
  - `external_ids` (array of objects, optional): The order's links to records in other systems. An empty list when there are none.
  - `external_type` (string | null, optional): `shopify` for a Shopify order; null for YoPrint orders.
  - `from_legacy` (boolean, optional): true for an order that was moved over from the old format.
  - `full_amount_due` (string (date-time) | null, optional): Full payment due date. ISO 8601 with offset, or null.
  - `grouped_pdf` (array of objects, optional): PDF links, grouped: `Main` (only for roles with `view_order_finance`), `Job` (not on Shopify orders), `Shipment` and the team's templates.
    - Each item:
      - `documents` (array of objects, optional)
      - `label` (string, optional)
  - `has_external_integration_sync_error` (boolean, optional): true when the last sync with an integration failed.
  - `has_invoice` (boolean, optional): true when the order has at least one invoice, so a zero invoiced total can be told apart from no invoice.
  - `has_not_invoiced_items` (boolean, optional): true when some line items are not on an invoice yet.
  - `has_over_invoiced_items` (boolean, optional): true when some line items are invoiced for more than the order has.
  - `has_shipment_items_not_allocated` (boolean, optional): true when some line items are not on a shipment yet.
  - `has_shipment_items_over_allocated` (boolean, optional): true when some line items are on shipments for more than the order has.
  - `has_valid_invoice` (boolean, optional): true when at least one of the order's invoices is in a valid state.
  - `has_valid_shipment` (boolean, optional): true when at least one of the order's shipments is in a valid state.
  - `inventory_status` (string | null, optional): Stock status of the order's lines: `not_committed`, `committed`, `partially_committed`, `not_applicable` or `pending`.
  - `invoice_lock_version` (integer | string | null, optional): Changes whenever the order's invoices change.
  - `invoiced_discount_subtotal` (decimal pair, optional): 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 https://developer.yoprint.com/concepts/money-and-quantities.md.
  - `invoiced_order_item_subtotal` (decimal pair, optional): 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 https://developer.yoprint.com/concepts/money-and-quantities.md.
  - `invoiced_shipment_subtotal` (decimal pair, optional): 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 https://developer.yoprint.com/concepts/money-and-quantities.md.
  - `invoiced_tax_subtotal` (decimal pair, optional): 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 https://developer.yoprint.com/concepts/money-and-quantities.md.
  - `invoiced_total` (decimal pair, optional): 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 https://developer.yoprint.com/concepts/money-and-quantities.md.
  - `is_client_note_editable` (boolean, optional): false for a Shopify order, whose client note comes from Shopify.
  - `is_external` (boolean, optional): true for an order synced from an integration such as Shopify.
  - `is_legacy` (boolean, optional): true for an order made in the old format.
  - `is_rush` (boolean, optional)
  - `issue_date` (string (date-time) | null, optional): Issue date. ISO 8601 with offset, or null.
  - `items` (array of objects, optional): `change_pricing_group` and `change_pricing_strategy` only: the repriced lines.
    - Each item:
      - `_meta` (object, optional): The line's own values again (`id`, `type`, `order_id`, `unit_price`, `subtotal` and so on). Always an object.
      - `id` (string, optional)
      - `inventory_status` (string | null, optional): Stock status of the line.
      - `job` (object, optional)
      - `lock_version` (integer | null, optional): The line's own lock version (a microsecond timestamp).
      - `order_id` (string, optional)
      - `order_unique_key` (string, optional): The order's `unique_key`. The line's own `unique_key` is not in the answer: use `id`.
      - `position` (integer, optional)
      - `pricing` (object, optional)
      - `pricing_rule_applied` (object | null, optional): 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.
        - `after` (string, optional): Full summary only: the price after the rule, as a decimal string.
        - `after_total` (decimal pair, optional): 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. See https://developer.yoprint.com/concepts/money-and-quantities.md.
        - `base` (string, optional): Full summary only: that starting price, as a decimal string with at least 2 decimal places.
        - `base_type` (string, optional): 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_price` (string | null, optional): 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_total` (decimal pair, optional): 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. See https://developer.yoprint.com/concepts/money-and-quantities.md.
        - `pricing_group_id` (string | null, optional): The pricing group whose rule applied.
        - `pricing_group_name` (string | null, optional): Full summary only: the group's name now.
        - `pricing_group_removed` (boolean | null, optional): Full summary only: true when the group was removed since. The line keeps its price.
        - `pricing_rule_id` (string | null, optional): The rule that applied.
        - `rule` (object | null, optional): 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.
          - `id` (string, optional)
          - `label` (string | null, optional)
          - `position` (integer, optional)
        - `type` (string, optional): `product` on a line.
      - `product` (object, optional)
      - `quantity` (object, optional): The quantity, trailing zeros dropped: 10 is `{ "value": 10, "dp": 0 }`.
      - `subtotal` (decimal pair, optional): `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. See https://developer.yoprint.com/concepts/money-and-quantities.md.
      - `trashed` (boolean, optional): true when the line was deleted.
      - `type` (string, optional): The kind of line: db_catalog, user_simple, db_variant, custom or fee.
      - `unit_price` (decimal pair, optional): 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. See https://developer.yoprint.com/concepts/money-and-quantities.md.
  - `job_lock_version` (integer | string | null, optional): Changes whenever the order's jobs change.
  - `last_payment_request_date` (string (date-time) | null, optional): When a payment reminder was last emailed for the order. ISO 8601 with offset, or null.
  - `lock_version` (integer | string | null, optional): Changes on every save.
  - `mode` (string, optional): Older flag: `create` for a draft, `view` once published. One of: `"create"`, `"view"`, `"edit"`.
  - `name` (string | null, optional)
  - `order_balance_due` (decimal pair, optional): 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 https://developer.yoprint.com/concepts/money-and-quantities.md.
  - `order_item_cart_total` (decimal pair, optional): 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 https://developer.yoprint.com/concepts/money-and-quantities.md.
  - `order_item_lock_version` (integer | string | null, optional): Changes whenever the order's line items change.
  - `order_margin_percentage` (decimal pair, optional): 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 https://developer.yoprint.com/concepts/money-and-quantities.md.
  - `order_markup_percentage` (decimal pair, optional): 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 https://developer.yoprint.com/concepts/money-and-quantities.md.
  - `order_profit` (decimal pair, optional): 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 https://developer.yoprint.com/concepts/money-and-quantities.md.
  - `paid_amount` (integer | number | string | null, optional): 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](/concepts/money-and-quantities/).
  - `participants` (array of objects, optional): `change_customer`, `change_pricing_group` and `change_pricing_strategy` only: who receives the order's messages.
  - `payment_lock_version` (integer | string | null, optional): Changes whenever the order's payments change.
  - `payment_term_id` (string | null, optional)
  - `pricing_group_id` (string | null, optional)
  - `pricing_strategy` (string | null, optional): `job_separately`, `job_together` or `service_loc_together`.
  - `prod_note` (string | null, optional): The production note.
  - `producible_item_count` (number | integer | string | null, optional): Quantity to produce.
  - `quickbook_disable_sync` (boolean, optional): true when QuickBooks sync is off for this order.
  - `quickbook_disable_sync_at` (string (date-time) | null, optional): When the switch was last changed. ISO 8601 with offset, or null.
  - `quickbook_disable_sync_by` (string | null, optional): The team member who last changed the switch, or null.
  - `quickbook_disable_sync_reason` (string | null, optional): 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_sync` (string (date-time) | null, optional): When a QuickBooks sync of the order last failed. ISO 8601 with offset, or null.
  - `quickbook_last_success_sync` (string (date-time) | null, optional): When QuickBooks last accepted the order. ISO 8601 with offset, or null.
  - `quickbooks_hold` (object | null, optional): 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.
    - `code` (string, optional): One of: `"changed"`, `"deleted"`, `"rejected"`.
    - `detail` (string | null, optional)
  - `quote` (boolean, optional): Older flag: true for a quote.
  - `ship_due_date` (string (date-time) | null, optional): Ship due date. ISO 8601 with offset, or null.
  - `shipment_billable_fee_invoice_status` (string | null, optional): Whether those shipping fees are on an invoice. Null when there is nothing to bill.
  - `shipment_billable_fee_total` (decimal pair, optional): 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 https://developer.yoprint.com/concepts/money-and-quantities.md.
  - `shipment_cost_total` (decimal pair, optional): 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 https://developer.yoprint.com/concepts/money-and-quantities.md.
  - `shipment_lock_version` (integer | string | null, optional): Changes whenever the order's shipments change.
  - `shipping_address` (object | null, optional): An address, as the address operations return it. Same fields as `data.billing_address` above.
  - `shipping_address_id` (string | null, optional)
  - `shopify_last_error_sync` (string (date-time) | null, optional): When a Shopify sync of the order last failed. Shopify orders only. ISO 8601 with offset, or null.
  - `shopify_last_success_sync` (string (date-time) | null, optional): When Shopify last accepted the order. Shopify orders only. ISO 8601 with offset, or null.
  - `shopify_terminal_topic` (string | null, optional): 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_date` (string (date-time) | null, optional): Production start. ISO 8601 with offset, or null.
  - `status` (object | null, optional): The order's status (always included).
    - `color` (string, required): A hex color, such as `#2196f3`.
    - `customer_label` (string, required): 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`.
    - `id` (string, required)
    - `label` (string, required): The status name people see.
    - `position` (integer, required): Sort order within its list, lowest first.
    - `role` (string, required): Which list the status belongs to: `order`, `quote`, `job`, `shipment`, `purchase_order`, `pipeline` or `customer_message`.
    - `trashed` (boolean, required): true for a deleted status.
    - `type` (string, required): `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_id` (string, optional): The task preset, for `pipeline` statuses only; absent for other roles.
  - `status_completion_date` (string (date-time) | null, optional): When the order's status last moved to an end status. ISO 8601 with offset, or null.
  - `status_id` (string, optional): The order's status (from the team's sales order or quote statuses).
  - `status_last_change_date` (string (date-time) | null, optional): Last status change. ISO 8601 with offset, or null.
  - `tags` (array of objects, optional)
    - Each item:
      - `color_hex` (string | null, optional): Tag color, for example `#E53935`.
      - `id` (string, optional)
      - `name` (string, optional)
  - `total_qty_need_ordering` (string, optional): Quantity still to buy, as a decimal string with 8 decimal places (`"24.00000000"`).
  - `trashed` (boolean, optional): true when the order is deleted.
  - `type` (string, optional): Older name for `object_type`. One of: `"order"`, `"quote"`.
  - `unallocated_amount` (integer | number | string | null, optional): 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](/concepts/money-and-quantities/).
  - `updated_at` (string (date-time) | null, optional): Last changed. ISO 8601 with offset, or null.
  - `version` (integer | string | null, optional): The order format version.
  - `wallet_currency_iso` (string | null, optional): The order's currency code (`USD` and so on), or null on older orders without one.
  - `warehouse_id` (string | null, optional)
  - `calc_discount` (integer | number | string | null, optional, deprecated): **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](/concepts/money-and-quantities/).
  - `calc_subtotal` (integer | number | string | null, optional, deprecated): **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](/concepts/money-and-quantities/).
  - `calc_tax` (integer | number | string | null, optional, deprecated): **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](/concepts/money-and-quantities/).
  - `calc_total` (integer | number | string | null, optional, deprecated): **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](/concepts/money-and-quantities/).
- `status` (integer, required)
- `success` (boolean, required)

Example response:

```json
{
  "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-1188",
    "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": false,
    "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
}
```

## Errors

- `401` The API key is missing or wrong (`unauthenticated`).
- `403` You 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.
- `404` Not 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.
- `422` The 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.

## Related

- [Update a sales order or quote](https://developer.yoprint.com/reference/sales-orders/v2-order-update.md): `PUT /v2/api/store/{team_slug}/v2/sales_order/{order_unique_key}`
- [List sales order statuses](https://developer.yoprint.com/reference/statuses/v1-status-list-sales-order.md): `GET /v1/api/store/{team_slug}/setting/status/sales_order`
- [List quote statuses](https://developer.yoprint.com/reference/statuses/v1-status-list-quote.md): `GET /v1/api/store/{team_slug}/setting/status/quote`
- [List payment terms](https://developer.yoprint.com/reference/payment-terms/v1-payment-term-index.md): `GET /v1/api/store/{team_slug}/setting/payment_term`