Skip to content

Resources

Variants

Every Variants endpoint, with the scope it enforces, the body it takes, a response you can read, and the refusals it can return.

List size and colour variants.

get/organizations/{organization}/passports/{id}/variants
Scope
passports:read
Idempotency-Key
Not accepted
Returns
200

Path parameters

organizationstringRequired

The organization this request acts for. The credential must hold a grant for it.

idstringRequired

The identifier of the resource. Treat it as an opaque string.

Query parameters

limitstringOptional

How many records to return. The server may return fewer.

cursorstringOptional

The next_cursor from the previous page. A cursor encodes the filters it was issued under; sending it with different filters is refused with cursor_invalid.

gtinstringOptional

Return only the variant with this GTIN. Valid 8, 12, 13 and 14-digit GTINs are normalized to 14 digits.

Errors

Every refusal this endpoint can return, with the status it arrives with.

Request
curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/variants?limit=25" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"
Response · 200
{
  "object": "list",
  "data": [
    {
      "object": "variant",
      "id": "d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/variants/d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
      "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
      "gtin": "03453120000011",
      "size": "M",
      "colour": "Navy",
      "livemode": true,
      "created_at": "2026-08-01T12:00:03.114Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/variants?limit=25

Create size and colour variants.

post/organizations/{organization}/passports/{id}/variants
Scope
passports:write
Idempotency-Key
Accepted
Returns
201

Path parameters

organizationstringRequired

The organization this request acts for. The credential must hold a grant for it.

idstringRequired

The identifier of the resource. Treat it as an opaque string.

Request body

variantsarray of objectsRequired

Send 1–1000 variants for a textile or general passport, up to 2000 per passport across requests. The whole batch is inserted or refused and returned in request order. GTINs and size/colour pairs must be unique. The passport’s own lead GTIN is allowed; another passport’s lead or variant in the same organization and mode is refused, including trashed passports. Successful retries with the same Idempotency-Key replay before collision and capacity checks. Correctable preflight refusals do not consume the key. Connector credentials can add variants to drafts only; they cannot remove variants.

gtinstringRequired

A valid 8, 12, 13 or 14-digit GTIN, including its check digit. Stored and returned as 14 digits.

sizestringOptional

Size, 1–70 Unicode characters after trimming whitespace. Provide size, colour, or both.

colourstringOptional

Colour, 1–70 Unicode characters after trimming whitespace. Size and colour pairs are unique without case sensitivity.

Errors

Every refusal this endpoint can return, with the status it arrives with.

Request
curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/variants" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "variants": [
    {
      "gtin": "03453120000011",
      "size": "M",
      "colour": "Navy"
    }
  ]
}'
Response · 201
{
  "object": "list",
  "data": [
    {
      "object": "variant",
      "id": "d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/variants/d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
      "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
      "gtin": "03453120000011",
      "size": "M",
      "colour": "Navy",
      "livemode": true,
      "created_at": "2026-08-01T12:00:03.114Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/variants

Delete one variant. Connector credentials cannot delete variants.

Destructive
delete/organizations/{organization}/passports/{id}/variants/{variantId}
Scope
passports:write
Idempotency-Key
Accepted
Returns
200

Path parameters

organizationstringRequired

The organization this request acts for. The credential must hold a grant for it.

idstringRequired

The identifier of the resource. Treat it as an opaque string.

variantIdstringRequired

The identifier of the resource. Treat it as an opaque string.

Errors

Every refusal this endpoint can return, with the status it arrives with.

Request
curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/variants/d41d8cd9-8f00-4b20-a204-9800998ecf84" \
  -X DELETE \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
Response · 200
{
  "object": "variant",
  "id": "d41d8cd9-8f00-4b20-a204-9800998ecf84",
  "deleted": true
}

DELETE /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/variants/d41d8cd9-8f00-4b20-a204-9800998ecf84

Remove variants by GTIN.

Destructive
post/organizations/{organization}/passports/{id}/variants/remove
Scope
passports:write
Idempotency-Key
Accepted
Returns
200

Path parameters

organizationstringRequired

The organization this request acts for. The credential must hold a grant for it.

idstringRequired

The identifier of the resource. Treat it as an opaque string.

Request body

gtinsarray of stringsRequired

Send 1–1000 valid GTINs, normalized to 14 digits. Present rows are removed; missing rows appear in absent. A successful same-key retry replays the original result; a keyless retry lists removed rows as absent. Each effective removal call on a published or deactivated passport charges the destructive cap once. Connector credentials cannot remove variants. Removal uses bounded batches. On a later failure, error.details.removed lists completed removals. Retry without Idempotency-Key to reconcile; the same key replays the recorded failure.

Errors

Every refusal this endpoint can return, with the status it arrives with.

Request
curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/variants/remove" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "gtins": [
    "03453120000011"
  ]
}'
Response · 200
{
  "removed": [
    "03453120000011"
  ],
  "absent": []
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/variants/remove

Read the sizes and colours a person reviews before publishing, with their fingerprint.

get/organizations/{organization}/passports/{id}/variants/review
Scope
passports:read
Idempotency-Key
Not accepted
Returns
200

Path parameters

organizationstringRequired

The organization this request acts for. The credential must hold a grant for it.

idstringRequired

The identifier of the resource. Treat it as an opaque string.

Errors

Every refusal this endpoint can return, with the status it arrives with.

Request
curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/variants/review" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"
Response · 200
{
  "object": "variant_review",
  "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "fingerprint": "3b2f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f",
  "agent_written_count": 1,
  "variants": [
    {
      "id": "d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "gtin": "03453120000011",
      "size": "M",
      "colour": "Navy",
      "agent_written": {
        "keyId": "pcmcp_a1",
        "keyName": "Claude",
        "at": "2026-09-18T09:12:44.000Z",
        "sourceClass": "agent_asserted"
      }
    },
    {
      "id": "8d3f1c22-6b7e-4d1a-9e2f-5a6b7c8d9e0f",
      "gtin": "05012345678900",
      "size": "L",
      "colour": "Navy",
      "agent_written": null
    }
  ]
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/variants/review