MyLION Integration Doc

Appearance

Product Webhook Notification ​

The Product Webhook Notification from MyLION keeps you informed about changes to product attributes, templates, and inventory levels. By subscribing to this webhook, you can stay up-to-date with the latest information about your products, ensuring accurate and timely data synchronization. Below, you'll find comprehensive details about the payload structure of the notification and how to set up your receiving endpoint to process these product updates.

Payload Structure ​

The Product Webhook Notification payload includes information about the changes made to various aspects of a product. Here's an overview of the payload structure:

json
{
  "topLevelProducts": [ 
    {
      "id": {
        "mylionId": 123,
        "externalId": "EXT_PROD_123"
      },
      "type": "simple", 
      "parentId": {
        "mylionId": 456,
        "externalId": "EXT_PROD_456"
      },
      "code": "PROD123", 
      "parentCode": null,
      "codeManufacturer": "MANU123",
      "taxClass": "27%", 
      "barCode": "123456789",
      "weight": {
        "value": 1.5,
        "measure": "kg"
      },
      "netWeight": {
        "value": 1.2,
        "measure": "kg"
      },
      "sizeX": {
        "value": 10.0,
        "measure": "cm"
      },
      "sizeY": {
        "value": 15.0,
        "measure": "cm"
      },
      "sizeZ": {
        "value": 5.0,
        "measure": "cm"
      },
      "diameter": {
        "value": 5.0,
        "measure": "cm"
      },
      "descriptions": [
        {
          "language": "en", 
          "name": "Product Name", 
          "longDescription": "Long description of the product.", 
          "shortDescription": "Short description",
          "searchKeywords": "keyword1, keyword2, keyword3"
        }
      ],
      "stock": 100.0, 
      "price": {
        "salesPrice": {
          "price": 50.0, 
          "dateFrom": null,
          "dateTo": null,
          "scales": [
            {
              "minimumQuantity": 5,
              "price": 1231.12
            }
          ]
        },
        "discountedSalesPrice": {
          "price": 45.0, 
          "dateFrom": null,
          "dateTo": null,
          "scales": [
            {
              "minimumQuantity": 5,
              "price": 1231.12
            }
          ]
        },
        "purchasePrice": {
          "price": 40.0, 
          "dateFrom": null,
          "dateTo": null,
          "scales": [
            {
              "minimumQuantity": 5,
              "price": 1231.12
            }
          ]
        },
        "customerGroupProductPrices": [
          {
            "price": 50.0, 
            "customerGroupId": { 
              "mylionId": 123, 
              "externalId": "CUSTOMER_GROUP_1"
            }
          }
        ],
        "customerGroupProductDiscounts": [
          {
            "discountedPrice": 40.0,
            "discountPercentage": 10.0,
            "customerGroupId": { 
              "mylionId": 123, 
              "externalId": "CUSTOMER_GROUP_1"
            },
            "dateFrom": "2023-08-14T12:00:00Z",
            "dateTo": "2023-08-21T12:00:00Z"
          }
        ],
      },
      "template": "Template1",
      "attributes": [
        {
          "attributeMyLionId": 123, 
          "value": "Red",
          "valueMyLionId": 456,
          "valueTranslations": [
            {
              "language": "en",
              "translation": "Red"
            },
            {
              "language": "fr",
              "translation": "Rouge"
            }
          ],
          "values": [
            {
              "myLionId": 101, 
              "defaultTranslation": "Value 1", 
              "valueTranslations": [
                {
                  "language": "en",
                  "translation": "Value 1"
                },
                {
                  "language": "fr",
                  "translation": "Valeur 1"
                }
              ]
            },
            {
              "myLionId": 102, 
              "defaultTranslation": "Value 2", 
              "valueTranslations": [
                {
                  "language": "en",
                  "translation": "Value 2"
                },
                {
                  "language": "fr",
                  "translation": "Valeur 2"
                }
              ]
            }
          ]
        }
      ],
      "categories": [
        {
          "myLionId": 123, 
          "externalId": "EXT_CAT_123"
        }
      ],
      "active": true
    }
  ],
  "childProducts": [ 
  ],
  "templates": [ 
    {
      "id": {
        "mylionId": 123, 
        "externalId": "EXT_TEMPLATE_123"
      },
      "name": "Product Template", 
      "attributes": [
        {
          "myLionId": 101, 
          "label": "Size", 
          "labelTranslations": [
            {
              "language": "en",
              "translation": "Size"
            },
            {
              "language": "fr",
              "translation": "Taille"
            }
          ],
          "type": "S", 
          "valueSet": [
            {
              "myLionId": 201, 
              "defaultTranslation": "Small",
              "valueTranslations": [
                {
                  "language": "en",
                  "translation": "Small"
                },
                {
                  "language": "fr",
                  "translation": "Petit"
                }
              ]
            },
            {
              "myLionId": 202, 
              "defaultTranslation": "Medium",
              "valueTranslations": [
                {
                  "language": "en",
                  "translation": "Medium"
                },
                {
                  "language": "fr",
                  "translation": "Moyen"
                }
              ]
            }
          ],
          "isUsedForProductVariation": true,
          "isMandatory": false
        }
      ]
    }
  ],
  "categories": [ 
    {
      "id": { 
        "myLionId": 123, 
        "externalId": "EXT_CAT_123"
      },
      "parentId": {
        "myLionId": 456,
        "externalId": "EXT_CAT_456"
      },
      "position": 1,
      "descriptions": [ 
        {
            "language": "en", 
            "name": "Category Name"
        }
      ]
    }
  ],
  "customerGroups": [ 
    {
      "id": { 
        "myLionId": 123, 
        "externalId": "EXT_CUSTOMER_GROUP_123"
      },
      "name": "Customer Group 1"
    }
  ]
}
java
@Data
public class Id {
  private Integer mylionId;
  private String externalId;
}

