1. Create an API key

Go to Admin → API Keys, click Create API Key, and copy the secret. It is shown only once.

2. Authenticate

Pass the key as a Bearer token on every request:

Authorization: Bearer drfid_sk_live_...

Base URL: https://www.droprfid.com/api/v1

Middleware examples use DROP_RFID_API_BASE_URL and DROP_RFID_API_KEY. See the API-client public API guide.

Copy-paste middleware starter

The public API client repo includes a dependency-free Node example with commands for listing and creating SKUs, creating orders, listing sessions, fetching one session, and generating demo session data when enabled.

export DROP_RFID_API_BASE_URL="https://www.droprfid.com/api/v1"
export DROP_RFID_API_KEY="drfid_sk_live_replace_me"
node examples/node-public-api.mjs list-skus

Open examples/node-public-api.mjs for the runnable version.

3. List sessions

Returns every scan session for your organization with embedded device metadata.

GET /api/v1/public/sessions

curl -H "Authorization: Bearer drfid_sk_live_..." \
  https://www.droprfid.com/api/v1/public/sessions

4. Get one session with RFIDs

Returns the session, its scanned RFID tags, and the device that produced them.

GET /api/v1/public/sessions/{session_id}

curl -H "Authorization: Bearer drfid_sk_live_..." \
  https://www.droprfid.com/api/v1/public/sessions/<session_id>

{
  "id": "...",
  "org_id": "...",
  "device_id": "...",
  "status": "completed",
  "created_at": "2026-04-22T09:00:00Z",
  "completed_at": "2026-04-22T09:03:12Z",
  "device": {
    "id": "...",
    "name": "Warehouse-01",
    "serial_number": "SN-000123",
    "status": "active"
  },
  "rfids": [
    { "rfid_code": "E200470000...", "tid": "...", "rssi": -42, "read_count": 6, "scanned_at": "..." }
  ]
}

5. Orders

List, create, fetch, and update orders. Orders carry SKU line items with expected quantities.

GET     /api/v1/public/orders          # optional ?status=pending
POST    /api/v1/public/orders          # create
GET     /api/v1/public/orders/{order_id}
PATCH   /api/v1/public/orders/{order_id}  # body: { "status": "completed" }

Create with SKU items

curl -X POST -H "Authorization: Bearer drfid_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "order_number": "PO-1042",
    "items": [
      { "sku_id": "sku-uuid-1", "expected_quantity": 24 },
      { "sku_id": "sku-uuid-2", "expected_quantity": 6 }
    ]
  }' \
  https://www.droprfid.com/api/v1/public/orders

Update status

curl -X PATCH -H "Authorization: Bearer drfid_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"status": "completed"}' \
  https://www.droprfid.com/api/v1/public/orders/<order_id>

Allowed status values: pending, in_progress, review_required, blocked, completed, cancelled.

6. Containers

Containers are named collections with recorded contents and optional RFID or barcode identifiers — a tagged box whose contents you can retrieve by scanning it. They live on their own path: containers never appear under /public/orders, and orders never appear under /public/containers.

GET     /api/v1/public/containers          # optional ?tag=holiday
POST    /api/v1/public/containers          # create
GET     /api/v1/public/containers/{container_id}
PATCH   /api/v1/public/containers/{container_id}

Create with recorded contents

curl -X POST -H "Authorization: Bearer drfid_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Christmas decorations — Box 1",
    "items": [
      { "sku_id": "sku-uuid-1", "expected_quantity": 12 }
    ],
    "identifiers": [
      { "type": "rfid", "value": "E2004700ABCD" },
      { "type": "barcode", "value": "00123" }
    ]
  }' \
  https://www.droprfid.com/api/v1/public/containers

Recorded contents describe what the container holds. They are not evidence that each item was individually scanned, and they never affect order fulfilment or inventory counts.

Rename or re-stock

curl -X PATCH -H "Authorization: Bearer drfid_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"revision": 3, "display_name": "Christmas decorations — Attic"}' \
  https://www.droprfid.com/api/v1/public/containers/<container_id>

revision is required on PATCH and must match the value you last read. A stale revision returns 409 rather than silently overwriting a concurrent edit. Supplying items or identifiers replaces that collection wholesale.

7. SKUs

Manage the SKU registry — products, variants, and the RFID codes bound to each. GET /skus/{sku_id} returns a SkuDetail with a rfids[] array.

GET     /api/v1/public/skus
POST    /api/v1/public/skus
GET     /api/v1/public/skus/{sku_id}
PATCH   /api/v1/public/skus/{sku_id}
DELETE  /api/v1/public/skus/{sku_id}

Create

curl -X POST -H "Authorization: Bearer drfid_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "sku_code":      "TSHIRT-RED-M",
    "product_title": "Classic Tee",
    "brand":         "Aqua",
    "color":         "Red",
    "size":          "M",
    "barcode":       "0123456789012",
    "rfids":         ["E200470000...", "E200470001..."],
    "rfid_ranges": [
      { "start": "1000", "end": "1050", "format": "numeric" },
      { "start": "00000000000000FE", "end": "0000000000000110", "format": "hex" }
    ]
  }' \
  https://www.droprfid.com/api/v1/public/skus

Use rfid_ranges to bind a contiguous block of codes without listing each one. Each entry has a start, end, and format — "numeric" (base-10 integers, zero-padded to the widest bound) or "hex" (exactly 16 hexadecimal digits). Ranges are expanded server-side and merged with any rfids you also supply; a single range is capped at 10,000 codes.

Partial update

All body fields are optional. Only fields you include are written. To clear a field, send an empty string. RFID bindings are managed separately.

curl -X PATCH -H "Authorization: Bearer drfid_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"product_title": "Classic Tee — Updated", "color": "Crimson"}' \
  https://www.droprfid.com/api/v1/public/skus/<sku_id>

Delete

curl -X DELETE -H "Authorization: Bearer drfid_sk_live_..." \
  https://www.droprfid.com/api/v1/public/skus/<sku_id>

Returns 204 No Content on success. Deleting a SKU also removes its RFID bindings (the underlying RFID scan history is retained).

8. Routines

List or create guided scanning workflows, or idempotently import reusable YAML and JSON routine manifests by routine code.

GET   /api/v1/public/routines
POST  /api/v1/public/routines
POST  /api/v1/public/routines/import

Create a guided receiving routine

curl -X POST -H "Authorization: Bearer drfid_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "inbound_receiving",
    "name": "Inbound Receiving",
    "description": "Capture a PO and location before scanning",
    "enabled": true,
    "config": {
      "start_fields": [
        {
          "key": "po_number",
          "label": "Purchase order",
          "type": "text",
          "required": true,
          "searchable": true,
          "display_in_sessions": true
        }
      ],
      "finish_fields": [],
      "completion_actions": []
    }
  }' \
  https://www.droprfid.com/api/v1/public/routines

Use completion actions to send signed webhook events, create reports, or perform supported Shopify write-backs with the action mode your operation requires.

Rate limits

Every API key is capped at 60 requests/minute and 1,000 requests/hour. All responses include:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1761096120

Over-limit requests return 429 Too Many Requests.

Versioning and stability