logo
API docs by Redocly

Showroom Integration API (1.0)

Download OpenAPI specification:Download

Introduction

This document describes the Fashion Cloud Showroom Integration API, which is meant to be used by back-end servers to import and export brand's core data.

Basic Flow

  1. Using the Integration API brands can implement server side applications to send Core Data into the Fashion Cloud Showroom.
  2. Data is processed and persisted in the data storage through the Ingest API.
  3. The Showroom uses the internal API and the CDN to display the data to the end user.
  4. Using the Integration API brands can also pull necessary data (i.e. orders) that is prepared by the Showroom Egest API.

    Brand Data

    All Brand Core Data should be identified with a unique brand code that is provided by the Showroon during the on-boarding process.

What is Brand Core Data? (check our api glossary)

  • Seasons
  • Divisions
  • Delivery Drops
  • Media
  • Customers/Locations
  • Options (Products)
  • Prices
  • Sizes
  • Catalogs
  • Marketing Assets
  • Stock
  • Users

API Requests

All the API methods are available on a single domain https://api.showroom.fashion.cloud. You can find the full paths in the endpoint documentation pages.

  • For Import Data we provide UPSERT based interfaces for creating and updating the data.

  • All endpoints are synchronous and idempotent.

  • For Export Data we provide GET based interfaces for fetching a single or bulk data objects.

Data Format:

The integration api communicates with json using HTTP POST/GET requests.

Required Headers:

Authentication

The Showroom team will create a Machine-to-Machine (M2M) authentication application for your brand and will send you the client ID and client secret through a secure link.

With this information, you can get a JWT token to authenticate your requests.

The JWT token should be passed in the Authorization header as a Bearer token.

The token should be requested from the Auth0 token endpoint using the client ID and client secret.

Here is an example of how to get the token using curl for a specific {non-prod} environment:

curl --request POST \
 --url https://hatchstudio-{non-prod-env}.eu.auth0.com/oauth/token \
 --header 'content-type: application/json' \
 --data '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET", "audience":"https://{non-prod-env}.showroom.fashion.cloud/","grant_type":"client_credentials"}'

For production environment, use the following:

curl --request POST \
 --url https://authorize.showroom.fashion.cloud/oauth/token \
 --header 'content-type: application/json' \
 --data '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET", "audience":"https://showroom.fashion.cloud/","grant_type":"client_credentials"}'

The response will contain the JWT token that you can use to authenticate your requests.

Important: The JWT token is valid for 24 hours.
Your brand is limited in the amount of M2M tokens that can be requested per day.
Please make sure to cache the token and only request a new one when the current one expires.

Glossary

Entities

Brand

  • Is created by the Showroom upon on-boarding
  • Is the top-level entity in the system.
  • Is identified by a short alphabetical code.
  • All entities in the system are tied to a particular brand. For example, theming information, divisions, seasons, options, etc

Division

  • Is a "sub-brand" within a brand.
  • Creates a strict separation between collections within one brand.
  • Options can not be shared between Divisions.

Season

  • Is a part of a Division
  • A set period of time in which a catalog of products is being sold.
  • Can be limited in time with start or/and end dates.
  • Options and marketing materials are available within a season.

Delivery Drop

  • A single possible delivery drop (a.k.a. delivery window) at which option can be delivered
  • Is assigned to multiple Seasons
  • Is assigned to multiple Options
  • Availability is always limited by seasons availability

Option

  • Is a combination of style and color in the Showroom system.
  • Has a list of media items (images and videos) and media3D items attached to it.

Size

  • Is assigned to the Options
  • Represents the lowest level of granularity for a product that can be ordered.
  • Can be either a single item, or a pack of items of the same Option.
  • Can have multiple dimensions and order constraints
  • Is shown on the PDP and in the order review documents.

Price

  • Is assigned to the Options on the size level.
  • Is shown on the PDP and in the order review documents.

Customer

  • Is a top-level entities to define your real-world customers
  • Is a used only to group Locations

Location

  • Is used to define real-world stores (doors).
  • Can have Price Groups and Currency assigned to show different Prices (price segmentation)
  • Can be limited to a set of users or be available to everyone within a brand

Media

Showroom uses 2 types of media (images/videos) assets:

  • Option media to display on the PDP, Laydown, Product Catalog, etc.
  • Seasonal marketing content like Looks, marketing videos, etc.

Asset

Are marketing materials used as a sales aid, showcasing a few options to be matched together.

  • Can be added to the presentation laydowns
  • Options can be linked to any Asset
  • During a presentation, a customer will see only the products that are available in its market segment

Asset Group

An entity which acts like a folder to group related assets together in one place.

  • Can be assigned a list of tags for easy filtering
  • Can have a name and description to be identified quickly and easily

Stock

Is the stock level of a particular SKU of an option

  • Stock data is not mandatory for the Showroom to work. If no stock data is provided, the system will assume that the stock level is unlimited.
  • Can be tied to a specific warehouse using the stockReferenceCode field. Same field is added to the customer Location entity to link the location to the warehouse. If stockReferenceCode is not set, the stock is assumed to be across all warehouses.
  • Stock code should be a unique identifier for a particular stock entity. For example if a stock entity has a stockReferenceCode, then code should be unique for that stockReferenceCode and SKU combination. The same applies if deliveryDropCode is set. In this case code should be unique for that deliveryDropCode and SKU combination and so on.
  • Can be soft deleted by setting the isActive field to false.

User

Is representation of a system user within the Showroom.

  • Can have different roles. The list of roles is available in the API endpoint documentation.
  • Can have access to multiple brands.

Order

Is the output of any sales appointment. Consider it a draft order to be imported to the next processing system.

  • Contains an order line per delivery date/option/size

Brand Catalog

Is an implementation of catalog and customer segmentation features.

  • Each presentation uses a catalog as a base for it's collection
  • Can be limited to a set of customers, locations, or/and users

Key DS components

Look Catalog

Is a catalog available to the user inside the presentation and used to browse Looks available within the Season/Division

Product Catalog

Is a catalog available to the user inside the presentation and used to browse Options available within the Season/Division

  • Only Options that are available to the market segment of the presentation customer are shown.

CMS

Is a Content Management System within the Showroom to configure Brand settings from the UI The CMS can be used for:

  • setting Brand-specific theming
  • managing Looks
  • updating Seasonal presentation settings (idle screens, landing pages, etc.)

LDP

Is a Look Detail Page that displays a single Look with additional information attached.

PDP

Is a Product Detail Page that displays a single Option with additional information attached (prices, color variations, etc.)

Assortment

Is a slide within a presentation.

Laydown

Is a central part of the presentation assortment where the user adds Options, Looks and text.

Fashion terminology

Market segmentation

The process of dividing a target market into smaller, more defined categories. It segments customers and audiences into groups with similar characteristics, such as demographics, interests, needs, or location.

Price segmentation

The process of charging different prices for the same or similar product or service based on internal business rules.

  • To create price segmentation the Showroom uses the concept of Price Groups with Currency
  • Price Groups and Currency must be assigned to Locations
  • Price Groups and Currency must be provided for each Price

    TBD;

Changelog

Option V2

What changed in V2:

  • New option endpoints /v2/option/{action}
  • tags was renamed to attributes, structure kept the same.
  • categories was renamed to productHierarchy and a new structure was introduced.
  • removed deprecated fields from V1.

Customers

Get

Fetch a single customer document with a set of underlying locations (by IDs).