@Data
public class ProductCollection {

  private List<Product> topLevelProducts;
  private List<Product> childProducts;
  private List<Template> templates;
}

@Data
public class Product {
  private Id id;
  private String type;
  private Id parentId;
  private String code;
  private String parentCode;
  private String codeManufacturer;
  private String taxClass;
  private String barCode;
  private ValueWithMeasure weight;
  private ValueWithMeasure netWeight;
  private ValueWithMeasure sizeX;
  private ValueWithMeasure sizeY;
  private ValueWithMeasure sizeZ;
  private ValueWithMeasure diameter;
  private List<ProductDescriptions> descriptions;
  private Double stock;
  private PriceDTO price;
  private String template;
  private List<AttributeValue> attributes;
  private List<Id> categories;
  private Boolean active;
}

@Data
public class ValueWithMeasure {

  private double value;
  private String measure;
}

@Data
public class ProductDescriptions {

  private String language;
  private String name;
  private String longDescription;
  private String shortDescription;
  private String searchKeywords;
}

@Data
public class PriceDTO {
  private ProductPrice salesPrice;
  private ProductPrice discountedSalesPrice;
  private ProductPrice purchasePrice;
  private List<CustomerGroupProductPrice> customerGroupProductPrices;
  private List<CustomerGroupProductDiscount> customerGroupProductDiscounts;
}

@Data
public class ProductPrice {
  private Double price;
  private Date dateFrom;
  private Date dateTo;
  private List<PriceScale> scales;
  private String currency;

  {
    scales = new ArrayList<>();
  }
}

@Data
public class PriceScale {
  private Double minimumQuantity;
  private Double price;
}

@Data
public class CustomerGroupProductPrice {
  private Id customerGroupId;
  private Double price;
}

@Data
public class CustomerGroupProductDiscount {
  private Id customerGroupId;
  private Double discountedPrice;
  private Double discountPercentage;
  private XMLGregorianCalendar dateFrom;
  private XMLGregorianCalendar dateTo;
}

@Data
public class AttributeValue {
  private Integer attributeMyLionId;
  private String type;
  private String label;
  private List<Translation> labelTranslations;
  private Integer position;
  private Boolean variation;
  private String value;
  private Integer valueMyLionId;
  private String valueExternalId;
  private List<Translation> valueTranslations;
  private List<Code> values;
}

@Data
public class Translation {
  String language;
  String translation;
}

@Data
public class Code {
  private Integer myLionId;
  private String defaultTranslation;
  private List<Translation> valueTranslations;
}

@Data
public class ProductImage {

  private String fileName;
  private String imageValueInBase64;
  private String fileUrl;
  private boolean isDefaultPicture;
}

@Data
public class GlobalAttribute {
  private Integer myLionId;
  private String label;
  private List<Translation> labelTranslations;
  private String type;
  private List<Code> valueSet;
  private boolean isUsedForProductVariation;
  private boolean isMandatory;
}

@Data
public class Template {
  private Id id;
  private String name;
  private List<GlobalAttribute> attributes;
}

@Data
public class Category {
    private Id id;
    private Id parentId;
    private Integer position;
    private List<CategoryDescription> descriptions;
}

