Update a job

PUT/v2/api/store/{team_slug}/v2/job/{hash_id}

v2Operation ID v2_public_job_update

Check success, not only the HTTP status: when the job's order is neither a draft nor published, this call answers HTTP 200 with { "status": 500, "success": false, "error": { "code": "action_not_allowed", "message": null } } and changes nothing.

Changes a job's name, note, position or rush flag, and adds, changes or removes its services, tasks, mockups and production files in one call.

Send only what you change. Each of service, pipeline, mockup and production_file is a list of actions: every entry has an action of create, update or delete, and entries you leave out stay as they are.

Changing services (the decoration, its location, option or order) reprices the job and recalculates the sales order's totals. Other changes don't touch prices.

To change the status use Change a job's status; for the job number use Change a job number; for dates use Schedule a job. Returns the updated job.

Permission

Needs permission to edit the job's sales order:

the team owner;
a role whose Manage Sales Orders permission is "update all";
a role with "update assigned" when you created the order or are assigned to it; or
on a draft order, its creator when their role can create sales orders.

Otherwise 403 user_is_not_authorized.

Business rules

The job's sales order must be a draft or published. Otherwise the reply is HTTP 200 with success: false and error.code action_not_allowed and nothing changes.
Every list entry needs an action. service entries need service_id, option, location and position unless they delete.
A task's status_id must belong to its pipeline_id (task preset).

Side effects

Changing services reprices the job and recalculates the order, its invoices and shipments that share pricing tiers.
Turning is_rush on or off sends the job.marked_as_rush or job.marked_as_not_rush webhook.
Deleting a mockup with approval_request_action: remove_open_items changes the job's open artwork approvals (see the field); Customer Portal pages the customer has open refresh for the approvals that remain.
Open Admin Portal pages refresh.

Path parameters

team_slugstringrequired
Your team slug, shown as Team ID next to your API key in Profile.
- Example your-team
hash_idstringrequired
The job's hash id (id). Hash ids only: a unique key or a document number gives 404.
- Example WaGvtaWsx7Kcn4

Query parameters

omit_media_approval_itemsstring
Optional. 1 (or true, yes, on) makes the answer smaller: each mockup and production file's current_approval leaves out its items list, and every other key stays as it is. The job's pending_approval and webhook payloads keep their items. Every file repeats its approval with all of its items, so a job with many files on one approval answers with far less data this way; read approval items from the approvals operations instead. Left out (or any other value), the answer is unchanged. Only the query string is read: a body field with this name is ignored.
- Example 1

Request body

application/json, required.

has_serviceboolean
Accepted for older clients; it changes nothing.
is_rushboolean
Marks the job as a rush job.
mockuparray of objects
Mockup actions. Mockups are uploaded files attached to the job.
Fields of each item (7)
- actionstringrequired
  - One of: "create", "update", "delete"
- idstringrequired
  The uploaded file (for create) or the mockup.
- approval_request_actionstring
  For delete: what to do with open artwork approvals that include this mockup. remove_open_items takes it out of every open approval of the job, and deletes each approval left with nothing to approve. With keep (the default) a mockup under an open approval stays in that approval.
  - One of: "keep", "remove_open_items"
- job_servicestring | array
  The job service or services the mockup shows.
- namestring
- positioninteger
  Required when action is create, but not used: YoPrint puts the new file last.
- show_in_pdfboolean
  Show it on the sales order PDF. Required unless action is delete.
namestring
The job name. A null is ignored (the name is kept).
notestring
The job note.
pipelinearray of objects
Task actions.
Fields of each item (10)
- actionstringrequired
  - One of: "create", "update", "delete"
- assigned_usersarray of strings
  User hash ids to assign.
- due_datestring (date-time) | null
  An ISO 8601 date or date-time, or null. Required (it may be null) when action is create.
- idstring
  The task. Required unless action is create.
- namestring
  The task name.
- pipeline_idstring
  The task preset. Required unless action is delete.
