Set the API host, Project, and tenant, obtain an access token, and send requests to InStore POS APIs.
InStore POS customization is API-first. You send HTTP requests to InStore APIs to update configuration such as the POS theme. This page explains the shared setup for those requests.
For the theme endpoints, see Theme API reference. To learn what to put in a theme payload, see Customize styles and behavior.
Prerequisites
- A migrated InStore POS tenant that you can load in a browser to see your changes, and to which you have InStore Center administration rights.
- An HTTP client, such as
curl, that can send headers and JSON request bodies.
API base host and path elements
Every InStore POS API path follows the same structure:
{mistApiBase}/{projectKey}/instore-tenants/{tenantId}/...
| Element | Description | Example |
|---|---|---|
mistApiBase | Your regional InStore API host. | https://api.instore.your-region.commercetools.com |
projectKey | Your commercetools Project key. | your-project-key |
tenantId | Your InStore tenant ID, the unique identifier that connects to the integration server. | your-tenant-id |
For example, the theme resource is
{mistApiBase}/{projectKey}/instore-tenants/{tenantId}/theme.Authenticate
Every request needs an InStore access token. Read operations are open to any authenticated caller. To run write operations (
PUT, PATCH), you must be assigned as an administrator to the tenant that you want to change. After you switch to that tenant environment in the InStore Center, the token from that environment grants the permissions required for write operations.Assemble the path from your host, Project, and tenant; take the token from the InStore Center; send both on every call.
Get a token from the InStore Center (recommended)
- Log into the InStore Center and switch to the tenant environment that you want to change.
- Open the Environment tab.
- Open your browser's developer tools and select the Network panel.
- Click an active request and find the Request Headers section.
- Copy the value of the
tokenheader.
Send that value as a
token header on each request:token: <token>
Treat the token as a secret. Never put it in a URL, query string, browser bundle, or repository as it grants administrative access to your tenant.
Run requests
You can use any HTTP client. The examples show the request line and JSON body. Add your authentication header and, for writes,
Content-Type: application/json.Request conventions
- Requests and responses are JSON. Send
Content-Type: application/jsonon writes. PUTreplaces a resource;PATCHapplies a partial, deep-merged update. To compare their merge behavior for theme payloads, see Theme API reference.- The InStore POS stores only the active configuration. There's no server-side history. Save your request and response payloads so you can restore or compare them later.