Create a status

POST/v1/api/store/{team_slug}/setting/status

v1Operation ID v1_public_status_store

Adds an in-between status (type: in_progress) to one list: sales orders, quotes, jobs, purchase orders, shipments, message threads, or the tasks of a task preset.

Every list already has one starting and one ending status, which you can rename but not add. To move the start or end marker to another status, use "Save a set of status changes" (POST /v1/api/store/{team_slug}/setting/status/sync).

Returns the new status.

Permission

Needs the Manage Settings permission. The team owner always has it.

Business rules

Only type: in_progress saves. pre_production passes validation but fails with 500; start and end are refused with 422.
pipeline_id is required when role is pipeline, and ignored for every other role.
Labels don't have to be unique.

Side effects

Team members who have YoPrint open see the new status at once.

Path parameters

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

Request body

application/json, required.

typestringrequired
Must be in_progress. Other types cannot be created with this operation (to create or change start or end statuses, use Save a set of status changes).
- Always "in_progress"
colorstringrequired
A hex color with the #, 3 or 6 digits: #1e88e5.
- Matches ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$
labelstringrequired
The name your team sees.
rolestringrequired
Which status list to add it to:
- order: sales orders
- quote: quotes
- job: jobs
- purchase_order: purchase orders
- shipment: shipments
- customer_message: message threads
- pipeline: tasks within a task preset (requires pipeline_id)
- One of: "order", "quote", "job", "purchase_order", "shipment", "customer_message", "pipeline"
customer_labelstring
Optional. What customers see in the customer portal.
pipeline_idstring
Required when role is pipeline: the ID of the task preset this status belongs to. Ignored for other roles.
positioninteger
Sort order within the list. Defaults to 0.
- Minimum -2147483648
- Maximum 2147483647

More examples (1)

A task status in a task preset

curl

curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/setting/status' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "color": "#43a047",    "label": "Screens burned",    "pipeline_id": "eIOQnV5PP0pp7c",    "position": 1,    "role": "pipeline",    "type": "in_progress"  }'

Response

200Successful response.

dataobjectrequired
Child fields (9)
- colorstringrequired
- customer_labelstringrequired
  What customers see in the customer portal. When none is set: Pending for start, In Progress for in_progress and pre_production, Completed for end.
- idstringrequired
- labelstringrequired
- positionintegerrequired
  Sort order within the list, lowest first.
- rolestringrequired
  Which list the status belongs to:
  - order: sales orders
  - quote: quotes
  - job: jobs
  - purchase_order: purchase orders
  - shipment: shipments
  - customer_message: message threads
  - pipeline: tasks within a task preset
  - One of: "order", "quote", "job", "purchase_order", "shipment", "customer_message", "pipeline"
- trashedbooleanrequired
  True for a deleted status. Only the full list includes deleted ones.
- typestringrequired
  The stage of the status in the workflow: start (first status in the list), pre_production, in_progress, or end (final status).
  - One of: "start", "pre_production", "in_progress", "end"
- pipeline_idstring
  The task preset, for pipeline statuses only. Absent for every other role.
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.
When
Your role lacks Manage Settings. The body is {"message": "Insufficient Permission"}, without the error envelope.
Fix
Use the key of a member whose role has Manage Settings, or the owner's.
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.
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
A required field is missing, color is not a hex color, or type or role is not an allowed value (validation_failed, with error.fields).
Fix
Send label, color like #1e88e5, type: in_progress and a role from the list.
500A business rule refused the request (see the operation's errors), or something failed inside YoPrint. Refusals use the error envelope with a code such as action_not_allowed; an unexpected failure answers {"message": "Server Error"}. Repeating a refusal gets the same answer; after an unexpected failure, read the record back before you retry a change.
When
type is pre_production. The body is {"message": "Server Error"}, without the error envelope.
Fix
Send type: in_progress. Nothing was saved.

PATCHUpdate a status without checks/v1/api/store/{team_slug}/setting/status/{status_reference}
POSTSave a set of status changes/v1/api/store/{team_slug}/setting/status/{status_reference}
GETList sales order statuses/v1/api/store/{team_slug}/setting/status/sales_order

Example request

curl

curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/setting/status' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "color": "#1e88e5",    "label": "Printing",    "position": 2,    "role": "order",    "type": "in_progress"  }'

Example response 200

{
  "data": {
    "color": "#1e88e5",
    "customer_label": "In Progress",
    "id": "0CoeFF1BmpcxxE",
    "label": "Printing",
    "position": 2,
    "role": "order",
    "trashed": false,
    "type": "in_progress"
  },
  "status": 200,
  "success": true
}

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 spec Support: support@yoprint.com yoprint.com