BoxHero API Reference

BoxHero API can be used for retrieving data from outside the app.
The writing operation will be released soon.

Endpoint

https://rest.boxhero-app.com

Request Example

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

In the [Settings] - [Integrations & API] menu, you can issue a new API token. All API requests should have 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, the error message is responded with the following additional information.
  • X-Ratelimit-Limit - Maximum queries per minute
  • X-Ratelimit-Remaining - Remaining queries
  • X-Ratelimit-Reset - Time to remaining query count reset (in seconds)

Response

Successes

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

Errors

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, 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

Type
Description
/errors/not-found
Fires when the requested resource cannot be found (for example, a product 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 handled.

Error Report and Development Requests

If the API is not working as expected or you experience inappropriate behavior, 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 to the said email address.

Resources

get
/v1/teams/linked

Retrieves the information of the team linked to the current API token.

Parameters
No parameters
Responses
200: OK
get
/v1/products

Retrieve the list of products.

Parameters
Query
product_ids
array
The list of identifiers for the products to be filtered.
location_ids
array
The ids of the locations to be used for quantity calculation.
cursor
integer
points to a specific spot in the items, allowing clients to request the next set of items.
limit
number
the maximum number of items to be returned in a single request
Responses
200: OK
get
/v1/products/{product_id}

Retrieve information about a specific product.

Parameters
Path
product_id*
integer
The id of the product to be queried
Query
location_ids
array
The ids of the locations to be used for quantity calculation.
Responses
200: OK
get
/v1/product-attrs

Retrieves the list of product attribute specifications used within the team.

Parameters
No parameters
Responses
200: OK
get
/v1/locations

Retrieve the list of locations.

Parameters
No parameters
Responses
200: OK
get
/v1/locations/{location_id}

Retrieve information about a specific location.

Parameters
Path
location_id*
integer
The id of the location to be queried
Responses
200: OK