Publish a draft sales order or quote

PATCH/v2/api/store/{team_slug}/v2/sales_order/{order_unique_key}/publish

v2Operation ID v2_public_order_publish

Publishes a draft: what the Publish button does in the web app. The order or quote then counts as created, shows in lists and reports, and can take payments, approvals and comments.

Publishing checks four things and reports them in data.validation: the order has a customer (has_customer), at least one line (has_order_items), no line on a phased-out or deleted product, size or color (has_sellable_items), and its pricing group is still in use (removed_pricing_group).

When a check fails the draft is not published: the answer is still 200, with data.valid: false. data.validation.unsellable_items lists each unsellable line with its reason (product_phased_out, product_deleted, variant_phased_out or variant_deleted): replace or remove those lines. data.validation.removed_pricing_group is null, or names the draft's pricing group when it was removed ({ id, name, removed, disabled }): choose another group with the change_pricing_group action. Then publish again.

When all checks pass the answer is data.valid: true. Do not rely on the HTTP status code alone: check success and data.valid in the response body to confirm the draft was published.

{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

Needs permission to edit this sales order or quote:

• The team owner
• A role with update_all_order
• A role with update_self_order, when the order was created by or is assigned to the API key's user
• The person who created a draft, with create_order

Quotes use the same sales order permissions.

Business rules

• Only drafts can be published. Publishing an order that is already published answers HTTP 200 with {"status": 500, "success": false, "error": {"code": "action_not_allowed", "message": null}} and changes nothing. Always check success and data.valid in the response body, not the HTTP status code.
• A draft without a customer, without lines, with an unsellable line, or on a removed pricing group is not published.

Side effects

• Sends the order.created webhook (quote.created for a quote).
• Works out stock status for the order's lines and jobs, and updates the customer's totals.
• When the team syncs to QuickBooks Online automatically, publishing a sales order that already has invoices (for example a copy made with clone_order) queues a sync.
• Emails nobody. Customer Portal pages the customer has open refresh.

Path parameters

• team_slugstringrequired

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

  • Example your-team
• order_unique_keystringrequired

  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

Request body

This operation takes no request body.

Response

200Successful response.

A 200 answer can still be a refusal

Check success (and the fields named below) as well as the HTTP status:

• A check failed: data.valid is false and data.validation says which. Fix: Add a customer or lines, replace the unsellable lines, or choose another pricing group (change_pricing_group), then publish again.
• The order is not a draft: success: false, error.code action_not_allowed (the body's status says 500). Fix: Check success in every reply. Read the order first: internal_status must be draft.

Refused with HTTP 200: `success` is false

{
  "error": {
    "code": "action_not_allowed",
    "message": null
  },
  "status": 500,
  "success": false
}

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.

  When

  The API key's role can't edit this order.

  Fix

  Ask the team owner for sales order edit permission.

• 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 such order in this team, or it is deleted.

  Fix

  Check the id; restore a deleted draft first.

Notes

• Do not rely on the HTTP status code alone. Always check success and data.valid in the response body: a 200 does not mean it was published.

Related

• POSTCreate a sales order or quote/v2/api/store/{team_slug}/v2/sales_order/new
• POSTAdd a line item to a sales order or quote/v2/api/store/{team_slug}/v2/sales_order/{order_unique_key}/order_item
• PUTRun an action on a sales order or quote/v2/api/store/{team_slug}/v2/sales_order/{order_unique_key}/action/{action_name}

Example request

curl

curl -X PATCH 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/publish' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1'

Example response 200

Response

{
  "data": {
    "id": "V4keXwwxMQyXw7",
    "lock_version": {
      "invoice_lock_version": 1793696400123456,
      "job_lock_version": 1793696400123456,
      "order_item_lock_version": 1793696400234567,
      "order_lock_version": 1793696400234567,
      "payment_lock_version": 1793696400123456,
      "shipment_lock_version": null
    },
    "valid": true,
    "validation": {
      "has_customer": true,
      "has_order_items": true,
      "has_sellable_items": true,
      "unsellable_items": []
    }
  },
  "status": 200,
  "success": true
}