Warehouse Fulfillment API

Who This Is For

This page is for warehouse operators or developers integrating a warehouse system with Fairground order fulfillment.

What You Can Do

• Issue and rotate warehouse API keys from Fairground UI.
• List seller-scoped orders that still need fulfillment.
• Create fulfillments for orders.
• Create shipments with tracking labels.
• Mark fulfillments as delivered.

Step 1: Create API Key In UI

1. Log in as the artist/seller owner account.
2. Go to Profile -> Settings -> Warehouse API Keys.
3. Select the artist populator to scope the key.
4. Create a key (name and optional expiry).
5. Copy the key once and store it securely.
6. Revoke keys from the same screen when rotating or exposed.

Step 2: Authenticate Warehouse Requests

Use the API key in the Authorization header for all warehouse endpoints: Authorization: Bearer <WAREHOUSE_API_KEY>

Warehouse endpoints live under /v1/warehouse/*.

Step 3: List Orders That Need Fulfillment

Use needs_fulfillment=true to let the backend filter orders for you.

1API_KEY="<your_warehouse_api_key>"
2BASE="https://api.fairground.music"
3
4curl -sS \
5  -H "Authorization: Bearer $API_KEY" \
6  "$BASE/v1/warehouse/orders?page=1&limit=20&needs_fulfillment=true"

Step 4: Create Fulfillment

Create a fulfillment when an order has no fulfillment id yet.

1ORDER_ID="order_xxx"
2LINE_ITEM_ID="ordli_xxx"
3
4curl -sS -X POST \
5  -H "Authorization: Bearer $API_KEY" \
6  -H "Content-Type: application/json" \
7  "$BASE/v1/warehouse/orders/$ORDER_ID/fulfillments" \
8  -d '{
9    "items": [
10      { "id": "'"$LINE_ITEM_ID"'", "quantity": 1 }
11    ]
12  }'

Then fetch fulfillments to get the new FULFILLMENT_ID.

1ORDER_ID="order_xxx"
2
3curl -sS \
4  -H "Authorization: Bearer $API_KEY" \
5  "$BASE/v1/warehouse/orders/$ORDER_ID/fulfillments"

Step 5: Add Shipment Tracking

Create the shipment against the fulfillment id. Include label_url in the payload.

1FULFILLMENT_ID="ful_xxx"
2
3curl -sS -X POST \
4  -H "Authorization: Bearer $API_KEY" \
5  -H "Content-Type: application/json" \
6  "$BASE/v1/warehouse/orders/$ORDER_ID/fulfillments/$FULFILLMENT_ID/shipments" \
7  -d '{
8    "items": [
9      { "id": "'"$LINE_ITEM_ID"'", "quantity": 1 }
10    ],
11    "labels": [
12      {
13        "tracking_number": "TRACK-123",
14        "tracking_url": "https://carrier.example/TRACK-123",
15        "label_url": "https://carrier.example/labels/TRACK-123.pdf"
16      }
17    ]
18  }'

Step 6: Mark Delivered

1curl -sS -X PATCH \
2  -H "Authorization: Bearer $API_KEY" \
3  -H "Content-Type: application/json" \
4  "$BASE/v1/warehouse/orders/$ORDER_ID/fulfillments/$FULFILLMENT_ID" \
5  -d '{
6    "status": "delivered"
7  }'

Legacy compatibility endpoint still supported: POST /v1/warehouse/orders/:order_id/fulfillments/:fulfillment_id/mark-as-delivered

Common Endpoints Reference

• GET /v1/warehouse/orders?page=1&limit=20&needs_fulfillment=true
• GET /v1/warehouse/orders/:order_id
• GET /v1/warehouse/orders/:order_id/fulfillments
• POST /v1/warehouse/orders/:order_id/fulfillments
• POST /v1/warehouse/orders/:order_id/fulfillments/:fulfillment_id/shipments
• PATCH /v1/warehouse/orders/:order_id/fulfillments/:fulfillment_id