- positioninteger
  - Minimum -2147483648
  - Maximum 2147483647
- start_datestring (date-time) | null
  An ISO 8601 date or date-time, or null. Required (it may be null) when action is create.
- status_idstring
  A status of that task preset. Required unless action is delete.
- unassigned_usersarray of strings
  User hash ids to unassign (update only).
positioninteger
The job's place among the order's jobs. To reorder every job safely, use Reorder the jobs of a sales order or quote.
- Minimum -2147483648
- Maximum 2147483647
production_filearray of objects
Production file actions.
Fields of each item (4)
- actionstringrequired
  - One of: "create", "update", "delete"
- idstringrequired
  The uploaded file (for create) or the production file.
- job_servicestring | array
  The job service or services the file is for.
- positioninteger
  Required when action is create, but not used: YoPrint puts the new file last.
scoped_idstring
Accepted but ignored here. Use Change a job number.
servicearray of objects
Service actions (the decorations on the job).
Fields of each item (8)
- actionstringrequired
  - One of: "create", "update", "delete"
- idstringrequired
  Required for every action. For update and delete, the job service's hash id. For create, a temporary id you choose that starts with tmpid- (tmpid-1); mockup and production_file entries in the same call can name it in job_service. Any other made-up value fails as a bad hash id.
- customer_notestring
  Customer notes.
- locationobject
  Where the service goes. Required unless action is delete.
  Child fields (3)
  - idstring
    The saved location. Required when type is database.
  - namestring
    The location name. Required when type is custom.
  - typestring
    database for one of your saved locations, custom for a name you type.
    One of: "database", "custom"
- notestring
  Internal notes.
- optionany
  The service option, as your service defines it. Required unless action is delete.
- positioninteger
  Order of the service on the job. Required unless action is delete.
  - Minimum -2147483648
  - Maximum 2147483647
- service_idstring
  The service from your team's services. Required unless action is delete.

More examples (1)

Rename a job and mark it rush

curl

curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/job/WaGvtaWsx7Kcn4' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "is_rush": true,    "name": "Front and back print"  }'

Response

200Successful response.

A 200 answer can still be a refusal

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

The order is neither a draft nor published (success: false, action_not_allowed). Fix: Check success in every reply, not only the HTTP status.

{
  "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
Your role can't edit this order (user_is_not_authorized).
Fix
Ask the team owner to adjust your role or assign you to the order.
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
The job isn't your team's, its order is an old (version 1) order, or an entry's id (task, mockup, production file) isn't on this job. Jobs on quotes work too.
Fix
Use the job's hash id (id) from the order's job list; unique keys don't work in this path.
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 list entry breaks its field rules (for example a service without location.type): validation_failed.
Fix
Read error.fields and resend the entries.
When
A service, option, task preset or task status is not valid, a task gets only one of its two dates, or a file wasn't uploaded first: job_validation_error, with the reason in error.message and no error.fields.
Fix
Correct that entry and resend.

Notes

A refusal here is HTTP 200 with success: false and error.code action_not_allowed (the body's status says 500). A client that only checks the HTTP status will treat it as done.
Do not send status_id here. Use Change a job's status, which checks the status and sends the status webhook.
Mockup and production file create entries take the hash id of a file you uploaded first with the async upload (v1.public.async_upload.store); any other id is a 422.

GETGet one job of an order/v2/api/store/{team_slug}/v2/sales_order/{hash_id}/job/{job_id}
PUTChange a job's status/v2/api/store/{team_slug}/v2/job/{hash_id}/status
PUTChange a job number/v2/api/store/{team_slug}/v2/job/{hash_id}/scoped_id
PUTSchedule a job/v2/api/store/{team_slug}/v2/job/{hash_id}/update_prod_date
PUTReorder the jobs of a sales order or quote/v2/api/store/{team_slug}/v2/sales_order/{hash_id}/job/rearrange

Example request