Your first order

This flow creates an order. You need an API key with merchant_order:read (preview and lookup) and merchant_order:create (creation).

1. Prepare the order

Save the content as order.json. Replace the SKU and the design URL with your own values.

{
  "external_reference": "SHOP-10045",
  "delivery_address": {
    "first_name": "Max",
    "last_name": "Mustermann",
    "street": "Musterstraße",
    "house_number": "1",
    "postcode": "50667",
    "city": "Köln",
    "country": "DE",
    "email": "[email protected]"
  },
  "billing_address": {
    "first_name": "Max",
    "last_name": "Mustermann",
    "street": "Musterstraße",
    "house_number": "1",
    "postcode": "50667",
    "city": "Köln",
    "country": "DE",
    "email": "[email protected]"
  },
  "items": [
    {
      "sku": "TSHIRT-SCHWARZ-M",
      "external_id": "LINE-1",
      "amount": 2,
      "processings": [
        {
          "processing_type": "DTG",
          "position": "FRONT",
          "design_url": "https://example.com/designs/motiv-001.png"
        }
      ]
    }
  ]
}

You do not send prices, shipping method or manufacturer. Prices come from the catalog, the system decides everything else. The API rejects fields other than those in the schema with 403. An item with amount 2 is created as two individual pieces.

2. Preview

curl -X POST https://gateway.shirtee.cloud/api/orders/preview \
  -H "Authorization: Bearer $SHIRTEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @order.json

The preview writes nothing. If the input is faulty it answers 422 with a code in extra.error, for example UNKNOWN_SKU or VARIANT_INACTIVE. More under Preview before changing.

3. Create

curl -X POST https://gateway.shirtee.cloud/api/orders \
  -H "Authorization: Bearer $SHIRTEE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @order.json

Store the Idempotency-Key with your order. On a timeout you retry with the same key and the same body; no second order is created, see Retrying orders safely.

The response (201) contains the order in the status right after creation, for example:

{
  "id": 900001,
  "slug": "CL-7K3M9QX",
  "external_reference": "SHOP-10045",
  "status": "PENDING",
  "retention": null
}

Keep the id. It addresses the order in all further calls.

4. Interpret the status

Normally the status is PENDING, after which processing continues automatically. Depending on the check result, a different status can appear right after creation:

Status	Meaning
`PENDING`	Created, processing starts automatically
`PAUSE`	Short wait before assignment
`CHECK`	The order needs a review, for example because of an inactive variant or no available production partner. `retention` names the reason.
`ERROR`	An error holds the order, for example missing prices. `retention` names the reason.

CHECK and ERROR are not HTTP errors: the order exists. The reference for POST /api/orders describes all cases.

5. Look up the order

curl "https://gateway.shirtee.cloud/api/orders/900001?tracking=true" \
  -H "Authorization: Bearer $SHIRTEE_API_KEY"

With tracking=true the response contains the shipments (tracking number, link, carrier). Without the parameter the list is empty.

If you assigned your own number, you can also find the order by it: GET /api/orders/by-external-reference/{external_reference}.