Skip to main content
API docs by Redocly

Backend API (3.9)

Download OpenAPI specification:Download

This is the WIP documentation for the Highstreet API.

Image Resizing

Most image URLs returned by the Highstreet API can be requested in specific sizes by appending query string parameters. There are parameters for the width and height of the image. Aspect ratio's will not be distorted by resizing.

The names of the width and height parameters can differ per merchant. They are exposed in the Storefront Configuration under the image_url_params key.

In practice

In practice the apps do not respect the image_url_params but instead hard-code the names of the parameters inside the app.

Accounts

The account resource represents a customer's account.

Loyalty Programs

When a loyalty program is active the customer's e-mail address may already exist in the system. This can happen, for example, when the customer signed up for the loyalty program in a physical store. To protect the customer's privacy and their collected rewards creating an account will be refused for e-mails that already exist in the system.

After the refusal a verification e-mail will be sent to the e-mail address. The e-mail will contain a link to a web page where the customer can verify the e-mail address. Through an applink this webpage may be opened in the app. The Set password endpoint can be used to verify ownership of the account.

The app link looks as follows:

hs://account/password?token={verification-token}&handle={handle}

View account

Even though we require a first_name on registration, Demandware does not. The first_name may be empty for accounts registered on the merchant’s website.

Authorizations:
AccessToken
header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Authorization
required
string

Access token

Responses

Response samples

Content type
application/json
{
  • "custom": { },
  • "custom_identifiers": {
    },
  • "email": "bobby@tables.com",
  • "first_name": "Robert'); DROP",
  • "handle": "bobby@tables.com",
  • "id": "57982b5fecc2",
  • "last_name": "TABLE Students;--"
}

Create account

The email field is optional. When it is omitted the server assumes handle is an e-mail address and use it as such.

NOTE: When verification is required an e-mail is sent out to the customer.

Authorizations:
AccessToken
header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Authorization
string

Access token

Request Body schema: application/json
custom
object
Default: {}

Custom account attributes

email
string <email> non-empty

E-mail address

first_name
required
string non-empty

First name

handle
required
string non-empty

The login identifier, usually an e-mail address.

last_name
required
string non-empty

Last name

password
required
string >= 8 characters

Desired password

Responses

Request samples

Content type
application/json
{
  • "custom": { },
  • "email": "bobby@tables.com",
  • "first_name": "Robert'); DROP",
  • "handle": "bobby@tables.com",
  • "last_name": "TABLE Students;--",
  • "password": "pwpwpwpw"
}

Response samples

Content type
application/json
{
  • "custom": { },
  • "custom_identifiers": {
    },
  • "email": "bobby@tables.com",
  • "first_name": "Robert'); DROP",
  • "handle": "bobby@tables.com",
  • "id": "57982b5fecc2",
  • "last_name": "TABLE Students;--"
}

Update account

Authorizations:
AccessToken
header Parameters
Authorization
required
string

Access token

X-Selected-Storefront
required
string

Identifier of the selected storefront

Request Body schema: application/json
object (Address)

An address

object (Barcode)

Description of a barcode.

custom
object
Default: {}

Custom account attributes

object

A map of third party customer identifiers

email
required
string <email> non-empty

The customer's e-mail address.

first_name
string non-empty

Customer's first name

handle
required
string non-empty

The login identifier, usually an e-mail address.

id
string non-empty

Unique identifier for the account

last_name
required
string non-empty

Customer's last name

wishlist_id
string

The identifier of the customer's wishlist.

Responses

Request samples

Content type
application/json
{
  • "custom": { },
  • "custom_identifiers": {
    },
  • "email": "bobby@tables.com",
  • "first_name": "Robert'); DROP",
  • "handle": "bobby@tables.com",
  • "id": "57982b5fecc2",
  • "last_name": "TABLE Students;--"
}

Response samples

Content type
application/json
{
  • "custom": { },
  • "custom_identifiers": {
    },
  • "email": "bobby@tables.com",
  • "first_name": "Robert'); DROP",
  • "handle": "bobby@tables.com",
  • "id": "57982b5fecc2",
  • "last_name": "TABLE Students;--"
}

Set password

Sets the customer's password. This operation is not available for all merchants.

NOTE: When the token has expired a new e-mail will be sent to the customer.

Authorizations:
AccessToken
header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Request Body schema: application/json
handle
required
string <email> non-empty

The login identifier, usually an e-mail address.

password
required
string >= 8 characters

The customer's desired password

token
required
string non-empty

A password reset token

Responses

Request samples

Content type
application/json
{
  • "handle": "bobby@tables.com",
  • "password": "pwpwpwpw",
  • "token": "522e8e46-e2d4-466d-937b-bbb1cbef986f"
}

Response samples

Content type
application/json
{
  • "code": "invalid",
  • "field": "token",
  • "message": "reset token is invalid or expired"
}

Password Reset URL

Redirects to a password reset form hosted by the merchant.

Authorizations:
AccessToken
header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
{
  • "code": "convert_error",
  • "message": "can't convert Basket to cart"
}

Reset Password

This implements the forgot password flow. Not all merchants have a forgot password API so it is for that reason that this endpoint can either return a 204 and the e-commerce platform will send a password reset email to the specified handle or it will return a redirect to the merchant's password reset form on their website.

Authorizations:
AccessToken
header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Request Body schema: application/json
handle
required
string non-empty

The login identifier, usually an e-mail address.

Responses

Request samples

Content type
application/json
{
  • "handle": "bobby@tables.com"
}

Response samples

Content type
application/json
{
  • "code": "convert_error",
  • "message": "can't convert Basket to cart"
}

Augmentations

Address

Adds additional information to a partial address. The fields sent in the request will always be sent back.

Authorizations:
AccessToken
Request Body schema: application/json
required
object (PartialAddress)

An address

addition
string non-empty

Addition

city
string non-empty

The city name

company
string non-empty

The company name of the recipient

country_id
string (CountryCode) = 2 characters

A two character ISO 3166-1 Alpha-2 country code.

first_name
string non-empty

The recipient's first name

house_number
string non-empty

House number

last_name
string non-empty

The recipient's last name

postal_code
string non-empty

Postal or ZIP code

state
string non-empty

The state code.

street
string non-empty

Street name

telephone
string non-empty

The phone number of the recipient

Responses

Request samples

Content type
application/json
{
  • "address": {
    }
}

Response samples

Content type
application/json
{
  • "address": {
    }
}

Authentication

The Highstreet API uses OAuth 2.0 for authentication.

Get Url to Auth provider

Endpoint to fetch the authorization URL of an authentication provider such as Facebook. This URL should be opened in a web browser.

