Skip to main content
API docs by Redocly

Studio API (1.0)

Download OpenAPI specification:Download

This is a draft and has not yet been finalized

Some important changes to note:

  • Promotions are now deprecated. Meaning the following routes no longer exist:

    • OPTIONS /promotion/:store/promotions/?
    • OPTIONS /promotion/:store/promotions/*
    • GET /promotion/:store/promotions/?
    • GET /promotions/:unique_id/?
    • GET /promotion/:store/promotions/:unique_id/?
    • POST /promotion/:store/promotions/?
    • PUT /promotion/:store/promotions/?
    • PUT /promotion/:store/promotions/:unique_id/?
    • DELETE /promotion/:store/promotions/?
    • DELETE /promotion/:store/promotions/:unique_id/?

  • The merchant_id is now at the base of the path so for example: lookbook/:merchant/lookbooks is now /:merchant/lookbooks.

  • all references to cms_id, store within urls has been replaced with the merchant_id

  • Lookbooks, Walls and Push Notifications no longer belong to a store but belong to the merchant. This enables us to share Lookbooks, for example, across multiple stores.

  • Lookbooks, Walls and Push Notifications now also contain a list of tags that they are associated with.

  • A new endpoint has been added for Lookbooks, Walls and Push Notifications to enable adding tags.

App Status

List app status details for current merchant

This endpoint fetches current app status settings

path Parameters
merchant_id
required
string

The merchant ID

header Parameters
Authorization
required
string

Access token

Responses

Response samples

Content type
application/json
{
  • "android": {
    },
  • "default_message": "string",
  • "default_title": "string",
  • "enabled": true,
  • "ios": {
    },
  • "merchant": "string",
  • "messages": [
    ],
  • "titles": [
    ]
}

Updates App Status

This endpoint will allow updating App Status mode (enabled or not) and text for title and message

path Parameters
merchant_id
required
string

The merchant ID

header Parameters
Authorization
required
string

Access token

Request Body schema: application/json
object (UpdateAppStatusRequestParams)
object (AppStatusAndroid)

Specific information used by Android mobile apps

default_message
string

Default message displayed for all languages as body. Required, unless 'messages' is empty

default_title
string

Default title displayed for all languages as header. Required, unless 'titles' is empty.

enabled
required
boolean

Maintenance Status Enabled or Disabled

object (AppStatusIOS)

Specific information used by iOS mobile apps

Array of objects (AppStatusTranslatedMessage)

Translations for Messages for various languages and countries. When used, 'default_title' cannot be empty.

Array of objects (AppStatusTranslatedTitle)

Translations for Titles for various languages and countries. When used, 'default_title' cannot be empty.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "android": {
    },
  • "default_message": "string",
  • "default_title": "string",
  • "enabled": true,
  • "ios": {
    },
  • "merchant": "string",
  • "messages": [
    ],
  • "titles": [
    ]
}

BrokenLinkAlerts

Will dismiss all broken links alerts for a breakable

path Parameters
merchant_id
required
string

The merchant ID

header Parameters
Authorization
required
string

Access token

Request Body schema: application/json
breakable_id
integer

The ID of the content that has broken links

breakable_type
string
Enum: "Look" "Lookbook" "Lookbook::Video" "Lookbook::Image" "Lookbook::Timeframe" "V2::Row" "Row" "PushNotification" "ProductList"

The type of the breakable

Responses

Request samples

Content type
application/json
{
  • "breakable_id": 0,
  • "breakable_type": "Look"
}

Response samples

Content type
application/json
{
  • "code": "no_active_broken_link_found"
}

Content Extensions

List Content Extensions

path Parameters
merchant_id
required
string

The merchant ID

header Parameters
Authorization
required
string

Access token

Responses

Response samples

Content type
application/json
{}

Create Content Extension

path Parameters
merchant_id
required
string

The merchant ID

header Parameters
Authorization
required
string

Access token

Request Body schema: application/json
default_title
required
string

The default title

default_url
required
string <uri>

The default title

Array of objects (LocalizedContentExtensionTitle)

Language specific titles

Array of objects (LocalizedContentExtensionURL)

Storefront specific URLs

Responses

Request samples

Content type
application/json
{
  • "default_title": "string",
  • "default_url": "http://example.com",
  • "titles": [
    ],
  • "urls": [
    ]
}

Response samples

Content type
application/json
{}

View Content Extension

path Parameters
merchant_id
required
string

The merchant ID

content_extension_id
required
string

Content Extension ID

header Parameters
Authorization
required
string

Access token

Responses

Response samples

Content type
application/json
{}

Delete Content Extension

path Parameters
merchant_id
required
string

The merchant ID

content_extension_id
required
string

Content Extension ID

header Parameters
Authorization
required
string

Access token

Responses

Response samples

Content type
application/json
{
  • "code": "authentication_failed",
  • "message": "Invalid authentication token or credentials"
}

Update Content Extension

path Parameters
merchant_id
required
string

The merchant ID

content_extension_id
required
string

Content Extension ID

header Parameters
Authorization
required
string

Access token

Request Body schema: application/json
default_title
string

The default title

default_url
string <uri>

The default title

Array of objects (LocalizedContentExtensionTitle)

Language specific titles

Array of objects (LocalizedContentExtensionURL)

Storefront specific URLs

Responses

Request samples

Content type
application/json
{
  • "default_title": "string",
  • "default_url": "http://example.com",
  • "titles": [
    ],
  • "urls": [
    ]
}

Response samples

Content type
application/json
{}

Messages

List all messages

This endpoint fetches all the messages created by a merchant.

path Parameters
merchant_id
required
string

The merchant ID

query Parameters
storefront_id
string

The storefront id

status
string
Enum: "active" "published" "scheduled"

A status used to filter messages

header Parameters
Authorization
required
string

Access token

Responses

Response samples

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

Create a message

This endpoint creates a message for a merchant.

path Parameters
merchant_id
required
string

The merchant ID

header Parameters
Authorization
required
string

Access token

Request Body schema: application/json
object (CreateMessageRequestParams)
body
required
string

The body of the message

image_path
required
string

The image url for the visual element of the message

language
required
string

The language of the message

title
required
string

The title of the message

Responses

Request samples

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

Response samples

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

Delete a message

This endpoint deletes a message.

path Parameters
merchant_id
required
string

The merchant ID

message_id
required
string

The message id

header Parameters
Authorization
required
string

Access token

Responses

Response samples

Content type
application/json
{
  • "code": "authentication_failed",
  • "message": "Invalid authentication token or credentials"
}

Update a Message

This endpoint updates an existing message.

path Parameters
merchant_id
required
string

The merchant ID

message_id
required
string

The message id

header Parameters
Authorization
required
string

Access token

Request Body schema: application/json
object (UpdateMessageRequestParams)
body
string

The body of the message

image_path
string

The image url for the visual element of the message

title
string

The title of the message

Responses

Request samples

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

Response samples

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

Message Publications

Create a publication

This endpoint creates publication for a message.

path Parameters
message_id
required
string

The message id

header Parameters
Authorization
required
string

Access token

Request Body schema: application/json
object (CreatePublicationRequestParams)
placements
required
Array of strings
Items Value: "cart"

List of placements where the message will be shown in the app

publish_at
required
integer

Unix timestamp that indicates when the message should be published

storefront_ids
required
Array of strings

List of storefront_ids the publication is linked to

unpublish_at
integer

Unix timestamp that indicates until when the message should stay published

Responses

Request samples

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

Response samples

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

Delete a publication

This endpoint deletes a publication.

path Parameters
message_id
required
string

The message id

publication_id
required
string

The publication id

header Parameters
Authorization
required
string

Access token

Responses

Response samples

Content type
application/json
{
  • "code": "authentication_failed",
  • "message": "Invalid authentication token or credentials"
}

Update a publication

This endpoint updates an existing publication.

path Parameters
message_id
required
string

The message id

publication_id
required
string

The publication id

header Parameters
Authorization
required
string

Access token

Request Body schema: application/json
object (UpdatePublicationRequestParams)
placements
Array of strings
Items Value: "cart"

List of placements where the message will be shown in the app

publish_at
integer

Unix timestamp that indicates when the message should be published

storefront_ids
Array of strings

List of storefront_ids the publication is linked to

unpublish_at
integer

Unix timestamp that indicates until when the message should stay published

Responses

Request samples

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

Response samples

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

Published Messages

List published messages

This endpoint fetches published messages.

path Parameters
merchant_id
required
string

The merchant ID

query Parameters
storefront_id
string

The storefront id

Responses

Response samples

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

Push Notifications

Get list of all push notifications with filters support

path Parameters
merchant_id
required
string

The merchant ID

query Parameters
status
string
Enum: "sent" "scheduled"

Status of push notifications

content_type
string
Enum: "resource" "custom"

Content type of push notification

locales
string
Example: locales=en-NL, en-US, de-DE

Comma separated list of storefront_ids

from
string
Default: 0

Offset for returning results

to
string
Default: 10

Limit for the number of results returned

header Parameters
Authorization
required
string

Access token

Responses

Response samples

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

Get list of all push notifications stats for the merchant

This endpoint will respond information about total number of users and total number of subscribers.

path Parameters
merchant_id
required
string

The merchant ID

query Parameters
interval
string
Default: "1day"
Enum: "1day" "7days" "30days"

Period for report

header Parameters
Authorization
required
string

Access token

Responses

Response samples

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

Users

List all users

This endpoint will give a list of users allowed to access the specified merchant.

path Parameters
merchant_id
required
string

The merchant ID

header Parameters
Authorization
required
string

Access token

Responses

Response samples

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

Create User

Creates a new user with access to this merchant and sends them an email to let them set a password.

If a user with this email address already exists, the existing user will be updated to also have access to this merchant.

If the request body has the 'name' attribute it will update the user's name from the database with the one from the request.

path Parameters
merchant_id
required
string

The merchant ID

header Parameters
Authorization
required
string

Access token

Request Body schema: application/json
object (CreateUserRequestParams)

Params for creating a new user for a merchant

email
required
string

Email

name
string

Full Name

role
string

User role to be created, default to 'user'

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "email": "string",
  • "merchants": [
    ],
  • "name": "string",
  • "role": "user",
  • "uuid": "string"
}

Show User

This endpoint will show the details of a single user.

path Parameters
merchant_id
required
string

The merchant ID

uuid
required
string

User Unique Identifier

header Parameters
Authorization
required
string

Access token

Responses

Response samples

Content type
application/json
{
  • "email": "string",
  • "merchants": [
    ],
  • "name": "string",
  • "role": "user",
  • "uuid": "string"
}

Delete User

This endpoint will remove a user from a merchant.

If after removing the user from the merchant their list of 'allowed_merchants' is empty, it will also delete the user from the database.

path Parameters
merchant_id
required
string

The merchant ID

uuid
required
string

User Unique Identifier

header Parameters
Authorization
required
string

Access token

Responses

Walls

The Home wall is the first thing you see when you open a Highstreet app. Each storefront has one or more home walls, of which one and only one can be active at any given time.

A home wall consists of a collection of Rows. They are stacked on top of each other. Each wall must have at least 2 and at most 25 Rows before it can be activated. A row has a grid with 12 (invisible) columns and a configurable number of rows on which Tiles can be placed.

A Tile consists of coordinates describing the position on the grid, content (e.g. an image) and an optional linked resource (e.g. a lookbook or category).

Publish a wall

A Wall has 3 "states", Published, scheduled and unpublished(in drafts). These states determine what is visible in the app and when.

A Wall can have a different schedule for a number of different locales. For example a wall can be scheduled to be live in France on Monday and the US on Wednesday.

This endpoint is responsible for publishing, scheduling and unpublishing a wall. The endpoint accepts an array of objects representing a locale. If the time is in the future the wall will be scheduled, and if publish_at is now then the wall will be published.

Note that the array in the request will replace all current tags / schedules in the resource. E.g. if the wall is published in en-GB but the request does not include a en-GB tag then the en-GB tag will be removed from the resource and the resource will no longer be published in that locale.

path Parameters
merchant_id
required
string

The merchant ID

wall_id
required
string

Wall ID

header Parameters
Authorization
required
string

Access token

Request Body schema: application/json

Request body for publishing a wall

Array
id
string

Unique id of the locale tag

time
string

An ISO8061 formatted time stamp

time_zone
string

The time zone identifier eg Europe/Amsterdam

value
string

Human readable value of locale tag eg nl-NL

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "base_storefront": "string",
  • "gutter_size": 0,
  • "id": 0,
  • "name": "string",
  • "published": true,
  • "schedule_overview": [
    ],
  • "tagged_with": [
    ],
  • "rows": [
    ]
}

List all walls

  • The locales and view parameters cannot be combined.
  • The view parameter is ignored if it has an unknown value.
path Parameters
merchant_id
required
string

The merchant ID

query Parameters
locales
Array of strings

A comma separated list of locales

view
string
Enum: "published" "scheduled" "drafts"

The type of walls to list

header Parameters
Authorization
required
string

Access token

Responses

Response samples

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

Create a wall

path Parameters
merchant_id
required
string

The merchant ID

header Parameters
Authorization
required
string

Access token

Request Body schema: application/json

Request body for creating a wall

base_storefront
string

DEPRECATED: Used to determine which storefront to use when searching for products / categories.

name
string

Name of the home walls (inteded for merchants)

Responses

Request samples

Content type
application/json
{
  • "base_storefront": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "base_storefront": "string",
  • "gutter_size": 0,
  • "id": 0,
  • "name": "string",
  • "published": true,
  • "schedule_overview": [
    ],
  • "tagged_with": [
    ],
  • "rows": [
    ]
}

View active Wall

Retrieve the currently active wall. Passing in an optional array of locales will return a filtered set of walls for the matching locales.

path Parameters
merchant_id
required
string

The merchant ID

query Parameters
locales
Array of strings

A comma separated list of locales

Responses

Response samples

Content type
application/json
{
  • "base_storefront": "string",
  • "gutter_size": 0,
  • "id": 0,
  • "name": "string",
  • "published": true,
  • "schedule_overview": [
    ],
  • "tagged_with": [
    ],
  • "rows": [
    ]
}

Update a wall

A wall must have between 2 and 25 rows. Attempting to publish a wall with only one row results in an error.

path Parameters
merchant_id
required
string

The merchant ID

wall_id
required
string

Wall ID

header Parameters
Authorization
required
string

Access token

Request Body schema: application/json

Request body for updating a wall

name
string

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "base_storefront": "string",
  • "gutter_size": 0,
  • "id": 0,
  • "name": "string",
  • "published": true,
  • "schedule_overview": [
    ],
  • "tagged_with": [
    ],
  • "rows": [
    ]
}

Delete a wall

path Parameters
merchant_id
required
string

The merchant ID

wall_id
required
string

Wall ID

header Parameters
Authorization
required
string

Access token

Responses

Response samples

Content type
application/json
{
  • "error_code": "PUBLISHED_WALL",
  • "message": "Cannot delete published wall",
  • "success": false
}

Duplicate a wall

Copies a wall and all associated rows and tiles. The copied Wall will always be created as unpublished.

path Parameters
merchant_id
required
string

The merchant ID

wall_id
required
string

Wall ID

header Parameters
Authorization
required
string

Access token

Responses

Response samples

Content type
application/json
{
  • "copied_wall": 123
}

Update the order of rows

All row IDs should be present. Extra row IDs or missing row IDs are not allowed.

path Parameters
merchant_id
required
string

The merchant ID

wall_id
required
string

Wall ID

Request Body schema: application/json

Request body for changing the order of rows within a wall

order
Array of integers

List of row IDs

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "code": "INVALID_ORDER",
  • "message": "Missing or unknown rows",
  • "success": false
}

Rows

View a row

Represents a single row in a promotion wall.

path Parameters
merchant_id
required
string

The merchant ID

row_id
required
string

Row ID

header Parameters
Authorization
required
string

Access token

Responses

Response samples

Content type
application/json
{
  • "config": {
    },
  • "tiles": [
    ],
  • "type": "grid",
  • "id": 0
}

Update a Row

Updates a single row in a wall along with it's associated tiles

path Parameters
merchant_id
required
string

The merchant ID

row_id
required
string

Row ID

header Parameters
Authorization
required
string

Access token

Request Body schema: application/json

Request body for updating a row

required
object

Configuration of the row

required
Array of objects (TileRequest)

The tiles the row contains

type
required
string
Value: "grid"

The row type

Responses

Request samples

Content type
application/json
{
  • "config": {
    },
  • "tiles": [
    ],
  • "type": "grid"
}

Response samples

Content type
application/json
{
  • "config": {
    },
  • "tiles": [
    ],
  • "type": "grid",
  • "id": 0
}

Delete a Row

Deletes a single row in a promotion wall.

Note: A wall must have between 2 and 25 rows. Attempting to delete a row when the associated wall has only 2 rows will result in an error.

path Parameters
merchant_id
required
string

The merchant ID

row_id
required
string

Row ID

header Parameters
Authorization
required
string

Access token

Responses

Response samples

Content type
application/json
{
  • "error_code": "MINIMUM_REACHED",
  • "message": "Published walls must have at least 2 rows",
  • "success": false
}

Create a Row

Represents the collection of rows in a promotion wall. The collection of tiles, when placed on the grid, should cover the whole grid exactly. It’s not allowed to leave gaps, overlap tiles or let tiles stick out of the grid. A home wall can have at most 25 rows. Attempting to add more results in an error. A resource can only be linked once per wall. Tiles can be one of 2 types; img or video. The content body changes depending on the type.

path Parameters
merchant_id
required
string

The merchant ID

wall_id
required
string

Wall ID

header Parameters
Authorization
required
string

Access token

Request Body schema: application/json

Request body for creating a row

required
object

Configuration of the row

required
Array of objects (TileRequest)

The tiles the row contains

type
required
string
Value: "grid"

The row type

Responses

Request samples

Content type
application/json
{
  • "config": {
    },
  • "tiles": [
    ],
  • "type": "grid"
}

Response samples

Content type
application/json
{
  • "config": {
    },
  • "tiles": [
    ],
  • "type": "grid",
  • "id": 0
}

Lookbook

A Lookbook is a collection of Looks. Each Look contains an image and a number of 'hotspots'. These 'hotspots' are linked to individual products.

Get all Lookbooks.

Gets all look books by merchant_id. This endpoint is used by both the studio frontend and the middleware. Passing in an optional array of locales will return a filtered set of lookbooks for the matching locales. You can also pass an optional parameter of view with one of the following values: published, scheduled, drafts. These will each return the respective lookbooks depending on their status. Note that one lookbook could be published in one locale but scheduled in another. Therefore the same lookbook could appear in the both a published and scheduled list.

path Parameters
merchant_id
required
string

The merchant ID

query Parameters
locales
Array of strings

A optional set of locales to filter by

view
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a Lookbook

Creates a lookbook. When creating a Lookbook for the first time it will always be in an unpublished state

path Parameters
merchant_id
required
string

The merchant ID

header Parameters
Authorization
required
string

The valid session token, returned after logging a user in.

Request Body schema: application/json
display_categories
Array of strings
published
boolean
Default: false

Defines if the lookbook is published or not. Only published lookbooks are visible in the app.

title
string

Title of the lookbook

Responses

Request samples

Content type
application/json
{
  • "display_categories": [
    ],
  • "published": false,
  • "title": "string"
}

Response samples

Content type
application/json
{
  • "base_storefront": "string",
  • "created_at": 0,
  • "display_categories": "string",
  • "front_images": {
    },
  • "id": 0,
  • "index": 0,
  • "linked_to_tile": [
    ],
  • "look_count": 0,
  • "merchant_id": "string",
  • "published": true,
  • "schedule_overview": [
    ],
  • "title": "string",
  • "translations": {
    },
  • "updated_at": 0
}

Get a Lookbook

Get a specific Lookbook by merchant_id and id

path Parameters
merchant_id
required
string

The merchant ID

id
required
string

The id of the requested resource

header Parameters
Authorization
required
string

The valid session token, returned after logging a user in.

Responses

Response samples

Content type
application/json
{
  • "base_storefront": "string",
  • "created_at": 0,
  • "display_categories": "string",
  • "front_images": {
    },
  • "id": 0,
  • "index": 0,
  • "linked_to_tile": [
    ],
  • "look_count": 0,
  • "merchant_id": "string",
  • "published": true,
  • "schedule_overview": [
    ],
  • "title": "string",
  • "translations": {
    },
  • "updated_at": 0
}

Delete a Lookbook

Deletes a lookbook according to merchant id and lookbook id.

path Parameters
merchant_id
required
string

The merchant ID

id
required
string

The id of the requested resource

header Parameters
Authorization
required
string

The valid session token, returned after logging a user in.

Responses

Response samples

Content type
application/json
{
  • "error_code": "UNAUTHORIZED",
  • "message": "Permission denied",
  • "success": false
}

Duplicate a Lookbook

Copies a Lookbook and all associated Looks. The copied lookbook will always be created as unpublished. All tags associated with the lookbook will also be copied.

path Parameters
merchant_id
required
string

The merchant ID

id
required
string

The id of the requested resource

header Parameters
Authorization
required
string

The valid session token, returned after logging a user in.

Responses

Response samples

Content type
application/json
{
  • "copied_lookbook": "12"
}

Update order of looks

Represents the order of the looks in a particular lookbook.

When supplying a new order, all look IDs should be present. Extra or missing look ids are not allowed. Example Order:

  {
    "order": [1, 2, 3, 4]
  }
path Parameters
merchant_id
required
string

The merchant ID

id
required
string

The id of the requested resource

Request Body schema: application/json
order
Array of integers

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "error_code": "INVALID_ORDER",
  • "message": "Missing or unknown looks",
  • "success": false
}

Publish/Schedule a Lookbook

A Lookbook has 3 "states", Published, scheduled and unpublished(in drafts). These states determine what is visible in the app and when.

A Lookbook can have a different schedule for a number of different locales. For example a wall can be scheduled to be live in France on Monday and the US on Wednesday.

This endpoint is responsible for publishing, scheduling and unpublishing a wall. The endpoint accepts an array of objects representing a locale. If the time is in the future the wall will be scheduled, and if publish_at is now then the resource will be published.

Note that the array in the request will replace all current tags/schedules in the resource. Eg if the resource is published in en-GB but the request does not include an en-GB tag then the en-GB tag will be removed from the resource and the resource will no longer be published in that locale.

path Parameters
merchant_id
required
string

The merchant ID

id
required
string

The id of the requested resource

header Parameters
Authorization
required
string

The valid session token, returned after logging a user in.

Request Body schema: application/json
Array
id
string

Unique id of the locale tag

time
string

An ISO8061 formatted time stamp

time_zone
string

The time zone identifier eg Europe/Amsterdam

value
string

Human readable value of locale tag eg nl-NL

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "base_storefront": "string",
  • "created_at": 0,
  • "display_categories": "string",
  • "front_images": {
    },
  • "id": 0,
  • "index": 0,
  • "linked_to_tile": [
    ],
  • "look_count": 0,
  • "merchant_id": "string",
  • "published": true,
  • "schedule_overview": [
    ],
  • "title": "string",
  • "translations": {
    },
  • "updated_at": 0
}

Add tags to a lookbook

This endpoint is not currently in use!! Enables a lookbook to be associated with multiple store fronts or customer groups

path Parameters
merchant_id
required
string

The merchant ID

id
required
string

The id of the requested resource

Request Body schema: application/json
Array of objects (SimpleTag)
Array
tag_type
string

the type of tag. Could be either locale or customer_group

tag_value
string

The tag name eg. Men 30 - 40

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "base_storefront": "string",
  • "created_at": 0,
  • "display_categories": "string",
  • "front_images": {
    },
  • "id": 0,
  • "index": 0,
  • "linked_to_tile": [
    ],
  • "look_count": 0,
  • "merchant_id": "string",
  • "published": true,
  • "schedule_overview": [
    ],
  • "title": "string",
  • "translations": {
    },
  • "updated_at": 0
}

remove tags from a lookbook

Removes a set of tags from a lookbook

path Parameters
merchant_id
required
string

The merchant ID

id
required
string

The id of the requested resource

Request Body schema: application/json
Array of objects (Tag)
Array
id
string

unique database id

merchant_id
string

The merchant That this tag belongs to

tag_type
string

the type of tag. Could be either locale or customer_group

tag_value
string

The tag name eg. Men 30 - 40

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "error_code": "INVALID_PROPERTY",
  • "message": "The specified tags were not associated with this resource",
  • "success": false
}

Update order of lookbooks

Updates the order of lookbooks for a single locale.

When supplying a new order, all lookbook IDs should be present. Extra lookbook IDs or missing row IDs are not allowed.

Example Order:

  {
    "order": [1, 2, 3, 4]
  }
path Parameters
merchant_id
required
string

The merchant ID

locale
required
string

The locale you want to edit

header Parameters
Authorization
required
string

The valid session token, returned after logging a user in.

Request Body schema: application/json
order
Array of integers

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "error_code": "UNAUTHORIZED",
  • "message": "Permission denied",
  • "success": false
}

Look

Get all Looks by Lookbook

Get all looks of a certain lookbook

path Parameters
merchant_id
required
string

The merchant ID

id
required
string

The id of the requested resource

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a Look

Creates a look for a lookbook

path Parameters
merchant_id
required
string

The merchant ID

id
required
string

The id of the requested resource

header Parameters
Authorization
required
string

The valid session token, returned after logging a user in.

Responses

Response samples

Content type
application/json
{
  • "created_at": 0,
  • "hotspots": [
    ],
  • "id": 0,
  • "image": {
    },
  • "image_key": "string",
  • "images": {
    },
  • "index": 0,
  • "lookbook_id": 0,
  • "updated_at": 0
}

Get a Look

Get all looks of a certain lookbook

path Parameters
merchant_id
required
string

The merchant ID

id
required
string

The id of the requested resource

nested_id
required
string

The id of the requested resource

Responses

Response samples

Content type
application/json
{
  • "created_at": 0,
  • "hotspots": [
    ],
  • "id": 0,
  • "image": {
    },
  • "image_key": "string",
  • "images": {
    },
  • "index": 0,
  • "lookbook_id": 0,
  • "updated_at": 0
}

Update a Look

Updates a look for a lookbook

path Parameters
merchant_id
required
string

The merchant ID

id
required
string

The id of the requested resource

nested_id
required
string

The id of the requested resource

header Parameters
Authorization
required
string

The valid session token, returned after logging a user in.

Request Body schema: application/json

A json representation of a Look

id
integer
look
string

A JSON Hash

lookbook_id
integer

Responses

Request samples

Content type
application/json
{
  • "id": 0,
  • "look": "string",
  • "lookbook_id": 0
}

Response samples

Content type
application/json
{
  • "created_at": 0,
  • "hotspots": [
    ],
  • "id": 0,
  • "image": {
    },
  • "image_key": "string",
  • "images": {
    },
  • "index": 0,
  • "lookbook_id": 0,
  • "updated_at": 0
}

Delete a Look

Deletes a look for a lookbook

path Parameters
merchant_id
required
string

The merchant ID

id
required
string

The id of the requested resource

nested_id
required
string

The id of the requested resource

header Parameters
Authorization
required
string

The valid session token, returned after logging a user in.

Responses

Response samples

Content type
application/json
{
  • "error_code": "UNAUTHORIZED",
  • "message": "Permission denied",
  • "success": false
}

Push Notification

A studio user is able to create and schedule push notifications. Rich push notifications are now supported meaning that an image can be attached and viewed in the app.

A push notification consists of a title and a message. The Notification is also associated to a number of locations. These being home, category, lookbook, product. The Notification will contain a deeplink and open the app in the respective location.

Example of a rich push notification:

lockscreen rich preview

Schedules or sends a Push Notification

The push notifications are used to improve engagement with users of the Highstreet app and to promote promotions, products, categories or lookbooks.

A notification consists of a message, an optional title or a subtitle and additional information to guide the app in presenting rich notification content and allowing the app to take advantage of the deep linking feature.

A notification can also be sent to a single user by adding user's email address to the customer_id key

A notification is described as follows:

{
  "message": "The message of the push notification, displayed on device's lockscreen",
  "push_time": "1473172784",
  "store": "test",
  "destination_type": "categories",
  "destination_type_id": "xwhl123",
  "destination_name": "A category name",
  "cancelled": false
}
path Parameters
merchant_id
required
string

The merchant ID

header Parameters
Authorization
required
string

The valid session token, returned after logging a user in.

Request Body schema: application/json
content_type
required
string (ContentType)
Enum: "resource" "custom"

Is the push notification linked to a content in Studio or was it created custom (video/image)

customer_id
string

The email address of a customer. This will send the notifaction to this user only

destination_name
string

The human readable identifier of the destination

destination_type
required
string
Enum: "categories" "products" "lookbooks" "home"

The destination type for the deep linking

destination_type_id
required
string

The identifier for the destination type, if needed.

image_thumbnail_url
string

The url to a thumbnail created to display on the lock screen

image_url
string

The url to an image created to display in rich notifications

message
required
string

The message for the push notification.

push_time
string

When the notification will be sent.

required
Array of objects (SimpleTag)
title
required
string

The title for the push notification.

Responses

Request samples

Content type
application/json
{
  • "content_type": "resource",
  • "customer_id": "string",
  • "destination_name": "string",
  • "destination_type": "categories",
  • "destination_type_id": "string",
  • "image_thumbnail_url": "string",
  • "image_url": "string",
  • "message": "string",
  • "push_time": "string",
  • "tags": [
    ],
  • "title": "string"
}

Response samples

Content type
application/json
{
  • "cancelled": true,
  • "content_type": null,
  • "destination_name": "string",
  • "destination_storefront_id": "string",
  • "destination_type": "categories",
  • "destination_type_id": "string",
  • "expiration_time": 0,
  • "image_thumbnail_url": "string",
  • "image_url": "string",
  • "language": "string",
  • "merchant_id": "string",
  • "message": "string",
  • "push_time": "string",
  • "studio_id": "string",
  • "tagged_with": {
    },
  • "time_zone": "string",
  • "title": "string",
  • "unique_id": 0,
  • "video_url_480": "string",
  • "video_url_720": "string"
}

Send a push notification

The push notifications are used to improve engagement with users of the Highstreet app and to promote promotions, products, categories or lookbooks.

A notification consists of a message, an optional title or a subtitle and additional information to guide the app in presenting rich notification content and allowing the app to take advantage of the deep linking feature.

A notification can also be sent to a single user by adding user's email address to the customer_id key

A notification is described as follows:

  {
    "message": "The message of the push notification, displayed on device's lockscreen",
    "push_time": "1473172784",
    "store": "test",
    "destination_type": "categories",
    "destination_type_id": "xwhl123",
    "destination_name": "A category name",
    "cancelled": false
  }
path Parameters
merchant_id
required
string

The merchant ID

header Parameters
Authorization
required
string

The valid session token, returned after logging a user in.

Request Body schema: application/json
content_type
required
string (ContentType)
Enum: "resource" "custom"

Is the push notification linked to a content in Studio or was it created custom (video/image)

customer_id
string

The email address of a customer. This will send the notifaction to this user only

destination_name
string

The human readable identifier of the destination

destination_type
required
string
Enum: "categories" "products" "lookbooks" "home"

The destination type for the deep linking

destination_type_id
required
string

The identifier for the destination type, if needed.

image_thumbnail_url
string

The url to a thumbnail created to display on the lock screen

image_url
string

The url to an image created to display in rich notifications

message
required
string

The message for the push notification.

push_time
string

When the notification will be sent.

required
Array of objects (SimpleTag)
title
required
string

The title for the push notification.

Responses

Request samples

Content type
application/json
{
  • "content_type": "resource",
  • "customer_id": "string",
  • "destination_name": "string",
  • "destination_type": "categories",
  • "destination_type_id": "string",
  • "image_thumbnail_url": "string",
  • "image_url": "string",
  • "message": "string",
  • "push_time": "string",
  • "tags": [
    ],
  • "title": "string"
}

Response samples

Content type
application/json
{
  • "cancelled": true,
  • "content_type": null,
  • "destination_name": "string",
  • "destination_storefront_id": "string",
  • "destination_type": "categories",
  • "destination_type_id": "string",
  • "expiration_time": 0,
  • "image_thumbnail_url": "string",
  • "image_url": "string",
  • "language": "string",
  • "merchant_id": "string",
  • "message": "string",
  • "push_time": "string",
  • "studio_id": "string",
  • "tagged_with": {
    },
  • "time_zone": "string",
  • "title": "string",
  • "unique_id": 0,
  • "video_url_480": "string",
  • "video_url_720": "string"
}

Create Image for notification

Push notifications now support Rich notifications. This means that we can assign an image to the notification. We generate this image for the client depending on the destination type of the notification. Only push notifications with a destination type of products, lookbooks, categories or home will have an image attached. The destination_type_id related to the id of the resource. The only slightly confusing part is with home the destination_type_id is actually the id of a Tile and not a Wall.

path Parameters
merchant_id
required
string

The merchant ID

header Parameters
Authorization
required
string

The valid session token, returned after logging a user in.

Request Body schema: application/json
destiantion_type_id
string
destination_type
string

Responses

Request samples

Content type
application/json
{
  • "destiantion_type_id": "string",
  • "destination_type": "string"
}

Response samples

Content type
{
  • "image_thumbnail_url": "string",
  • "image_url": "string"
}

Get a single Notification

Returns a single Push Notification by id and merchant_id

path Parameters
merchant_id
required
string

The merchant ID

id
required
string

The id of the requested resource

header Parameters
Authorization
required
string

The valid session token, returned after logging a user in.

Responses

Response samples

Content type
application/json
{
  • "cancelled": true,
  • "content_type": null,
  • "destination_name": "string",
  • "destination_storefront_id": "string",
  • "destination_type": "categories",
  • "destination_type_id": "string",
  • "expiration_time": 0,
  • "image_thumbnail_url": "string",
  • "image_url": "string",
  • "language": "string",
  • "merchant_id": "string",
  • "message": "string",
  • "push_time": "string",
  • "studio_id": "string",
  • "tagged_with": {
    },
  • "time_zone": "string",
  • "title": "string",
  • "unique_id": 0,
  • "video_url_480": "string",
  • "video_url_720": "string"
}

update a push notification

Updates a notification. One signal doesn't actually support this functionality. So behind the scenes we are cancelling the original notification and creating a new one.

path Parameters
merchant_id
required
string

The merchant ID

id
required
string

The id of the requested resource

header Parameters
Authorization
required
string

The valid session token, returned after logging a user in.

Request Body schema: application/json
content_type
required
string (ContentType)
Enum: "resource" "custom"

Is the push notification linked to a content in Studio or was it created custom (video/image)

customer_id
string

The email address of a customer. This will send the notifaction to this user only

destination_name
string

The human readable identifier of the destination

destination_type
required
string
Enum: "categories" "products" "lookbooks" "home"

The destination type for the deep linking

destination_type_id
required
string

The identifier for the destination type, if needed.

image_thumbnail_url
string

The url to a thumbnail created to display on the lock screen

image_url
string

The url to an image created to display in rich notifications

message
required
string

The message for the push notification.

push_time
string

When the notification will be sent.

required
Array of objects (SimpleTag)
title
required
string

The title for the push notification.

Responses

Request samples

Content type
application/json
{
  • "content_type": "resource",
  • "customer_id": "string",
  • "destination_name": "string",
  • "destination_type": "categories",
  • "destination_type_id": "string",
  • "image_thumbnail_url": "string",
  • "image_url": "string",
  • "message": "string",
  • "push_time": "string",
  • "tags": [
    ],
  • "title": "string"
}

Response samples

Content type
application/json
{
  • "cancelled": true,
  • "content_type": null,
  • "destination_name": "string",
  • "destination_storefront_id": "string",
  • "destination_type": "categories",
  • "destination_type_id": "string",
  • "expiration_time": 0,
  • "image_thumbnail_url": "string",
  • "image_url": "string",
  • "language": "string",
  • "merchant_id": "string",
  • "message": "string",
  • "push_time": "string",
  • "studio_id": "string",
  • "tagged_with": {
    },
  • "time_zone": "string",
  • "title": "string",
  • "unique_id": 0,
  • "video_url_480": "string",
  • "video_url_720": "string"
}

Cancel a notification

Cancels a pending push notification.

path Parameters
merchant_id
required
string

The merchant ID

id
required
string

The id of the requested resource

header Parameters
Authorization
required
string

The valid session token, returned after logging a user in.

Responses

Response samples

Content type
application/json
{
  • "error_code": "TOO_LATE",
  • "message": "push notification is already sent",
  • "success": false
}

User

The User model on the studio is fairly simple. A User is able to login and logout of the studio as well as reset their password. A User is allowed access to a merchant via the merchants attribute.

User Model:

attribute type description
email string Unique identifier of the user
password_digest string Hashed password
reset_digest string Hashed reset token for use when resetting a password
reset_sent_at datetime Time when reset token was sent
merchants array An array of merchants the user has access to. This is normally just one
super_admin boolean Highstreet staff admin staff. Gives the user access to all merchants
last_updated integer Timestamp of when record was last updated

Check if a User is authenticated

This Simply lets you know wether the current user is logged in or not.

header Parameters
Authorization
required
string

The valid session token, returned after logging a user in.

Responses

Response samples

Content type
text/plain; charset=utf-8
Permission denied

View intercom details

Responses

Response samples

Content type
{
  • "name": "string"
}

Login a User

This authenticates a User and returns a valid session token. This Session token can then be attached to the HTTP_AUTHORIZATION for all future requests.

Request Body schema: application/json
email
string

The user's email address

password
string

A valid password

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "token": "laksjoiqw84y3298rflksajbflksanfasf89puas98fyuaw800329"
}

Logout a User

This logs a user out of the studio and destroys their session.

header Parameters
Authorization
required
string

The valid session token, returned after logging a user in.

Responses

Response samples

Content type
application/json
{
  • "error_code": "nil",
  • "message": "Not logged in",
  • "success": false
}

Get all Merchants for a user

Typically a user only has access to one merchant. However there are a few cases where some users have access to multiple. This endpoint returns an array of available merchant ids

header Parameters
Authorization
required
string

The valid session token, returned after logging a user in.

Responses

Response samples

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

Send a Password reset email

This endpoint will find the User by the supplied email address and send them an email containing a link for them to reset their password.

Request Body schema: application/json
email
string

The Users email address

Responses

Request samples

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

Response samples

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

Reset Users password

This will update the Users password with the supplied information. There is no password confirmation validation on this endpoint as it only accepts one password attribute. Therefore the frontend must check that the supplied passwords match.

If an expired or invalid reset token is supplied the server will return a 400.

Request Body schema: application/json
email
string

The Users email address

password
string

The new password

token
string

A valid password reset token

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string",
  • "token": "string"
}

Response samples

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

Validate a password_reset token

Check wether a given token is valid for a given user.

path Parameters
token
required
string

A valid token. This is extracted from the link sent in the email

Request Body schema: application/json
email
string

The Users email address

Responses

Request samples

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

Response samples

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

Tag

Resources such as lookbooks, push notifications and home walls can be tagged. These tags are in place to add a store front or customer group to a resource. Enabling the same resource to be shared across multiple store fronts and customer groups.

Get all Tags

Get all available tags for a merchant. The response is grouped by tag_type for example locale or customer_group

path Parameters
merchant_id
required
string

The merchant ID

Responses

Response samples

Content type
application/json
{
  • "customer_group": [
    ],
  • "locale": [
    ]
}

Settings

Get appearance settings

Returns appearance configurations

path Parameters
merchant_id
required
string

The merchant ID

header Parameters
Authorization
required
string

The valid session token, returned after logging a user in.

Responses

Response samples

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

Refresh the cache

Refreshes the cache for a list of storefronts

path Parameters
merchant_id
required
string

The merchant ID

header Parameters
Authorization
required
string

The valid session token, returned after logging a user in.

Request Body schema: application/json
Array of objects (CacheRefreshSchedule)
Array
id
string

The storefront id

time
string

An ISO8061 time stamp

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "error_code": "string",
  • "message": "string",
  • "success": true
}

Cancel a Cache refresh

Cancels a cache refresh event using the schedule_id. This is returned by the {merchant_id}/settings/cache_refresh/schedules end point. This will cancel a cache refresh schedule for all associated storefronts.

path Parameters
merchant_id
required
string

The merchant ID

id
required
string

The id of the requested resource

header Parameters
Authorization
required
string

The valid session token, returned after logging a user in.

Responses

Response samples

Content type
application/json
{
  • "error_code": "UNAUTHORIZED",
  • "message": "Permission denied",
  • "success": false
}

Get all scheduled refreshes

Returns a list of scheduled cache refreshes

path Parameters
merchant_id
required
string

The merchant ID

header Parameters
Authorization
required
string

The valid session token, returned after logging a user in.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Merchants

Get a merchant

This endpoint fetches a merchant including storefronts.

path Parameters
id
required
string

The merchant identifier

Responses

Response samples

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

Get Categories

Returns a flat list of available categories for the locale.

path Parameters
merchant_id
required
string

The merchant ID

locale
required
string

The locale you want to edit

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a Category

Checks if the category exists

path Parameters
merchant_id
required
string

The merchant ID

id
required
string

The id of the requested resource

locale
required
string

The locale you want to edit

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "path": "string",
  • "title": "string"
}

Get Products

Returns a search of products for the catalog of the specified locale

path Parameters
merchant_id
required
string

The merchant ID

locale
required
string

The locale you want to edit

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Upload an Image

path Parameters
merchant_id
required
string

The merchant ID

Request Body schema: multipart/form-data
upfile
string <binary>

The file to upload.

Responses

Response samples

Content type
{
  • "image_key": "string"
}

Upload Video content

Uploads and transcodes video content for use in a home wall.

path Parameters
merchant_id
required
string

The merchant ID

header Parameters
Authorization
required
string

The valid session token, returned after logging a user in.

Request Body schema: multipart/form-data
rows
string

The number of rows the tile will take up

columns
string

The number of columns the tile will take up

placeholder
string <binary>

The image file to upload. This is displayed whilst the video is loading in the app

video
string <binary>

The video file to upload

Responses

Response samples

Content type
application/json
{
  • "placeholder": "string",
  • "videos": { }
}

Adds translations to a resource

Create translations for a resource. For example POST /scotch/lookbooks/2/translations will create translations for the specified lookbook.

path Parameters
merchant_id
required
string

The merchant ID

resource
required
string

The name of requested resource type, eg lookbooks

id
required
string

The id of the requested resource

header Parameters
Authorization
required
string

The valid session token, returned after logging a user in.

Request Body schema: application/json

The number of rows the tile will take up

Array of objects (Translation)
Array
locale
string

The locale

section
string
text
string

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "error_code": "string",
  • "message": "string",
  • "success": true
}