BoxHero API Reference

This is a public API that can be used to retrieve data within BoxHero from outside the app.

Endpoint

https://rest.boxhero-app.com

Sample Request

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

Authorization

To issue a new API token, please navigate to [Settings] - [Integrations & API] in the PC/web version of BoxHero. All API requests should have the Authorization header as a Bearer {API token}.

Rate limits

We rate limit the API requests as follows.

  • 5 queries per second for each endpoint.

Once you are rate limited, you will see an error message with the following additional information.

  • X-Ratelimit-Limit - Maximum queries per minute

  • X-Ratelimit-Remaining - Remaining queries

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

Response

Success

Any response with an HTTP status code within the 200 range means that the API was processed successfully.

Error

A response with an HTTP status code in the 400 or 500 range means that the request failed to be processed.

  • 400 range: error due to information provided with the request (ex: missing a required parameter).

  • 500 range: error due to a problem associated with the server.

When an error occurs, you can expect the following 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

TypeDescription

/errors/not-found

Fires when the requested resource cannot be found (for example, an item with a specific ID does not exist).

/errors/invalid-request

There is an error in the parameters provided with the request. (The 'errors' field in the response will contain parameter-specific errors).

/errors/invalid-team-mode

Fires when the requested query cannot be processed in the current team mode (for example, using the location lookup API in basic mode).

/errors/tokens/required

Fires when an API token is required to process the request but is not provided.

/errors/tokens/invalid

Fires if the API token provided is invalid (e.g., the API token has expired).

/errors/too-many-requests

A request has exceeded the rate limit.

/errors/unhandled

There was a server-side error that was not resolved.

/errors/core/usage-limit-exceeded

Cannot process request due to usage limit. Please upgrade your team's plan.

Reporting Errors and Development Requests

If the API is not working as expected or you experience other difficulties, please send us an email with your response to the email address listed below.

Additionally, if you have any development requests regarding the API, please send us an email at support+boxhero@bgpworks.com.

Frequently Asked Questions

If only a few items are retrieved when viewing a list:

For resources that may contain a large amount of data (e.g., item lists, transaction lists), the list view API limits the number of items returned in a single request through pagination. Our API uses a cursor-based pagination method. To retrieve a list in the next page, please refer to the details below:

To determine if pagination is required, check whether pagination-related parameters (such as has_more, cursor) are present in the request body of the endpoint in the API documentation.

  1. Check Pagination Information

  • List view API responses that require pagination include has_more and cursor fields. - The has_more field is a boolean that indicates whether additional data exists beyond the current page. - The cursor field provides the cursor value needed to request the next page.

  1. Retrieve the Next Page

  • If has_more is true, it means there is an additional page available. To request the next page, add cursor={received cursor value} to the parameters of your original request. This will return the subsequent data.

  1. Retrieve the Full List

  • To retrieve the complete list, repeat the process above until has_more is false.

API Reference

https://rest.boxhero-app.com/docs/api

Last updated