This endpoint is only available for customers with Single Sign-On.

Authorizations:
AccessToken
path Parameters
provider
required
string
Enum: "facebook" "google" "stijlpas" "twitter"

Identifier of the authentication provider.

NOTE: "stijlpas" is a Shoeby specific provider.

header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
{}

Cookies

Gets cookies using the customer's access token. The cookies can be used to continue the session on the web. This allows the user to view personal content that requires that would require a session.

Authorizations:
AccessToken
header Parameters
Authorization
required
string

Access token

X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
{
  • "cookies": [
    ]
}

Token endpoint

Requests an access token.

NOTE: The grant type authorization_code is only available for customers with single sign-on enabled.

NOTE: The grant type sign_in_with_apple is only available for customers with Sign in with Apple enabled.

Authorizations:
AccessToken
Request Body schema: application/json

An OAuth 2.0 Access Token Request encoded as form data

grant_type
required
string
code
required
string

The authorization code the app that obtained through the applink.

Responses

Request samples

Content type
application/json
Example
{
  • "grant_type": "authorization_code",
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "expires_in": 0,
  • "refresh_token": "string",
  • "token_type": "bearer"
}

Branded Media

Branded Media used by mobile apps while launching (splash screen) or when showing account view

Get Branded Media

Authorizations:
AccessToken
query Parameters
media_type
required
string
Enum: "splash_screen" "account_header"

Type of the Branded Media. Can only be splash_screen or account_header

device
required
string
Enum: "phone" "tablet"

The device for which the branded media should be returned

format
string
Enum: "blurred" "compressed"

The format of the branded media, if not set the default is "compressed"

header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
{
  • "url": "string"
}

Cachewarmer

Controls the cachewarmer by scheduling and cancelling jobs

Cancel Job

Cancel a job (either Refresh, Flush or Warm)

Authorizations:
AccessToken
header Parameters
X-Purge-Secret
required
string

A secret that provides access to the cachewarmer functionality.

Request Body schema: application/json
job_id
required
string

Responses

Request samples

Content type
application/json
{
  • "job_id": "abc-def-ghi"
}

Response samples

Content type
application/json
{
  • "status": "CANCELLED"
}

List Jobs

Get a list of jobs currently in the queue and their scheduled time from across all DCs

Authorizations:
AccessToken
header Parameters
X-Purge-Secret
required
string

A secret that provides access to the cachewarmer functionality.

Responses

Response samples

Content type
application/json
{
  • "jobs": [
    ]
}

Purge the cache

Purges the cache for the merchant

You may send through the X-Selected-Storefront parameter to flush only one storefront.

at_timestamp must be set in the JSON body, a value of 0 means flush immediatey.

Authorizations:
AccessToken
header Parameters
X-Selected-Storefront
string

Identifier of the selected storefront

X-Purge-Secret
required
string

A secret that provides access to the cachewarmer functionality.

Request Body schema: application/json
at_timestamp
required
integer

Responses

Request samples

