Skip to content
YoPrintDevelopers

Email an approval request to the customer

Open .md

PATCH/v1/api/store/{team_slug}/approvals/{hash_id}/send_to_customer

v1Operation ID v1_public_approvals_send_to_customer

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_slugstringrequired

    Your team slug, shown as Team ID next to your API key in Profile.

    • Example your-team
  • hash_idstringrequired

    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.

Response

200Successful response.

  • dataobjectrequired
    Child fields (26)
    • approved_bystring

      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_idstring | null

      The contact who completed it in the Customer Portal, when YoPrint knows which contact it was. Null otherwise.

    • approved_by_userstring | null

      The hash id of the team member who completed it on the customer's behalf, if any.

    • completedboolean

      True once the customer finished, whether they approved or asked for changes.

    • completed_atstring (date-time) | null
    • created_atstring (date-time)
    • customer_last_viewed_contact_idstring | null

      The last contact known to have opened it in the Customer Portal. Null when none is known.

    • customer_last_viewed_datestring (date-time) | null
    • idstring
    • itemsarray of objects

      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.

      Fields of each item (9)
      • idstring

        The item's id.

      • media_idstring | null

        media items: the file's id.

      • mockup_design_idstring | null

        mockup_design items: the design's id.

      • namestring | null
      • notes_from_customerstring | null
      • notes_to_customerstring | null
      • positioninteger
      • statusstring
        • One of: "pending-approval", "approved", "need-changes"
      • typestring

        media: an uploaded mockup file. mockup_design: a design made in the mockup designer.

        • One of: "media", "mockup_design"
    • job_idstring | null

      Job approvals only.

    • job_namestring

      An empty string for order approvals.

    • job_scoped_idstring

      The job number, such as JOB-1001. An empty string for order approvals.

    • mockuparray of objects | null

      Job approvals: the uploaded mockup files only (designs are only in items); an empty list when there are none. Null for order approvals.

      Fields of each item (11)
    • notes_from_customerstring | null
    • notes_to_customerstring | null
    • order_external_typestring | null
    • order_idstring | null
    • order_object_typestring | null

      sales_order or quote.

      • One of: "sales_order", "quote"
    • order_quoteboolean

      True when the approval is on a quote.

    • order_scoped_idstring

      The order or quote number.

    • request_bystring | null

      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.

    • signaturestring | null

      The customer's signature, when they signed.

    • signed_terms_textstring | null

      The terms the customer agreed to when signing.

    • statusstring

      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"
    • typestring

      job: artwork approval for one job's mockups. order: approval of the whole order.

      • One of: "job", "order"
  • statusintegerrequired
  • successbooleanrequired

Errors

  • 401The API key is missing or wrong (unauthenticated).

  • 403You are not allowed to do this. api_access_not_in_plan: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only {"message": "Insufficient Permission"}. Other refusals use the error envelope, with unauthorized or user_is_not_authorized.

  • 404Not found. page_not_found: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. code: null, with a message that starts "No query results for": there is no record with that id.

    When
    No approval of this team has this id.
    Fix
    Use an id from the approvals list.

  • 422The request was refused and changed nothing. validation_failed lists what to fix in error.fields; other codes name a business rule, explained in error.message. A few checks answer with only {"message": "..."}. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer connect_timeout ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.

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

AI agents: read /llms.txt; add .md to any page URL for its Markdown. Guides and concepts in one file: /llms-full.txt.

Download the OpenAPI specSupport: support@yoprint.comyoprint.com