Add a job to a sales order or quote

POST/v2/api/store/{team_slug}/v2/sales_order/{hash_id}/job

v2Operation ID v2_public_job_store

Adds a job to a sales order or quote. Add the job first, then add line items linked to it (job: {"type": "linked", "id": ...}): every line on the job takes its decoration price.

A job can carry, all optional:

service: decoration services from Settings, each at a print location with one of the service's price options (services are not listed on the public API: copy service_id and option from an existing job or job preset);
pipeline: work pipelines (production steps), each with a starting status;
mockup and production_file: files you uploaded first, shown on the job.

Each service, pipeline and mockup entry needs action: "create", or it is skipped silently; a production_file entry without action is refused with 422. To tie a mockup to a service, give the service a temporary id of your own (for example tmpid-1) and use it in the mockup's job_service.

The job gets the team's next job number and the order's production dates. The answer is the job.

Works on drafts and published orders. In any other state the call answers HTTP 200 with {"status": 500, "success": false, "error": {"code": "action_not_allowed", "message": null}} and changes nothing: check success, not only the HTTP status. {hash_id} is the order's id (for example V4keXwwxMQyXw7); the ord_ unique key 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

Each service, pipeline and mockup entry needs action: "create", or it is skipped silently. A production_file entry without action is refused with 422 validation_failed.
A service must exist in the team's Settings ("Service Not Found") and option must be one of its options ("Service does not contain such option ...").
A pipeline needs pipeline_id and status_id; its start_date and due_date go together.
scoped_id is ignored: jobs always take the team's next job number.

Side effects

Recalculates the decoration pricing of the order's jobs and the order totals.
Refreshes the order for people who have it open in the web app. On a published order, 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
hash_idstringrequired
The sales order's or quote's id (a hash id). The ord_ unique key and the order number do not work here.
- Example V4keXwwxMQyXw7

Request body

application/json, required.

draft_session_idstring
Used by the web app's mockup designer. Leave it out.
draft_session_mockuparray of objects
Used by the web app's mockup designer. Leave it out.
has_serviceboolean
Ignored; kept for older clients.
is_rushboolean
mockuparray of objects
Mockup images, uploaded first.
Fields of each item (6)
- actionstringrequired
  Send create on every entry: a service, pipeline or mockup without it is skipped silently; a production file without it is refused.
  - One of: "create"
- idstringrequired
  The upload's id.
- positionintegerrequired
- show_in_pdfbooleanrequired
  Show it on the order PDF.
- job_serviceany
  The temporary service id (or ids) this mockup belongs to.
- namestring
namestring | null
The job's name, for example "Front logo".
notestring
An internal note.
pipelinearray of objects
Work pipelines (production steps).
Fields of each item (8)
- actionstringrequired
  Send create on every entry: a service, pipeline or mockup without it is skipped silently; a production file without it is refused.
  - One of: "create"
- pipeline_idstringrequired
  A work pipeline id from Settings.
- status_idstringrequired
  The pipeline's starting status id.
- assigned_usersany
  A user id, or a list of user ids, to assign.
- due_datestring (date-time) | null
  Due date (ISO 8601 date or date-time), or null. Send together with start_date.
- namestring
- positioninteger
- start_datestring (date-time) | null
  Start date (ISO 8601 date or date-time), or null. Send together with due_date.
positioninteger
Where the job sits among the order's jobs. Leave it out to add it last.
production_filearray of objects
Production files, uploaded first.
Fields of each item (5)
- actionstringrequired
  Send create on every entry: a service, pipeline or mockup without it is skipped silently; a production file without it is refused.
  - One of: "create"
- idstringrequired
  The upload's id.
- positionintegerrequired
- job_serviceany
  The temporary service id (or ids) this file belongs to.
- namestring
scoped_idstring
Accepted but ignored: the job gets the team's next job number. To change it afterwards, use Change a job number.
servicearray of objects
Decoration services.
Fields of each item (8)
- actionstringrequired
  Send create on every entry: a service, pipeline or mockup without it is skipped silently; a production file without it is refused.
  - One of: "create"
- service_idstringrequired
  A decoration service id. Services are not listed on the public API: copy service_id from a job's services (Get one job of an order) or from a job preset (List job presets).
- customer_notestring
  A note the customer sees.
- idstring
  Your temporary id for this service, to reference it from mockups.
- locationobject
  Child fields (3)
  - idstring
    A print location id.
  - namestring
    A custom location name.
  - typestring
    database for a saved print location (send id), custom for a free name (send name).
    One of: "database", "custom"
- notestring
- optionstring
  One of the service's price option names, exactly as the service has it (the match is exact, case included), such as 2 Color. Copy it from services[].option on an existing job or job preset. Another name, or none, is refused with 422 job_validation_error "Service does not contain such option …".
- positioninteger
  Order among the job's services. Required with id.

More examples (1)

A job with a name only

curl

curl -X POST 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/job' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "name": "Team shirts"  }'

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, error.code action_not_allowed (the body's status says 500). Fix: Check success in every reply, and the order's internal_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
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.
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
option is not one of the service's option names, exactly: job_validation_error "Service does not contain such option …" (the name you sent).
Fix
Copy the option name from services[].option on an existing job or job preset that uses the service.
When
The service is not one of the team's ("Service Not Found:…"), or a required field is missing (job_validation_error).
Fix
Copy service_id from an existing job or job preset.

POSTAdd a job from a job template/v2/api/store/{team_slug}/v2/sales_order/{hash_id}/job_template
POSTAdd a line item to a sales order or quote/v2/api/store/{team_slug}/v2/sales_order/{order_unique_key}/order_item
PUTUpdate a job/v2/api/store/{team_slug}/v2/job/{hash_id}
POSTUpload a file/v1/api/store/{team_slug}/async_upload
GETGet one job of an order/v2/api/store/{team_slug}/v2/sales_order/{hash_id}/job/{job_id}
GETList job presets/v1/api/store/{team_slug}/setting/job_preset

Example request