Here you can find more information on how to use this API. See the additional pages for more deep dives on authentication, pagination, etc.
The API accepts HTTP requests and all endpoints follow the same format.
The HTTP method describes the action you want to take on a resource. We use standard HTTP methods for all our resources, e.g., GET, POST, UPDATE, and DELETE.
The usual requirements and behavior of each HTTP method are described below. To learn more about scopes, see Using the API: Authentication.
| HTTP Method | Required Scope | Description |
|---|---|---|
GET | *.read | Fetch a specific resource or collection of resources |
POST | *.write | Add a new resource to a collection or act on a specific resource |
UPDATE | *.write | Replace a specific resource with a new value |
DELETE | *.write | Remove a specific resource from a collection |
Each resource on the API has a specific path. The path will always include a major version path segment, e.g., /v1/bookings.
Refer to the API Reference to learn more about each specific resource and the paths for them. We follow a RESTful scheme meaning that path segments will have collections as path segments. If a specific resource is needed, an ID segment is suffixed to the collection.
v1/bookings: Collection of bookingsv1/bookings/{id}: Specific booking
Headers are used to provide additional information to your requests and our responses. Here is a list of the most common headers and their purpose.
This header contains your authentication identification. This must contain a valid bearer token for all requests that require scopes.
Authorization: Bearer <YOUR_ACCESS_TOKEN>Read more about this in Using the API: Authentication.
The Accept header is used to indicate what media type you can consume as a client. We only allow application/json in the API. We might expand the API to support multiple media types in the future, so you should always include this header in your requests to avoid interruption of service.
The Accept-Language header is used to indicate what language or locale you want the response in. The possible values are limited by the host's configured Storefront languages. See Localization to learn more.
All API requests should include a valid User-Agent header. This header identifies the application or user making requests to the API. This is not a means of authentication but instead a way to understand the origin of requests. This will allow us to reach out to you if we see odd or dangerous behavior and usage of the API and quickly let you understand the origin of those requests.
Here are some examples of how you could structure the header.
User-Agent: My-Company-Name
User-Agent: My-Company-Name/Marketing-Automation-ScriptMost endpoints in the API require authentication. Read more about the ways to authenticate in Using the API: Authentication
A lot of the endpoints accept parameters. These can either be required for the operation, e.g., resource IDs, or optional to modify the behavior, e.g., pagination.
For every request you will receive a response confirming that the request was handled. The response's status code indicates the overall result of the request. Consult the MDN Web Docs: HTTP response status codes for more details of each status code.
In general, you can interpret the codes as;
200 - 299: Indicates that the operation was a success, e.g.,200 OK300 - 399: Indicates that you have to continue the operation with another request, e.g., `301 Moved Permanently400 - 499: Indicates that something was incorrect in the request, e.g.,400 Bad Request500 - 599: Indicates that the API failed to complete your request, e.g.,500 Internal server error
All requests will return a JSON object in the response body. Refer to the specific endpoints in the API Reference to understand what properties to expect for each endpoint.
Some rules are cross-cutting however.
- Timestamps are always ISO 8601 formatted as
YYYY-MM-DDTHH:MM:SSZ - Failed requests (status
400 - 599) contain a standard error body with an error code and description. See Errors for details.