NAV
API v2 API v3
json

General information

Authentication

SALESmanago API v3 uses a new and simpler authentication mechanism. The only authentication field required is a Header API-KEY containing your API key. You can create a new API key in SALESmanago ➔ Integration Center ➔ API ➔ API v3.

Example:

<?php
    curl_setopt($ch, CURLOPT_HTTPHEADER, array(
        'API-KEY: S7LOELpItzOXVAZzMa…VEMbIJL6EH4Z45TTgK'
        )
    );
?>

Note: You can specify when your API key expires, as well as revoke an already created API key. If you have trouble with authentication, start by verifying that your API key is valid. The key status can be checked in the same place where you create new keys.

Header name: API-KEY
Header value: API key from SALESmanago

Validations

To make sure the data transferred to SALESmanago is well-structured, ordered, and easily accessible we use validations for some specific fields. The most important validations include:

Data type Standard External resources
Email RFC882 RFC882 at ietf.org
URL Apache URL validator UrlValidator at apache.org
Currency ISO 4217 ISO 4217 at SIX
Language ISO 639-1 ISO 639-1 at loc.gov
Language and region BCP 47 BCP 47 codes at Microsoft

Methods and Content-Types

SALESmanago API v3 uses two HTTP methods:

All POST requests must be encapsulated in JSON format. Most libraries automatically add Content-Type: application/json header when sending data encapsulated in JSON.

General errors and warnings

It’s only those who do nothing that make no mistakes. – Joseph Conrad

SALESmanago API is designed to gracefully accept all data that meet the requirements and reject only those requests that cannot be processed. Below you can find a list of general errors and warnings with Reason codes assigned to them.

Error/warning Reason code HTTP
Authentication error
Error message
10 400
Field exceeds limit
fieldName|min:0|max:256|Error message
11 400
Data trimmed warning
fieldName|max:256|Warning message
12 200
Missing required field
fieldName|Error message
13 400
Wrong field type
fieldName:type|Error message
14 400
Using non-unique value
fieldName|Error message
15 400
Trying to access resource with identifier not present in SALESmanago
fieldName|Error message
16 400
Trying to set a required value as null
fieldName|Error message
17 400
Value not matching a required structure (RegEx)
fieldName|Error message
18 400
Trying to add a resource above available limit
resourceName|limit:3|Error message
19 400

Product management

Creating a Product Catalog

Sample request:

{
  "catalogName": "Example.com Product Catalog",
  "catalogId": "21c2-...-3266", 
  "setAsDefault": false,
  "currency": "USD",
  "location": "examplecom"
}

This method lets you create a Product Catalog – an entity representing your online store. Product Catalogs are crucial for many functionalities in SALESmanago, including Recommendation Frames, emails with product blocks, dynamic WebPushes, and more.

To maintain backwards compatibility with XML Product Feeds, you need to specify a location field when creating a new Product Catalog. This field is used when assigning external events (such as CART or PURCHASE) to a proper Product Catalog.

Some properties of Product Catalogs can be updated, including catalog name, currency, or location. To identify a Product Catalog, use the catalogId value. You can always check the catalogId value in SALESmanago ➔ Integration Center ➔ Product Catalogs.

Endpoint:

https://api.salesmanago.com/v3/product/catalogUpsert

Available fields in the request addContactExtEvent method:

Field Limits Description
catalogName* 255 Internal name of the Product Catalog to help you identify it in SALESmanago.
catalogId 36 Catalog identifier that is used to update an existing catalog. Do not specify when creating a new one.
setAsDefault bool Flag used to determine if Product Catalog should be available for Recommendation Frames
currency* ISO 4217 ISO currency code, e.g. USD, EUR, etc.
location* 255
questionmark
only a-zA-Z0-9_ cannot start with a digit
Legacy field for assigning products to External Events.

Sample response:

{
  "requestId": "381d-...-12e7",
  "catalogId": "21c2-...-3266"
}

Adding or updating a product

Sample request:

