Warehouse Quickstart
Recommended setup for a 3PL or warehouse: create a warehouse-scoped key, add a webhook endpoint, verify signatures, then use polling for backfill and reconciliation.
Use webhooks for new work and polling for reconciliation.
A warehouse integration should treat outbound webhooks as the primary signal for new or changed work, while continuing to use the existing list endpoints for backfill, replay, and periodic reconciliation. For multi-location merchants, scope each key and webhook endpoint to the fulfillment locations that warehouse is responsible for.
- 1. Create a warehouse API key in the merchant portal.
- 2. Create a webhook endpoint and subscribe to order, inventory, and fulfillment events.
- 3. Verify webhook signatures before accepting payloads.
- 4. Poll the orders, inventory, and fulfillments APIs for backfill and reconciliation.
- 5. Create fulfillments and tracking updates through the integration API.
Create a warehouse key with the write scopes you need.
Most 3PLs should use the Warehouse preset or an equivalent custom scope set with orders.read, products.read, inventory.read, inventory.write, fulfillments.read, and fulfillments.write. If the merchant operates multiple warehouses, choose Specific locations and assign only the fulfillment locations that this partner should handle.
[
"orders.read",
"products.read",
"inventory.read",
"inventory.write",
"fulfillments.read",
"fulfillments.write"
]Add a webhook endpoint for outbound events.
Webhook endpoints are merchant-managed in the merchant portal. Subscribe to the events your warehouse needs, store the signing secret securely, and validate every delivery with the timestamped HMAC signature. Endpoint location filters are independent from API key filters, so merchants can route one warehouse to a subset of fulfillment locations without affecting other integrations.
timestamp = header["X-Rarely-Webhook-Timestamp"]
raw_body = request body bytes
signed_payload = timestamp + "." + raw_body
expected = HMAC_SHA256(signing_secret, signed_payload)Use fulfillment writes after your warehouse accepts the work.
Once the warehouse has picked and shipped, create a fulfillment or update tracking using the same merchant-scoped API key. Use idempotency keys on write requests so retried submissions do not double-apply.
curl -X POST "https://merchants.rarely.co//api/integrations/v1/fulfillments/FULFILLMENT_ID/tracking" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: warehouse-tracking-001" \
-H "Content-Type: application/json" \
-d '{
"tracking_number": "1Z9999999999999999",
"tracking_url": "https://www.ups.com/track?tracknum=1Z9999999999999999",
"carrier_name": "UPS",
"service_level": "Ground"
}'