Content type
application/json
{
  • "at_timestamp": 0
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Refresh the cache

Refresh (Flush and Warm) the cache for a merchant

You may send through the X-Selected-Storefront parameter to warm only one storefront.

at_timestamp must be set in the JSON body, a value of 0 means warm immediatey.

Authorizations:
AccessToken
header Parameters
X-Selected-Storefront
string

Identifier of the selected storefront

X-Purge-Secret
required
string

A secret that provides access to the cachewarmer functionality.

Request Body schema: application/json
at_timestamp
required
integer

Responses

Request samples

Content type
application/json
{
  • "at_timestamp": 0
}

Response samples

Content type
application/json
{
  • "job_ids": [
    ],
  • "status": "SCHEDULED"
}

Warm the cache

Warm the cache for the merchant

You may send through the X-Selected-Storefront parameter to warm only one storefront.

at_timestamp must be set in the JSON body, a value of 0 means warm immediatey.

Authorizations:
AccessToken
header Parameters
X-Selected-Storefront
string

Identifier of the selected storefront

X-Purge-Secret
required
string

A secret that provides access to the cachewarmer functionality.

Request Body schema: application/json
at_timestamp
required
integer

Responses

Request samples

Content type
application/json
{
  • "at_timestamp": 0
}

Response samples

Content type
application/json
{
  • "job_ids": [
    ],
  • "status": "SCHEDULED"
}

Carts

The cart resource represents a customer's cart.

Each cart contains coupon codes, items and vouchers.

Items

The items property contains a list of items the customer has added to their cart. Items consist of an identifier (id), a quantity (quantity), a product (product_id) and optionally a product configuration (configuration and bundle configuration).

Item identifiers are assigned to an item by the server. When the identifier of an item is not known yet (e.g. when adding a new product), the client must send a temporary identifier (temp_id). The server will return this temporary identifier along with the real identifier (id) to ensure client and server are working with the same item.

Once an identifier has been assigned the client should stop using the temporary identifier.

Coupon codes

Coupon codes are currently ignored entirely.

Vouchers

When the merchant has a loyalty program it is possible to redeem vouchers in the cart. To redeem a voucher it can be added to the vouchers list by its ID.

Also see the GET /loyalty/vouchers call.

State and data races

It could be the case that two clients are managing the same cart at the same time, causing the clients to fall out of sync.

Clients can notice this situation using the If-Match and ETag headers. Using this mechanism an error will be returned in case the client and server state are out of sync. The request header If-Match is optional: when it's not present the server ensures the state of the client will be that as specified by the client, possibly overriding the state set previously by another client.

In case of a conflict the client is responsible for resolving it. When a conflict occurs, the server will respond with a 412 Precondition failed and provide the current state of the cart as known by the server.

Errors

Each cart contains a list of errors (_errors). Errors provide feedback on the client's request and inform the client of failed actions performed by the server.

NOTE: The list of errors ephemeral (i.e. not persisted). In practice this means that the errors will be available in POST and PUT responses only.

Each error has an error type (type) and an error code (code). The following error types are available: refer to:

  • cart_error refers to the cart as a whole. Example: clients tries to add too many items to the cart.
  • cart_item_error refers to a specific items. The server will return an id or temp_id to identify the item exactly. Example: client tries to add a product that does not exist.
  • coupon_code_error refers to a coupon code. Example: client tries to add a coupon code that is invalid in combination with another coupon code.
  • voucher_error refers to a voucher. Example: client tries to redeem a non-existing voucher.

The following error codes are available:

  • cart_full: Client attempted to add more than the maximum number of items.
  • product_unavailable: Client attempted to add a product that is unavailable.
  • quantity_changed: Desired quantity was not available and was lowered by the server.
  • unknown_item: Client referred to an item with an identifier (id) that does not exist (anymore).
  • invalid_coupon: Client attempted to add an invalid coupon code.
  • expired_coupon: Client attempted to add an expired coupon code.
  • too_many_coupons: Client reached maximum amount of coupon codes.

TODO: voucher error codes.

Create a cart

Create a cart

Authorizations:
AccessToken
header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Authorization
required
string

Access token

Request Body schema: application/json
required
Array of objects (CartCouponCode)
required
Array of objects (CartItem)
required
Array of objects (CartVoucher)

Responses

Request samples

Content type
application/json
{
  • "coupon_codes": [ ],
  • "items": [ ],
  • "vouchers": [ ]
}

Response samples

Content type
application/json
{
  • "_errors": [ ],
  • "_messages": [ ],
  • "id": "59166f6b52f6",
  • "items": [ ],
  • "tax_included": true,
  • "totals": {
    },
  • "vouchers": [ ]
}

View a cart

View a cart

Authorizations:
AccessToken
path Parameters
cart_id
required
string

Unique identifier of the cart.

header Parameters
Authorization
required
string

Access token

X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
{
  • "_errors": [ ],
  • "_messages": [ ],
  • "coupon_codes": [ ],
  • "id": "59166f6b52f6",
  • "items": [
    ],
  • "loyalty_totals": {
    },
  • "tax_included": true,
  • "totals": {
    },
  • "vouchers": [
    ]
}

Update a cart

Update a cart

Authorizations:
AccessToken
path Parameters
cart_id
required
string

Unique identifier of the cart.

header Parameters
Authorization
required
string

Access token

X-Selected-Storefront
required
string

Identifier of the selected storefront

If-Match
string

The If-Match header. TODO Link to spec.

Request Body schema: application/json
required
Array of objects (CartCouponCode)
required
Array of objects (CartItem)
required
Array of objects (CartVoucher)

Responses

Request samples

Content type
application/json
{
  • "coupon_codes": [ ],
  • "items": [
    ],
  • "vouchers": [
    ]
}

Response samples

Content type
application/json
{
  • "_errors": [
    ],
  • "_messages": [ ],
  • "coupon_codes": [ ],
  • "id": "59166f6b52f6",
  • "items": [
    ],
  • "tax_included": true,
  • "totals": {
    },
  • "vouchers": [
    ]
}

Transfer a cart

Transfer the contents of a cart from a session belonging to a guest to a session belonging to a registered user. Transferring in the opposite direction (from registered to guest session) is not supported.

Authorizations:
AccessToken
path Parameters
cart_id
required
string

Unique identifier of the cart.

header Parameters
Authorization
required
string

Access token

X-Selected-Storefront
required
string

Identifier of the selected storefront

Request Body schema: application/json
access_token
required
string non-empty

Access token of the session this cart should be transferred to.

Responses

Request samples

Content type
application/json
{
  • "access_token": "string"
}

Response samples

Content type
application/json
{
  • "_errors": [
    ],
  • "_messages": [ ],
  • "coupon_codes": [
    ],
  • "id": "a1b2c3d4e5f6",
  • "items": [
    ],
  • "loyalty_totals": {
    },
  • "promotional_items": [
    ],
  • "tax_included": true,
  • "totals": {
    },
  • "vouchers": [
    ]
}

Categories

The category tree is used as the bases of the navigation within the app.

The root category can also be referred to as the category tree. With each category having a number of children.

Root

Authorizations:
AccessToken
header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
{
  • "children": [
    ],
  • "id": "string",
  • "image": "string",
  • "include_in_menu": true,
  • "position": 0,
  • "product_count": 0,
  • "recommendations": {
    },
  • "title": "string"
}

Tree

Returns the complete category tree. The response is identical to the single category call invoked with the :id of the root category.

Authorizations:
AccessToken
header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
{
  • "children": [
    ],
  • "id": "root",
  • "include_in_menu": true,
  • "position": 0,
  • "product_count": 8,
  • "title": "Women"
}

ID

Returns and Category and it's children

Authorizations:
AccessToken
path Parameters
id
required
string

Unique identifier of the resource.

header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
{
  • "children": [
    ],
  • "id": "string",
  • "image": "string",
  • "include_in_menu": true,
  • "position": 0,
  • "product_count": 0,
  • "recommendations": {
    },
  • "title": "string"
}

Checkout

The checkout resource exposes endpoints to manage a checkout session.

Addresses

The shipping address for a checkout session can be set to the billing address by setting a billing_address and setting the shipping_address to null.

{
  "addresses": {
    "billing_address": { ... },
    "shipping_address": null
  }
}

NOTE: In response bodies the shipping address will be null both when it's missing and when it's set to the billing address. The list of _errors can be used to tell the difference (i.e. there will be an error with code missing and field shipping_address).

Data dependencies

Updating one piece of information may invalidate a previously valid piece of information. The list of available payment and shipping methods tends to depend on the billing or shipping address for example. The list of _errors should be checked every time the checkout session has been updated.

Notes

  • Invalid data (such as an invalid address) is persisted on some e-commerce platforms and discarded on others.
  • None of the checkout endpoints currently check for the If-Match request header, even though an Etag response header is returned.

Order tracking

Order Tracking Sequence Diagram

Start Checkout

Starts a checkout session.

Details may be pre-filled by the server or remembered from a previous session.

Authorizations:
AccessToken
header Parameters
Authorization
required
string

Access token

X-Selected-Storefront
required
string

Identifier of the selected storefront

Request Body schema: application/json
cart_etag
required
string non-empty

The last seen ETag value of the cart

cart_id
required
string non-empty

The identifier of the cart to start a checkout session for.

flow
string
Value: "applepay"

The checkout flow that will be used

Responses

Request samples

Content type
application/json
{
  • "cart_etag": "a836e7d92648956ga39895fd38e93f785e",
  • "cart_id": "a1b2c3d4e5f6"
}

Response samples

Content type
application/json
{
  • "_errors": [
    ],
  • "addresses": {
    },
  • "coupon_codes": [ ],
  • "email": "test@highstreetapp.com",
  • "id": "a1b2c3d4e5f6",
  • "payment_method": null,
  • "shipping_method": null,
  • "tax_included": true,
  • "totals": {
    }
}

View Checkout

Views the current state of the checkout.

Authorizations:
AccessToken
path Parameters
checkout_id
required
string

Checkout ID.

header Parameters
Authorization
required
string

Access token

X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
{
  • "_errors": [
    ],
  • "addresses": {
    },
  • "coupons": [
    ],
  • "custom": { },
  • "email": "user@example.com",
  • "id": "string",
  • "payment_method": {
    },
  • "shipping_method": {
    },
  • "tax_included": true,
  • "totals": {
    }
}

Update Checkout

Updates the checkout session. Each top-level property can be updated individually.

NOTE: Some data implicitly depend on one another. The validity of the selected shipping or payment methods, for example, may depend on the customer's address. In other words: the absense of an error does not mean the error has been permanently.

Authorizations:
AccessToken
path Parameters
checkout_id
required
string

Checkout ID.

header Parameters
Authorization
required
string

Access token

X-Selected-Storefront
required
string

Identifier of the selected storefront

Request Body schema: application/json
non-empty
object (CheckoutAddresses)

The customer's billing and shipping addresses.

NOTE: If the shipping_address is null and the list of _errors does not contain an error referencing the shipping_address field, the billing address will be used as the shipping address.

Array of objects (CouponList)

List of coupons used in the checkout session

custom
object
email
string <email> (Email) non-empty

E-mail address of the customer

object or null (PaymentMethod)

The chosen payment method

object or null (ShippingMethod)

The chosen payment method

Responses

Request samples

Content type
application/json
{
  • "addresses": {
    },
  • "coupon_codes": [
    ],
  • "custom": { },
  • "email": "user@example.com",
  • "payment_method": {
    },
  • "shipping_method": {
    }
}

Response samples

Content type
application/json
{
  • "_errors": [
    ],
  • "addresses": {
    },
  • "coupons": [
    ],
  • "custom": { },
  • "email": "user@example.com",
  • "id": "string",
  • "payment_method": {
    },
  • "shipping_method": {
    },
  • "tax_included": true,
  • "totals": {
    }
}

Finalize Checkout

Finalizes a checkout session. After finalization clients are expected to interact with a PSP (Payment Processor).

Starting the interaction with the PSP is done through a HTTP GET request.

The Server expects a json hash containing tracking configuration from the app. Currently tracking with facebook and google is supported. A request to track both of these would look like the following:

{
  "analytics": [
    {
      "ga_ul": "en-nl",
      "ga_sr": "750x1334",
      "ga_av": "2.31.10",
      "ga_cid": "8407a770-ad5a-480a-a723-f00adc399789",
      "ga_an": "MarliesDekkers",
      "ga_tid": "UA-49257414-1",
      "hs_type": "GA"
    },
    {
      "fb_app_id": "UA-49257414-1",
      "fb_ad_id": "1111-1111-1111-1111"
      "hs_type": "facebook"
    }
  ]
}
Authorizations:
AccessToken
path Parameters
checkout_id
required
string

Checkout ID.

header Parameters
Authorization
required
string

Access token

X-Selected-Storefront
required
string

Identifier of the selected storefront

Request Body schema: application/json
required
Array of objects
Array
hs_type
required
string
Enum: "GA" "facebook"

The analytics tracker type.

Responses

Request samples

Content type
application/json
{
  • "analytics": [
    ]
}

Response samples

Content type
application/json
{}

Available Payment Methods

Gets the list of available payment methods for the given checkout session.

Authorizations:
AccessToken
path Parameters
checkout_id
required
string

Checkout ID.

header Parameters
Authorization
required
string

Access token

X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
{}

Available Shipping Methods

Gets the list of available shipping methods for the given checkout session.

Pick up in store

The special shipping method code hs.pick-up-in-store indicates that customers can pick up the products in a brick and mortar store, rather than have it shipped to an address.

The pick up in store shipping method does not have any sub options. Instead, the GET /stores endpoint can be used to fetch a list of stores close to a location. The list of stores can be treated as a list of sub options. The id of a Store can be used as a sub option code.

Example:

{
  "shipping_method": {
    "code": "hs.pick-up-in-store",
    "options": [
      { "code": "02-ANTWERPEN" }
    ]
  }
}
Authorizations:
AccessToken
path Parameters
checkout_id
required
string

Checkout ID.

header Parameters
Authorization
required
string

Access token

X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
{
  • "shipping_methods": [
    ]
}

Checkout configuration

Gets configuration options for the (native) checkout.

Authorizations:
AccessToken
header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
{}

Apple Pay

Authorizations:
AccessToken
path Parameters
order_id
required
string

Order ID.

header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Request Body schema: application/json

ApplePay token

object
token
string

The apple pay token

Responses

Request samples

Content type
application/json
{
  • "payload": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success"
}

Webcheckout URL

Get the URL of the web checkout.

Authorizations:
AccessToken
header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
{}

Content Pages

Content pages are web pages hosted by the merchant.

Get a list of content pages

Returns a list of content pages. As of API version 3.9 content pages can also be personal. This is indicated by the value of personal.

Authorizations:
AccessToken
header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
Example
{}

Filter parameters

The following deeplinks accept filters:

  • hs://categories/{category-id}: links to the products within a category.
  • hs://categories/{category-id}/search/{query}: links to a product search within a category.
  • hs://search/{query}: links to a global product search query.

A filter consists of at least 2 query string parameters. The first parameter describes the attribute being filtered on:

filter[$i][attribute]=$attribute

The additional parameters describe the acceptable value or values. At least one acceptable value is required:

filter[$i][in][$j]=$value

Filters are numbered, starting from 0 ($i). Acceptable values ($value) are also numbered, starting from 0 ($j).

Example: only return green or blue products.

hs://products/{search}?filter[0][attribute]=color&filter[0][in][0]=green&filter[0][in][1]=blue

Example: only return red products made from cotton.

hs://categories/{category-id}/search/{search}?filter[0][attribute]=color&filter[0][in][0]=red&filter[1][attribute]=material&filter[1][in][0]=cotton

NOTE: The schema hs will be replaced by the merchant specific schema.

Jobs

Endpoints to schedule jobs.

These endpoints are available on the following domain:

MERCHANTID-MERCHANT_ENV.api.highstreetapp.com

MERCHANTID = the configured merchant id in the app. MERCHANT_ENV = the applicable environment of the Merchant's backend. eg staging. Note that when the -MERCHANT_ENV is omitted then the production environment is assumed. Also note the - that should be present between MERCHANTID and MERCHANT_ENV. When MERCHANT_ENV is omitted then the - should also be omitted.

Reindex categories

Schedules a job that refreshes the order of products within categories.

Note that this job only refreshes the order of products. The product data itself (such as pricing) is not refreshed.

Authorizations:
basic_auth
header Parameters
Authorization
required
string

Authorization header. This endpoint expects Basic Authentication

Request Body schema: application/json

Request body to schedule a job to reindex categories

countries
required
Array of strings (CountryCode) [ items = 2 characters ]

List of country codes

Responses

Request samples

Content type
application/json
{
  • "countries": [
    ]
}

Response samples

Content type
application/json
{
  • "job_id": "d02b7e035bd31021168e7557"
}

Stock Notifications

Schedules a job to send back in stock notifications to customers that registered to receive one.

This endpoint can be called any time the stock of a product changes from 0 (out of stock) to greater than 0 (back in stock).

This endpoint should only be called with product IDs of fully configured products. The following products types are supported:

Platform Product types
Magento 1 & Magento 2 simple
Salesforce Commerce Cloud item and variant
Self-implemented fixed and variant

Partially configured products are not supported.

After receiving a back in stock notification the user will not receive a second notification for the same product (unless they explicitly register again).

Authorizations:
basic_auth
header Parameters
Authorization
required
string

Authorization header. This endpoint expects Basic Authentication

Request Body schema: application/json

Request body for scheduling back in stock notifications

countries
required
Array of strings[ items = 2 characters ]

One or more countries that the product has come back in stock in. If a product has come back in stock in The Netherlands (NL) but not in the United States (US) then US should not be included in the list.

delivery_time
string

The date and time the notification should be delivered to the customer in ISO 8601 standard format. Notifications will be sent as soon as possible by default.

max_recipients
number >= 1

The maximum number of customers that will receive a notification. If the number of customers that want to receive a notification is higher than the maximum number of recipients the users that registered first are prioritised. Notifications are sent to all interested customers by default.

required
Array of objects (Translation)

Translations for the body of the notification. All languages for the given countries should be included.

product_id
required
string

The ID of the product that has come back in stock.

required
Array of objects (Translation)

Translations for the title of the notification. All languages for the given countries should be included.

Responses

Request samples

Content type
application/json
{
  • "countries": [
    ],
  • "delivery_time": "2019-11-04T13:25:34+00:00",
  • "max_receivers": 24,
  • "message_translations": [
    ],
  • "product_id": "1234_AB-S",
  • "title_translations": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "03b6c7d6bfa2"
}

Lookbooks

Lookbooks are used by merchants to showcase their products

Get Lookbooks

Authorizations:
AccessToken
header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Looks

Authorizations:
AccessToken
path Parameters
lookbook_id
required
string

Lookbook ID.

header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Loyalty Membership

When signing up for a loyalty membership, the loyalty program may require the customer to confirm their membership through, for example, an e-mail. The API will indicate this on all loyalty related enpoints.

Some loyalty programs don't require the customer to opt-in to a loyalty membership, but create a membership for you when an E-commerce account is created.

Changelog

  • 19-06-2018
    • Introduce membership_level
  • Replace membership_barcode with card_barcode.
  • Introduce confirmed flag.
  • Introduce points_balance (optional).
  • Introduce collection_counters object (optional).

View membership

Authorizations:
AccessToken
header Parameters
Authorization
required
string

Access token

X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
{
  • "card_barcode": {
    },
  • "collection_counters": {
    },
  • "confirmed": true,
  • "membership_level": {
    },
  • "points_balance": 350
}

Create membership

Loyalty programs may require additional information such as the gender or date of birth of a customer in order to better target customers.

When required, this data should be set on the E-commerce account resource before creating a membership.

Authorizations:
AccessToken
header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Authorization
required
string

Access token

Responses

Response samples

Content type
application/json
{
  • "card_barcode": {
    },
  • "collection_counters": {
    },
  • "confirmed": true,
  • "membership_level": {
    },
  • "points_balance": 350
}

Remove memberbership

Removes the customer's membership when the customer no longer wishes to participate in the loyalty program.

Loyalty programs may require the customer to confirm through, for example, e-mail.

Authorizations:
AccessToken
header Parameters
Authorization
required
string

Access token

X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
{
  • "verification_required": false
}

Voucher

The Voucher resource exposes loyalty vouchers and campaigns.

View vouchers

Lists the customer's collected vouchers and the currently running campaigns.

Authorizations:
AccessToken
query Parameters
cart_id
string

A cart ID. When given, only the vouchers that can be used in a cart will be returned.

header Parameters
Authorization
required
string

Access token

X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
{
  • "collectable": [
    ],
  • "collected": [
    ]
}

LoyaltyOrders

The Order resource exposes a customer's order history.

Changelog

  • Add a currency_code to display the correct currency symbol.
  • Add a prices_include_tax to pick the correct totals.
  • Replace date with creation_date (note that creation_date is optional)
  • Replace status object with a string (note that status is optional)
  • Replace price of an order items with full_price
  • Remove bundle_configuration for order items
  • Replace shipping_address with shipments
  • Replace shipping_method with shipments
  • Replace payment_method with payments

NOTE: There can be multiple shipments and multiple payments.

History

Lists all orders made by the customer

Authorizations:
AccessToken
header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Authorization
required
string

Access token

Responses

Response samples

Content type
application/json
{
  • "orders": [
    ]
}

Messages

Messages are used by merchants to comunicate with their uses on specific parts of the application.

Get Messages

Authorizations:
AccessToken
query Parameters
placement
string

Placement where the message will be shown.

header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Authorization
required
string

Access token

Responses

Response samples

Content type
application/json
{
  • "messages": [
    ]
}

Products

Notes

  • The GET /categories/:id/products endpoint has been deprecated in favour of a query string on product search.

Featured

Fetches a list of (personalized) recommended products.

Note that not all recommenders support restricting results to a single category.

Authorizations:
AccessToken
path Parameters
recommender_id
required
string

Identifier of the recommender to use

query Parameters
visitor_id
required
string

Unique visitor ID.

cat
string

The category to restrict results to.

header Parameters
Authorization
string

Access token

X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Search

Searching and filtering products.

Filters

Products can be filtered by attribute. Three filter types are currently supported:

  • The set membership filter (in) only yields products where the value of a given attribute is present in a set of given values. Example: only products in the color red or orange.

  • The range filter (range) only yields products where the value of a particular attribute falls between a minimum and maximum. Example: only products in the price range 50 to 100 euros.

  • The equality filter (eq) only yields products with a particular value for a particular attribute. Example: only products with from the brand "H&M".

The available list of attributes, the filter type and their possible values can be found under the filters property.

Notes

  • product_count will not be guaranteed to be there any more.
Authorizations:
AccessToken
query Parameters
q
string <= 50 characters

A search query

cat
string

The category to restrict results to.

cursor
number
Default: 0

The cursor position

size
number
Default: 20

Maximum number of results

sort
string

The sort option. Value will be an id of a sorting option returned in the product search result

{attr}:in
string

Set membership filter. Replace {attr} with an attribute code. Values are separated by a pipe (|).

Example: c_size:in=S|M.

{attr}:range
string <^[0-9]+,[0-9]+$>

Range filter. Replace {attr} with an attribute code. The minimum and maximum are separated by a comma (,).

Example: price:range=50,100.

{attr}:eq
string

Equality filter. Replace {attr} with an attribute code.

Example: brand:eq=637.

header Parameters
Authorization
string

Access token

X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
{
  • "filters": [
    ],
  • "product_count": 46,
  • "results": [
    ],
  • "sorting_options": [
    ]
}

Details

Products in detail.

Authorizations:
AccessToken
path Parameters
product_id
required
string

A product ID

header Parameters
Authorization
string

Access token

X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
{
  • "analytics_attributes": {
    },
  • "available": true,
  • "caption": "Summer Collection",
  • "custom_attributes": [
    ],
  • "description": "<em>You</em> can read me if you want to.",
  • "id": "1234",
  • "labels": [
    ],
  • "media": [],
  • "name": "Sweater",
  • "pricing": {
    },
  • "size_guide_url": "https://merchant.com/size-guide.html",
  • "sku": "CS-4632-0001",
  • "specifications": "<ul><li>Crew Neck</li><li>100% Cotton</li></ul>",
  • "stock_notifications": false,
  • "store_availability": false,
  • "web_url": "https://merchant.com/products/1234",
  • "configuration": {
    },
  • "prefill_bucket": "6a473d3e",
  • "promotions": [
    ],
  • "variation_attribute_values": {
    }
}

Availability

Fetches up-to-date availability and pricing for a product.

Authorizations:
AccessToken
path Parameters
product_id
required
string

A product ID

header Parameters
Authorization
string

Access token

X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
{
  • "availabilities": [
    ]
}

Related

Fetch products related to a particular product. Multiple types of relations, such as recommendations, cross-sell, up-sell are supported.

Authorizations:
AccessToken
path Parameters
product_id
required
string

A product ID

header Parameters
Authorization
string

Access token

X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
{
  • "related_product_groups": [
    ]
}

Store Availability

Fetches the availability of a product in nearby stores. Only Product IDs of fully configured products (i.e. fixed or variant products ) are supported.

This endpoint requires a location as either a (partial) address (address) or as coordinates (latitude + longitude).

Authorizations:
AccessToken
path Parameters
product_id
required
string

A product ID

query Parameters
address
string

A single line address query

max_distance
number

Require stores to be at most maximum_distance kilometres from the reference location. The default value is 100.

longitude
number

The longitude in which to search (overrides address)

latitude
number

The latitude in which to search (overrides address)

header Parameters
Authorization
string

Access token

X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
{
  • "reference_location": {
    },
  • "results": [
    ]
}

Push Notifications

Registers a device to receive push Notifications. A endpoint to record push notification open events is also provided.

Currently Highstreet has an integration with Onesignal and for some clients Marketing Cloud. The registration endpoint will register the device with Onesignal and if configured Marketing Cloud.

Register a device to recieve push notifications

Registers a device with a push provider.

Authorizations:
AccessToken
Request Body schema: application/json
appIdentifier
string

The app identifer eg com.denhamjeans.highstreet.app

appName
string

The name of the app eg Denham

appVersion
string

The version of the app

appVersionString
string

The semantic version of the app

backInStockNotificationsEnabled
boolean

DEPRECATED: Can the device receive back in stock notifications? This flag is unused.

debug
boolean

Marks the device to accept test notifications

deviceModel
string

The brand of the device. eg iPhone

deviceToken
string

The unique identifier of the app

deviceType
string

The operating system of the device eg ios

email
string

The email adress of the user if they are logged in

language
string

The 2 digit language code of the device

locale
string

The 4 digit local code of the device. Eg country_LANGUAGE

notificationsEnabled
boolean

Can the device recieve notifications or not

selectedStorefront
string

The selected highstreet storefront

supportsSilentNotifications
boolean
timeZone
string

The time zone of the device

Responses

Request samples

Content type
application/json
{
  • "appIdentifier": "com.denhamjeans.highstreet.app",
  • "appName": "Denham",
  • "appVersion": "29",
  • "appVersionString": "2.50.0",
  • "backInStockNotificationsEnabled": false,
  • "debug": false,
  • "deviceModel": "iPhone",
  • "deviceToken": "29d3b2b3a603971d732df3d479e274f6497b35293dc71a3e0d3fd56da2c1f2d8",
  • "deviceType": "ios",
  • "email": "r2d2@highstreetmobile.com",
  • "language": "en",
  • "locale": "en_NL",
  • "notificationsEnabled": true,
  • "selectedStorefront": "en-NL",
  • "supportsSilentNotifications": false,
  • "timeZone": "Europe/Amsterdam"
}

Response samples

Content type
application/json
{
  • "id": "HS_eyJvbmVzaWduYWwiOiI5=="
}

Update push notification settings

Updates the device info/settings with a push provider. For example if a user no longer wishes to recieve push notifications.

Authorizations:
AccessToken
path Parameters
installation_id
required
string
Request Body schema: application/json
appIdentifier
string

The app identifer eg com.denhamjeans.highstreet.app

appName
string

The name of the app eg Denham

appVersion
string

The version of the app

appVersionString
string

The semantic version of the app

backInStockNotificationsEnabled
boolean

DEPRECATED: Can the device receive back in stock notifications? This flag is unused.

debug
boolean

Marks the device to accept test notifications

deviceModel
string

The brand of the device. eg iPhone

deviceToken
string

The unique identifier of the app

deviceType
string

The operating system of the device eg ios

email
string

The email adress of the user if they are logged in

language
string

The 2 digit language code of the device

locale
string

The 4 digit local code of the device. Eg country_LANGUAGE

notificationsEnabled
boolean

Can the device recieve notifications or not

selectedStorefront
string

The selected highstreet storefront

supportsSilentNotifications
boolean
timeZone
string

The time zone of the device

Responses

Request samples

Content type
application/json
{
  • "appIdentifier": "com.denhamjeans.highstreet.app",
  • "appName": "Denham",
  • "appVersion": "29",
  • "appVersionString": "2.50.0",
  • "backInStockNotificationsEnabled": false,
  • "debug": false,
  • "deviceModel": "iPhone",
  • "deviceToken": "29d3b2b3a603971d732df3d479e274f6497b35293dc71a3e0d3fd56da2c1f2d8",
  • "deviceType": "ios",
  • "email": "r2d2@highstreetmobile.com",
  • "language": "en",
  • "locale": "en_NL",
  • "notificationsEnabled": true,
  • "selectedStorefront": "en-NL",
  • "supportsSilentNotifications": false,
  • "timeZone": "Europe/Amsterdam"
}

Response samples

Content type
application/json
{
  • "id": "HS_eyJvbmVzaWduYWwiOiI5=="
}

Track a notification open event

This endpoint consumes data related to a push notifcation and sends an event to the relevant push provider to track an open event.

Authorizations:
AccessToken
Request Body schema: application/json
installation_id
string

The installation id of the device

object

Responses

Request samples

Content type
application/json
{
  • "installation_id": "89yfo947fhyo8w7hgo9we97hfo8er7hvedbweb==",
  • "notification": {
    }
}

Response samples

Content type
application/json
{
  • "code": "convert_error",
  • "message": "can't convert Basket to cart"
}

Stock Subscriptions

Create subscription

Registers a customer for receiving a push notification when a product comes back in stock.

Authorizations:
AccessToken
header Parameters
Authorization
required
string

Access token

X-Selected-Storefront
required
string

Identifier of the selected storefront

Request Body schema: application/json
email
string <email>

Customer's email address

installation_id
required
string

Customer's push notification installation ID.

product_id
required
string

A product ID. Only fully configured products are supported.

Responses

Request samples

Content type
application/json
{
  • "email": "test@highstreetmobile.com",
  • "installation_id": "HS_eyJtYXJrZXRpbmdfY2xvdWQiOiI5YzdlMWI3ZS02Yzc1LTRjODMtYTZkOS0wYWYzMjlhYTBhNWEiLCJvbmVzaWduYWwiOiJjYzM5YWZkOS0zMzM5LTRiOWYtYTJiNS02ZjUyOTQ5Mzk3MmQifQ==",
  • "product_id": "1234_AB-S"
}

Response samples

Content type
application/json
{
  • "id": "Y2MzOWFmZDktMzMzOS00YjlmLWEyYjUtNmY1Mjk0OTM5NzJkLjEyMzRfQUItUw=="
}

Storefronts

Exposes configuration settings.

Select storefront

Selects the best matching storefront based on language and locale. The locale is given more weight in the selection than the language.

Authorizations:
AccessToken
query Parameters
lang
required
string

Language

locale
required
string

Locale

Responses

Response samples

Content type
application/json
{
  • "fallback": "string",
  • "storefronts": [
    ]
}

List of Storefronts

Gets a list of all available storefronts from a Merchant

Authorizations:
AccessToken

Responses

Response samples

Content type
application/json
{
  • "fallback": "string",
  • "storefronts": [
    ]
}

View storefront

Gets the configuration for a storefront by ID. The country parameter is required as Storefront settings can vary depending on the country. Specifically in the case of Apple Pay.

Authorizations:
AccessToken
path Parameters
storefront_id
required
string

Storefront identifier

query Parameters
country
required
string

The country identifer

Responses

Response samples

Content type
application/json
{
  • "configuration": {
    },
  • "identifier": "nl-NL"
}

Countries

Gets the list of countries a storefront covers. For each country some address details are provided to help build address forms.

Available since API version 3.7.

Authorizations:
AccessToken
path Parameters
storefront_id
required
string

Storefront identifier

Responses

Response samples

Content type
application/json
{
  • "countries": [
    ]
}

Stores

Exposes endpoints to find stores in the real world.

Find nearby stores

Find stores close to a postal code. It's possible to fetch a list of stores filtered by their purpose. Currently the only purpose is "pick up in store".

Pagination

Demandware does not support filtering stores by attribute. To support fetching a filtered list of stores the plan is as follows:

  • add a start query string parameter
  • add a length / size query string parameter
  • add query string parameters for the latitude and longitude

Response bodies will include a key next in the response holding a URL that clients can use to fetch the next batch of length stores with the middleware making sure unwanted stores are filtered out.

Most likely we'll also want to avoid fetching the latitude and longitude on the next page. The URL in next can add the longitude and latitude to the query string to avoid that.

Pagination will not be part of the initial implementation. The above are notes on how this will be implemented.

Authorizations:
AccessToken
query Parameters
address
string

A single line address query

max_distance
number

Require stores to be at most maximum_distance kilometres from the reference location. The default value is 100.

longitude
number

The longitude in which to search (overrides address)

latitude
number

The latitude in which to search (overrides address)

tags
string

A comma separated list of tags on which to search a store by

store_type
string
Value: "pick_up_in_store"

Limit the stores to a particular type. Omit the parameter to fetch all types of stores.

postal_code
string

Postal code. DEPRECATED use address.

header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
{
  • "reference_location": {
    },
  • "stores": [
    ]
}

Find Store by id

Finds a store by it's id.

Authorizations:
AccessToken
path Parameters
id
required
string

Unique identifier of the resource.

header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Responses

Response samples

Content type
application/json
{
  • "address": {
    },
  • "coordinates": {
    },
  • "id": "ff5e5f52-d62e-e511-80c8-02bfac10024b",
  • "name": "Scotch & Soda"
}

Visitor

Information regarding a visitor. These endpoints are used in the personal recommendaions flow.

Create Visitor ID

A personal recommendation engine will require a unique identifier for a visitor. This identifier will be used in the tracking of events as well as of course for fetching product recommendations. The origin of the unique identifier will be the middleware as it will depend on the recommendation platform as to how this identifier is fetched / generated.

The app should get a visitor identifier from the following endpoint. This identifier should then be stored by the app.

The endpoint expects the user's access token to be present in the Authorization header.

In the case of a login event the current visitor id should be passed in the request body. Depending on the recommendation engine this could be used to sync accounts.

Authorizations:
AccessToken
header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Authorization
string

Access token

Request Body schema: application/json
visitor_id
string non-empty

Unique identifier for the visitor

Responses

Request samples

Content type
application/json
{
  • "visitor_id": "string"
}

Response samples

Content type
application/json
{
  • "visitor_id": "1234-5678-9012-1234"
}

Wall

The home wall is a collection of rows that are displayed below each other. A row is a grid of blocks. The grid is 12 blocks wide and a variable number of blocks tall. The grid is used to place "tiles" on.

A tile is a rectangle that displays content and can optionally link to another screen in the app (such as a category).

The position and size of a tile are expressed as numbers: [x, y, w, h].

  • x: the top left corner's X position on the grid
  • y: the top left corner's Y position on the grid
  • w: the width of the tile in blocks
  • h: the height of the tile in blocks

Home wall diagram

Content

There are different types of tiles for different kinds of content:

  • An img tile to display an image
  • A video tile to display a video (since version 3.7)
  • A look tile to display an image from a lookbook, including the hotspots (since version 3.8).
  • A product_list tile to display a list of products. The products to display are described by the content key.

Tiles can be linked to a resource. A resource is another screen in the app. When a customer taps on a tile that is linked to a resource the app opens that screen. There are different types of resources:

  • The category type links a tile a specific category
  • The product type links a tile to a specific product
  • The lookbook type links a tile to a specific lookbook
  • The lookbook_look type links a tile a specific look within a specific lookbook
  • The url type links a tile to webpage in the in-app browser
  • The contentextension type links a tile to a webpage opened as if it is native content (available since version 3.6)

Configuration

The look and feel of the home wall can be controlled remotely. The following aspects can be configured:

  • The background color
  • The distance between tiles in a grid (the "gutter size")
  • The distance between the top and bottom of rows (the "horizontal margin")
  • The distance between the rows and the edges of the screen (the "vertical margin")
  • The corner radius of the tiles
  • The amount of shadow a tile has

TODO

  • Gutter size: does the gutter size on get storefronts take precedence?
  • What is the meta field for resources? Does the app use it? What fields does it hold?

Home

Fetches the home wall

Authorizations:
AccessToken

Responses

Response samples

Content type
application/json
{}

Wishlists

Wishlists are lists of products that registered customers can maintain. They can be used to implement, for example, favorites or gift registries.

Fetch wishlist

Authorizations:
AccessToken
path Parameters
id
required
string

Unique identifier of the wishlist

header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Authorization
required
string

Access token

Responses

Response samples

Content type
application/json
{
  • "item_count": 1,
  • "items": [
    ]
}

Add wishlist item

Adds a product to a wishlist. The items is added at the end of the existing wishlist.

Authorizations:
AccessToken
path Parameters
id
required
string

Unique identifier of the wishlist

header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Authorization
required
string

Access token

Request Body schema: application/json

Wishlist item

required
object

Item to add to the wishlist

product_id
required
string

The ID of the product to add to the wishlist

Responses

Request samples

Content type
application/json
{
  • "item": {
    }
}

Response samples

Content type
application/json
{
  • "code": "invalid",
  • "message": "invalid or expired token"
}

Delete wishlist item

Delete an item from a wishlist. If the item doesn't exist on the server the operations is treated as a success.

Authorizations:
AccessToken
path Parameters
id
required
string

Unique identifier of the wishlist

item_id
required
string

Unique identifier of an item on a wishlist

header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Authorization
required
string

Access token

Responses

Response samples

Content type
application/json
{
  • "code": "invalid",
  • "message": "invalid or expired token"
}

Changelog

4.0 - 2020-08-19

Added

  • Introduce promotions into the CartItem and ProductResult.

4.0 - 2019-08-02

Added

  • Introduce events_tracking_host and feature_personal_recommendations to the storefront config. Available on all API versions.

4.0 - 2019-07-19

Added

  • Introduce max_number_of_coupons to the storefront config. Available on all API versions.

4.0 - 2019-07-11

Added

  • Introduce the error code item_id_changed for cart_item_error.

4.0 - 2019-04-11

Changed

  • GET /wall: add the tile type product_list.

Added

  • Introduce GET /featured_products/{id} endpoint.
  • Introduce POST /visitor_id endpoint.
  • Introduce POST /jobs/reindex-categories endpoint. Available on all API versions.

3.9 - 2018-06-13

Changed

  • GET /stores: deprecate postal_code parameter in favour of address.

3.9 - 2018-06-19

Added

  • Introduce membership_level on GET /account/loyalty

3.9 - 2018-05-09

Added

  • Introduce POST /cookies endpoint.
  • Introduce GET /auth/{provider} endpoint.

Changed

  • POST /token: support the grant type authorization_code.
  • GET /contentpages: add the personal, show_guest, show_registered_user and icon properties.

3.8 - 2018-04-11

Added

  • GET /wall: introduce tiles of type 'look'.

3.7 - 2018-02-13

Changed

  • GET /storefront: deprecate checkout_external in favor of checkout.
  • GET /wall: introduce tiles of type video.

Example

  {
    "rect": [0, 0, 12, 12],
    "content": {
      "videos": {
        "mp4_720": "http://highstreet.video.staging.com.global.prod.fastly.net/scotch-uk/walls/video/ilq366NPW-e8iNc08ZjWtg/video/generic_720",
        "mp4_480": "http://highstreet.video.staging.com.global.prod.fastly.net/scotch-uk/walls/video/ilq366NPW-e8iNc08ZjWtg/video/generic_480",
        "mp4_360": "http://highstreet.video.staging.com.global.prod.fastly.net/scotch-uk/walls/video/ilq366NPW-e8iNc08ZjWtg/video/generic_360"
      },
      "placeholder": "http://cms-staging-highstreetapp.imgix.net/scotch-uk/walls/video/ilq366NPW-e8iNc08ZjWtg/placeholder?fit=crop\u0026fm=jpg\u0026q=50"
    },
    "type": "video",
    "resource": {
      "type": "category",
      "id": "5"
    }
  }

3.6 - 2017-09-06

Added

  • GET /wall: introduce tiles of type 'contextextension'.

Example

  {
    "rect": [0, 0, 12, 12],
    "content": {
      "url": "http://cms-staging-highstreetapp.imgix.net/scotch-uk/promotions/4GNKm7WosspYSgVdYbVf6Q_source?fit=crop\u0026fm=jpg\u0026q=50",
      "parallax": true
    },
    "type": "img",
    "resource": {
      "type": "contentextension",
      "title": "Stories",
      "url": "https://www.scotch-soda.com/nl/nl/FW17-ABLAUNCH.html"
    }
  }

Orders

Order Summary

Lists all orders in summary format

Authorizations:
AccessToken
query Parameters
status
string
Value: "ready_for_pick_up_in_store"

Filter orders by their status

store_id
string

Filter orders by store they were placed in or can be picked up in

header Parameters
X-Selected-Storefront
required
string

Identifier of the selected storefront

Authorization
required
string

Access token

Responses

Response samples

Content type
application/json
{
  • "next_cursor": 0,
  • "orders": [
    ]
}

Order Detail

Shows a single order in detail

Authorizations:
AccessToken
path Parameters
id
required
string

Unique identifier of the resource.

header Parameters
Authorization
required
string

Access token

Responses

Response samples

Content type
application/json
{
  • "barcode": {
    },
  • "billing_address": {
    },
  • "creation_date": 1500460060,
  • "currency_code": "EUR",
  • "id": "PNZfEiFcNM",
  • "items": [],
  • "number": "EU000027546",
  • "payments": [
    ],
  • "prices_include_tax": true,
  • "shipments": [
    ],
  • "source": "app",
  • "status": "cancelled",
  • "totals": {
    }
}