Relay | Fulfillment platform

Relay API reference

Complete reference for the Relay REST API, webhooks, and native integrations. Written for the engineers building against your fulfillment pipeline.

Getting started

The Relay API is a versioned REST API served over HTTPS. All requests and responses use JSON.

Base URL: https://anatar.com/api/v1
Key format: ak_live_... / ak_test_...

Authenticate every request with an API key in the Authorization header. Live keys start with ak_live_; sandbox keys start with ak_test_. Both are minted from Studio > Settings > Integrations. The full secret is shown exactly once at mint time - store it in your secret manager, never in source control. The sandbox endpoint is the same host - the token is the gate.

What this key can access

A key is scoped to one company. It can read inventory, create fulfillment orders, file inbound (live key), subscribe to webhooks, place and reorder Anatar production jobs, submit RFQs, and read invoices and payments. It cannot read another company, Studio files, or team membership. Responses never include internal UUIDs, label costs, postage margin, or label PDFs.

GET/api/v1/me

Auth test. Any valid live or sandbox key. Returns mode (live or sandbox), the company name, and this key's scopes. No customer or key UUIDs.

Request

curl https://anatar.com/api/v1/me \
  -H "Authorization: Bearer $RELAY_API_KEY"

Response

{
  "data": {
    "mode": "sandbox",
    "customer": {
      "name": "Acme Industries",
      "slug": "acme",
      "customerNumber": "CUS-1042"
    },
    "key": {
      "name": "Studio sandbox",
      "prefix": "ak_test_a1b2",
      "scopes": ["orders:read", "orders:write", "inventory:read", "inventory:write", "webhooks:manage"]
    }
  }
}

API conventions

Every endpoint follows the same envelope, pagination, idempotency, and rate-limit rules.

Product identity

