Supplier quickstart - PlatformDTC

This walks through a full cycle. Replace sq_agt_supplier with your issued key.

Test the whole loop with no real order. If we’ve already issued your key and registered your service, skip Step 1. To exercise pull → accept → ship on demand, spawn a sandbox order assigned to you — no payment, no merchant order created:

curl -s -X POST https://api.platformdtc.com/api/v1/fulfillment/test_orders \
  -H "X-Agent-Key: sq_agt_supplier" | jq '.data'

It returns a fulfillment_order_id (a TEST-SKU-001 line at request_status: submitted). Run Steps 2–4 against that id. Call it again any time for a fresh test order — and when you’re done, DELETE /test_orders purges every sandbox order you created in one call (real orders untouched).

curl -s -X POST https://api.platformdtc.com/api/v1/fulfillment/fulfillment_services \
  -H "X-Agent-Key: sq_agt_supplier" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Acme 3PL","callback_url":"https://acme.example.com/dtc","supplier_id":"acme-co",
       "inventory_management":true,"tracking_support":true,"requires_shipping_method":true,
       "webhook_topics":["fulfillment_orders/fulfillment_request_submitted","fulfillments/create","orders/fulfilled"]}' \
  | jq '.data.fulfillment_service'

The response includes your location_id (orders routed to you are assigned to this location) and your webhook_secret. supplier_id is the routing key: order lines whose product carries this same value are auto-assigned to you (omit it to receive only manually-moved lines). Store the webhook_secret now — it is returned only on this registration call and is the single key you verify the X-Webhook-Signature HMAC with on both topic webhooks and the lightweight callback.webhook_topics is optional: pass it to subscribe to topic webhooks in the same call — we create the subscription for you (returned as webhook_subscription_id), pointed at your callback_url (override with webhook_url) and signed with the same webhook_secret. Omit it to receive only the lightweight callback and poll for work. See Inventory & webhooks.

Pull the orders waiting on you

curl -s "https://api.platformdtc.com/api/v1/fulfillment/assigned_fulfillment_orders?assignment_status=fulfillment_requested&limit=50" \
  -H "X-Agent-Key: sq_agt_supplier" | jq '.data.fulfillment_orders'

Each item has the ship-to destination and line_items (with remaining_quantity).

Accept the request

curl -s -X POST https://api.platformdtc.com/api/v1/fulfillment/fulfillment_orders/fo_123/fulfillment_request/accept \
  -H "X-Agent-Key: sq_agt_supplier" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"message":"Processing, ships in 24h"}' | jq '.data.fulfillment_order.status'

The FO moves to in_progress. (To decline instead, see Fulfillment orders.)

Ship it with tracking

curl -s -X POST https://api.platformdtc.com/api/v1/fulfillment/fulfillments \
  -H "X-Agent-Key: sq_agt_supplier" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"fulfillment":{
        "line_items_by_fulfillment_order":[
          {"fulfillment_order_id":"fo_123",
           "fulfillment_order_line_items":[{"id":"foli_1","quantity":2}]}],
        "tracking_info":{"company":"UPS","number":"1Z999",
          "url":"https://www.ups.com/track?tracknum=1Z999"},
        "notify_customer":true}}' | jq '.data.fulfillment'

When all lines are shipped the FO becomes closed and we fire orders/fulfilled.

Omit fulfillment_order_line_items to ship all remaining lines, or send a smaller quantity for a partial shipment — the FO stays in_progress until everything ships.