# Ask the customer to approve an order

```http
POST https://secure.yoprint.com/v2/api/store/{team_slug}/v2/sales_order/{hash_id}/approval
```

- API version: v2
- Operation ID: `v2_public_order_approval_store`
- Section: Sales › [Sales order approvals](https://developer.yoprint.com/reference/sales-order-approvals.md)
- Web page: https://developer.yoprint.com/reference/sales-order-approvals/v2-order-approval-store/
- Authentication: `Authorization: Bearer YOUR_API_KEY`

Creates an order approval on a published sales order or quote and, unless you say otherwise, emails it to the customer.

An order approval asks the customer to approve the whole sales order or quote. They open it from the email or the customer portal, type their name as a signature, and approve it or ask for changes. Artwork approvals for single jobs are separate (List all approvals of an order shows both).

With `send_later: true`, or when the order has no customer, the approval is created but not emailed: its `status` is `pending`. Send it later from the web app or with the `send_approval_reminder` action. An emailed approval comes back as `sent-to-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.

The answer is the new approval. `{hash_id}` is the order's `id` (for example `V4keXwwxMQyXw7`); the `ord_` unique key is not accepted here.

## Permission

Any member of the team.

## Business rules

- The order must be published: drafts are refused ("No Permission - you cannot add approval to an order/quote mode: draft").
- An order can have only one pending order approval: "An Order/Quote can only has one pending approval."
- When emailing (an order with a customer, without `send_later`), someone on the order must have an email address (422 `approval_email_no_recipient`); otherwise send it with `send_later: true`.
- Shopify orders refuse approvals.

## Side effects

- Without `send_later`, on an order with a customer: emails the approval to the customer, and both the approval's `status` and the order's `approval_status` become `sent-to-customer`.
- With `send_later: true`, or on an order without a customer: nothing is emailed, the approval is `pending` and the order's `approval_status` is `requested`.
- The email's link opens the approval for the contact it was sent to: when that contact answers in the customer portal, the approval's `approved_by` is `contact`, with `approved_by_contact_id`.
- 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`.
- `hash_id` (string, required): The sales order's or quote's `id` (a hash id). The `ord_` unique key and the order number do not work here. Example `V4keXwwxMQyXw7`.

## Request body

Content type `application/json`, required.

Fields:

- `notes_to_customer` (string, optional): A note shown to the customer with the approval.
- `send_later` (boolean, optional): true to create the approval without emailing it. Default false.

### Example request

```bash
curl -X POST 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/approval' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'X-Yoprint-Decimal-Format: exact-v1' \
  -H 'Content-Type: application/json' \
  -d '{
    "notes_to_customer": "Please review the sizes and colors.",
    "send_later": false
  }'
```

## Response

`200` Successful response.

Fields:

- `data` (object, required): An approval.
  - `id` (string, required)
  - `status` (string | null, required): `pending` (created, not emailed), `sent-to-customer`, `viewed-by-customer`, `need-changes` or `completed` (approved). When it was completed without a `status`, the Record answer shows `null` and later reads show `""`.
  - `type` (string, required): `order` for a whole-order approval, `job` for an artwork approval. One of: `"order"`, `"job"`.
  - `approved_by` (string, optional): `contact` when a contact of the order's customer answered in the customer portal (see `approved_by_contact_id`), `user` when a team member recorded the answer (as Record the customer's answer does), `customer` otherwise, including before any answer. One of: `"contact"`, `"user"`, `"customer"`.
  - `approved_by_contact_id` (string | null, optional): The contact who answered in the customer portal, or null (always null when a team member recorded the answer).
  - `approved_by_user` (string | null, optional): The team member who recorded the answer, or null.
  - `completed` (boolean, optional): true once the customer (or you, for them) answered: approved or changes needed.
  - `completed_at` (string (date-time) | null, optional): When the customer answered. ISO 8601 with offset, or null.
  - `created_at` (string (date-time) | null, optional): Created. ISO 8601 with offset, or null.
  - `customer_last_viewed_contact_id` (string | null, optional): The contact who last opened it in the customer portal, or null when that isn't known.
  - `customer_last_viewed_date` (string (date-time) | null, optional): When the customer last opened it. ISO 8601 with offset, or null.
  - `items` (array of objects, optional): Job approvals: the mockups under review.
  - `job_id` (string | null, optional)
  - `notes_from_customer` (string | null, optional)
  - `notes_to_customer` (string | null, optional)
  - `order_id` (string, optional)
  - `order_scoped_id` (string, optional)
  - `signature` (string | null, optional): The signer's typed name.
- `status` (integer, required)
- `success` (boolean, required)

Example response:

```json
{
  "data": {
    "approved_by": "customer",
    "approved_by_contact_id": null,
    "approved_by_user": null,
    "completed": false,
    "created_at": "2026-11-03T09:00:00+00:00",
    "customer_last_viewed_contact_id": null,
    "customer_last_viewed_date": null,
    "id": "xTKi8BqFVVmlL6",
    "notes_to_customer": "Please review the sizes and colors.",
    "order_id": "V4keXwwxMQyXw7",
    "order_scoped_id": "SO1001",
    "status": "sent-to-customer",
    "type": "order"
  },
  "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`.
- `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.
- `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: A draft, a second pending approval, a Shopify order, or no email recipient. Fix: Publish first, complete or delete the pending approval, or use `send_later`.

## Related

- [Record the customer's answer to an order approval](https://developer.yoprint.com/reference/sales-order-approvals/v2-order-approval-complete.md): `PUT /v2/api/store/{team_slug}/v2/sales_order/{hash_id}/approval/{hash_id2}/complete`
- [Run an action on a sales order or quote](https://developer.yoprint.com/reference/sales-orders/v2-order-single-action.md): `PUT /v2/api/store/{team_slug}/v2/sales_order/{order_unique_key}/action/{action_name}`
- [Delete an order approval](https://developer.yoprint.com/reference/sales-order-approvals/v2-order-approval-destroy.md): `DELETE /v2/api/store/{team_slug}/v2/sales_order/{hash_id}/approval/{hash_id2}`