Skip to main content

Integration guide

Fabrixa API integration guide — auth, first order, webhook handling, error recovery
DEVELOPERS — INTEGRATION GUIDE

Auth to fulfilment in fifteen minutes.

Copy-paste walkthrough of the Fabrixa REST API: authenticate, list available products, place an order, register a webhook, handle the lifecycle events. JSON over HTTPS, bearer-token auth, idempotent requests, retry-safe webhooks. No surprises.

REST + JSON · BEARER AUTH · IDEMPOTENT · WEBHOOK-DRIVEN

PREREQUISITES

What you need before you start.

01
API KEY

Issued from your Fabrixa account dashboard. Sandbox key for development, production key for live orders. Both are bearer tokens.

02
WEBHOOK ENDPOINT

A publicly-reachable HTTPS endpoint on your side that can accept JSON POST requests. Localhost works in dev via tunnelling tools.

03
ARTWORK FILES

Print-ready artwork accessible via HTTPS URL. Adobe Illustrator, Photoshop, raster, or vector. We fetch the file when we render the print job.

STEP 1 — AUTHENTICATE

Test the API key with a hello call.

Bearer-token auth. Sandbox base URL is https://sandbox.api.fabrixa.com/v1; production swaps the subdomain.

GET /v1/account
# Verify auth and account access
curl https://sandbox.api.fabrixa.com/v1/account \
  -H "Authorization: Bearer $FABRIXA_API_KEY" \
  -H "Accept: application/json"

# 200 OK
{
  "account_id": "acct_4fK8B2qZ",
  "environment": "sandbox",
  "tier": "production",
  "webhook_url": null
}

A 401 means the key is wrong or revoked. Generate a new one from the dashboard. A 403 means the key is valid but you lack permission for the resource (rare on /account).

STEP 2 — LIST PRODUCTS

Discover the SKUs available to your account.

Returns the catalogue with product IDs, base materials, sizes, and pricing tiers. Cache locally; the catalogue refresh isn’t per-request.

GET /v1/products
GET /v1/products?category=apparel&page=1&limit=20

# Response (truncated)
{
  "data": [
    {
      "product_id": "prod_tee_unisex_aop",
      "category": "apparel.tees-tops",
      "name": "Unisex AOP T-shirt",
      "base": "organic-cotton-160gsm",
      "sizes": ["XS","S","M","L","XL","XXL"],
      "print": "reactive-aop",
      "production_hub": "PT",
      "lead_time_days": { "min": 6, "max": 9 }
    }
  ],
  "page": 1,
  "has_more": true
}
STEP 3 — PLACE AN ORDER

Idempotent order creation.

Set Idempotency-Key on every order request — safe to retry the same call without creating duplicate orders. Use a UUID per logical order on your side.

POST /v1/orders
POST /v1/orders
Idempotency-Key: 8e6f4b2a-7c1d-4f3e-9a8b-1e2d3c4b5a6f

{
  "order_ref": "shopify-1042",
  "items": [
    {
      "product_id": "prod_tee_unisex_aop",
      "size": "L",
      "quantity": 2,
      "artwork_url": "https://cdn.yourbrand.com/art/drop-001.png"
    }
  ],
  "recipient": {
    "name": "Lena Costa",
    "address_line1": "Rua das Flores 12",
    "city": "Porto",
    "country": "PT",
    "postal_code": "4050-262"
  },
  "packaging": "white-label"
}

# 201 Created
{
  "order_id": "ord_8e6f4b2a",
  "status": "received",
  "estimated_dispatch": "2026-05-15",
  "webhook_events": ["order.printed","order.dispatched"]
}
STEP 4 — WEBHOOK ENDPOINT

Subscribe to the order lifecycle.

Set the webhook URL once at the account level. Every order’s lifecycle events POST to that URL. Verify the HMAC signature before processing.

PUT /v1/account/webhook
PUT /v1/account/webhook

{
  "url": "https://api.yourbrand.com/fabrixa/webhook",
  "events": [
    "order.received",
    "order.printed",
    "order.dispatched",
    "order.failed"
  ]
}

# Webhook payload (POST to your endpoint)
{
  "event": "order.dispatched",
  "order_id": "ord_8e6f4b2a",
  "order_ref": "shopify-1042",
  "timestamp": "2026-05-15T11:32:08Z",
  "tracking": {
    "carrier": "DHL",
    "tracking_number": "JJD0123456789",
    "tracking_url": "https://dhl.com/track/JJD0123456789"
  }
}

Full event reference and signature verification on the webhooks page.

ERROR HANDLING & RATE LIMITS

What to expect when things go wrong.

ERROR RESPONSE SHAPE

Errors are JSON, never HTML.

Error response
{
  "error": {
    "code": "artwork_unreachable",
    "message": "GET on artwork_url failed (timeout 30s)",
    "request_id": "req_94kQ7r2L",
    "retryable": true
  }
}

Codes are stable strings — safe to switch on. retryable: true means safe to retry with the same idempotency key.

RATE LIMITS

Sliding window, headers tell you the budget.

  • Sandbox: 60 req / minute per key
  • Production: 600 req / minute per key (raise on request)
  • Headers: X-RateLimit-Remaining, X-RateLimit-Reset
  • 429 response on overage with Retry-After seconds
  • Webhook deliveries don’t count toward your inbound budget
STUCK?

Talk to a solutions engineer.

For integration support, sandbox-key issues, custom requirements, or capacity planning — technical SE channel rather than the sales line. Average response inside one business day.

Cart (0 items)

Create your account