API (구)

BoxHero's API allows developers to integrate our inventory management capabilities with external applications for efficient data retrieval and interaction.

---

API Reference

For detailed endpoint documentation, please visit: https://rest.boxhero.io/docs/api

---

Endpoint

All API requests should be directed to the following base URL: https://rest.boxhero-app.com

Authentication

All API requests must include an Authorization header with a Bearer token:

Authorization: Bearer {API_TOKEN}

To obtain an API token:

1. Log into your BoxHero account on the Desktop (Web).

2. Navigate to Settings > Integrations.

3. Generate a new API token.

Making Requests

Here's a sample API request to retrieve products.

curl -X 'GET' \
  'https://rest.boxhero-app.com/v1/items?location_ids=12345&location_ids=34567&limit=100' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer test-api-token-123'

Rate Limits

To ensure system stability, we impose the following rate limits:

• 5 queries per second for each endpoint.

Once you are rate limited, you will see an error message with the following:

• X-Ratelimit-Limit - Maximum queries per minute

• X-Ratelimit-Remaining - Remaining queries

• X-Ratelimit-Reset - Time (in seconds) remaining until query count reset

---

Responses

Success

Responses with HTTP status codes in the 200 range indicate successful API processing.

Error

Status codes in the 400 or 500 range indicate API request failures:

• 400 range: Client-side error from information provided with the request (e.g., missing required parameters).

• 500 range: Server-side error.

Example Error Response:

{
  "id": "ex_ku3gij67k9xzc8ef6r5esyu5",
  "type": "/errors/tokens/invalid",
  "title": "Authentication token is invalid. Please provide a valid token.",
  "correlation_id": "rq_z4g7dh55ykol7v2cx6homkpd",
  "given": "invalid-token-123"
}

• id : A unique ID to identify the error.

• type : A code in the form of a URL that identifies the type of error.

• title : Provide the contents of the error in human-readable form.

• correlation_id : Points to the ID of the request associated with the error.

• others : Additional fields may be included to provide additional information, such as "given" in the example.

Common Error Types

Type	Description
/errors/not-found	Requested resource not found (e.g., item with a specific ID does not exist).
/errors/invalid-request	Invalid parameters in request.
/errors/invalid-team-mode	Requested query cannot be processed in current team mode (e.g., using the location lookup API in Basic Mode).
/errors/tokens/required	Missing API token.
/errors/tokens/invalid	Invalid API token (e.g., API token has expired).
/errors/too-many-requests	Exceeded the rate limit.
/errors/unhandled	Unresolved server-side error.
/errors/core/usage-limit-exceeded	Reached usage limit. Plan upgrade required.

Pagination

For endpoints returning large datasets (e.g., item lists, transaction lists), the list view API limits the number of items returned in a single request through pagination. We use cursor-based pagination:

To determine if pagination is required, check whether pagination-related parameters are present in the request body of the endpoint in the API documentation.

Pagination Parameters

• has_more : A boolean that indicates whether more data exists beyond the current page.

• cursor : Provides the cursor value for retrieving the next page.

Retrieving the Next Page

• Check if has_more is true. It means there’s another page available.

• If true, send another request including cursor={received cursor value} in the parameters. This will return the subsequent data.

• Repeat until has_more is false to retrieve the full list.

---

Support and Feedback

If you encounter issues or need additional API functionality, please contact our support team. We welcome your feedback for API improvements and new feature requests.

BoxHero’s API: A Simple Way to Integrate Your Inventory DataBoxHero Blog