# Quotes and sales orders

> A quote and a sales order are one record with a type. Draft and published, converting, statuses, an order's dates, approvals, the Customer Portal, and what else an order carries.

Web page: https://developer.yoprint.com/how-yoprint-works/quotes-and-sales-orders/

A **quote** prices work for a customer. A **sales order** is work the shop has agreed to do: it's what the shop makes, ships, bills and gets paid for. In YoPrint they're one kind of record with a type, so a quote becomes a sales order without being copied. In the web app they're **Quotes** and **Sales Orders**.

## From quote to sales order

**Diagram:** The usual path. The record keeps its id and its document number all the way through.

1. **Draft quote**: Built in private: customer, lines, prices and dates → publish
2. **Quote**: Sent to the customer, who approves it → convert
3. **Sales order**: Made, shipped, invoiced and paid

When a customer orders without a quote, the shop skips it:

**Diagram:** Publishing is one-way. Converting works both ways.

1. **Draft sales order**: Built in private → publish
2. **Sales order**: Made, shipped, invoiced and paid

- The type is the order's `object_type`: `quote` or `sales_order`.
- Converting works both ways: a sales order can go back to being a quote, which releases the stock held for it. Orders synced from Shopify, or made for a customer synced from Shopify, can't be converted.
- A quote can have invoices and shipments too, but shipping labels can only be bought on a sales order.
- Quotes and sales orders share one sequence of document numbers, such as `SO1001` for a quote and `SO1002` for the next sales order.
- Deleting an order deletes its jobs, invoices and shipments, and moves a published order's payments to the customer's store credit. A deleted order can be restored. See [What a write also does](https://developer.yoprint.com/concepts/side-effects.md).

## Draft or published

Every order starts as a **draft**, and publishing it is a one-way step: in the web app, the **Publish** button.

|                                  | Draft                                              | Published                                                    |
| -------------------------------- | -------------------------------------------------- | ------------------------------------------------------------ |
| Customer                         | Can be changed                                     | Fixed                                                        |
| Lines, prices and dates          | Change freely, with no history                     | Change, and each change is recorded in the order's history   |
| Comments, approvals and payments | Not yet                                            | Yes                                                          |
| GoShippo labels                  | Not yet (a label bought elsewhere can be recorded) | Yes, on a sales order                                        |
| Stock                            | Not held                                           | Held for its lines, on a sales order                         |
| Webhooks                         | None                                               | `order.created` or `quote.created` fires when it's published |

Publishing checks the order first. It needs a customer, at least one line, lines whose products can still be sold, and a pricing group that hasn't been removed. When a check fails, nothing is published and the answer says which check failed.

## Statuses

A **status** is a stage the team names itself, such as "Pending approval" or "In production". It sits alongside draft and published, not instead of them: every order has a status, even a draft.

|                  | Draft or published                   | Status                                                                                                                                           |
| ---------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Who sets it      | YoPrint, when the order is published | The team, from its own list                                                                                                                      |
| How often        | Once                                 | Whenever the work moves on                                                                                                                       |
| What it controls | What can be done to the order        | Not what the order allows: it tells people where the work is. A few status changes have effects, such as a shipment's fulfilling a Shopify order |
| Webhook          | `order.created` or `quote.created`   | `sales_order.status_changed` or `quote.status_changed`                                                                                           |

Quotes, sales orders, jobs, shipments, purchase orders and message threads each have their own list, and tasks use their task preset's. Each status has a **type**: `start`, `pre_production`, `in_progress` or `end`. Here are the sales order statuses a new team starts with:

**Diagram:** A converted quote starts in the sales order list's start status, unless you choose another.

1. **start**: Pending
2. **in_progress**: Pending approval, Good to go, Waiting goods, Pending production, In production, Pending payment
3. **end**: Completed

## An order's dates

**Diagram:** The usual order. YoPrint doesn't force it: each date is set on its own.

1. **Issue date**: `issue_date`: when the order was issued
2. **Production**: `start_date` to `due_date`: when the shop makes it
3. **Ship due**: `ship_due_date`: when it must ship
4. **In hands**: `cust_due_date`: when the customer needs it

Two more dates say when the customer pays: `deposit_due` and `full_amount_due`, set by the order's payment terms. See [Invoices and payments](https://developer.yoprint.com/how-yoprint-works/invoices-and-payments.md).

## Approvals and the Customer Portal

The **Customer Portal** is the website where a shop's customers see their quotes and orders, approve them, send messages and pay. An **approval** asks the customer to agree to something:

| Approval                | What the customer approves                                   | Webhook when they answer                                       |
| ----------------------- | ------------------------------------------------------------ | -------------------------------------------------------------- |
| Quote or order approval | The quote or order itself, with notes, terms and a signature | `order_approval.approved` or `order_approval.change_requested` |
| Artwork approval        | A job's mockups, one by one                                  | `job_approval.approved` or `job_approval.change_requested`     |

**Diagram:** Asking for changes needs a note from the customer. Approvals start only once the order is published.

1. **Pending**: Created, not sent yet
2. **Sent to customer**: Emailed with a link to the Customer Portal
3. **Viewed by customer**: The customer opened it
4. **Approved, or changes requested**: The customer's answer: `completed` or `need-changes`

## What else an order carries

|                            | What it is                                                                                                                             |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Customer and addresses** | Who it's for, with billing and shipping addresses. New orders take the customer's defaults.                                            |
| **Pricing group**          | The markups that price its lines. See [Products and pricing](https://developer.yoprint.com/how-yoprint-works/products-and-pricing.md). |
| **Payment terms**          | The deposit and when payment is due.                                                                                                   |
| **Rush**                   | A flag on the order. Each job has its own too.                                                                                         |
| **Tags and assignees**     | Labels for finding orders, and the team members responsible.                                                                           |
| **Comments**               | Notes for the team. The customer never sees them.                                                                                      |
| **Messages**               | Emails and texts with the customer and other recipients.                                                                               |
| **Files**                  | Artwork and attachments on the order.                                                                                                  |
| **History**                | Who changed what, once it's published.                                                                                                 |

Cloning an order makes a new draft with a new number, from the same customer and lines.

## In the API

[Create and change orders](https://developer.yoprint.com/guides/orders.md): Create, change, publish, approve, convert, delete and restore.

[Quote to payment](https://developer.yoprint.com/guides/quote-to-payment.md): Walk one order from a draft quote to a paid sales order.

[Sales orders reference](https://developer.yoprint.com/reference/sales-orders.md): Orders and quotes, with their line items, approvals and other parts under them.