@Data
public class CategoryDescription {
    private String language;
    private String name;
}

@Data
public class CustomerGroup {
  private Id id;
  private String name;
}

JSON Structure Explanation ​

The highlighted lines are the required properties.

  • 'topLevelProducts': An array of top-level products (product updates). Only updated or new products are sent in the payload. See explanation for product properties in the section below
  • 'childProducts': An array of child products (if applicable). Only updated or new child products are sent in the payload. Same structure as topLevelProducts. See explanation for product properties in the section below
  • 'templates': An array of all product templates. Templates are always sent in the payload, even if they have not changed. See explanation for product templates in the section below
  • 'customerGroups': An array of all customer groups. Customer groups are always sent in the payload, even if they have not changed. See explanation for customer groups in the section below

IDs ​

MyLION uses two types of IDs to identify products and other entities. The first type is the MyLION ID, which is a unique identifier of type Integer generated by MyLION. The second type is the external ID, which is an identifier of type String provided by you. The external ID is used to identify products in your system. Currently, this API only supports receiving external IDs for products see the Response section for details. Despite this, structure of the payload contains both types of IDs for all entities. External IDs are only filled for producta and only if you have provided them to MyLION.

json
{
  "id": {
    "mylionId": 123,
    "externalId": "EXT_PROD_123"
  }
}

Hint for processing the payload ​

The payload contains the top-level products and the child products. The child products are the variants of the top-level products. The child products are not included within the top-level products, they are included in the childProducts array.
Templates and their attributes along with Customer Groups are always sent in the payload, even if they have not changed. It is recommended to process the Templates and Customer Groups first, then process the Top-level Products, and finally the Child Products.

Product Properties ​

  • 'id': The unique identifiers of the product.
  • 'type': The type of the product. Possible values simple, variant, variable
  • 'parentId': The unique identifiers of the parent product, if one exists.
  • 'code': The product code.
  • 'parentCode': The parent product code if one exists.
  • 'codeManufacturer': The manufacturer code of the product.
  • 'taxClass': The tax class of the product. See the Tax Classes section for possible values.
  • 'barCode': The barcode of the product.
  • 'weight': The gross weight of the product.
    • 'value': The weight value.
    • 'measure': The weight measure.
  • 'netWeight': The net weight of the product.
    • 'value': The net weight value.
    • 'measure': The net weight measure.
  • 'sizeX': The size X of the product.
    • 'value': The size X value.
    • 'measure': The size X measure.
  • 'sizeY': The size Y of the product.
    • 'value': The size Y value.
    • 'measure': The size Y measure.
  • 'sizeZ': The size Z of the product.
    • 'value': The size Z value.
    • 'measure': The size Z measure.
  • 'descriptions': An array of product information in different languages.
    • 'language': The language of the product. ISO 639-1:2002 codes are used. Examples: en, hu
    • 'name': The name of the product.
    • 'shortDescription': The shorter description of the product.
    • 'longDescription': The long description of the product.
  • 'stock': The current stock of the product.
  • 'salesPrice': The sales price of the product.
    • 'price': The net price of the product.
    • 'dateFrom': The date from which this price is valid.
    • 'dateTo': The date until this price is valid.
    • 'scales': An array of price scales.
      • 'minimumQuantity': The minimum quantity for the price scale.
      • 'price': The net price for the price scale.
  • 'discountedSalesPrice': The discounted sales price of the product. Same structure as salesPrice.
  • 'purchasePrice': The purchase price of the product. Same structure as salesPrice.
  • 'customerGroupProductPrices': An array of customer group product prices.
    • 'customerGroupId': The unique identifiers of the customer group. Customer groups are sent in the payload. See the Customer Groups section for details.
    • 'price': The net price of the product.
    • 'dateFrom': The date from which the discount is valid.
    • 'dateTo': The date until the discount is valid.
  • 'customerGroupProductDiscounts': An array of customer group product discounts.
    • 'customerGroupId': The unique identifiers of the customer group. Customer groups are sent in the payload. See the Customer Groups section for details.
    • 'discountedPrice': The discounted net price of the product.
    • 'discountPercentage': The discount percentage of the product.
    • 'dateFrom': The date from which the discount is valid.
    • 'dateTo': The date until the discount is valid.
  • 'template': The template name this product belongs to. See the Product Templates section for details.
  • 'attributes': the values of the attributes for the product.
    • 'attributeMyLionId': The unique identifier for the attribute.
    • 'value': The default transition value of the attribute in human-readable form. Only filled if the attribute is a single value.
    • 'valueMyLionId': The unique identifier of the value of the attribute if the value is a code value. Only filled if the attribute is a single code value.
    • 'valueTranslations': An array of translations for the value of the attribute. Only filled if the attribute is a single value.
      • 'language': The language of the translation.
      • 'translation': The translation of the value.
    • 'values': An array of values for the attribute. Only filled if the attribute is a multi-value code.
      • 'myLionId': The unique identifier for the value.
      • 'defaultTranslation': The default translation for the value.
      • 'valueTranslations': An array of translations for the value.
        • 'language': The language of the translation.
        • 'translation': The translation of the value.
  • 'categories': An array of category ids this product is associated with.
  • 'active': Whether the product is active.

