Skip to content
YoPrintDevelopers

Save a set of status changes

Open .md

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

v1Operation ID v1_public_status_sync

Creates, updates and deletes several statuses in one request, all or nothing. This is how the web app saves the status settings page, and the only way to move a list's start or end marker.

Call it as POST /v1/api/store/{team_slug}/setting/status/sync: the last path segment must be the word sync. Any other word answers 405.

Send data, a list of changes, each with an action:

  • create: a new status. Needs label, color, role, type (in_progress or end) and position.
  • update: an existing status, by id. Send position and what changes. Unlike the single update, it can change type.
  • delete: an in_progress status, by id.

Returns every status of the team, including deleted ones, like the full list.

Permission

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

Business rules

  • All changes run in one transaction: if one fails, none is saved.
  • Updating a status to type: start or end turns the list's current start or end status into in_progress, so each list keeps one of each.
  • A start or end status can't be changed to another type directly. Mark another status as start or end instead.
  • delete works only on in_progress statuses; any other type fails the whole request with 500.
  • create accepts only type in_progress or end; start and pre_production fail the whole request with 500. A created end status does not demote the existing one.
  • Task statuses (role: pipeline): this call doesn't decode pipeline_id, so a task status created here belongs to no task preset, and an update that sends pipeline_id detaches it from its preset. Use "Create a status" and "Update a status" for task statuses.

Side effects

  • Team members who have YoPrint open see each change at once.

Path parameters

  • team_slugstringrequired

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

    • Example your-team
  • status_referencestringrequired

    Always the word sync. Any other value answers 405.

    • One of: "sync"
    • Example sync

Request body

application/json, required.

  • dataarray of objectsrequired
    • At least 1 item
    Fields of each item (9)
    • actionstringrequired
      • One of: "create", "update", "delete"
    • colorstring

      A hex color with the #, 3 or 6 digits: #1e88e5.

      • Matches ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$
    • customer_labelstring
    • idstring

      Required for update and delete: the status to change.

    • labelstring

      Required for create.

    • pipeline_idstring

      Do not send. This operation does not link statuses to task presets. To create task statuses (role: pipeline), use Create a status instead.

    • positioninteger

      Required for create and update.

      • Minimum -2147483648
      • Maximum 2147483647
    • rolestring

      Required for create. Which status list it belongs to (order, quote, job, purchase_order, pipeline, or shipment). customer_message statuses cannot be created here, and task statuses (pipeline) should be created with Create a status instead.

      • One of: "order", "quote", "job", "purchase_order", "pipeline", "shipment"
    • typestring

      Required for create, which accepts in_progress or end. On update, setting start or end moves that stage marker to this status; see the rules.

      • One of: "start", "pre_production", "in_progress", "end"

Response

200Successful response.

  • dataarray of objectsrequired
    Fields of each item (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.

    When
    An update or delete id is not one of your team's statuses.
    Fix
    Use ids from the full 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
    data is empty, an item has no action, or a create item misses a required field (validation_failed).
    Fix
    Send at least one change, each with its action and the fields that action needs.

  • 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
    A delete targets a status that is not in_progress, a create has the wrong type, or a start/end status is updated to another type. The body is {"message": "Server Error"}, without the error envelope.
    Fix
    Follow the rules above. Nothing was saved.

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