Customer API

The Customer API enables your customers to interact with your shop using a REST API. This allows them to send and manage their orders, as well as check the availability of products.

Customers will be able to:

• Find products by their product code or by combining a brand name with the product code.
• Check the current availability and prices of the products.
• Send new order.
• List all existing orders, including the products in each order, and verify the payment and processing statuses for each order.

OAuth customer authorization in your other app or web

• You can also utilize this API in other systems where you want to enable your customers to log in using the same credentials they have in the shop. This is possible thanks to the OAuth 2.0 Authorization Code flow.

HTTPS Only

App API requires to communiacate over secured HTTPS protocol. There is no traffic redirection from HTTP to HTTPS. The API responds with 403 Forbidden error code when requested on HTTP protocol.

Compressed Responses Only

• The API will send compressed responses only.
• Compression algorithm can be chosen by the client.
• Supported algorithm is Gzip
• All API requests have to contain the Accept-Encoding header with gzip value.
• The API will respond with 400 Bad Request response code if such the request will not be called with such Accept-Encoding value.

Accept-Encoding: gzip

Content type

• The API requires Content-Type header to be included in the requests with body
• Typically, it is required for POST and PATCH request with body containing JSON

Content-Type: application/json

Feature Requests

If you need additional possibilities in the API, please write us your requests at [email protected].

Authentication

The Customer API uses OAUTH 2.0 to authenticate requests.

Customer API Password

• Each customer needs to generate its own password in their User Profile.
• The merchant needs to first allow the customer to use the Customer API for each customer.

Access Token

POST /api/customer/oauth/access-token

Request Body Parameters:

• grant_type: string - client_credentials
• client_id: string
• client_secret: string
• scope: string - all

Beware! These parameters are inside the request body in the application/x-www-form-urlencoded format; not in JSON, not in URL query parameters.

Request

POST /api/customer/oauth/access-token HTTP/1.1
Host: theshopname.com
Content-Type: application/x-www-form-urlencoded
Accept-Encoding: gzip

grant_type=client_credentials
&client_id=d194b033-1975-43e5-a083-96bdbe3ea1cd
&client_secret=164381f6-dcea-46c1-bf8f-f9f22288970c
&scope=all

Success Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "_type": "AccessToken",
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIiLCJqdGkiOiIyZjMzNmQ2NjVkODFlMGMyZjE5OWY1ZmNhOGZhMTBjMDIwZjQwNWY3NTdiYjUwZDY5YWExNzNmZWZhZTRhMDUyMWIxN2Q4ODA4NTdiYThkNiIsImlhdCI6MTYxNjA2Mjc2OCwibmJmIjoxNjE2MDYyNzY4LCJleHAiOjE2MTYwNjYzNjgsInN1YiI6ImQxOTRiMDMzLTE5NzUtNDNlNS1hMDgzLTk2YmRiZTNlYTFjZCIsInNjb3BlcyI6WyJlbWFpbCJdfQ.1ey--ElXdCkZ474FNozO1r-uec9Q87Cd227yUX0BHUdtgND09IOFosEl1epIM434m7Fjx0POqhypOHTEbHNE9cEhQJmFePwe5eDRvMi_dPVhbiduFoFuAjPu4zNcAxvDWcVFf0kM4T-ytTK0kiSh0zcW0KzIg_3M8iXmnp6DbDE"
}

Error Response

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

{
    "error": "invalid_client",
    "error_description": "Client authentication failed",
    "message": "Client authentication failed",
    "status": 401
}

Authorized API Calls

Add Authorization header with value Bearer ACCESS_TOKEN_STRING where ACCESS_TOKEN_STRING is the received access_token from /api/customer/oauth/access-token endpoint.

Error Response for Invalid Access Token

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Content-Encoding: gzip

{
    "error": "access_denied",
    "error_description": "The resource owner or authorization server denied the request.",
    "status": 400
}

Error Response for Expired Token:

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Encoding: gzip

{
  "error": "invalid_token",
  "error_description": "The access token expired"
}