Tax Classes ​

CODENAME
5%5% VAT content
18%18% VAT content
27%27% VAT content
AAMPersonal tax exemption
TAMTax-exempt activity
KBAETTax-exempt intra-Community sales, without new means of transport
KBAUKTax-exempt sales of intra-Community new means of transport
EAMTax-exempt extra-Community product supply (product export to a third country)
NAMTax-exempt on other grounds related to international transactions
ATKOutside the scope of VAT
EUFAD37based on Section 37 of the VAT Act, a reverse charge transaction carried out in another Member State
EUFADEReverse transaction carried out in another Member State, not subject to Section 37 of the VAT Act
EUENon-reverse charge transaction performed in another Member State
HOTransaction in a third country
FADReverse Charge VAT

Product Templates ​

  • 'id': The unique identifiers of the template.
  • 'name': The name of the template.
  • 'attributes': An array of attributes for the template.
    • 'myLionId': The unique identifier of the attribute.
    • 'label': The label of the attribute.
    • 'labelTranslations': An array of translations for the label of the attribute.
      • 'language': The language of the translation.
      • 'translation': The translation of the label.
      • 'type': The type of the attribute. Possible values are: N, S, A, B, L, M
        • 'N': Numeric | Can be integer or float.
        • 'S': String | Max length is 2000 characters.
        • 'A': Textarea (basically a string with a larger size) | No size limit.
        • 'B': Boolean | Can be true or false.
        • 'L': List of Codes - one value can be selected
        • 'M': Multi-List - same a L, but multiple values can be selected
    • 'valueSet': An array of values for the attribute. Only filled if the attribute is of type List or Multi-List.
      • 'myLionId': The unique identifier of the value.
      • 'defaultTranslation': The default translation for the value.
      • 'valueTranslations': An array of translations for the value.
        • 'language': The language of the translation.
        • 'translation': The translation of the value.
    • 'isUsedForProductVariation': Whether the template is used for product variation.
    • 'isMandatory': Whether the template is mandatory.

Categories ​

  • 'id': The unique identifiers of the category.
  • 'parentId': The unique identifiers of the parent category. If the category is a top-level category, this will be null.
  • 'position': The position of the category within the parent category.
  • 'descriptions': An array of descriptions for the category.
    • 'language': The language of the description.
    • 'name': The name of the category.

Customer Groups ​

  • 'id': The unique identifiers of the customer group.
  • 'name': The name of the customer group.

Response ​

You can respond to the product update with data about the updated products. If you provide a response, MyLION will update the external IDs of the products with the ones you provide. If you don't provide a response, MyLION will not update the external IDs of the products and will not generate an error. It is your decision whether you want to provide a response or not. We recommend providing a response to ensure that MyLION has your external IDs therefore you won't have to look up the product by the MyLION ID.

The response should be in the following format:

json
[
  {
    "myLionId": 123,
    "externalId": "EXT_PROD_123"
  }
]
java
@Data
public class MLProductResponseListDTO extends ArrayList<MLProductResponseDTO>{
}

@Data
public class MLProductResponseDTO {
  private Integer myLionId;
  private String externalId;
}

Receiving Endpoint ​

To process the Product Update Webhook Notification from MyLION, you need to set up a receiving endpoint in your application. The endpoint URL should follow this format:

bash
https://<your_base_url>/rest/mylion/v1/products

When MyLION sends a webhook notification, it will make a POST request to the specified endpoint with the payload containing the updated product information. The expected response is HTTP OK (200).

Processing the Notification ​

Upon receiving the webhook notification, you can process the payload to update your product database or system with the latest information. You should validate the authenticity of the incoming request using the webhook authentication method previously outlined to ensure the data's integrity. You should start with the attributes then process the products starting with the top-level products, then the child level ones.