Take a job to print it

POST /print-jobs/{jobId}/claim

Take a job to print it: the job, its printer and what to send — a label Manifold rendered inline (a SKU's ZPL) or a link to the label its carrier app stored, signed for fifteen minutes.

409 PrintJobNotOpen for another agent's job, one already answered, or one whose printer has since moved to another site or agent or been removed — that job is failed with the reason (fulfillment.print-job-failed) and its printer never shown. Only a print agent's device token calls it (POST /api/auth/print-agent/token); a person's session is refused 403 PrintAgentOnly. Appends fulfillment.print-job-sent. Idempotent by state: a job is sent once, so the agent's retry on a job it already took appends nothing and answers it again.

Access

Requires printing:write.

How scopes come from roles: Scopes and roles. Getting a token: Authentication and app tokens.

Retries

Idempotent by state: a job is sent once, so the agent's retry on a job it already took appends nothing and answers it again.

Why every write carries a key: Idempotency and retries.

Facts appended

fulfillment.print-job-failed
fulfillment.print-job-sent

What a fact is: Facts and the journal.

AI agent tool

No agent tool. only a print agent takes a job, under its device token, to send it to the printer it reaches

Connecting an agent: AI agents.

Example

curl

curl -X POST 'https://fulfillment.getmanifold.io/print-jobs/pjb_01a15a20-4400-7e55-8f66-6f7a8b9c0d1e/claim' \
  -H "Authorization: Bearer $MANIFOLD_TOKEN"

JavaScript (fetch)

const response = await fetch("https://fulfillment.getmanifold.io/print-jobs/pjb_01a15a20-4400-7e55-8f66-6f7a8b9c0d1e/claim", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.MANIFOLD_TOKEN}` },
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const answer = await response.json();

Response · 200 · application/json

{
  "job": {
    "id": "pjb_01a15a20-4400-7e55-8f66-6f7a8b9c0d1e",
    "locationId": "loc_01a0f6b0-1100-7e51-8f62-7a8b9cadbec4",
    "printerId": "prn_01a15a10-2c00-7a11-8b22-3c4d5e6f7a8b",
    "agentId": "pag_01a15a0f-9e00-7c33-8d44-5e6f7a8b9c0d",
    "purpose": "sku-label",
    "document": {
      "_tag": "sku-labels",
      "sku": "MUG-SPECKLE",
      "copies": 12
    },
    "content": {
      "name": "Speckled mug",
      "barcode": "9312345000017"
    },
    "status": "sent",
    "requestedAt": "2026-10-20T02:41:07.330Z",
    "updatedAt": "2026-10-20T02:41:07.912Z",
    "sentAt": "2026-10-20T02:41:07.912Z"
  },
  "printer": {
    "id": "prn_01a15a10-2c00-7a11-8b22-3c4d5e6f7a8b",
    "name": "Dispatch Zebra",
    "locationId": "loc_01a0f6b0-1100-7e51-8f62-7a8b9cadbec4",
    "agentId": "pag_01a15a0f-9e00-7c33-8d44-5e6f7a8b9c0d",
    "language": "zpl",
    "media": {
      "widthMm": 50,
      "heightMm": 25,
      "dpi": 203
    },
    "connection": {
      "_tag": "network-raw",
      "host": "192.168.1.40",
      "port": 9100
    },
    "defaultFor": [
      "sku-label",
      "bin-label"
    ],
    "removed": false,
    "createdAt": "2026-10-15T01:12:40.215Z",
    "updatedAt": "2026-10-15T01:12:40.215Z"
  },
  "content": {
    "_tag": "inline",
    "contentType": "application/zpl",
    "body": "^XA\n^CI28\n^PW400\n^LL200\n^FO16,16^A0N,24,24^FB368,2,0,L^FH\\^FDSpeckled mug^FS\n^FO16,80^BY2^BCN,42,Y,N,N^FH\\^FD9312345000017^FS\n^FO16,152^A0N,32,32^FB368,1,0,L^FH\\^FDMUG-SPECKLE^FS\n^PQ12,0,1,Y\n^XZ"
  }
}

The panel writes this call in other languages. It does not send it: Manifold's APIs do not take calls from a web page on another site, so run the call from your own code or terminal. The whole API as OpenAPI: fulfillment-manager.openapi.json. Base URL https://fulfillment.getmanifold.io.

Errors

Every refusal is a status and a JSON body whose _tag names it. A refused call changes nothing.

`401`

Refusal	What it means	What to do
`Unauthorized` reason	The token is missing, expired or not one Manifold issued.	Get a fresh token and send the call again.
`TokenAlreadyUsed` tokenId	A single-use app token was already spent.	Mint a new token for this call.

`402`

Refusal	What it means	What to do
`SubscriptionRequired` status	The organization's subscription has lapsed, so writes are refused.	An owner settles billing. Reads still work meanwhile.

`403`

Refusal	What it means	What to do
`PrintAgentOnly` reason	This call is a print agent's alone, or a person's alone. `reason` says which.	Call it with the right credential.
`TenantRequired` userId	The token names no organization.	Choose the organization, then get a new token.
`ScopeRequired` required	The token's roles do not grant the scope this call needs.	Ask an owner or admin for a role that grants it.

`404`

Refusal	What it means	What to do
`PrintJobNotFound` jobId	No print job of this organization has that id.	List the site's print jobs.
`FulfillmentOrderNotFound` orderId	No such record in this organization.	Check the id in the path or the body.
`ConsignmentNotFound` consignmentId	No such record in this organization.	Check the id in the path or the body.
`LabelNotStored` consignmentId	The carrier app has not stored a label for this booking yet.	Try again once the booking is labelled.

`409`

Refusal	What it means	What to do
`PrintJobNotOpen` jobId, status	The job is another agent's, or already answered.	Take and answer only your own open jobs.
`MirroredFromSource` source	This area is fed by your source system until the organization goes live.	Make the change in the source system, or go live first.

`410`

Refusal	What it means	What to do
`LabelExpired` consignmentId, storedAt	The label was kept 90 days and is gone.	Book the parcel again for a new label.

`503`

Refusal	What it means	What to do
`LabelStoreUnavailable` reason	File storage did not answer, so nothing was stored.	Send the same request again shortly.
`RequestLogUnavailable` tokenId, reason	The service could not record the request, so it did nothing.	Send the same request again shortly.

How refusals work everywhere: Errors.