Authorizations:
Bearer
Request Body schema: application/json
customerID
required
string (CustomerID is the internal customer identifier)
locationIDs
Array of strings (List of locationIDs which are the internal location identifiers)

Responses

Request samples

Content type
application/json
{
  • "customerID": "string",
  • "locationIDs": [
    ]
}

Response samples

Content type
application/json
{
  • "brandCode": "HAT",
  • "customerCode": "HAT5",
  • "id": "CUSTOMER_HAT_HAT5",
  • "locations": [
    ],
  • "name": "Vans customer 5",
  • "phone": "001-908-397-6122x5657",
  • "vatNumber": "002595"
}

GetByCode

Fetch a single customer document with a set of underlying locations (by Code).

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string (brandCode of the customer)
customerCode
required
string (customerCode is the code of the customer)
locationCodes
Array of strings (List of locationCodes which are the location identifiers)

Responses

Request samples

Content type
application/json
{
  • "brandCode": "string",
  • "customerCode": "string",
  • "locationCodes": [
    ]
}

Response samples

Content type
application/json
{
  • "brandCode": "HAT",
  • "customerCode": "HAT5",
  • "id": "CUSTOMER_HAT_HAT5",
  • "locations": [
    ],
  • "name": "Vans customer 5",
  • "phone": "001-908-397-6122x5657",
  • "vatNumber": "002595"
}

Upsert

Create or Update existing customer entity. The uniqueness of the customer is determined by the customerCode (provided by the client during creation).

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string (Brand identifier that the customer belongs to)
customerCode
required
string (Uniquely identifies the customer in the brand's internal systems e.g. CRM)
name
required
string (Name of the customer)
phone
string (Main phone number of the customer)
vatNumber
string (VAT number of the customer)

Responses

Request samples

Content type
application/json
{
  • "brandCode": "string",
  • "customerCode": "string",
  • "name": "string",
  • "phone": "string",
  • "vatNumber": "string"
}

Response samples

Content type
application/json
{
  • "brandCode": "HAT",
  • "customerCode": "FOO",
  • "id": "CUSTOMER_HAT_FOO",
  • "name": "Customer name",
  • "phone": "+31629468500",
  • "vatNumber": "NL12345678B01"
}

Locations

Get

Fetch a single location by its internal ID

Authorizations:
Bearer
Request Body schema: application/json
locationID
required
string (LocationID is the internal location ID)

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "addressLine1": "addrline1",
  • "addressLine2": "addrline2",
  • "brandCode": "HAT",
  • "brandUserIds": [
    ],
  • "city": "The City",
  • "country": "NL",
  • "currency": "DKK",
  • "customerCode": "HAT5",
  • "divisionCodes": [
    ],
  • "id": "LOCATION_HAT_HAT141",
  • "isActive": true,
  • "languageCode": "en-US",
  • "locationCode": "HAT141",
  • "locationType": [
    ],
  • "name": "Name loc foo",
  • "postalCode": "1234AB",
  • "priceGroups": [
    ],
  • "stateProvince": "The Province of the State",
  • "stockReferenceCodes": [
    ]
}

GetByBrandUserIDs

DEPRECATED: use GetList instead

Fetch locations by list of brandUserIDs. Response will return a list of locations with at least one of the brandUserIDs from the request set on the location

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string (brandCode of the customer)
brandUserIDs
required
Array of strings (brandUserIDs that have access to locations)

Responses

Request samples

Content type
application/json
{
  • "brandCode": "string",
  • "brandUserIDs": [
    ]
}

Response samples

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

GetByCodes

DEPRECATED: use GetList instead

Fetch locations by their codes

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string (brandCode of the customer)
locationCodes
required
Array of strings (List of locationCodes which are the location identifiers)

Responses

Request samples

Content type
application/json
{
  • "brandCode": "string",
  • "locationCodes": [
    ]
}

Response samples

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

GetList

Fetch locations by multiple parameters.

Authorizations:
Bearer
Request Body schema: application/json

GetLocationList returns Locations filtered by a number of parameters. Returns up to a 100 locations if no pagination is provided.

brandCode
required
string (brandCode of the customer)
brandUserIDs
Array of strings

List of brandUserIDs that have access to locations. When not specified or empty, no filtering by brandUserIDs codes happens.

customerCodes
Array of strings

List of customerCodes locations belong to. When not specified or empty, no filtering by customer codes happens.

divisionCodes
Array of strings

List of divisionCodes locations are related to. When not specified or empty, no filtering by division codes happens.

isActiveOnly
boolean
Default: "false"

Whether or not filter out inactive locations.

locationCodes
Array of strings

List of locationCodes which are the location identifiers. When not specified or empty, no filtering by location codes happens.

object (customer.Pagination)

Responses

Request samples

Content type
application/json
{
  • "brandCode": "string",
  • "brandUserIDs": [
    ],
  • "customerCodes": [
    ],
  • "divisionCodes": [
    ],
  • "isActiveOnly": true,
  • "locationCodes": [
    ],
  • "pagination": {
    }
}

Response samples

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

Upsert

Create or Update location entity. Uniqueness is determined by the locationCode (provided by the client during creation). You can deactivate a location by updating the entity to have isActive set to false, by doing so it will not be available during the presentation creation/to any user.

