Documentation

Use of the API reference

The API reference documentation provides detailed information about the API endpoints that is needed to interact with them.

Page structure

For each type of resource managed by the API, the reference documentation contains a dedicated page structured as explained below.

Representations

This section documents the JSON representation of the resource managed by the API. The resource is listed first, followed by the respective resource draft used when creating a new resource.
  • Resource: Each field of the resource is listed with its data type and a description of its purpose or role in a business or technical context. Fields that are indicated with an asterisk symbol are always present in a response, optional fields can be omitted. If applicable, minimum, and maximum values for a field are mentioned. For optional fields, a default value may be listed, which applies if the field is absent.
  • Resource draft: The resource draft contains all fields defined by the client. Required fields, indicated with an asterisk symbol, must be provided. Optional fields can be omitted to leave a field blank; if a default value is defined, it applies if the field is absent. If applicable, minimum, and maximum values for a field are mentioned.
  • Sub-resources and embedded objects: The representation section also documents sub-resources and other objects that can be embedded in the resource.
For built-in or common types, follow the link to see the documentation of the type. If a field's data type is a modeled object, you can expand the field to see the documentation of the embedded object inline.

Endpoints

After the representations section, which documents the data types exchanged with the API, the page lists all available endpoints. It starts with the Read methods (Get and Query), followed by the Write methods (Create, Update, and Delete ).
  • Get Resource: Retrieve a single resource by its unique identifier.
    • Get Resource by ID: Retrieve a resource by its unique platform-assigned identifier.
    • Get Resource by Key: Retrieve a resource by its user-defined unique key.
  • Query Resources: Retrieve a collection of resources that match a Query Predicate embedded in a PagedQueryResult.
  • Check if Resource exists: Similar to GET methods, but they do not return the resource. Instead, they return only a status code indicating whether a resource with a given ID or key exists.
    • Check if Resource exists by ID
    • Check if Resource exists by Key
    • Check if Resource exists by Query Predicate
  • Create Resource: Create a new resource by providing a resource draft.
  • Update Resource: Update an existing resource by providing its id or key, the current version, and a list of Update Actions.
  • Update Actions: This section lists the available Update Actions for the resource. For optional fields, you can use leave the field value empty to unset the field.
  • Delete Resource: Delete a resource by providing its id or key and the current version.
For resources that are Store-scoped, the aforementioned methods are also documented in their respective in Store variant.
Our Search APIs have one Read method Search Resource only that provides similar functionality as Get, Query, and Check.

Method descriptions

Each method section documents the technical details required to use the API endpoint:

  • The HTTP method and the endpoint's path are listed at the top, followed by a short description of the method's purpose and behavior in a business context. If applicable, the documentation mentions which Message the method generates and which specific errors can occur.
  • The OAuth scopes required to call the endpoint are listed.
  • Path parameters are described in a table, followed by query parameters if applicable. If a query parameter is required, it is marked with an asterisk symbol.
  • The request section describes the structure of the request body, usually linking to the representation of the expected object.
  • The response section lists the possible HTTP status codes returned by the endpoint in successful cases. Generic error responses are documented in a dedicated page. The type of the response body is also documented with a link to its representation (not for Check methods).

Make API calls

Turn the documentation into action and start making API calls. You can use the cURL examples provided on each endpoint in the documentation or your own tools to interact with the API.

cURL examples

Each endpoint contains an example request in cURL syntax that you can use to test the endpoint. The example shows the required parameters and the expected JSON response. Note that the cURL command contains placeholders for path variables like {projectKey} or {id} that you must replace with actual values. You must also replace {BEARER_TOKEN} with a valid token, which you can obtain via the OAuth token endpoint.

Postman examples

If you prefer to use Postman for testing the API, you can import a collection containing all endpoints of the Composable Commerce HTTP API, Import API, and Connect API. You can find the collection in our GitHub repository.

Bruno examples

We provide the same collections of API request examples for Bruno, available from this repository.

API Playgrounds

You can interactively explore and test API endpoints using the API Playgrounds embedded in the Merchant Center. The playground allows you to:
  • Select an endpoint and view its parameters and request body.
  • Enter your own values for parameters and payloads.
  • Execute requests directly against the API (no additional authorization via OAuth token needed).
  • View formatted responses and error messages.