API Documentation

API Reference

Explore our comprehensive API documentation. Learn how to authenticate, make requests, and leverage our endpoints to build powerful e-commerce experiences.

API Basics

Authentication

The API uses an auth token to recognize customers. The following endpoints can issue tokens:

POST /login
POST /register
POST /addToCart

When a token is issued, it will be set as a cookie named token and also returned as a root level property on the JSON response.

The auth token can be submitted with requests in two ways:

As a cookie (automatic if your environment allows cookies)
As a bearer token in the Authorization header

To clear the token cookie, call POST /logout. If no valid auth token is presented but required, the API responds with 401. Tokens expire after one week.

Project & Country

All endpoints require the following path parameters:

project - Your project key (e.g. finecollections)
country - ISO 3166-1 alpha-2 country code (e.g. DE for Germany)

Language

The API determines the client's language from the Accept-Language header by default. To override this, use the lang query parameter on relevant endpoints.

Endpoints

Products

Get Products

GET/:project/:country/getProducts

Query Parameters:

qFull text search term (optional)
filtersFilters (optional)
sortSort by attribute (optional)
fromPagination offset (optional)
sizeNumber of results (optional)

Filters format: categories:tShirts|size:M|colors:blue,white

Sort format: price:desc or just price

Get Product

GET/:project/:country/getProduct

Query Parameters:

idProduct ID (optional)
skuSKU / Variant ID (optional)

Either id or sku must be specified.

Customer / Authentication

Get Customer

GET/:project/:country/getCustomer

Register

POST/:project/:country/register

Body Parameters:

salutation
title(optional)
givenName
familyName
email
password

If a valid auth token of an anonymous customer is presented, the customer is upgraded to a registered customer.

Login

POST/:project/:country/login

Body Parameters:

email
password

If an anonymous customer's cart exists, it will be merged with the registered customer's cart.

Logout

POST/:project/:country/logout

Clears the token cookie.

Set Customer Details

POST/:project/:country/setCustomerDetails

Body Parameters:

salutation(optional)
title(optional)
givenName(optional)
familyName(optional)
birthDate(optional)
phoneNumber(optional)
isSubscribedToNewsletter(optional)
preferredLanguage(optional)

Cart

Add To Cart

POST/:project/:country/addToCart

Body Parameters:

sku
quantity(optional)

If quantity is not provided, one instance is added. Creates an anonymous customer if no auth token is present.

Set Cart Item Quantity

POST/:project/:country/setCartItemQuantity

Body Parameters:

sku
quantity

Remove From Cart

POST/:project/:country/removeFromCart

Body Parameters:

sku

Logistics / Shipping

Set Shipping Address

POST/:project/:country/setShippingAddress

Body Parameters:

country
salutation
title(optional)
givenName
familyName
streetAddress
supplement(optional)
postalCode
city
region(optional)
phoneNumber(optional)

Set Shipping Method

POST/:project/:country/setShippingMethod

Body Parameters:

typeKeye.g. standard, express, clickAndCollect
carrierKeye.g. dhl, hermes (optional)

Payment

Set Billing Address

POST/:project/:country/setBillingAddress

Body Parameters:

country
salutation
title(optional)
givenName
familyName
streetAddress
supplement(optional)
postalCode
city
region(optional)
phoneNumber(optional)

Set Payment Method

POST/:project/:country/setPaymentMethod

Body Parameters:

keyPayment Method Key
dataPayment Data (optional)

Orders

Get Orders

GET/:project/:country/getOrders

Get Order

GET/:project/:country/getOrder

Query Parameters:

idOrder ID

Place Order

POST/:project/:country/placeOrder

Body Parameters:

dataPayment Data (optional)

Requires shipping and billing addresses to be set and at least one item in the cart.