Every catalog item has a Relay product id (PRD-####). That is the identifier you should send and store. sku is an optional customer or UPC code and is often null - do not require it. Inventory, order lines, inbound, and webhooks all return both fields.

Recipient data

Ship-to name, address, phone, and email are recipient PII. They are only returned on authenticated partner routes, only for your company, and only the documented fields (no extra keys). Traffic is HTTPS on anatar.com. API keys are hashed at rest; integration secrets are AES-256-GCM encrypted.

Response envelope

Successful responses wrap the result in a data key. Errors return an error object with a human-readable message and optional structured details. List endpoints that paginate also return a meta object.

Envelopes

// Success
{ "data": { ... } }

// Success with pagination (list endpoints)
{ "data": [ ... ], "meta": { "limit": 100, "offset": 0, "total": 1284 } }

// Error
{ "error": { "message": "Order not found", "details": null } }

Idempotency

Order and inbound creation accept externalId + externalSource. Reposting the same pair returns the existing record instead of creating a duplicate, which makes retries safe. Always set these from your own system of record (order id, PO number).

Rate limits

Limits (fixed 60-second window)

`Authenticated` 300 req/min per keyrequired	Counted per API key across all endpoints. Exceeding it returns 429 with retryAfterSeconds in the error details.
`Unauthenticated` 30 req/min per IPrequired	Invalid or missing tokens are throttled per client IP before any database work.

429 response

{
  "error": {
    "message": "Rate limit exceeded",
    "details": { "limit": 300, "retryAfterSeconds": 42 }
  }
}

Scopes

Each key carries scopes. Calling an endpoint without the required scope returns 403. Default keys carry all scopes.

Available scopes

`orders:read` scopeoptional	List and fetch orders and tracking.
`orders:write` scopeoptional	Create, reorder, cancel, and confirm delivery of orders.
`inventory:read` scopeoptional	List inventory, product detail, movement history, inbound receipts.
`inventory:write` scopeoptional	Create inbound shipments, archive products.
`webhooks:manage` scopeoptional	List, subscribe, and unsubscribe webhook endpoints.

Order lifecycle

Orders move through a fixed pipeline. Each transition can emit a webhook (see the Webhooks section).

Status pipeline

received -> allocated -> packed -> shipped -> delivered
     |            |
     +------------+--> cancelled (only before shipment)

Orders

Create fulfillment orders, poll their status, reorder to the same address, cancel before shipment, and confirm delivery.

GET/api/v1/ordersorders:read

List orders newest-first with limit/offset pagination. Response includes a meta object with the total count.

Query parameters

`limit` integeroptional	Page size, 1-200. Defaults to 100.
`offset` integeroptional	Rows to skip. Defaults to 0.
`status` stringoptional	Filter by status: received, allocated, packed, shipped, delivered, cancelled.
`since` ISO 8601 timestampoptional	Only orders created at or after this time. Invalid timestamps return 400.
`shippedSince` ISO 8601 timestampoptional	Only orders shipped at or after this time. meta.total is the exact count. Invalid timestamps return 400.

Request

curl "https://anatar.com/api/v1/orders?status=shipped&since=2026-09-01T00:00:00Z&limit=50" \
  -H "Authorization: Bearer $RELAY_API_KEY"

GET/api/v1/orders/{numberOrId}orders:read

Fetch one order with lines and packaging. Use the order number (RLY-YYYYMM-####).

Request

curl https://anatar.com/api/v1/orders/RLY-202609-0042 \
  -H "Authorization: Bearer $RELAY_API_KEY"

POST/api/v1/ordersorders:write

Create a fulfillment order. Live keys enter the warehouse queue. Sandbox keys (ak_test_) create SBX- orders that never reserve stock or get picked; advance them with POST /orders/{number}/simulate.

Body

`shipTo` objectrequired	Destination address. See the field reference below.
`lines` array (1-100)required	Items to ship. Each line needs quantity plus productId (PRD-####, preferred) or sku. Most warehouse products only have a product id - sku is optional.
`externalId` string (max 200)optional	Your system order id. Combined with externalSource for idempotency.
`externalSource` string (max 100)optional	Origin system tag, e.g. "erp", "shopify", "zapier".
`notes` string (max 5000)optional	Free-form instructions for the warehouse.

shipTo fields

`line1` string (max 200)required	Street address.
`city` string (max 100)required	City.
`state` string (max 100)required	State, province, or region.
`postalCode` string (max 20)required	Postal / ZIP code.
`country` string (2 chars)required	ISO 3166-1 alpha-2 country code, e.g. US.
`name` string (max 200)optional	Recipient name.
`company` string (max 200)optional	Company name.
`line2` string (max 200)optional	Suite, unit, floor.
`phone` string (max 30)optional	Contact phone for the carrier.
`email` string (email)optional	Contact email for delivery notifications.

Request

curl -X POST https://anatar.com/api/v1/orders \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "SO-88412",
    "externalSource": "erp",
    "shipTo": {
      "name": "Jordan Blake",
      "company": "Acme Retail",
      "line1": "500 Commerce Way",
      "line2": "Suite 210",
      "city": "Austin",
      "state": "TX",
      "postalCode": "78701",
      "country": "US",
      "email": "jordan@acmeretail.com"
    },
    "lines": [
      { "productId": "PRD-1010", "quantity": 25 },
      { "productId": "PRD-1011", "quantity": 25 }
    ],
    "notes": "Include packing slip PO 88412"
  }'

Response 201

{
  "data": {
    "number": "RLY-202609-0042",
    "status": "received",
    "externalId": "SO-88412",
    "externalSource": "erp",
    "shipTo": { "name": "Jordan Blake", "city": "Austin", "state": "TX", "country": "US", "postalCode": "78701", "line1": "500 Commerce Way" },
    "notes": "Include packing slip PO 88412",
    "addressValid": true,
    "addressMessages": [],
    "lines": [
      { "productId": "PRD-1010", "sku": null, "name": "Black Tee - Medium", "qty": 25, "qtyShipped": 0, "imageUrl": null },
      { "productId": "PRD-1011", "sku": null, "name": "Black Tee - Large", "qty": 25, "qtyShipped": 0, "imageUrl": null }
    ],
    "packagingItems": [],
    "package": null,
    "tracking": null,
    "trackerCode": "TRK7F2K9Q",
    "trackerUrl": "https://anatar.com/track/TRK7F2K9Q",
    "shippedAt": null,
    "deliveredAt": null,
    "cancelledAt": null,
    "createdAt": "2026-09-03T14:02:11.000Z",
    "updatedAt": "2026-09-03T14:02:11.000Z"
  }
}

POST/api/v1/addresses/validateorders:write

Pre-flight address check. Body is { addresses: [shipTo, ...] } (1-200). Results are index-aligned: valid true/false/null, messages, and a normalized shipTo when deliverable.

POST/api/v1/orders/batchorders:write

Create up to 200 orders in one request. The body is { orders: [...] } where each entry matches the single-order schema. Each order is processed independently; the response reports per-order success or failure.

POST/api/v1/orders/{numberOrId}/reorderorders:write

Create a new order shipping to the same address as an existing one. Send an empty body to clone the original lines exactly, or pass lines to change products or quantities and notes to replace the note. Pass externalId + externalSource to make the call idempotent. Returns the new order with status received.

POST/api/v1/orders/{numberOrId}/cancelorders:write

Cancel an order by number and release any reserved inventory. Orders that already shipped cannot be cancelled - the call returns 409.

POST/api/v1/orders/{numberOrId}/deliverorders:write

Confirm delivery of a shipped order (for carriers without tracking integration). Emits order.delivered to your webhooks. Live keys only.

POST/api/v1/orders/{numberOrId}/simulateorders:write

Sandbox keys only. Advance a test order to allocated, shipped, or delivered without touching warehouse stock, labels, or billing. Fires the matching sandbox webhook. Body: { status: allocated | shipped | delivered }.

Inventory

Live stock levels for every active product in your Relay catalog, including reserved and incoming quantities. Identify products by product id (PRD-####). SKU is optional and often empty.

GET/api/v1/inventoryinventory:read

List active products that have stock on hand, reserved, or incoming.

Request

curl https://anatar.com/api/v1/inventory \
  -H "Authorization: Bearer $RELAY_API_KEY"

Item fields

`productId` stringrequired	Relay product id (PRD-####). Use this on order lines.
`sku` string \| nulloptional	Customer or UPC code when one exists. Often null.
`name` stringrequired	Product display name.
`qtyOnHand` integerrequired	Physical units in the warehouse.
`qtyReserved` integerrequired	Units allocated to open orders.
`qtyAvailable` integerrequired	On hand minus reserved - what you can sell right now.
`qtyIncoming` integerrequired	Units expected from inbound shipments not yet received.
`lowStock` booleanrequired	True when available quantity is at or below the reorder point.

GET/api/v1/inventory/{productId}inventory:read

Fetch one product by product id (PRD-####) or sku. Add ?include=movements for the 50 most recent inventory movements (receives, allocations, adjustments).

Request

curl "https://anatar.com/api/v1/inventory/PRD-1010?include=movements" \
  -H "Authorization: Bearer $RELAY_API_KEY"

DELETE/api/v1/inventory/{productId}inventory:write

Archive a product. It stops appearing in listings and can no longer be ordered; movement history is preserved.

Inbound shipments

Tell the warehouse what stock is on the way. Received units are checked in at the dock and become available automatically.

GET/api/v1/inboundinventory:read

List inbound receipts with their check-in status.

POST/api/v1/inboundinventory:write

Create an inbound shipment (ASN). Identify existing catalog items with productId. To file a new incoming UPC, send sku plus name.

Body

`lines` array (1-200)required	Each line needs quantity plus productId or sku. Use productId for catalog items. sku + name creates a new incoming UPC.
`tracking` string (max 200)optional	Carrier tracking number for the inbound freight.
`expectedOn` date (YYYY-MM-DD)optional	Expected arrival date.
`notes` string (max 2000)optional	Instructions for receiving.
`externalId` string (max 200)optional	Your PO or ASN number - idempotency key with externalSource.
`externalSource` string (max 80)optional	Origin system tag.

Request

curl -X POST https://anatar.com/api/v1/inbound \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "PO-2091",
    "externalSource": "erp",
    "tracking": "1Z999AA10123456784",
    "expectedOn": "2026-09-12",
    "lines": [
      { "productId": "PRD-1010", "quantity": 500 },
      { "sku": "TEE-NVY-M", "name": "Navy Tee - Medium", "quantity": 300 }
    ]
  }'

Tracking

Every order gets a tracker code at creation. Use it for API lookups or hand the public tracking page straight to your customer.

GET/api/v1/tracking/{code}orders:read

Fetch shipment status by tracker code: order status, carrier, tracking number, ship and delivery timestamps, destination, and line items.

Request

curl https://anatar.com/api/v1/tracking/TRK7F2K9Q \
  -H "Authorization: Bearer $RELAY_API_KEY"

The same code powers the customer-facing tracking page - no authentication required: https://anatar.com/track/{code}. Safe to embed in transactional email and order-status pages. It deep-links to the carrier's own tracking when available.

Webhooks

Push notifications for order lifecycle events. Prefer webhooks over polling for anything user-facing.

Events

`order.received` eventoptional	Order accepted by Relay (created via API, Shopify, Zapier, or manually).
`order.allocated` eventoptional	Inventory reserved; order is ready to pick.
`order.shipped` eventoptional	Label purchased and package handed to the carrier. Payload includes tracking.
`order.delivered` eventoptional	Carrier confirmed delivery.

GET/api/v1/webhookswebhooks:manage

List your active webhook subscriptions for this key's mode. A sandbox key only sees sandbox endpoints.

POST/api/v1/webhookswebhooks:manage

Subscribe an HTTPS endpoint (plain http and private/internal hosts are rejected with 400). A sandbox key registers a sandbox endpoint that only receives test-order events. The signing secret is returned once in this response - store it immediately. Limit: 25 active subscriptions per mode.

Request

curl -X POST https://anatar.com/api/v1/webhooks \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.acme.com/hooks/relay",
    "events": ["order.shipped", "order.delivered"]
  }'

Response 201

{
  "data": {
    "id": "3f1c8b7a-...",
    "url": "https://api.acme.com/hooks/relay",
    "events": ["order.shipped", "order.delivered"],
    "active": true,
    "source": "api",
    "secret": "whsec_4f6e1a...  // shown once - store it now"
  }
}

DELETE/api/v1/webhooks/{id}webhooks:manage

Unsubscribe (deactivate) a webhook endpoint.

Delivery format

Deliveries are HTTP POSTs with a JSON body and three headers. Respond with any 2xx within 10 seconds to acknowledge.

Headers

`X-Relay-Event` stringrequired	The event name, e.g. order.shipped.
`X-Relay-Signature` hex stringrequired	HMAC-SHA256 of the raw request body, keyed with your webhook secret.
`X-Relay-Delivery` uuidrequired	Unique delivery id. Use it to deduplicate redelivered events.

Example payload (order.shipped)

{
  "event": "order.shipped",
  "order": {
    "number": "RLY-202609-0042",
    "status": "shipped",
    "externalId": "SO-88412",
    "externalSource": "erp",
    "trackerCode": "TRK7F2K9Q",
    "trackerUrl": "https://anatar.com/track/TRK7F2K9Q",
    "tracking": {
      "carrier": "usps",
      "number": "9400111899560000000000",
      "status": "PRE_TRANSIT",
      "statusAt": "2026-09-04T18:22:40.000Z"
    },
    "shippedAt": "2026-09-04T18:22:40.000Z",
    "lines": [
      { "productId": "PRD-1010", "sku": null, "name": "Black Tee - Medium", "qty": 25, "qtyShipped": 25, "imageUrl": null }
    ]
  },
  "tracking": { "number": "9400111899560000000000", "carrier": "usps" }
}

Verifying signatures

Always verify the signature against the raw request bytes before parsing JSON. Reject requests whose signature does not match.

Node.js verification

const crypto = require("node:crypto");

function verifyRelaySignature(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(signatureHeader, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express example - capture the raw body, verify, then parse
app.post("/hooks/relay", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.get("X-Relay-Signature") || "";
  if (!verifyRelaySignature(req.body, signature, process.env.RELAY_WEBHOOK_SECRET)) {
    return res.status(401).end();
  }
  const payload = JSON.parse(req.body.toString("utf8"));
  // handle payload.event ...
  res.status(200).end();
});

Retry policy

Non-2xx responses and timeouts are retried with exponential backoff (2, 4, 8, ... minutes, capped at 120) for up to 8 attempts, after which the delivery is marked failed. Your handler should be idempotent - the same event can arrive more than once.

Shopify integration

Native two-way sync: Shopify orders flow into Relay for fulfillment, and Relay pushes tracking back to Shopify when the order ships.

Connect with Shopify

Setup (under 2 minutes)

Sign in to Studio > Settings > Integrations, enter your store domain, and click Connect with Shopify.
Approve the Anatar Relay app on Shopify's consent screen. It requests only read_orders and fulfillment write access - nothing else.
Done. Order webhooks are registered automatically and the access token is stored encrypted (AES-256-GCM). No tokens to copy or manage.
Make sure your Shopify variant SKUs match your Relay catalog SKUs - that mapping drives everything.

Prefer to run your own credentials? The Advanced option in Studio accepts a custom app token (scopes: read_orders, write_fulfillments, read_fulfillments, read_merchant_managed_fulfillment_orders, write_merchant_managed_fulfillment_orders).

What syncs

`orders/create` Shopify -> Relayrequired	New paid orders are ingested as Relay fulfillment orders. Lines are matched by SKU; orders with no mappable SKUs are skipped.
`orders/cancelled` Shopify -> Relayrequired	Cancellations propagate to Relay when the order has not shipped yet.
`Fulfillment push` Relay -> Shopifyrequired	When Relay ships an order, the Shopify order is marked fulfilled with carrier and tracking number.

Inbound Shopify webhooks are verified with Shopify's HMAC signature before processing. Duplicate deliveries are ignored via the order's external id, so replays are safe.

Zapier

Connect Relay to 6,000+ apps without writing code. The Zapier app authenticates with the same API key as direct API access.

Available in Zapier

`New Order` triggeroptional	Fires when Relay accepts an order (order.received).
`Order Shipped` triggeroptional	Fires with tracking details when an order ships.
`Order Delivered` triggeroptional	Fires when the carrier confirms delivery.
`Create Order` actionoptional	Creates a fulfillment order from any Zap.
`Find Inventory Item` searchoptional	Looks up live stock for a SKU.

Connect with Zapier

One click adds Anatar Relay to your Zapier account, then authenticate with your API key - mint a dedicated key named "Zapier" in Studio > Settings > Integrations so you can revoke it independently. Triggers use REST hooks (webhook subscriptions under the hood), so they fire in seconds rather than on a polling schedule.

Production jobs

Anatar custom production (ORD-####). Warehouse shipments stay on /orders. Create and reorder require a live key - they open real work in Anatar OS.

GET/api/v1/jobs

List this company's production jobs. Scope: jobs:read.

POST/api/v1/jobs

Live keys only. Open an unpriced job. Body: { name?, notes?, lines: [{ description, quantity, detail? }], shipTo? }.

GET/api/v1/jobs/{number}

One job by ORD-####. Lines, stage, tracker URL, related invoices.

POST/api/v1/jobs/{number}/reorder

Live keys only. Clone the job into a new ORD- and a draft invoice. Optional body: { notes, lines: [{ description, quantity }] }.

Quotes and RFQ

Read sent quotes. Submit an RFQ with a live key. Anatar prices it and sends the quote; accept/decline stays on the public review URL.

GET/api/v1/quotes

Sent quotes plus your submitted RFQs. Scope: quotes:read.

POST/api/v1/quotes

Live keys only. Submit an RFQ. Body: { name?, notes?, lines: [{ description, quantity, detail? }] }.

GET/api/v1/quotes/{number}

Quote or RFQ detail, including reviewUrl once Anatar has sent it.

Billing

Customer-facing invoices and payments. Drafts stay in Anatar. Pay through the invoice payUrl.

GET/api/v1/invoices

Open and paid invoices. Scope: billing:read.

GET/api/v1/invoices/{number}

Invoice detail with lines, payUrl, and pdfUrl.

GET/api/v1/payments

Succeeded payments and receipts.

Testing your integration

The sandbox is the same API host - it is gated by your sandbox token, not a public playground. Mint an ak_test_ key in Studio. Those requests never enter the warehouse queue, reserve stock, or bill. Live-only writes (inbound create, inventory archive, mark delivered, production create, RFQ, production reorder) return 403 on a sandbox key.

Mint a sandbox key. In Studio > Settings > Integrations click Mint sandbox key. Authenticate with Authorization: Bearer ak_test_... against the same base URL. GET /me returns mode: "sandbox".
Create and read sandbox orders. POST /orders with the test key creates an SBX- order. Live keys cannot see it. Inventory reads still return your real catalog so you can send real productIds.
Register a sandbox webhook, then simulate lifecycle. POST /webhooks with the test key subscribes only to sandbox events. POST /orders/{number}/simulate with { "status": "shipped" } advances the order and fires the matching event. Inbound writes and inventory archives stay live-key only.

Do not point production storefronts at a live key until this loop passes. A live key still creates real warehouse work.

Errors and status codes

Errors are returned with a conventional HTTP status and a JSON error object. Validation failures include per-field details from the schema validator.

Status codes

`200 / 201` successoptional	Request succeeded / resource created.
`400` bad requestoptional	Malformed parameter or unknown reference - e.g. an invalid since timestamp or an unknown SKU on an order line.
`401` unauthorizedoptional	Missing, malformed, or revoked API key.
`403` forbiddenoptional	The key lacks the required scope.
`404` not foundoptional	Resource does not exist or belongs to another account.
`409` conflictoptional	State conflict - e.g. cancelling a shipped order, or exceeding the webhook subscription limit.
`422` validationoptional	Request body failed schema validation. error.details.fieldErrors maps each field to its errors.
`429` rate limitedoptional	Too many requests. Back off for error.details.retryAfterSeconds.
`500 / 502` server erroroptional	Unexpected failure. Safe to retry with idempotency keys set.

Validation error example

// 422 - schema validation
{
  "error": {
    "message": "Validation failed",
    "details": {
      "formErrors": [],
      "fieldErrors": {
        "shipTo": ["Too big: expected string to have <=2 characters"]
      }
    }
  }
}

Need help? Your Anatar account team can trace any request. Include the endpoint, timestamp (with timezone), and your key prefix (e.g. ak_live_a1b2) - never send the full secret.

Relay | Fulfillment platform

Relay API reference

Complete reference for the Relay REST API, webhooks, and native integrations. Written for the engineers building against your fulfillment pipeline.

Getting started

The Relay API is a versioned REST API served over HTTPS. All requests and responses use JSON.

Base URL: https://anatar.com/api/v1
Key format: ak_live_... / ak_test_...

What this key can access

GET/api/v1/me

Auth test. Any valid live or sandbox key. Returns mode (live or sandbox), the company name, and this key's scopes. No customer or key UUIDs.

Request

curl https://anatar.com/api/v1/me \
  -H "Authorization: Bearer $RELAY_API_KEY"

Response

{
  "data": {
    "mode": "sandbox",
    "customer": {
      "name": "Acme Industries",
      "slug": "acme",
      "customerNumber": "CUS-1042"
    },
    "key": {
      "name": "Studio sandbox",
      "prefix": "ak_test_a1b2",
      "scopes": ["orders:read", "orders:write", "inventory:read", "inventory:write", "webhooks:manage"]
    }
  }
}

API conventions

Every endpoint follows the same envelope, pagination, idempotency, and rate-limit rules.

Product identity

Recipient data

Response envelope

Envelopes

// Success
{ "data": { ... } }

// Success with pagination (list endpoints)
{ "data": [ ... ], "meta": { "limit": 100, "offset": 0, "total": 1284 } }

// Error
{ "error": { "message": "Order not found", "details": null } }

Idempotency

Rate limits

Limits (fixed 60-second window)

`Authenticated` 300 req/min per keyrequired	Counted per API key across all endpoints. Exceeding it returns 429 with retryAfterSeconds in the error details.
`Unauthenticated` 30 req/min per IPrequired	Invalid or missing tokens are throttled per client IP before any database work.

429 response

{
  "error": {
    "message": "Rate limit exceeded",
    "details": { "limit": 300, "retryAfterSeconds": 42 }
  }
}

Scopes

Each key carries scopes. Calling an endpoint without the required scope returns 403. Default keys carry all scopes.

Available scopes

`orders:read` scopeoptional	List and fetch orders and tracking.
`orders:write` scopeoptional	Create, reorder, cancel, and confirm delivery of orders.
`inventory:read` scopeoptional	List inventory, product detail, movement history, inbound receipts.
`inventory:write` scopeoptional	Create inbound shipments, archive products.
`webhooks:manage` scopeoptional	List, subscribe, and unsubscribe webhook endpoints.

Order lifecycle

Orders move through a fixed pipeline. Each transition can emit a webhook (see the Webhooks section).

Status pipeline

received -> allocated -> packed -> shipped -> delivered
     |            |
     +------------+--> cancelled (only before shipment)

Orders

Create fulfillment orders, poll their status, reorder to the same address, cancel before shipment, and confirm delivery.

GET/api/v1/ordersorders:read

List orders newest-first with limit/offset pagination. Response includes a meta object with the total count.

Query parameters

`limit` integeroptional	Page size, 1-200. Defaults to 100.
`offset` integeroptional	Rows to skip. Defaults to 0.
`status` stringoptional	Filter by status: received, allocated, packed, shipped, delivered, cancelled.
`since` ISO 8601 timestampoptional	Only orders created at or after this time. Invalid timestamps return 400.
`shippedSince` ISO 8601 timestampoptional	Only orders shipped at or after this time. meta.total is the exact count. Invalid timestamps return 400.

Request

curl "https://anatar.com/api/v1/orders?status=shipped&since=2026-09-01T00:00:00Z&limit=50" \
  -H "Authorization: Bearer $RELAY_API_KEY"

GET/api/v1/orders/{numberOrId}orders:read

Fetch one order with lines and packaging. Use the order number (RLY-YYYYMM-####).

Request

curl https://anatar.com/api/v1/orders/RLY-202609-0042 \
  -H "Authorization: Bearer $RELAY_API_KEY"

POST/api/v1/ordersorders:write

Create a fulfillment order. Live keys enter the warehouse queue. Sandbox keys (ak_test_) create SBX- orders that never reserve stock or get picked; advance them with POST /orders/{number}/simulate.

Body

`shipTo` objectrequired	Destination address. See the field reference below.
`lines` array (1-100)required	Items to ship. Each line needs quantity plus productId (PRD-####, preferred) or sku. Most warehouse products only have a product id - sku is optional.
`externalId` string (max 200)optional	Your system order id. Combined with externalSource for idempotency.
`externalSource` string (max 100)optional	Origin system tag, e.g. "erp", "shopify", "zapier".
`notes` string (max 5000)optional	Free-form instructions for the warehouse.

shipTo fields

`line1` string (max 200)required	Street address.
`city` string (max 100)required	City.
`state` string (max 100)required	State, province, or region.
`postalCode` string (max 20)required	Postal / ZIP code.
`country` string (2 chars)required	ISO 3166-1 alpha-2 country code, e.g. US.
`name` string (max 200)optional	Recipient name.
`company` string (max 200)optional	Company name.
`line2` string (max 200)optional	Suite, unit, floor.
`phone` string (max 30)optional	Contact phone for the carrier.
`email` string (email)optional	Contact email for delivery notifications.

Request

curl -X POST https://anatar.com/api/v1/orders \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "SO-88412",
    "externalSource": "erp",
    "shipTo": {
      "name": "Jordan Blake",
      "company": "Acme Retail",
      "line1": "500 Commerce Way",
      "line2": "Suite 210",
      "city": "Austin",
      "state": "TX",
      "postalCode": "78701",
      "country": "US",
      "email": "jordan@acmeretail.com"
    },
    "lines": [
      { "productId": "PRD-1010", "quantity": 25 },
      { "productId": "PRD-1011", "quantity": 25 }
    ],
    "notes": "Include packing slip PO 88412"
  }'

Response 201

{
  "data": {
    "number": "RLY-202609-0042",
    "status": "received",
    "externalId": "SO-88412",
    "externalSource": "erp",
    "shipTo": { "name": "Jordan Blake", "city": "Austin", "state": "TX", "country": "US", "postalCode": "78701", "line1": "500 Commerce Way" },
    "notes": "Include packing slip PO 88412",
    "addressValid": true,
    "addressMessages": [],
    "lines": [
      { "productId": "PRD-1010", "sku": null, "name": "Black Tee - Medium", "qty": 25, "qtyShipped": 0, "imageUrl": null },
      { "productId": "PRD-1011", "sku": null, "name": "Black Tee - Large", "qty": 25, "qtyShipped": 0, "imageUrl": null }
    ],
    "packagingItems": [],
    "package": null,
    "tracking": null,
    "trackerCode": "TRK7F2K9Q",
    "trackerUrl": "https://anatar.com/track/TRK7F2K9Q",
    "shippedAt": null,
    "deliveredAt": null,
    "cancelledAt": null,
    "createdAt": "2026-09-03T14:02:11.000Z",
    "updatedAt": "2026-09-03T14:02:11.000Z"
  }
}

POST/api/v1/addresses/validateorders:write

Pre-flight address check. Body is { addresses: [shipTo, ...] } (1-200). Results are index-aligned: valid true/false/null, messages, and a normalized shipTo when deliverable.

POST/api/v1/orders/batchorders:write

POST/api/v1/orders/{numberOrId}/reorderorders:write

POST/api/v1/orders/{numberOrId}/cancelorders:write

Cancel an order by number and release any reserved inventory. Orders that already shipped cannot be cancelled - the call returns 409.

POST/api/v1/orders/{numberOrId}/deliverorders:write

Confirm delivery of a shipped order (for carriers without tracking integration). Emits order.delivered to your webhooks. Live keys only.

POST/api/v1/orders/{numberOrId}/simulateorders:write

Inventory

Live stock levels for every active product in your Relay catalog, including reserved and incoming quantities. Identify products by product id (PRD-####). SKU is optional and often empty.

GET/api/v1/inventoryinventory:read

List active products that have stock on hand, reserved, or incoming.

Request

curl https://anatar.com/api/v1/inventory \
  -H "Authorization: Bearer $RELAY_API_KEY"

Item fields

`productId` stringrequired	Relay product id (PRD-####). Use this on order lines.
`sku` string \| nulloptional	Customer or UPC code when one exists. Often null.
`name` stringrequired	Product display name.
`qtyOnHand` integerrequired	Physical units in the warehouse.
`qtyReserved` integerrequired	Units allocated to open orders.
`qtyAvailable` integerrequired	On hand minus reserved - what you can sell right now.
`qtyIncoming` integerrequired	Units expected from inbound shipments not yet received.
`lowStock` booleanrequired	True when available quantity is at or below the reorder point.

GET/api/v1/inventory/{productId}inventory:read

Fetch one product by product id (PRD-####) or sku. Add ?include=movements for the 50 most recent inventory movements (receives, allocations, adjustments).

Request

curl "https://anatar.com/api/v1/inventory/PRD-1010?include=movements" \
  -H "Authorization: Bearer $RELAY_API_KEY"

DELETE/api/v1/inventory/{productId}inventory:write

Archive a product. It stops appearing in listings and can no longer be ordered; movement history is preserved.

Inbound shipments

Tell the warehouse what stock is on the way. Received units are checked in at the dock and become available automatically.

GET/api/v1/inboundinventory:read

List inbound receipts with their check-in status.

POST/api/v1/inboundinventory:write

Create an inbound shipment (ASN). Identify existing catalog items with productId. To file a new incoming UPC, send sku plus name.

Body

`lines` array (1-200)required	Each line needs quantity plus productId or sku. Use productId for catalog items. sku + name creates a new incoming UPC.
`tracking` string (max 200)optional	Carrier tracking number for the inbound freight.
`expectedOn` date (YYYY-MM-DD)optional	Expected arrival date.
`notes` string (max 2000)optional	Instructions for receiving.
`externalId` string (max 200)optional	Your PO or ASN number - idempotency key with externalSource.
`externalSource` string (max 80)optional	Origin system tag.

Request

curl -X POST https://anatar.com/api/v1/inbound \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "PO-2091",
    "externalSource": "erp",
    "tracking": "1Z999AA10123456784",
    "expectedOn": "2026-09-12",
    "lines": [
      { "productId": "PRD-1010", "quantity": 500 },
      { "sku": "TEE-NVY-M", "name": "Navy Tee - Medium", "quantity": 300 }
    ]
  }'

Tracking

Every order gets a tracker code at creation. Use it for API lookups or hand the public tracking page straight to your customer.

GET/api/v1/tracking/{code}orders:read

Fetch shipment status by tracker code: order status, carrier, tracking number, ship and delivery timestamps, destination, and line items.

Request

curl https://anatar.com/api/v1/tracking/TRK7F2K9Q \
  -H "Authorization: Bearer $RELAY_API_KEY"

Webhooks

Push notifications for order lifecycle events. Prefer webhooks over polling for anything user-facing.

Events

`order.received` eventoptional	Order accepted by Relay (created via API, Shopify, Zapier, or manually).
`order.allocated` eventoptional	Inventory reserved; order is ready to pick.
`order.shipped` eventoptional	Label purchased and package handed to the carrier. Payload includes tracking.
`order.delivered` eventoptional	Carrier confirmed delivery.

GET/api/v1/webhookswebhooks:manage

List your active webhook subscriptions for this key's mode. A sandbox key only sees sandbox endpoints.

POST/api/v1/webhookswebhooks:manage

Request

curl -X POST https://anatar.com/api/v1/webhooks \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.acme.com/hooks/relay",
    "events": ["order.shipped", "order.delivered"]
  }'

Response 201

{
  "data": {
    "id": "3f1c8b7a-...",
    "url": "https://api.acme.com/hooks/relay",
    "events": ["order.shipped", "order.delivered"],
    "active": true,
    "source": "api",
    "secret": "whsec_4f6e1a...  // shown once - store it now"
  }
}

DELETE/api/v1/webhooks/{id}webhooks:manage

Unsubscribe (deactivate) a webhook endpoint.

Delivery format

Deliveries are HTTP POSTs with a JSON body and three headers. Respond with any 2xx within 10 seconds to acknowledge.

Headers

`X-Relay-Event` stringrequired	The event name, e.g. order.shipped.
`X-Relay-Signature` hex stringrequired	HMAC-SHA256 of the raw request body, keyed with your webhook secret.
`X-Relay-Delivery` uuidrequired	Unique delivery id. Use it to deduplicate redelivered events.

Example payload (order.shipped)

{
  "event": "order.shipped",
  "order": {
    "number": "RLY-202609-0042",
    "status": "shipped",
    "externalId": "SO-88412",
    "externalSource": "erp",
    "trackerCode": "TRK7F2K9Q",
    "trackerUrl": "https://anatar.com/track/TRK7F2K9Q",
    "tracking": {
      "carrier": "usps",
      "number": "9400111899560000000000",
      "status": "PRE_TRANSIT",
      "statusAt": "2026-09-04T18:22:40.000Z"
    },
    "shippedAt": "2026-09-04T18:22:40.000Z",
    "lines": [
      { "productId": "PRD-1010", "sku": null, "name": "Black Tee - Medium", "qty": 25, "qtyShipped": 25, "imageUrl": null }
    ]
  },
  "tracking": { "number": "9400111899560000000000", "carrier": "usps" }
}

Verifying signatures

Always verify the signature against the raw request bytes before parsing JSON. Reject requests whose signature does not match.

Node.js verification

const crypto = require("node:crypto");

function verifyRelaySignature(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(signatureHeader, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express example - capture the raw body, verify, then parse
app.post("/hooks/relay", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.get("X-Relay-Signature") || "";
  if (!verifyRelaySignature(req.body, signature, process.env.RELAY_WEBHOOK_SECRET)) {
    return res.status(401).end();
  }
  const payload = JSON.parse(req.body.toString("utf8"));
  // handle payload.event ...
  res.status(200).end();
});

Retry policy

Shopify integration

Native two-way sync: Shopify orders flow into Relay for fulfillment, and Relay pushes tracking back to Shopify when the order ships.

Connect with Shopify

Setup (under 2 minutes)

Sign in to Studio > Settings > Integrations, enter your store domain, and click Connect with Shopify.
Approve the Anatar Relay app on Shopify's consent screen. It requests only read_orders and fulfillment write access - nothing else.
Done. Order webhooks are registered automatically and the access token is stored encrypted (AES-256-GCM). No tokens to copy or manage.
Make sure your Shopify variant SKUs match your Relay catalog SKUs - that mapping drives everything.

What syncs

`orders/create` Shopify -> Relayrequired	New paid orders are ingested as Relay fulfillment orders. Lines are matched by SKU; orders with no mappable SKUs are skipped.
`orders/cancelled` Shopify -> Relayrequired	Cancellations propagate to Relay when the order has not shipped yet.
`Fulfillment push` Relay -> Shopifyrequired	When Relay ships an order, the Shopify order is marked fulfilled with carrier and tracking number.

Inbound Shopify webhooks are verified with Shopify's HMAC signature before processing. Duplicate deliveries are ignored via the order's external id, so replays are safe.

Zapier

Connect Relay to 6,000+ apps without writing code. The Zapier app authenticates with the same API key as direct API access.

Available in Zapier

`New Order` triggeroptional	Fires when Relay accepts an order (order.received).
`Order Shipped` triggeroptional	Fires with tracking details when an order ships.
`Order Delivered` triggeroptional	Fires when the carrier confirms delivery.
`Create Order` actionoptional	Creates a fulfillment order from any Zap.
`Find Inventory Item` searchoptional	Looks up live stock for a SKU.

Connect with Zapier

Production jobs

Anatar custom production (ORD-####). Warehouse shipments stay on /orders. Create and reorder require a live key - they open real work in Anatar OS.

GET/api/v1/jobs

List this company's production jobs. Scope: jobs:read.

POST/api/v1/jobs

Live keys only. Open an unpriced job. Body: { name?, notes?, lines: [{ description, quantity, detail? }], shipTo? }.

GET/api/v1/jobs/{number}

One job by ORD-####. Lines, stage, tracker URL, related invoices.

POST/api/v1/jobs/{number}/reorder

Live keys only. Clone the job into a new ORD- and a draft invoice. Optional body: { notes, lines: [{ description, quantity }] }.

Quotes and RFQ

Read sent quotes. Submit an RFQ with a live key. Anatar prices it and sends the quote; accept/decline stays on the public review URL.

GET/api/v1/quotes

Sent quotes plus your submitted RFQs. Scope: quotes:read.

POST/api/v1/quotes

Live keys only. Submit an RFQ. Body: { name?, notes?, lines: [{ description, quantity, detail? }] }.

GET/api/v1/quotes/{number}

Quote or RFQ detail, including reviewUrl once Anatar has sent it.

Billing

Customer-facing invoices and payments. Drafts stay in Anatar. Pay through the invoice payUrl.

GET/api/v1/invoices

Open and paid invoices. Scope: billing:read.

GET/api/v1/invoices/{number}

Invoice detail with lines, payUrl, and pdfUrl.

GET/api/v1/payments

Succeeded payments and receipts.

Testing your integration

Mint a sandbox key. In Studio > Settings > Integrations click Mint sandbox key. Authenticate with Authorization: Bearer ak_test_... against the same base URL. GET /me returns mode: "sandbox".
Create and read sandbox orders. POST /orders with the test key creates an SBX- order. Live keys cannot see it. Inventory reads still return your real catalog so you can send real productIds.
Register a sandbox webhook, then simulate lifecycle. POST /webhooks with the test key subscribes only to sandbox events. POST /orders/{number}/simulate with { "status": "shipped" } advances the order and fires the matching event. Inbound writes and inventory archives stay live-key only.

Do not point production storefronts at a live key until this loop passes. A live key still creates real warehouse work.

Errors and status codes

Errors are returned with a conventional HTTP status and a JSON error object. Validation failures include per-field details from the schema validator.

Status codes

`200 / 201` successoptional	Request succeeded / resource created.
`400` bad requestoptional	Malformed parameter or unknown reference - e.g. an invalid since timestamp or an unknown SKU on an order line.
`401` unauthorizedoptional	Missing, malformed, or revoked API key.
`403` forbiddenoptional	The key lacks the required scope.
`404` not foundoptional	Resource does not exist or belongs to another account.
`409` conflictoptional	State conflict - e.g. cancelling a shipped order, or exceeding the webhook subscription limit.
`422` validationoptional	Request body failed schema validation. error.details.fieldErrors maps each field to its errors.
`429` rate limitedoptional	Too many requests. Back off for error.details.retryAfterSeconds.
`500 / 502` server erroroptional	Unexpected failure. Safe to retry with idempotency keys set.

Validation error example

// 422 - schema validation
{
  "error": {
    "message": "Validation failed",
    "details": {
      "formErrors": [],
      "fieldErrors": {
        "shipTo": ["Too big: expected string to have <=2 characters"]
      }
    }
  }
}

Need help? Your Anatar account team can trace any request. Include the endpoint, timestamp (with timezone), and your key prefix (e.g. ak_live_a1b2) - never send the full secret.