# Email an approval request to the customer

```http
PATCH https://secure.yoprint.com/v1/api/store/{team_slug}/approvals/{hash_id}/send_to_customer
```

- API version: v1
- Operation ID: `v1_public_approvals_send_to_customer`
- Section: Sales › [Approvals](https://developer.yoprint.com/reference/approvals.md)
- Web page: https://developer.yoprint.com/reference/approvals/v1-approvals-send-to-customer/
- Authentication: `Authorization: Bearer YOUR_API_KEY`

Emails the customer a link to the approval in the customer portal. Use it to send a new approval, or to remind them. A `pending` approval becomes `sent-to-customer`; sending again later emails again and leaves the status as it is.

The email goes to the order's message participants who receive email (`can_receive_mail` true and `status` `all` or `message`), or, if there are none, the order's contact. The subject starts with the sales order or quote number in brackets (with the customer PO number, if any), then "Job - <job name> Artwork Approval Required" for a job approval or "Order Approval Required" for an order approval. It is email only, never SMS. Send no body.

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.

Returns the approval.

## Permission

Any member of the team.

## Business rules

- The approval must not be completed, and its order must be saved: not a draft, and not an unsaved edit copy.
- Someone on the order must be able to receive email.
- At most 60 calls a minute for your whole team. The 61st call is refused and blocks your team's email sending: from then on this operation, sending order details, payment reminders and approval reminders, and sending message templates are refused with 422 until YoPrint support lifts the block.

## Side effects

- Sends an email to the customer, recorded in the order's messages.
- Logs "approval sent" in the order's activity.
- A `pending` approval becomes `sent-to-customer`; for an order approval, the order's approval status does too.
- People with the order open, and the customer's open Customer Portal pages, see the change live. No webhook fires on sending.

## 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 approval's `id`, from the approvals list. A hash id; unique keys and document numbers are refused with 404. Example `Fi0zPeMlwKadEo`.

## Request body

This operation takes no request body.

### Example request

```bash
curl -X PATCH 'https://secure.yoprint.com/v1/api/store/your-team/approvals/Fi0zPeMlwKadEo/send_to_customer' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'X-Yoprint-Decimal-Format: exact-v1'
```

## Response

`200` Successful response.

Fields:

- `data` (object, required)
  - `approved_by` (string, optional): `contact` when a Customer Portal contact completed it (`approved_by_contact_id`). `user` when a team member completed it. Otherwise `customer`, even before anyone has approved it. One of: `"contact"`, `"user"`, `"customer"`.
  - `approved_by_contact_id` (string | null, optional): The contact who completed it in the Customer Portal, when YoPrint knows which contact it was. Null otherwise.
  - `approved_by_user` (string | null, optional): The hash id of the team member who completed it on the customer's behalf, if any.
  - `completed` (boolean, optional): True once the customer finished, whether they approved or asked for changes.
  - `completed_at` (string (date-time) | null, optional)
  - `created_at` (string (date-time), optional)
  - `customer_last_viewed_contact_id` (string | null, optional): The last contact known to have opened it in the Customer Portal. Null when none is known.
  - `customer_last_viewed_date` (string (date-time) | null, optional)
  - `id` (string, optional)
  - `items` (array of objects, optional): Job approvals: each mockup file or design, in order, with its own status and notes. `media` items also carry the file's details and expiring links; `mockup_design` items carry the design's revision and page previews. An empty list for order approvals.
    - Each item:
      - `id` (string, optional): The item's id.
      - `media_id` (string | null, optional): `media` items: the file's id.
      - `mockup_design_id` (string | null, optional): `mockup_design` items: the design's id.
      - `name` (string | null, optional)
      - `notes_from_customer` (string | null, optional)
      - `notes_to_customer` (string | null, optional)
      - `position` (integer, optional)
      - `status` (string, optional): One of: `"pending-approval"`, `"approved"`, `"need-changes"`.
      - `type` (string, optional): `media`: an uploaded mockup file. `mockup_design`: a design made in the mockup designer. One of: `"media"`, `"mockup_design"`.
  - `job_id` (string | null, optional): Job approvals only.
  - `job_name` (string, optional): An empty string for order approvals.
  - `job_scoped_id` (string, optional): The job number, such as `JOB-1001`. An empty string for order approvals.
  - `mockup` (array of objects | null, optional): Job approvals: the uploaded mockup files only (designs are only in `items`); an empty list when there are none. Null for order approvals.
    - Each item:
      - `created_at` (string (date-time), optional)
      - `file_name` (string, optional)
      - `id` (string, optional): The same id as the matching `media` item in `items`.
      - `media_id` (string, optional): The file's id.
      - `mime_type` (string, optional)
      - `name` (string, optional)
      - `notes_from_customer` (string | null, optional)
      - `notes_to_customer` (string | null, optional)
      - `position` (integer, optional)
      - `status` (string, optional): One of: `"pending-approval"`, `"approved"`, `"need-changes"`.
      - `url` (string, optional): A signed download link. It expires; don't store it.
  - `notes_from_customer` (string | null, optional)
  - `notes_to_customer` (string | null, optional)
  - `order_external_type` (string | null, optional)
  - `order_id` (string | null, optional)
  - `order_object_type` (string | null, optional): `sales_order` or `quote`. One of: `"sales_order"`, `"quote"`.
  - `order_quote` (boolean, optional): True when the approval is on a quote.
  - `order_scoped_id` (string, optional): The order or quote number.
  - `request_by` (string | null, optional): A team member's hash id, or null. Approvals created in the web app or through the API are null here: neither records who requested them.
  - `signature` (string | null, optional): The customer's signature, when they signed.
  - `signed_terms_text` (string | null, optional): The terms the customer agreed to when signing.
  - `status` (string, optional): `pending`: not sent yet. `sent-to-customer`: emailed. `viewed-by-customer`: the customer opened it. `need-changes`: the customer finished and asked for changes ("Review requested"). `completed`: approved. One of: `"pending"`, `"sent-to-customer"`, `"viewed-by-customer"`, `"need-changes"`, `"completed"`.
  - `type` (string, optional): `job`: artwork approval for one job's mockups. `order`: approval of the whole order. One of: `"job"`, `"order"`.
- `status` (integer, required)
- `success` (boolean, required)

Example response:

```json
{
  "data": {
    "approved_by": "customer",
    "approved_by_contact_id": null,
    "approved_by_user": null,
    "completed": false,
    "completed_at": null,
    "created_at": "2026-11-03T09:30:00+00:00",
    "customer_last_viewed_contact_id": null,
    "customer_last_viewed_date": null,
    "id": "Fi0zPeMlwKadEo",
    "items": [
      {
        "collection": "mockup",
        "created_at": "2026-11-03T09:30:00+00:00",
        "download_url": "https://example.com/media/front-logo.png?download=1",
        "file_name": "front-logo.png",
        "id": "Top25MBL9YyCKV",
        "is_image": true,
        "media_id": "b0l2VJxwa3ppc7",
        "mime_type": "image/png",
        "name": "front-logo",
        "notes_from_customer": null,
        "notes_to_customer": null,
        "position": 1,
        "preview": {
          "large": "https://example.com/media/front-logo-1200.png",
          "medium": "https://example.com/media/front-logo-800.png",
          "small": "https://example.com/media/front-logo-250.png"
        },
        "preview_url": "https://example.com/media/front-logo-800.png",
        "show_in_pdf": null,
        "size": 182044,
        "status": "pending-approval",
        "type": "media",
        "url": "https://example.com/media/front-logo.png?download=1",
        "view_url": "https://example.com/media/front-logo.png"
      }
    ],
    "job_id": "K6iF8n29iwOZnj",
    "job_name": "Front logo",
    "job_scoped_id": "JOB-1001",
    "mockup": [
      {
        "collection": "mockup",
        "created_at": "2026-11-03T09:30:00+00:00",
        "file_name": "front-logo.png",
        "id": "Top25MBL9YyCKV",
        "is_image": true,
        "media_id": "b0l2VJxwa3ppc7",
        "mime_type": "image/png",
        "name": "front-logo",
        "notes_from_customer": null,
        "notes_to_customer": null,
        "position": 1,
        "preview": {
          "large": "https://example.com/media/front-logo-1200.png",
          "medium": "https://example.com/media/front-logo-800.png",
          "small": "https://example.com/media/front-logo-250.png"
        },
        "show_in_pdf": null,
        "size": 182044,
        "status": "pending-approval",
        "url": "https://example.com/media/front-logo.png?download=1",
        "view_url": "https://example.com/media/front-logo.png"
      }
    ],
    "notes_from_customer": null,
    "notes_to_customer": "Please check the logo size.",
    "order_external_type": null,
    "order_id": "V4keXwwxMQyXw7",
    "order_object_type": "sales_order",
    "order_quote": false,
    "order_scoped_id": "SO1001",
    "request_by": null,
    "signature": null,
    "signed_terms_text": null,
    "status": "sent-to-customer",
    "type": "job"
  },
  "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.
  - When: No approval of this team has this id. Fix: Use an `id` from the approvals list.
- `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: Nobody on the order has an email address (`approval_email_no_recipient`). Fix: Add a contact with an email address to the order, then send again.
  - When: The approval is completed, or the order is still a draft or an unsaved edit copy (`approval_already_completed`, "You cannot send completed approval to customer again."). Fix: Create a new approval, or save the order first.
  - When: The order came from Shopify (`shopify_approval_workflow_locked`). Fix: Shopify orders do not use approvals in YoPrint.
  - When: Your team called this more than 60 times in a minute, or its email sending was already blocked (`validation_error`, "You are sending too many emails in a short period of time..."). Fix: Contact YoPrint support. Space out bulk sends to stay well under 60 a minute.

## Notes

- Don't loop this over many approvals quickly: the per-team limit counts every call that reaches it, including ones that then fail with 404 or 422, and going over it blocks your team's email sending until support lifts it.

## Related

- [List approvals](https://developer.yoprint.com/reference/approvals/v1-approvals-index.md): `GET /v1/api/store/{team_slug}/approvals`
- [Delete an approval](https://developer.yoprint.com/reference/approvals/v1-approvals-destroy.md): `DELETE /v1/api/store/{team_slug}/approvals/{hash_id}`