Authorizations:
Bearer
Request Body schema: application/json
addressLine1
string (Primary location address information)
addressLine2
string (Optional additional location address information)
allowUIEmailUpdates
boolean (Defines whether the location's buyer email list can be updated from the ui - defaults to false)
brandCode
required
string (Brand identifier that the location belongs to)
brandUserIds
Array of strings (A list of brand user IDs which have access to this location)

If value is not set or it is an empty list, location will be available to ALL users. If no user codes match existing users, location will not be available.

buyerEmails
Array of strings (A list of buyer emails that should be on the mailing list regarding this location)
city
string (Location town or city)
country
string (Country of the location)
currency
required
string (The currency for the price group of this location. Should be ISO 4217 3-letter)
customerCode
required
string

Customer identifier that the location belongs to. The value should match an existing Customer.customerCode. Locations without existing Customers will not be displayed in the system.

divisionCodes
required
Array of strings (A list of all division codes to which the location has access)

If division code does not match any existing division.divisionCode, location will not be available.

isActive
boolean (IsActive defines whether the customer location is active and therefore able to buy)

If set to false, location will not appear in the showroom UI.

languageCode
string (Defines the language preference of the location. To note; we currently do not provide multi-lingual support)
locationCode
required
string (Uniquely identifies the location in the brand's internal systems e.g. CRM)
locationType
required
Array of strings (Defines whether the location is a store, warehouse or invoice address (sometimes referred to as point of sale, ship-to, invoice-to))

Options: SellTo, ShipTo, InvoiceTo

name
required
string (Name of the location)
postalCode
string (Location postal code)
priceGroups
required
Array of strings (A list of all price groups codes to which the location is assigned)

All the product options will be filtered by the price availability within one currency+priceGroup combination. Make sure, your customer locations have proper groups assigned.

stateProvince
string (Location state, province or administrative area (depending on country))
stockReferenceCodes
Array of strings

A list of stock reference codes of this location - used to calculate stock availability (e.g. a list of warehouses that the location can order from).

Stock will be aggregated across all matching stock reference codes. If stock reference codes do not match any existing stock.stockReferenceCode, location will show all products as out of stock. If no stock reference codes are provided, location will show all aggregated stock.

Responses

Request samples

Content type
application/json
{
  • "addressLine1": "string",
  • "addressLine2": "string",
  • "allowUIEmailUpdates": true,
  • "brandCode": "string",
  • "brandUserIds": [
    ],
  • "buyerEmails": [
    ],
  • "city": "string",
  • "country": "string",
  • "currency": "string",
  • "customerCode": "string",
  • "divisionCodes": [
    ],
  • "isActive": true,
  • "languageCode": "string",
  • "locationCode": "string",
  • "locationType": [
    ],
  • "name": "string",
  • "postalCode": "string",
  • "priceGroups": [
    ],
  • "stateProvince": "string",
  • "stockReferenceCodes": [
    ]
}

Response samples

Content type
application/json
{
  • "addressLine1": "Google maps, cell 862/17",
  • "brandCode": "HAT",
  • "city": "NonExisting",
  • "country": "USA",
  • "currency": "USD",
  • "customerCode": "CUST01",
  • "divisionCodes": [
    ],
  • "id": "LOCATION_HAT_LOC01",
  • "isActive": true,
  • "languageCode": "en_US",
  • "locationCode": "LOC01",
  • "locationType": [
    ],
  • "name": "Central location of supercustomer 1",
  • "postalCode": "862/172225",
  • "priceGroups": [
    ],
  • "stateProvince": "LA",
  • "stockReferenceCodes": [
    ]
}

Bulk Upsert

Upsert multiple locations at once. Maximum 1000 locations per request.

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string <string> (Brand code)

Brand code issued by the showroom

required
Array of objects (Locations)

list of locations to upsert

Responses

Request samples

Content type
application/json
{
  • "brandCode": "HAT",
  • "locations": [
    ]
}

Response samples

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

Brands

Get

Get Brand by brandCode

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string (BrandCode is the unique code of the brand and it is used as the main identifier of the brand)

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "brandCode": "HAT",
  • "divisions": {
    },
  • "isActive": true,
  • "name": "Name",
  • "theme": {
    }
}

UpdateSizeConfig

UpdateSizeConfig by brandCode

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string (BrandCode is the unique code of the brand and it is used as the main identifier of the brand)
object (SizeConfig to set the order of sizes shown in the size tables)

Responses

Request samples

Content type
application/json
{
  • "brandCode": "string",
  • "sizeConfig": {
    }
}

Response samples

Content type
application/json
{
  • "mainSizeOrder": [
    ],
  • "subSizeOrder": {
    }
}

Divisions

Get

Get a division of a brand by divisionCode and brandCode.

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string (BrandCode that this division belongs to)
divisionCode
required
string (DivisionCode used by the brand internally, for example, in their ERP system, to uniquely identify a division)

Responses

Request samples

Content type
application/json
{
  • "brandCode": "string",
  • "divisionCode": "string"
}

Response samples

Content type
application/json
{
  • "divisionCode": "DIV1",
  • "seasons": {
    }
}

Upsert

Create or Update an existing division. The uniqueness of the division is determined by divisionCode and brandCode.

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string (BrandCode that this division belongs to)
divisionCode
required
string (DivisionCode used by the brand internally, for example, in their ERP system, to uniquely identify a division)
name
required
string (Name of the division, to be used in the user interface of the digital showroom)

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "divisionCode": "DIV1",
  • "name": "Division 1",
  • "seasons": {
    }
}

Seasons

Get

Get a season of a brand by seasonCode, divisionCode and brandCode.

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string (BrandCode that this season belongs to)
divisionCode
required
string (DivisionCode that this season belongs to)
seasonCode
required
string (SeasonCode used by the brand internally to uniquely identify the season)

Responses

Request samples

Content type
application/json
{
  • "brandCode": "string",
  • "divisionCode": "string",
  • "seasonCode": "string"
}

Response samples

Content type
application/json
{
  • "brandCode": "HAT",
  • "divisionCode": "DIV1",
  • "market": "m",
  • "name": "summer 2020",
  • "orderEndDate": "2009-02-13T23:31:31Z",
  • "orderStartDate": "2009-02-13T23:31:30Z",
  • "seasonCode": "S1"
}

Upsert

Create or Update an existing season. The uniqueness of the season is determined by seasonCode, divisionCode and brandCode.

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string (BrandCode that this season belongs to)
divisionCode
required
string (DivisionCode that this season belongs to)
market
string (If the products in a catalog are unique for a particular market, this should be populated)
name
required
string (Name of the season, to be used in the user interface of the digital showroom)
orderEndDate
string (Last date on which products in the season are available for ordering This is leading when determining whether a presentation can be created for products in a season If there are products available in the season with a later order end date, they will not be able to be ordered after the season has ended)
orderStartDate
required
string (Start date from which products in the season are available for ordering This is leading when determining whether a presentation can be created for products in a season If there are products available in the season with an earlier order start date, they will not be able to be ordered until the season start date is reached)
seasonCode
required
string (SeasonCode used by the brand internally to uniquely identify the season)

Responses

Request samples

Content type
application/json
{
  • "brandCode": "string",
  • "divisionCode": "string",
  • "market": "string",
  • "name": "string",
  • "orderEndDate": "string",
  • "orderStartDate": "string",
  • "seasonCode": "string"
}

Response samples

Content type
application/json
{
  • "brandCode": "HAT",
  • "divisionCode": "D1",
  • "market": "m",
  • "name": "summer 2020",
  • "orderEndDate": "2009-02-13T23:31:31Z",
  • "orderStartDate": "2009-02-13T23:31:30Z",
  • "seasonCode": "S1"
}

Delivery Drops

GetByCode

Get a delivery drops of a brand by code

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string (The brand code assigned by the showroom)
codes
required
Array of strings (A list of delivery drop codes used during the DeliveryDrop creation)

Responses

Request samples

