Implementation

Order placement is asynchronous. This page walks through the full flow — placing an order, polling for completion, using idempotency keys, and placing on behalf of vendor child organizations.

Placement Flow

1. Place the order. `POST /api/orders` returns immediately with a tracking `id`, the assigned `orderNumber`, and `status: "Pending"`.
2. Poll for completion. Call `GET /api/orders/{id}` periodically. The status moves from `"Pending"` to `"Completed"` once the order is fully placed (or `"Failed"` if something went wrong).
3. Read the result. When `status` is `"Completed"`, the `order` field on the response contains the full order — items, prices, VAT, totals, and the assigned delivery date.

POST /api/orders
       │
       ▼  { id, orderNumber, status: "Pending" }
GET /api/orders/{id}    →  status: "Pending"     (still placing)
GET /api/orders/{id}    →  status: "Completed"   ✓ order details available
                         or status: "Failed"     ✗ see errorMessage

A typical order takes between 3 seconds and 30 seconds to reach `"Completed"`. We recommend polling every 5 seconds.

Idempotency #

To prevent accidental duplicate orders on network retries, supply an `Idempotency-Key` header with each `POST /api/orders` request:

Idempotency-Key: 7c3a9f12-4b1e-4a8d-9c5b-1a2b3c4d5e6f

Use a unique value per logical order (e.g., a UUID generated by your system). If you re-send the same request body with the same key, you'll receive the original tracking `id` back instead of creating a new order.

Idempotency keys are scoped to the target organization. There is no expiry — once a key has been used for an order, that key is reserved for that order forever.

Placing on Behalf of a Vendor Child #

If your account has child vendor organizations (e.g., separate departments), you can place orders specifically for one of them by including `organizationId` in the request body:

{
  "organizationId": 56789,
  "reference": "PO-2026-0042",
  "deliveryAddress": { ... },
  "designs": [ ... ]
}

Rules:

• The target organization must be a vendor child of the calling vendor (i.e., its `parentId` must be your vendor org).
• If you omit `organizationId` or set it to your own vendor org, the order is placed for your vendor.
• The order ends up under the target organization in the system, with billing / shipping context appropriate to that org.

Designs and logos referenced in the request can be owned by either the calling vendor or the target organization.

Worked Example #

Place an order for two designs (one with player names and numbers) plus a batch of bare number transfers:

1. Submit the order

curl -X POST '/api/orders' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7c3a9f12-4b1e-4a8d-9c5b-1a2b3c4d5e6f' \
  -d '{
    "reference": "PO-2026-0042",
    "comment": "The clothes should be at Jet Sport by monday",
    "originOfDelivery": "Tee Jays Warehouse",
    "email": "vendor@example.com",
    "contactName": "Peter Smith",
    "deliveryAddress": {
      "name": "Football Club ABC",
      "address": "Stadium Road 1",
      "zip": "8800",
      "city": "Viborg",
      "country": "DK",
      "contactPerson": "Peter Smith"
    },
    "designs": [
      {
        "designId": 299571,
        "instances": [
          { "size": "M", "quantity": 1 },
          { "size": "L", "quantity": 1 },
          { "size": "XL", "quantity": 5 }
        ]
      },
      {
        "designId": 298791,
        "instances": [
          { "size": "M", "quantity": 5, "name": "Smith", "number": "10" },
          { "size": "L", "quantity": 7, "name": "Jones", "number": "27" }
        ]
      }
    ],
    "logos": [
      {
        "logoId": 100113,
        "quantity": 18
      },
      {
        "logoId": 494679,
        "digits": [
          { "digit": "1", "quantity": 5 }
        ]
      }
    ]
  }'

Response:

{
  "id": 4711,
  "orderNumber": "20002502",
  "status": "Pending"
}

2. Poll for completion

curl -X GET '/api/orders/4711' \
  -H 'Authorization: Bearer YOUR_API_KEY'

While placing:

{
  "id": 4711,
  "status": "Pending",
  "orderNumber": "20002502"
}

Once placed:

{
  "id": 4711,
  "status": "Completed",
  "orderNumber": "20002502",
  "order": {
    "orderNumber": "20002502",
    "placedAtUtc": "2026-05-05T13:14:30Z",
    "latestDeliveryDate": "2026-05-13T00:00:00",
    "reference": "PO-2026-0042",
    "comment": "The clothes should be at Jet Sport by monday",
    "originOfDelivery": "Tee Jays Warehouse",
    "deliveryAddress": {
      "name": "Football Club ABC",
      "address": "Stadium Road 1",
      "zip": "8800",
      "city": "Viborg",
      "country": "DK",
      "contactPerson": "Peter Smith"
    },
    "currency": "DKK",
    "subTotal": 2817.03,
    "vat": 704.26,
    "vatRate": 25.0,
    "total": 3521.28,
    "designs": [
      {
        "designId": 299571,
        "designMul": "MUL327815",
        "designTitle": "Home kit",
        "instances": [
          { "size": "M", "quantity": 1 },
          { "size": "L", "quantity": 1 },
          { "size": "XL", "quantity": 5 }
        ]
      },
      {
        "designId": 298791,
        "designMul": "MUL327187",
        "designTitle": "Away kit",
        "instances": [
          {
            "size": "M",
            "quantity": 5,
            "name": "Smith",
            "number": "10"
          },
          {
            "size": "L",
            "quantity": 7,
            "name": "Jones",
            "number": "27"
          }
        ]
      }
    ],
    "logos": [
      {
        "logoId": 100113,
        "logoSku": "151107",
        "logoTitle": "Club Crest",
        "quantity": 18
      },
      {
        "logoId": 494679,
        "logoSku": "1019141",
        "logoTitle": "Number transfer",
        "quantity": 5,
        "value": "1"
      }
    ]
  }
}

The `order` field contains the full breakdown including totals — see the Order Object reference.

Pricing #

You don't supply prices in the request. The system calculates everything on your behalf based on the items, quantities, your vendor's pricing tiers, and any applicable startup or heating fees. Prices appear on the response when the order reaches `"Completed"`.