{
  "catalogId": "21c2-...-3266",
  "products": [
    {
      "productId": "1234",
      "name": "Turtleneck sweater",
      "mainCategory": "sweaters",
      "categoryExternalId": "8642",
      "description": "Classic sweater with...",
      "productUrl": "https://example.com/shop/sweaters/turtleneck-sweater",
      "mainImageUrl": "https://example.com/media/turtleneck-sweater-cover.jpg",
      "available": true,
      "price": 79.99,
      "systemDetails": {
        "manufacturer": "My Brand",
        "gender": 0,
        "color": "black"
      }
    },
    {
      "productId": "1235",
      "name": "White t-shirt",
      "brand": "My Brand",
      "mainCategory": "t-shirts",
      "categoryExternalId": "1050",
      "categories": [
        "Winter collection",
        "Linen products"
      ],
      "description": "Classic t-shirt with...",
      "productUrl": "https://example.com/shop/t-shirts/white-t-shirt",
      "mainImageUrl": "https://example.com/media/white-t-shirt-cover.jpg",
      "imageUrls": [
        "https://example.com/media/white-t-shirt1.jpg",
        "https://example.com/media/white-t-shirt2.jpg",
        "https://example.com/media/white-t-shirt3.jpg"
      ],
      "available": true,
      "active": true,
      "quantity": 90,
      "price": 29.99,
      "discountPrice": 19.99,
      "unitPrice": 19.99,
      "systemDetails": {
        "manufacturer": "My Brand",
        "popularity": 40,
        "gender": 0,
        "season": "summer",
        "color": "white",
        "bestseller": true,
        "newProduct": false
      },
      "customDetails": {
        "detail1": "linen",
        "detail2": "short"
      }
    }
  ]
}

This method lets you add or update products in a Product Catalog. In SALESmanago products are identified by the field productId. This can be the product ID from your eCommerce platform, the SKU or EAN code. This field is unique per product.

You can upload product variants if they meet both of the following conditions: 1. Product variant has its own productId. 2. Product variant has its own URL.

Endpoint:

https://api.salesmanago.com/v3/product/upsert

Field Limits Description
catalogId* 36 Catalog identifier that is used to identify the Product Catalog for the upserted product
products* 100
questionmark
You can transfer up to 100 products in one request.
Array of product objects with fields specified below
productId* 255 Product identifier from your eCommerce platform
name* 255 Product name. You can use diacritics and special characters.
mainCategory* 255 Category name that can be used in emails and when displaying Recommendation Frames
categoryExternalId 255 Category ID used for AI processing and calculating recommendations. If you don’t specify this field, the category ID will be assigned based on the mainCategory field.
categories 5*255 Other categories (array)
description 16384
questionmark
Most functionalities can use only the first 1024 characters.
Product description used in emails and custom Recommendation Frames. Most functionalities can use the first 1024 characters only.
productUrl* 2048
questionmark
Most functionalities can use only the first 512 characters
Product URL that is used to match visits with products. Most functionalities can use the first 512 characters only.
mainImageUrl 2048
questionmark
Most functionalities can use only the first 512 characters
Image URL to be used in Recommendation Frames and emails. Most functionalities can use the first 512 characters only.
imageUrls 5*2048 Additional product images that will be used in upcoming features
available* bool Marks products as temporarily unavailable. This allows you to prevent them from showing up in Recommendation Frames.
active bool Marks products as no longer present in your store. This will effectively turn off a given product.
quantity int Available quantity to be used in custom Recommendation Frames
price * float (19.2)
questionmark
This value can contain up to 19 digits before the decimal point and 2 digits after the decimal point
Standard product price
discountPrice float (19.2)
questionmark
This value can contain up to 19 digits before the decimal point and 2 digits after the decimal point
Discount product price. You can use this value to display product promo price next to a crossed out standard product price in emails and Recommendation Frames.
systemDetails n/a Set of details that can be used in various mechanisms in SALESmanago
manufacturer 255 Standard product details
season 255 Standard product details
color 25 Standard product details
popularity int Integer value to mark how popular the upserted product is, for example, using a range 1-100.
bestseller bool Flags that you can use in emails and custom Recommendation Frames
newProduct bool Flags that you can use in emails and custom Recommendation Frames
gender (systemDetails object) enum
questionmark
(-1, 0, 1, 2, 3, 4)
Enum to identify the gender the product is designed for:
-1 – undefined,
0 – female,
1 – male,
2 – other,
4 – unisex
customDetails (object) 5*255 List of additional details as key-value pairs.

Note: You can use custom key names (instead of detailX), however, some functionalities will still refer to those values using a key detailX.

Sample response:

{
  "requestId": "381d-...-12e7",
  "productIds": ["1234", "1235"]
}