Content type
application/json
{
  • "brandCode": "string",
  • "codes": [
    ]
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

GetByIds

Get a delivery drops of a brand by ID

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string (The brand code assigned by the showroom)
ids
required
Array of strings (A list of Showroom unique ids)

Responses

Request samples

Content type
application/json
{
  • "brandCode": "string",
  • "ids": [
    ]
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

GetBySeason

Get delivery drops of a brand by season codes

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string (The brand code assigned by the showroom)
seasonCodes
required
Array of strings (A list of season codes used during the Season creation)

Responses

Request samples

Content type
application/json
{
  • "brandCode": "string",
  • "seasonCodes": [
    ]
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Upsert

Create or Update an existing DeliveryDrop.

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string <string> (Brand code)

Brand code issued by the showroom

code
required
string <string> (Code)

A value used on the brand side to uniquely identify the delivery drop

index
integer <integer> (Delivery Drop index)

A numeric value to sort delivery drops. If 2 indexes are equal, the order is not determined. Values from -2,147,483,648 to 2,147,483,647 are supported. default: 0

isActive
boolean <boolean> (Is active?)

Indicates whether DeliveryDrop is active. Basically a soft-delete functionality

name
required
string <string> (Delivery Name)

Name of the delivery drop visible to the users

seasonCodes
required
Array of strings <string> (Season codes)

A list of season codes in which this delivery drop can be used. Seasons should exist.

Responses

Request samples

Content type
application/json
{
  • "brandCode": "HAT",
  • "code": "delivery_42",
  • "index": 42,
  • "isActive": true,
  • "name": "Holidays",
  • "seasonCodes": [
    ]
}

Response samples

Content type
application/json
{
  • "brandCode": "HAT",
  • "code": "delivery_42",
  • "id": "DELIVERY_DROP_DELIVERY_42",
  • "index": 7,
  • "isActive": "true",
  • "name": "Holidays",
  • "seasonCodes": [
    ]
}

Options V1

GetByCodes

DEPRECATED: use GetByCodes in Options V2 instead

Fetch options by external code

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string (brand identifier that the option belongs to)
codes
required
Array of strings (external code of options for fetching)

Responses

Request samples

Content type
application/json
{
  • "brandCode": "string",
  • "codes": [
    ]
}

Response samples

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

GetByIDs

DEPRECATED: use GetByIDs in Options V2 instead

Fetch options by internal ids and optional price filters

Authorizations:
Bearer
Request Body schema: application/json
object (Is used to filter options by the price availability)
ids
required
Array of strings (internal ids of options for fetching)

Responses

Request samples

Content type
application/json
{
  • "filtersByPrice": {
    },
  • "ids": [
    ]
}

Response samples

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

SetMediaByCodes

DEPRECATED: use SetMediaByCodes in Options V2 instead

Attaches the media by their internal ids to the option by option code Multiple options/media combination can be requested under the same brandCode

Authorizations:
Bearer
Request Body schema: application/json

Deprecated: use SetMediaByCodesV2Request instead

brandCode
string <string> (Brand Code)

brand identifier that the options and media belong to

Array of objects (Options)

list of options and their media IDs

Responses

Request samples

Content type
application/json
{}

Response samples

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

Upsert

DEPRECATED: use Upsert in Options V2 instead

Create or Update an option by option code

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string (brand identifier that the option belongs to)
categories
required
Array of strings (list of categories that the option belongs to)
colorCode
required
string (brand-specific color or pattern code of the option this is the code that will shown as the code of the option color in the catalog)
colorName
required
string (brand-specific color or pattern name of the option this is the name that will shown as the name of the option color in the catalog)
countryOfOrigin
string (country of origin of the option)
deliveryDates
Array of strings (Use delivery drop codes instead. List of available delivery dates of the option)

Deprecated: Use deliveryDropCodes field instead

deliveryDropCodes
Array of strings (list of available delivery drop codes of the option)
description
required
string (style description. Used as title of the option in lists and detail pages)
divisionCode
required
string

division code to which this option belongs should match an existing Division.division.Code to be displayed.

Array of objects (extra information to be attached to this option)
gender
required
string (gender (and age) categorisation of a style)
isActive
boolean

whether the option is active or not. Active works as a soft delete where the product is no longer shown in the catalog and will not be available to order in case it is set to false.

optionCode
required
string (unique identifier for an option. For most brands this field is the combination of styleCode and colorCode)
seasonCodes
required
Array of strings (list of season codes in which the option is available for selling)
sizes
Array of strings (list of available sizes)

Deprecated: Use Size entity per SKU instead

status
string (the status of the option. This may drive how the option appears in the digital showroom. Does not affect product availability in the system)

Options: soldout, cancelled, new, updated

styleCode
required
string (unique identifier for a style)
Array of objects (list of tags to describe the option)

Responses

Request samples

Content type
application/json
{
  • "brandCode": "string",
  • "categories": [
    ],
  • "colorCode": "string",
  • "colorName": "string",
  • "countryOfOrigin": "string",
  • "deliveryDates": [
    ],
  • "deliveryDropCodes": [
    ],
  • "description": "string",
  • "divisionCode": "string",
  • "fields": [
    ],
  • "gender": "string",
  • "isActive": true,
  • "optionCode": "string",
  • "seasonCodes": [
    ],
  • "sizes": [
    ],
  • "status": "string",
  • "styleCode": "string",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "brandCode": "HAT",
  • "categories": [
    ],
  • "colorCode": "011",
  • "colorName": "Black",
  • "countryOfOrigin": "coo valid",
  • "deliveryDropCodes": [
    ],
  • "description": "Lorem ipsum dolor sit amet",
  • "divisionCode": "div42",
  • "fields": [
    ],
  • "gender": "reptiloid",
  • "id": "OPTION_HAT_OPTIONCODE",
  • "isActive": true,
  • "modifiedAt": "2020-09-24T14:22:23Z",
  • "optionCode": "someCode",
  • "seasonCodes": [
    ],
  • "sizes": [
    ],
  • "status": "new",
  • "styleCode": "DM0DM03810911",
  • "tags": [
    ]
}

Options V2

Fetch

Fetch options by external code

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string (brand identifier that the option belongs to)
codes
required
Array of strings (external code of options for fetching)

Responses

Request samples

Content type
application/json
{
  • "brandCode": "string",
  • "codes": [
    ]
}

Response samples

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

Fetch Options List

Fetch filtered list of options

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string ((Required) Brand code issued by Stitch - if brandCode is the only filter provided then Pagination is mandatory)
divisionCodes
Array of strings ((Optional) list of division codes that options belong to)
isActiveOnly
boolean ((Optional) if set to true will only return active options)
modifiedAfter
string <date-time> ((Optional) return options that have a last modified date after the provided timestamp)
modifiedBefore
string <date-time> ((Optional) return options that have a last modified date before the provided timestamp)
optionCodes
Array of strings ((Optional) list of option unique identifiers)
object (Pagination is used to paginate the stock items)
seasonCodes
Array of strings ((Optional) list of season codes that options belong to)

Responses

Request samples

Content type
application/json
{
  • "brandCode": "string",
  • "divisionCodes": [
    ],
  • "isActiveOnly": true,
  • "modifiedAfter": "2019-08-24T14:15:22Z",
  • "modifiedBefore": "2019-08-24T14:15:22Z",
  • "optionCodes": [
    ],
  • "pagination": {
    },
  • "seasonCodes": [
    ]
}

Response samples

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

Attach media

Attaches the media by their internal ids to the option by option code Multiple options/media combination can be requested under the same brandCode

Authorizations:
Bearer
Request Body schema: application/json
brandCode
string <string> (Brand Code)

brand identifier that the options and media belong to

Array of objects (Options)

list of options and their media IDs

Responses

Request samples

Content type
application/json
{}

Response samples

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

Upsert

Create or Update an option by option code

Authorizations:
Bearer
Request Body schema: application/json
Array of objects (list of option attributes. Attributes describe specific characteristics of the option and are used for filtering and search)
brandCode
required
string (brand identifier that the option belongs to)
colorCode
required
string (brand-specific color or pattern code of the option this is the code that will shown as the code of the option color in the catalog)
colorName
required
string (brand-specific color or pattern name of the option this is the name that will shown as the name of the option color in the catalog)
countryOfOrigin
string (country of origin of the option)
deliveryDropCodes
Array of strings (list of available delivery drop codes of the option)
description
required
string (style description. Used as title of the option in lists and detail pages)
divisionCode
required
string

division code to which this option belongs should match an existing Division.division.Code to be displayed.

Array of objects (extra information to be attached to this option)
gender
required
string (gender (and age) categorisation of a style)
isActive
boolean

whether the option is active or not. Active works as a soft delete where the product is no longer shown in the catalog and will not be available to order in case it is set to false.

optionCode
required
string (unique identifier for an option. For most brands this field is the combination of styleCode and colorCode)
required
object (productHierarchy described with two levels)
seasonCodes
required
Array of strings (list of season codes in which the option is available for selling)
status
string (the status of the option. This may drive how the option appears in the digital showroom)
styleCode
required
string (unique identifier for a style)

Responses

Request samples

Content type
application/json
{
  • "attributes": [
    ],
  • "brandCode": "string",
  • "colorCode": "string",
  • "colorName": "string",
  • "countryOfOrigin": "string",
  • "deliveryDropCodes": [
    ],
  • "description": "string",
  • "divisionCode": "string",
  • "fields": [
    ],
  • "gender": "string",
  • "isActive": true,
  • "optionCode": "string",
  • "productHierarchy": {
    },
  • "seasonCodes": [
    ],
  • "status": "string",
  • "styleCode": "string"
}

Response samples

Content type
application/json
{
  • "attributes": [
    ],
  • "brandCode": "HAT",
  • "colorCode": "011",
  • "colorName": "Black",
  • "countryOfOrigin": "coo valid",
  • "deliveryDropCodes": [
    ],
  • "description": "Loremipsumdolor sitamet",
  • "divisionCode": "div42",
  • "fields": [
    ],
  • "gender": "reptiloid",
  • "id": "OPTION_HAT_OPTIONCODE",
  • "isActive": true,
  • "modifiedAt": "2020-09-24T14:22:23Z",
  • "optionCode": "someCode",
  • "productHierarchy": {
    },
  • "seasonCodes": [
    ],
  • "sizes": [
    ],
  • "status": "new",
  • "styleCode": "DM0DM03810911"
}

Attach images

Attaches images to options by their media codes. Multiple options can be upserted at once. The order of which the image codes are sent determines the order they appear on the product detail page.

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string <string> (Brand Code)

brand identifier that the options and media belong to

Array of objects (Options)

list of options and their image media codes

Responses

Request samples

Content type
application/json
{
  • "brandCode": "HAT",
  • "options": [
    ]
}

Response samples

Content type
application/json
{
  • "brandCode": "HAT",
  • "options": [
    ]
}

Attach videos

Attaches videos to options by their media codes. Multiple options can be upserted at once. The order of which the video codes are sent determines the order they appear on the product detail page.

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string <string> (Brand Code)

brand identifier that the options and media belong to

Array of objects (Options)

list of options and their video media codes

Responses

Request samples

Content type
application/json
{
  • "brandCode": "HAT",
  • "options": [
    ]
}

Response samples

Content type
application/json
{
  • "brandCode": "HAT",
  • "options": []
}

Prices

OptionPrices

fetch prices of options by option ids, currency, priceGroupID for a specific brandCode

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string (brand identifier that the option price belongs to)
currency
required
string (currency for the price group. ISO 4217 3-letter currency code)
optionIDs
required
Array of strings (list of internal option ids)
priceGroupID
required
string (unique identifier for the price group as set by the brand)

Responses

Request samples

Content type
application/json
{
  • "brandCode": "string",
  • "currency": "string",
  • "optionIDs": [
    ],
  • "priceGroupID": "string"
}

Response samples

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

Upsert

Create or Update an option price by the brand priceCode identifier

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string (brand identifier that the option price belongs to)
currency
required
string (currency for the price group. ISO 4217 3-letter currency code)
optionCode
required
string (unique identifier for an option. For most brands this field is the combination of styleCode and colorCode)
priceCode
required
string (unique identifier for the price)
priceGroupID
required
string (unique identifier for the price group as set by the brand)
required
Array of objects (list of price details per size)
validFrom
string (start of validity window for the price (i.e.: for a discount for a specific period, or for an upcoming price change) Leave empty if it is valid immediately)
validTo
string (end of validity window for this price Leave empty if it is valid eternally, or until further notice)

Responses

Request samples

Content type
application/json
{
  • "brandCode": "string",
  • "currency": "string",
  • "optionCode": "string",
  • "priceCode": "string",
  • "priceGroupID": "string",
  • "pricePerSize": [
    ],
  • "validFrom": "string",
  • "validTo": "string"
}

Response samples

Content type
application/json
{
  • "brandCode": "HAT",
  • "currency": "USD",
  • "id": "PRICE_HAT_SOMEPRICECODE",
  • "optionCode": "SOMEOPTIONCODE",
  • "priceCode": "somePriceCode",
  • "priceGroupID": "1",
  • "pricePerSize": [
    ],
  • "styleOptionID": "OPTION_HAT_SOMEOPTIONCODE",
  • "validFrom": "2020-02-04T15:03:24Z",
  • "validTo": "2021-02-03T15:03:24Z"
}

BulkUpsert

create or update an option price by the brand priceCode identifier

Bulk Upsert is limited to 1000 prices per request

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string
required
Array of objects (Prices)

list of prices to upsert

Responses

Request samples

Content type
application/json
{
  • "brandCode": "string",
  • "prices": [
    ]
}

Response samples

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

Sizes

Get by Option codes

Fetch sizes and prepacks assigned to options by their codes

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string <string> (Brand code)

Brand code issued by the showroom

optionCodes
required
Array of strings <string> (Option codes)

A list of option codes assigned during import

Responses

Request samples

Content type
application/json
{
  • "brandCode": "string",
  • "optionCodes": [
    ]
}

Response samples

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

Get List

fetch a list of sizes and prepacks based on the provided filters

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string ((Required) Brand code)
isActiveOnly
boolean ((Optional) Whether to return only active sizes. Note that inactive sizes might be available via prepacks)
modifiedAfter
string <date-time> ((Optional) Only return sizes that have been modified after the provided timestamp)
modifiedBefore
string <date-time> ((Optional) Only return sizes that have been modified before the provided timestamp)
optionCodes
Array of strings ((Optional) List of option codes)
object (Pagination is used to paginate the stock items)

Responses

Request samples

Content type
application/json
{
  • "brandCode": "string",
  • "isActiveOnly": true,
  • "modifiedAfter": "2019-08-24T14:15:22Z",
  • "modifiedBefore": "2019-08-24T14:15:22Z",
  • "optionCodes": [
    ],
  • "pagination": {
    }
}

Response samples

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

Upsert

create or update an option size or prepack by SKU field value

Authorizations:
Bearer
Request Body schema: application/json

Each size represents a unique set of dimensions for a particular option. Use Size field to specify the main dimention and subSizes map to add additional ones. Combination of Size and all the subsizes should be unique as it can be shown to a user in a table view.

brandCode
required
string <string> (Brand code)

Brand code issued by the showroom

object <map> (is a set of rules enforced upon the item during the draft order creation Options: `minimum: <int>`, `multiplier: <int>`)

Is a set of rules enforced upon the item during the draft order creation

isActive
boolean <boolean> (a field to soft-delete or disable sizes from the API)

A field to soft-delete or disable sizes from the API. Even if the size is inactive, it can be available via prepacks

optionCode
required
string <string> (Option code)

Code of the product option to which this size belongs

Array of objects (catalog.PackItem)

If this size is a prepack, this field will contain the items in the prepack. If this size is not a prepack, this field will be empty

size
required
string <string> (the human-readable size name that will be displayed for the users)

The human-readable size name that will be displayed for the users

sku
required
string <string> (SKU)

This field can store any identifier that is unique on the client side. Can be sku/ean/internal id. The value will be used as the main identifier for the order line.

object <map> (is useful for the multidimentional sizes like pants or bras. For example, "inseam":"32")

An additional size dimensions for the main size. Is useful for the multidimentional sizes like pants or bras. Does not apply to prepacks

Responses

Request samples

Content type
application/json
{
  • "brandCode": "HAT",
  • "constraints": {
    },
  • "isActive": true,
  • "optionCode": "OPTIONCODE1",
  • "packItems": [
    ],
  • "size": "30",
  • "sku": "OPTIONCODE1.M42.30",
  • "subSizes": {
    }
}

Response samples

Content type
application/json
{
  • "brandCode": "HAT",
  • "constraints": {
    },
  • "id": "SIZE_HAT_OPTIONCODE1.M42.30",
  • "isActive": true,
  • "optionCode": "OPTIONCODE1",
  • "optionID": "OPTION_HAT_OPTIONCODE1",
  • "size": "30",
  • "sku": "OPTIONCODE1.M42.30",
  • "subSizes": {
    }
}

Bulk Upsert

Bulk Upsert is a request to upsert many sizes or prepacks at once

Bulk Upsert is limited to 1000 sizes per request

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string <string> (Brand code)

Brand code issued by the showroom

required
Array of objects (Sizes)

list of sizes to upsert

Responses

Request samples

Content type
application/json
{
  • "brandCode": "HAT",
  • "sizes": [
    ]
}

Response samples

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

Catalogs

GetByCode

Get a catalog by it's code assigned during the creation

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string <string> (Brand code)

Brand code issued by the showroom

code
required
string <string> (Code)

A value used on the brand side to uniquely identify the catalog

Responses

Request samples

Content type
application/json
{
  • "brandCode": "HAT",
  • "code": "CATALOG_42"
}

Response samples

Content type
application/json
{
  • "availCustomerCodes": [
    ],
  • "availLocationCodes": [
    ],
  • "availUserCodes": [
    ],
  • "brandCode": "HAT",
  • "code": "CATALOG_42",
  • "createdAt": "2021-10-06T11:19:54Z",
  • "id": "CATALOG_HAT_CATALOG_42",
  • "isActive": true,
  • "modifiedAt": "2021-10-06T11:19:54Z",
  • "name": "Premium season Summer/Fall 2022",
  • "selDeliverydropCodes": [
    ],
  • "selDivisionCodes": [
    ],
  • "selOptionCodes": [
    ],
  • "selSKUs": [
    ],
  • "selSeasonCodes": [
    ],
  • "selStyleCodes": [
    ]
}

GetUserCatalogs

Find User/Custom Catalogs within a brand

Authorizations:
Bearer
Request Body schema: application/json
brandCatalogCodes
Array of strings <string> (Code of the parent Brand Catalog)

A list of brand catalog codes to filter

brandCode
required
string <string> (Brand code)

Brand code issued by the showroom

codes
Array of strings <string> (Codes)

A list of user Catlaog codes to fetch upon

userCodes
Array of strings <string> (User codes)

A list of user codes codes to filter

Responses

Request samples

Content type
application/json
{
  • "brandCatalogCodes": [
    ],
  • "brandCode": "HAT",
  • "codes": [
    ],
  • "userCodes": [
    ]
}

Response samples

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

UpsertBrandCatalog

Upsert new or existing Brand Catalog

Authorizations:
Bearer
Request Body schema: application/json
availCustomerCodes
Array of strings <string> (List of customer codes)

list of customers that can be used to create presentations with this catalog. Empty list means that all customers can be used with this catalog

availLocationCodes
Array of strings <string> (List of location codes)

list of locations that can be used to create presentations with this catalog. Empty list means that all locations can be used with this catalog

availUserCodes
Array of strings <string> (List of user codes)

list of users that can access this catalog. Empty list means that all users can use this catalog to create presentations

brandCode
required
string <string> (Brand code)

Brand code issued by the showroom

code
required
string <string> (Code)

A value used on the brand side to uniquely identify the catalog

isActive
boolean <boolean> (is a toggle for the soft delete)
Default: "false"

A field to soft-delete or disable a catalog from the API

name
required
string <string> (Name)

name of a catalog to be shown on the UI

selDeliverydropCodes
Array of strings <list> (Selector by Delivery Drop Codes)

list of delivery drop codes to filter options upon. Empty list means that all delivery drops are available within the catalog

selDivisionCodes
Array of strings <list> (Selector by Division Codes)

list of division codes to filter options upon. Empty list means that all divisions are available within the catalog

selOptionCodes
Array of strings <list> (Selector by Option Codes)

list of option codes to filter the collection upon. Empty list means that all options are available within the catalog

selSKUs
Array of strings <list> (Selector by SKU)

list of SKUs to filter options upon. Empty list means that all SKUs are available within the catalog

selSeasonCodes
Array of strings <list> (Selector by Season Codes)

list of season codes to filter options upon. Empty list means that all seasons are available within the catalog

selStyleCodes
Array of strings <list> (Selector by Style Codes)

list of stlye codes to filter options upon. Empty list means that all styles are available within the catalog

Responses

Request samples

Content type
application/json
{
  • "availCustomerCodes": [
    ],
  • "availLocationCodes": [
    ],
  • "availUserCodes": [
    ],
  • "brandCode": "HAT",
  • "code": "CATALOG_42",
  • "isActive": true,
  • "name": "Premium season Summer/Fall 2022",
  • "selDeliverydropCodes": [
    ],
  • "selDivisionCodes": [
    ],
  • "selOptionCodes": [
    ],
  • "selSKUs": [
    ],
  • "selSeasonCodes": [
    ],
  • "selStyleCodes": [
    ]
}

Response samples

Content type
application/json
{
  • "availCustomerCodes": [
    ],
  • "availLocationCodes": [
    ],
  • "availUserCodes": [
    ],
  • "brandCode": "HAT",
  • "code": "CATALOG_42",
  • "createdAt": "2021-10-06T11:19:54Z",
  • "id": "CATALOG_HAT_CATALOG_42",
  • "isActive": true,
  • "modifiedAt": "2021-10-06T11:19:54Z",
  • "name": "Premium season Summer/Fall 2022",
  • "selDeliverydropCodes": [
    ],
  • "selDivisionCodes": [
    ],
  • "selOptionCodes": [
    ],
  • "selSKUs": [
    ],
  • "selSeasonCodes": [
    ],
  • "selStyleCodes": [
    ]
}

UpsertUserCatalogs

Upsert new or existing User(Custom) Catalog

Authorizations:
Bearer
Request Body schema: application/json
brandCatalogCode
required
string <string> (Code of the parent Brand Catalog)

The User Catalog is always a subset of a Brand Catalog

brandCode
required
string <string> (Brand code)

Brand code issued by the showroom

code
required
string <string> (Code)

A value used on the brand side to uniquely identify the catalog

isActive
boolean <boolean> (is a toggle for the soft delete)
Default: "false"

A field to soft-delete or disable a catalog from the API

name
required
string <string> (Name)

name of a catalog to be shown on the UI

optionCodes
Array of strings <list> (Selector by Option Codes)

list of option codes to filter the collection upon. Empty list means that all options are available within the catalog

userCodes
Array of strings <string> (List of user codes)

list of users that can access this catalog. Empty list means that all users can use this catalog to create presentations

Responses

Request samples

Content type
application/json
{
  • "brandCatalogCode": "CATALOG_42",
  • "brandCode": "HAT",
  • "code": "CATALOG_42",
  • "isActive": true,
  • "name": "Premium season Summer/Fall 2022",
  • "optionCodes": [
    ],
  • "userCodes": [
    ]
}

Response samples

Content type
application/json
{
  • "brandCatalogCode": "PREMIUM",
  • "brandCode": "HAT",
  • "code": "CODE42",
  • "createdAt": "2022-10-27T13:34:46Z",
  • "id": "USER_CATALOG_HAT_CODE42",
  • "isActive": true,
  • "modifiedAt": "2022-10-27T13:34:46Z",
  • "name": "Premuim Europe 2045",
  • "optionCodes": [
    ],
  • "userCodes": [
    ]
}

Marketing Assets

GetAssetGroups

Fetch existing asset groups by codes

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string <string> (Brand code)

Brand code issued by the showroom

codes
required
Array of strings <list> (Codes)

List of asset group codes to fetch by

tags
Array of strings <list> (Tags)

List of tags to filter by

Responses

Request samples

Content type
application/json
{
  • "brandCode": "HAT",
  • "codes": [
    ],
  • "tags": [
    ]
}

Response samples

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

GetAssets

Fetch existing assets by codes

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string <string> (Brand code)

Brand code issued by the showroom

codes
required
Array of strings <list> (Codes)

List of asset codes to fetch by

Responses

Request samples

Content type
application/json
{
  • "brandCode": "HAT",
  • "codes": [
    ]
}

Response samples

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

SearchAssets

Search marketing assets by a number of filters, like options, codes, tags, seasonCodes and divisionCodes

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string <string> (Brand code)

Brand code issued by the showroom

divisionCodes
Array of strings <list> (Division codes)

List of division codes to search by

groupCodes
Array of strings <list> (Group codes)

List of group codes to search by

groupIDs
Array of strings <list> (Group IDs)

List of group IDs to search by

onlyActive
boolean <boolean> (Is Active)

A field to search for assets that are soft-deleted

optionCodes
Array of strings <list> (Option codes)

List of option codes to search by

search
string <string> (Search text)

text to search for in name or description of assets

seasonCodes
Array of strings <list> (Season codes)

List of season codes to search by

tags
Array of strings <list> (Tags)

List of tags to search by

Responses

Request samples

Content type
application/json
{
  • "brandCode": "HAT",
  • "divisionCodes": [
    ],
  • "groupCodes": [
    ],
  • "groupIDs": [
    ],
  • "onlyActive": true,
  • "optionCodes": [
    ],
  • "search": "An asset about west virginia",
  • "seasonCodes": [
    ],
  • "tags": [
    ]
}

Response samples

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

UpsertAsset

Create new or update existing asset

Authorizations:
Bearer
Request Body schema: application/json
assetGroupCodes
Array of strings <list> (Asset Group Codes)

A list of group codes which the asset should belong to

brandCode
required
string <string> (Brand code)

Brand code issued by the showroom

code
required
string <string> (Code)

A value used on the brand side to uniquely identify the group

description
string <string> (Description)

description of the asset to be upserted

divisionCodes
Array of strings <list> (Division Codes)

A list of division codes assigned to the asset

Array of objects (Fields)

A list of fields with extra information to be attached with the asset to be shown on the UI

index
string <integer> (Index)

A numeric value to sort on the UI. If 2 indexes are equal, the order is not determined. Values from -2,147,483,648 to 2,147,483,647 are supported. default: 0

isActive
boolean <boolean> (a field to soft-delete or disable assets from the API)

A field to soft-delete or disable assets from the API

mediaCode
required
string <string> (Media Code)

media code of the asset. Should match one used during media upload, might be code of a video or an image

name
string <string> (Name)

name of the asset to be upserted

optionCodes
Array of strings <list> (Option Codes)

A list of options codes assigned to the asset

seasonCodes
Array of strings <list> (Season Codes)

A list of season codes assigned to the asset

tags
Array of strings <list> (Tags)

A list of tags assigned to the asset used for filtering

Responses

Request samples

Content type
application/json
{
  • "assetGroupCodes": [
    ],
  • "brandCode": "HAT",
  • "code": "CODE_1",
  • "description": "we all enjoy the country roads and the nearby mountains",
  • "divisionCodes": [
    ],
  • "fields": [
    ],
  • "index": 1,
  • "isActive": true,
  • "mediaCode": "MEDIA_CODE_1",
  • "name": "West Virgina Mountains",
  • "optionCodes": [
    ],
  • "seasonCodes": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "BrandCode": "HAT",
  • "Code": "CODE_1",
  • "CreatedAt": "2009-02-13T23:31:30Z",
  • "Description": "we all enjoy the country roads and the nearby mountains",
  • "DivisionCodes": [
    ],
  • "Fields": [
    ],
  • "GroupCodes": [
    ],
  • "ID": "ASSET_HAT_CODE_1",
  • "Index": 1,
  • "IsActive": true,
  • "MediaCode": "MEDIA_CODE_1",
  • "ModifiedAt": "2009-02-13T23:31:30Z",
  • "Name": "West Virgina Mountains",
  • "OptionCodes": [
    ],
  • "SeasonCodes": [
    ],
  • "Tags": [
    ]
}

UpsertAssetGroup

Create new or update existing asset group

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string <string> (Brand code)

Brand code issued by the showroom

code
required
string <string> (Code)

A value used on the brand side to uniquely identify the group

description
required
string <string> (Description)

The Country Roads and it's culture

Array of objects (Fields)

Custom brand defined fields with extra information to be shown on the UI

index
string <integer> (Index)

A numeric value to sort groups. If 2 indexes are equal, the order is not determined. Values from -2,147,483,648 to 2,147,483,647 are supported. default: 0

isActive
boolean <boolean> (Is Active)

A field to soft-delete or disable groups

name
required
string <string> (Name)

Name of the group to be shown on the UI

tags
Array of strings <list> (Tags)

A list of tags to be assigned to the asset group

Responses

Request samples

Content type
application/json
{
  • "brandCode": "HAT",
  • "code": "CODE_1",
  • "description": "Group containing all key looks for our brand",
  • "fields": [
    ],
  • "index": 1,
  • "isActive": true,
  • "name": "Virginia",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "Assets": [
    ],
  • "BrandCode": "HAT",
  • "Code": "CODE_1",
  • "CreatedAt": "2009-02-13T23:31:30Z",
  • "Description": "The Country Roads and it's culture",
  • "Fields": [
    ],
  • "ID": "ASSET_GROUP_HAT_CODE_1",
  • "Index": 1,
  • "IsActive": false,
  • "ModifiedAt": "2009-02-13T23:31:30Z",
  • "Name": "Virginia",
  • "Tags": [
    ]
}

Stock

Get Stock List

GetList returns a filtered list of stock items

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string <string> (Brand code)

Brand code issued by the showroom - if brandCode is the only filter provided then pagination is mandatory

codes
Array of strings <list> (Codes)

list of stock unique identifiers

isActiveOnly
boolean <boolean> (Is Active Only)
Default: "false"

if set to true will only return active stock items

modifiedAfter
string <date-time> ((Optional) fetch stock that was modified after a certain date time) RFC3339
optionCodes
Array of strings <list> (Option codes)

list of option codes to filter stock by

object (Pagination is used to paginate the stock items)

Responses

Request samples

Content type
application/json
{
  • "brandCode": "HAT",
  • "codes": [
    ],
  • "isActiveOnly": true,
  • "modifiedAfter": "2019-08-24T14:15:22Z",
  • "optionCodes": [
    ],
  • "pagination": {
    }
}

Response samples

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

Bulk Upsert

Upsert multiple stock items at once

Bulk Upsert is limited to 1000 stock per request

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string <string> (Brand code)

Brand code issued by the showroom

required
Array of objects (Stock)

list of stock to upsert

Responses

Request samples

Content type
application/json
{
  • "brandCode": "HAT",
  • "stock": [
    ]
}

Response samples

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

Users

GetUsersByBrandCode

List users by brand code

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string (BrandCode is the unique code of the brand and it is used as the main identifier of the brand) non-empty
limit
integer <int32> (Limit is the limit to how many users the list should return) non-empty
offset
integer <int32> (Offset is used for pagination) non-empty

Responses

Request samples

Content type
application/json
{
  • "brandCode": "BRAND",
  • "limit": 10,
  • "offset": 0
}

Response samples

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

Upsert

Create or Update existing user entity. The uniqueness of the user is determined by the brandUserID and brandCode.

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string (The main identifier of the brand) non-empty
brandUserID
required
string (Identifier used by a brand's internal systems to uniquely identify a user) non-empty
email
required
string (User's company email address) non-empty
isActive
boolean (Defines if the user is active or not)
name
required
string (The user name to display in the system) non-empty
roles
required
Array of strings (List of the comma separated user roles) [ items non-empty ]

Options:integration, presenter, contentManager, brandAdmin

Responses

Request samples

Content type
application/json
{
  • "brandCode": "BRAND",
  • "brandUserID": "albert.einstein",
  • "email": "albert.einstein@company.co",
  • "isActive": true,
  • "name": "Albert Einstein",
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "brandUser": [
    ],
  • "email": "test@user.email"
}

Media

Upsert

Implements versioned media uploads. Using this endpoint you can both create and update existing media assets. If the media asset does not exist in the system or there is one with an older version and the same mediaCode, the file will be downloaded and saved with overwrite. Otherwise, API will respond with the existing document immediately.

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string (Brand identifier that the media belongs to)
mediaCode
required
string (Unique identifier for a media)
type
string (- General: If the uploaded media is used in the digital showroom - Library: If the uploaded media is used in the content management system)
Default: "General"
Enum: "General" "Library"
url
required
string (Publicly available URL of the media. The service will try to pull the asset only once and will expect `2xx` status in the response)
version
string <int64>

Current version of the media file on the client-side. To update an asset, send a newer version than the last time. If the version is older or the same for existing media, the API will return the existing result immediately. A value of 0 can be used to reset the version, the file will always be updated when using 0 as version.

Values from -2,147,483,648 to 2,147,483,647 are supported. default: 0

Responses

Request samples

Content type
application/json
{
  • "brandCode": "string",
  • "mediaCode": "string",
  • "type": "General",
  • "url": "string",
  • "version": "string"
}

Response samples

Content type
application/json
{
  • "brandCode": "HAT",
  • "dimensions": {
    },
  • "id": "MEDIA_HAT_EXTERNALCODE",
  • "mediaCode": "externalcode",
  • "mimeType": "image/jpeg",
  • "name": "img.jpg",
  • "version": 4
}

Presentation

GetByIDs

Fetch full presentation information (metadata with assortments) by presentation ids

Authorizations:
Bearer
Request Body schema: application/json
ids
required
Array of strings (list presentation IDs for fetching)

Responses

Request samples

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

Response samples

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

GetList

Fetch presentation list of brand with pagination List is sorted by modifiedAt in descending order

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string (Brand identifier that presentations belong to)
creatorID
string (Optional filter by creatorID which is the brandUserID of the user who created the presentation - for reference check Users_GetUsersByBrandCode)
required
object (presentation.Pagination)

Responses

Request samples

Content type
application/json
{
  • "brandCode": "string",
  • "creatorID": "string",
  • "pagination": {
    }
}

Response samples

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

Draft Order

Get

Get a single order with all the order lines by order id.

Orders are never updated.
If multiple orders are created during single appointment, it's up to you, to keep them as separate orders or update existing order, using presentationID as PK.

Contains an order line per delivery date, option and size.

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string (Brand identifier that the order belongs to)
id
required
string (Internal order identifier)

Responses

Request samples

Content type
application/json
{
  • "brandCode": "BRAND",
  • "id": "ORDER_871a963f-56a4-4ba4-8f2f-af6ae39a9e97"
}

Response samples

Content type
application/json
{
  • "brandCode": "BRAND",
  • "catalogCode": "CATALOG_123",
  • "createdAt": "2020-01-11T16:24:52Z",
  • "customerCode": "FSHN74",
  • "customerLocationCode": "FSHN74_IT171931",
  • "groupEventID": "123456789",
  • "id": "ORDER_871a963f-56a4-4ba4-8f2f-af6ae39a9e97",
  • "lines": [
    ],
  • "orderName": "Your Selection",
  • "presentationID": "PRESENTATION_d78bc7aa-0f28-4a07-8a5a-7147b99c6b97",
  • "presentationName": "PRESENTATION Spring 2022",
  • "selectionID": "DRAFT_123455",
  • "userID": "super.name@company.com"
}

Get List

Get all orders after specified date. This list does not include order lines.

Empty response means no orders were created since createdAfter time. Data is in sync. Try again later.

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string (Brand identifier that the order belongs to)
createdAfter
required
string <date-time> RFC3339

Returns orders created after specified date.

Orders are returned in chronological order. This field should be used as cursor. Selecting new orders, created after the latest order you received during previous call.

limit
integer <int64> [ 1 .. 100 ]
Default: "100"

limits number of orders for a single request.

presentationIDs
Array of strings

Optional list of presentation IDs to filter orders by.

selectionIDs
Array of strings

Optional list of selection IDs to filter orders by.

Responses

Request samples

Content type
application/json
{
  • "brandCode": "BRAND",
  • "createdAfter": "2019-08-24T14:15:22Z",
  • "limit": 100,
  • "presentationIDs": [
    ],
  • "selectionIDs": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Webhook

Get

Current webhook configuration

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string (Brand identifier that the webhook belongs to) non-empty

Responses

Request samples

Content type
application/json
{
  • "brandCode": "BRAND"
}

Response samples

Content type
application/json
{
  • "brandCode": "BRAND",
  • "headers": [
    ],
  • "skipTLSVerify": false,
  • "subscriptions": [
    ],
  • "url": "https://your-webhook-url.co/webhook"
}

Setup

Upsert new webhook configuration. You can set up an HTTP(S) request and subscribe to events you want to receive.

Webhook mechanism is not meant to be reliable.
To keep data consistent, you should periodically call API to check the current state and reconcile the data.

There is no retries. Error responses are ignored.

Authorizations:
Bearer
Request Body schema: application/json
brandCode
required
string (Brand identifier that the webhook belongs to) non-empty
Array of objects (Collection of HTTP headers)

One can use this for authentication and client keys, like authorization, client-id and client-secret, along with additional flags for ETL or proxy.

Additionaly you will receive brand and event headers with brand code and event type respectively.

skipTLSVerify
boolean
Default: "false"

If true, TLS certificate validity check will be skiped.

Should not be used in production! If enabled the call will be made even with self-signed or invalid certificate. Which can lead to data breach.

Array of objects (List of events you want to receive with additional configuration)
url
required
string

URL address to receive your push events.

Do not store credentials in URL address! HTTP requests are often logged by nginx so URLs like http(s)://user:password@... or ...?client_secret=PA$$WORD should not be used.

Responses

Request samples

Content type
application/json
{
  • "brandCode": "BRAND",
  • "headers": [
    ],
  • "skipTLSVerify": false,
  • "subscriptions": [
    ],
  • "url": "https://your-webhook-url.co/webhook"
}

Response samples

Content type
application/json
{ }