API Documentation

BinHQ's REST API lets you integrate your fulfillment operations with external tools. Available on the Pro plan.

Authentication

All API requests must include a Bearer token in the Authorization header. You can create and manage API keys in your BinHQ dashboard under Settings → API.

Authorization: Bearer YOUR_API_KEY

Keep your API keys secure. Do not expose them in client-side code or public repositories. If a key is compromised, revoke it immediately from the Settings page and create a new one.

Rate Limiting

API requests are limited to 60 requests per minute per API key. If you exceed this limit, you will receive a 429 response. The Retry-After header in the response indicates how many seconds to wait before making another request.

Base URL

All API endpoints use the following base URL:

https://app.binhq.io/api/v1

Endpoints

GET/api/v1/orders

List orders from pick batches. Supports filtering by status (pending, picked, packed, fulfilled) and pagination via limit/offset.

Example Request

curl -X GET "https://app.binhq.io/api/v1/orders?status=pending&limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Example Response

{
  "data": [
    {
      "id": "cuid_abc123",
      "platformOrderId": "5678901234",
      "platformOrderNumber": "#1042",
      "status": "pending",
      "batchId": "cuid_batch789",
      "batchStatus": "open",
      "createdAt": "2026-03-20T14:30:00.000Z",
      "pickLines": [
        {
          "id": "cuid_line1",
          "productTitle": "Widget Pro",
          "variantTitle": "Large / Blue",
          "sku": "WP-LG-BLU",
          "binId": "cuid_bin001",
          "binName": "A-01-01",
          "quantityRequired": 2,
          "quantityPicked": 0,
          "status": "pending"
        }
      ]
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

GET/api/v1/batches

List pick batches. Supports filtering by status (open, in_progress, complete, expired) and pagination via limit/offset. Returns order and line counts plus pick line details.

Example Request

curl -X GET "https://app.binhq.io/api/v1/batches?status=open&limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Example Response

{
  "data": [
    {
      "id": "cuid_batch789",
      "status": "open",
      "orderCount": 5,
      "lineCount": 12,
      "createdAt": "2026-03-20T15:00:00.000Z",
      "completedAt": null,
      "pickLines": [
        {
          "id": "cuid_line1",
          "productTitle": "Widget Pro",
          "variantTitle": "Large / Blue",
          "sku": "WP-LG-BLU",
          "binId": "cuid_bin001",
          "binName": "A-01-01",
          "quantityRequired": 2,
          "quantityPicked": 0,
          "status": "pending"
        }
      ]
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

POST/api/v1/batches/fulfill

Fulfill specific orders within a batch. Provide a single batchId and an array of orderIds (platform order IDs) to mark as fulfilled. Returns the updated batch status.

Example Request

curl -X POST "https://app.binhq.io/api/v1/batches/fulfill" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "batchId": "cuid_batch789",
    "orderIds": ["5678901234", "5678901235"]
  }'

Example Response

{
  "success": true,
  "data": {
    "batchId": "cuid_batch789",
    "fulfilledOrderIds": ["5678901234", "5678901235"],
    "batchStatus": "complete",
    "batchCompletedAt": "2026-03-20T16:00:00.000Z"
  }
}

GET/api/v1/bins

List bin locations. Supports filtering by locationId and pagination via limit/offset. Returns bins with their sort order, location details, and assigned product count.

Example Request

curl -X GET "https://app.binhq.io/api/v1/bins?limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Example Response

{
  "data": [
    {
      "id": "cuid_bin001",
      "name": "A-01-01",
      "sortOrder": 1,
      "location": {
        "id": "cuid_loc001",
        "name": "Warehouse Main",
        "platformLocationId": "98765432"
      },
      "productCount": 4,
      "createdAt": "2026-03-20T12:00:00.000Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

POST/api/v1/bins/create

Create a new bin. Requires a locationId (UUID of an existing location) and a name. Sort order is optional (defaults to 0).

Example Request

curl -X POST "https://app.binhq.io/api/v1/bins/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "cuid_loc001",
    "name": "B-02-05",
    "sortOrder": 25
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "cuid_bin_new",
    "name": "B-02-05",
    "sortOrder": 25,
    "locationId": "cuid_loc001",
    "createdAt": "2026-03-20T17:00:00.000Z"
  }
}

GET/api/v1/products

List product-bin assignments. Returns variant-to-bin mappings with bin details and inventory levels. Supports filtering by variantId and pagination via limit/offset.

Example Request

curl -X GET "https://app.binhq.io/api/v1/products?limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Example Response

{
  "data": [
    {
      "id": "cuid_pb001",
      "platformVariantId": "44012345678",
      "platformProductId": "78901234",
      "isPrimary": true,
      "bin": {
        "id": "cuid_bin001",
        "name": "A-01-01",
        "sortOrder": 1,
        "locationId": "cuid_loc001"
      },
      "inventory": {
        "quantity": 42,
        "lastUpdatedAt": "2026-03-20T12:00:00.000Z"
      },
      "createdAt": "2026-03-15T10:00:00.000Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

POST/api/v1/products/assign

Assign a product variant to a bin. Requires variantId, productId, and binId. Optionally set an inventory quantity for the variant in that bin.

Example Request

curl -X POST "https://app.binhq.io/api/v1/products/assign" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "variantId": "44012345678",
    "productId": "78901234",
    "binId": "cuid_bin001",
    "quantity": 50
  }'

Example Response

{
  "success": true,
  "data": {
    "productBin": {
      "id": "cuid_pb_new",
      "platformVariantId": "44012345678",
      "platformProductId": "78901234",
      "binId": "cuid_bin001",
      "isPrimary": false
    },
    "inventory": {
      "quantity": 50,
      "lastUpdatedAt": "2026-03-20T17:30:00.000Z"
    }
  }
}

GET/api/v1/inventory

Get a complete inventory snapshot. Returns all locations, bins, product-bin assignments, and bin-level inventory quantities for your store.

Example Request

curl -X GET "https://app.binhq.io/api/v1/inventory" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Example Response

{
  "data": {
    "locations": [
      {
        "id": "cuid_loc001",
        "platformLocationId": "98765432",
        "name": "Warehouse Main"
      }
    ],
    "bins": [
      {
        "id": "cuid_bin001",
        "name": "A-01-01",
        "sortOrder": 1,
        "locationId": "cuid_loc001",
        "locationName": "Warehouse Main"
      }
    ],
    "productBins": [
      {
        "platformVariantId": "44012345678",
        "platformProductId": "78901234",
        "binId": "cuid_bin001",
        "binName": "A-01-01",
        "binSortOrder": 1,
        "locationId": "cuid_loc001",
        "isPrimary": true
      }
    ],
    "binInventory": [
      {
        "platformVariantId": "44012345678",
        "binId": "cuid_bin001",
        "binName": "A-01-01",
        "quantity": 42,
        "lastUpdatedAt": "2026-03-20T12:00:00.000Z"
      }
    ]
  }
}

Error Codes

When a request fails, the API returns a JSON error response with a status code and message.

Code	Name	Description
`400`	Bad Request	The request body is malformed or missing required fields. Check the request format and try again.
`401`	Unauthorized	The API key is missing or invalid. Ensure you are sending a valid Bearer token in the Authorization header.
`403`	Forbidden	Your API key does not have permission for this action. Check your plan level and API key scopes.
`404`	Not Found	The requested resource does not exist. Verify the ID or path is correct.
`429`	Too Many Requests	You have exceeded the rate limit of 60 requests per minute. Wait before retrying. The Retry-After header indicates when you can make requests again.
`500`	Internal Server Error	An unexpected error occurred on our end. If the issue persists, contact support at hello@binhq.io.

Need help with the API?

Reach out to our team and we'll help you get integrated.

Email hello@binhq.io