Upload Products

To upload products in your catalog, you need, as a prerequisite, to get an access token.
The steps to get a token are described in the Authentication and tokens page.

Once you are authenticated, you are able to upload products to your catalogue

Upload your first product

Now that you are authenticated, you can upload your first product via our REST API which is an HTTPS POST request to the Product Upsert API: Product Upsert

To send your product data to the SupplierXM platform, standard XML and JSON templates are provided.
These files may differ depending on the SupplierXM product category you choose for your products.

You can find examples of these standard files for the SupplierXM product category you are using, and the documentation for each attribute in the Attributes documentation.

Mandatory attributes:

  • GTIN
  • nameLegal or namePublicLong or namePublicShort

Attributes limited in Size:

  • namePublicLong is limited to 200 characters
  • namePublicShort is limited to 35 characters
>> replace 03036811359935 with your own gtin :)
>> add your access token to the HTTP header 

curl -H 'Authorization: Bearer SALSIFY_TOKEN' -XPOST 'https://apis.supplierxm.salsify.com/public/v1/products' -d '{
    "data": [
        {
            "gtin": "03036811359935",
            "namePublicLong": [
                {
                    "data": "Marmite Yeast Extract 250G",
                    "expressedIn": {
                        "code": "eng-GB",
                    }
                }
            ]
        }
    ]
}' -H 'Content-Type: application/json'

>> {"tracking": TRACKING_ID}

Bypassing SupplierXM mandatory rules

The SupplierXM standard import also provides a way for manufacturers to disable a control made of the platform. In order to do this, you only need to add a piece of XML just before the closing product tag.

<product>
  ...
  <validationRules>
    <validationRule>
      <type>DeactivateValidationRule</type>
      <ruleId><!-- the id of the rule --></ruleId>
    </validationRule>
  </validationRules>
</product>

This feature is also available in JSON:

{
  "data": [
    {
      "gtin": "05555555555550", --> gtin of the product the change are applicables to
      "validationRules": [
        {
          "rule_id": 7,
          "type": "ActivateValidationRule" --> To activate rule 7
        },
        {
          "rule_id": 34,
          "type": "DeactivateValidationRule" --> To deactivate rule 34
        }
      ],
    }
  ]
}

Available rules id

Rule IDField (Regulatory Rule)
4netContent (INCO)
5originText (INCO)
8ratioAlcohol (INCO)
19compulsoryStatements (CELEX)
23netContent (CELEX)
24originText (CELEX)
25hazardPictograms (CELEX)
27periodAfterOpening (CELEX)
29compulsoryStatements (CLP)
33composition (CLP)
34hazardPictograms (CLP)
36advices (2009/48/CE)
38compulsoryStatements (2009/48/CE)
48advices (767/2009)
3777drainedWeight (GDSN)
3779unitedNationsDangerousGoodsNumberCode (GDSN)
21541advices (INCO)
21545composition (INCO)
21547allergens (INCO)
21551conservations (INCO)
21553isPartitionedBy (INCO)

Get the upload status

Once a product is uploaded on SupplierXM platform through API, a tracking Id is provided to follow upload status:

{
    "tracking": 347269
}

The tracking Id can be used then to check import status.
It remains always valid.
More information on how to use it can be found in API reference: Product inbound tracking

Upload logistical hierarchies

📘

Understanding logistical trees

If you have not already, please read the Understanding logistical trees page

As described in the documentation (link above), logistical hierarchies can be uploaded (creation or update) under the logisticalHierarchies field in the inbound API.

Upload assets

Assets need to be uploaded in the "asset" key.
More information on pictures is provided in the Media assets documentation.

Assets can not be deleted once uploaded.
It is possible anyway to set an expiration date during asset import with the field fileEffectiveEndDateTime.

Updating an asset will erase all his attributes, thus, it is required to update all attributes if one of them has to be updated.
Any attribute's update contained in assets.pictures will update the updatedAt field of assets.pictures.

You should at least provide the URL of the picture to download in the field url.

{
    "data": [
        {
            "gtin": "03571996445009",
            "assets": {
                "pictures": [
                    {
                        "isPackshot": true,
                        "url": "https://stream.alkemics.com/images/logo-inverse.781f93875f9c12548f1a45118dde00b1.png"
                    },
                    {
                        "isPackshot": false,
                        "url": "https://stream.alkemics.com/images/logo-inverse.781f93875f9c12548f1a45118dde00b1.png"
                    }
                ]
            }
        }
    ]
}

You can also choose, when updating assets, to replace them instead of adding them.
To do so, set up a Replace parameters

{
    "assets": {
        "replace": {
            "pictures": true,
            "documents": true,
            "videos": true
        },
        "pictures": [],
        "documents": [],
        "videos": []
    }
}

Whenever a product is upserted with replace set as true, its existing assets are deleted.
Whenever a product is upserted with replace set as true, the new assets present in the payload, if they exist, should be added to product data.
Whenever a product is upserted with replace set as false, the new assets present in the payload, if they exist, should be appended to product data.

If no assets is updated in the payload, then the replace content doesn't matter, nothing will happen for this category of assets.

If replace is not present, all attributes are false
If present but some attributes are not present, they’ll default to false

{
    "assets": {
				"replace": {
            "pictures": true,
        },
        "pictures": [],
        "documents": [],
        "videos": []
    }
}

Means that videos and documents are false.

Upload specific data

If the data can be adapted to a retailer, the data is seen as specific and can be added to the specificData node.
To upload or update this specific data, you’ll have to specify the adapted data in the specificData.data field and also specify for which retailer the data is sent in the targetOrganization.id field.

{
  "data": [
    {
      "gtin": "05555555555550", --> gtin of the product the change are applicables to
      "specificData": [
        {
          "data": {
            "namePublicShort": [
              {
                "expressedIn": {
                  "code": "eng-GB"
                },
                "data": "adapted description of my product" --> adapted data for my retailer
              }
            ]
          },
          "targetOrganization": { "id": 1234 } --> id of the retailer
        }
      ]
    }
  ]
}

Upload Textile variants

📘

Understanding the variants

If you have not already, please read the Understand the variants page

As described in the documentation (link above), textile variants can be uploaded (creation or update) by specifying the variant in the list attribute textileVariantList in the inbound API.

More information are provided in the above link.

Upload : A more global Json Model

What does it look like if we take a more global approach, here's an example with media information, different products, a bulk of product information, and the Manufacturer's information.

{
    "data": [
        {
            "GPC": {
                "categoryCode": {
                    "code": "10000320"
                }
            },
            "aDRTunnelRestrictionCodeList": [
                {
                    "code": "NONE"
                }
            ],
            "advertisedInformations": [
                {
                    "data": "An amazing perfume smelling really nice",
                    "expressedIn": {
                        "code": "en-US"
                    }
                }
            ],
            "allergenTypeList": [],
            "allergens": [],
            "areaOfUseList": [
                {
                    "areaOfUseCode": {
                        "code": "WRIST"
                    }
                }
            ],
            "assets": {
                "pictures": [
                    {
                        "angleHorizontal": "2",
                        "angleOther": null,
                        "angleVertical": "0",
                        "contentType": "1",
                        "exportables": [],
                        "fileEffectiveEndDateTime": "2031-05-26T22:00:00",
                        "fileEffectiveStartDateTime": "2021-05-26T22:00:00",
                        "fileType": null,
                        "format": "JPEG",
                        "isPackshot": false,
                        "productFace": "0",
                        "tag": [
                            {
                                "tag": null
                            }
                        ],
                        "url": "https://classicurl.com/api/wedia/dam/variation/u5wa3z31qn5sepwezndd5f37uqzph3ibr8dswge/pf_eretail"
                    },
                    {
                        "angleHorizontal": "2",
                        "angleOther": null,
                        "angleVertical": "0",
                        "contentType": "1",
                        "exportables": [],
                        "fileEffectiveEndDateTime": "2031-01-10T23:00:00",
                        "fileEffectiveStartDateTime": "2021-01-10T23:00:00",
                        "fileType": null,
                        "format": "JPEG",
                        "isPackshot": true,
                        "productFace": "0",
                        "tag": [
                            {
                                "tag": null
                            }
                        ],
                        "url": "https://classicurl.com/api/wedia/dam/variation/u5wa3z31qn5sezmxnr45qg8xekzph2ibr8dswge/pf_eretail"
                    }
                ]
            },
            "brandHighlight": [
                {
                    "data": "We're an amazing perfume brand name AmazingPerfumeBrand and we do perfumes in Grace.",
                    "expressedIn": {
                        "code": "en-US"
                    }
                }
            ],
            "brandText": "Rose perfume",
            "colorDescription": [
                {
                    "data": null,
                    "expressedIn": {
                        "code": "en-US"
                    }
                }
            ],
            "colorGroup": null,
            "composition": [
                {
                    "data": "Grey Amber. WATER (AQUA). Civette Musk. Roses oil.",
                    "expressedIn": {
                        "code": "en-US"
                    }
                }
            ],
            "compulsoryStatements": [
                {
                    "text": [
                        {
                            "data": "Ingredients list may vary",
                            "expressedIn": {
                                "code": "en-US"
                            }
                        }
                    ]
                }
            ],
            "conservations": [
                {
                    "text": [
                        {
                            "data": "No specific",
                            "expressedIn": {
                                "code": "en-US"
                            }
                        }
                    ]
                }
            ],
            "consumerBenefits": [
                {
                    "sequenceNumberText": "1",
                    "text": [
                        {
                            "data": "Will make you smell great",
                            "expressedIn": {
                                "code": "en-US"
                            }
                        }
                    ]
                }
            ],
            "consumptionAdvice": [
                {
                    "data": "Spray once inside each wrists then rub it over your neck.",
                    "expressedIn": {
                        "code": "en-US"
                    }
                }
            ],
            "contactInformationList": [
                {
                    "availableTimeTextList": [],
                    "contactCommunicationChannelList": [
                        {
                            "contactCommunicationChannelCode": {
                                "code": "EMAIL"
                            },
                            "contactCommunicationChannelNameText": "Email",
                            "contactCommunicationChannelValueText": "[email protected]"
                        },
                        {
                            "contactCommunicationChannelCode": {
                                "code": "TELEPHONE"
                            },
                            "contactCommunicationChannelNameText": "Téléphone",
                            "contactCommunicationChannelValueText": "0 880 80 80 80"
                        }
                    ],
                    "contactDescriptionTextList": [],
                    "contactGLN": "3012827700101",
                    "contactNameText": "Service Consommateur AmazingPerfumeBrand",
                    "contactTypeCode": {
                        "code": "CONSUMER_SUPPORT"
                    },
                    "structuredAddressList": [
                        {
                            "cityText": "Les Ponts De Ce Cedex",
                            "countryCode": {
                                "code": "250"
                            },
                            "postalCodeText": "49130",
                            "provinceStateCodeText": null,
                            "streetAddressText": "Square Raoul Follereau"
                        }
                    ]
                },
                {
                    "availableTimeTextList": [],
                    "contactCommunicationChannelList": [],
                    "contactDescriptionTextList": [],
                    "contactGLN": "3012827700101",
                    "contactNameText": "AmazingPerfumeBrand marketing",
                    "contactTypeCode": {
                        "code": "TARGET_MARKET_INFORMATION_PROVIDER"
                    },
                    "structuredAddressList": [
                        {
                            "cityText": "BOULOGNE BILLANCOURT",
                            "countryCode": {
                                "code": "250"
                            },
                            "postalCodeText": "92100",
                            "provinceStateCodeText": null,
                            "streetAddressText": "45 RUE DES CHENES"
                        }
                    ]
                },
                {
                    "availableTimeTextList": [],
                    "contactCommunicationChannelList": [],
                    "contactDescriptionTextList": [],
                    "contactGLN": "3012827700101",
                    "contactNameText": "AmazingPerfumeBrand marketing",
                    "contactTypeCode": {
                        "code": "MANUFACTURER"
                    },
                    "structuredAddressList": [
                        {
                            "cityText": "BOULOGNE BILLANCOURT",
                            "countryCode": {
                                "code": "250"
                            },
                            "postalCodeText": "92100",
                            "provinceStateCodeText": null,
                            "streetAddressText": "45 RUE DES CHENES"
                        }
                    ]
                }
            ],
            "countryOfAssembly": {
                "code": "250"
            },
            "countryOfLastProcessing": {
                "code": "250"
            },
            "countryOfOriginList": [
                {
                    "countryOfOriginCode": {
                        "code": "250"
                    },
                    "countryOfOriginSubdivisionList": []
                }
            ],
            "createdShareValueStatement": [
                {
                    "data": "Packaging recyclable, check your local recycling processes",
                    "expressedIn": {
                        "code": "en-US"
                    }
                }
            ],
            "dangerousGoodsPackagingGroup": {
                "code": "NOT_APPLICABLE"
            },
            "dataCarrierTypeCode": {
                "code": "EAN_UCC_13_SYMBOL"
            },
            "dateOfLastApiModification": "2022-09-27+02:00",
            "description": [
                {
                    "data": "Especially great smell formula, now stay with you 20% longer",
                    "expressedIn": {
                        "code": "en-US"
                    }
                }
            ],
            "environmentstatement": [
                {
                    "data": "No whale was hurt or killed to manufacture this product. All our Civettes are vegan fed and gives their musks in a non invasive manner",
                    "expressedIn": {
                        "code": "en-US"
                    }
                }
            ],
            "firstOrderDateTime": null,
            "functionalName": [
                {
                    "data": "perfume",
                    "expressedIn": {
                        "code": "en-US"
                    }
                }
            ],
            "geneticallyModifiedDeclarationCode": {
                "code": "UNDECLARED"
            },
            "grossWeight": [
                {
                    "data": "70",
                    "expressedIn": {
                        "code": "g"
                    }
                }
            ],
            "gtin": "0012770208597",
            "hairTypes": [],
            "hasBatchNumber": true,
            "iCPEStorageCompatibilityCode": null,
            "importEuropeanClassification": "3307202002",
            "invoiceName": [
                {
                    "data": "Perfume 50 ml extra musk",
                    "expressedIn": {
                        "code": "en-US"
                    }
                }
            ],
            "isComplementaryWith": [
                {
                    "targetProduct": {
                        "gtin": "0012779003131"
                    }
                },
                {
                    "targetProduct": {
                        "gtin": "0012770110944"
                    }
                },
                {
                    "targetProduct": {
                        "gtin": "0012770111552"
                    }
                },
                {
                    "targetProduct": {
                        "gtin": "0012770111583"
                    }
                }
            ],
            "isConsumerUnit": true,
            "isDangerousSubstance": false,
            "isDerivedFrom": [],
            "isInvoiceUnit": true,
            "isIrradiated": false,
            "isOrderableUnit": true,
            "isPackagingMarkedReturnable": false,
            "isPromotionalItem": false,
            "isRechargeable": false,
            "isSeasonal": false,
            "isSizedBy": [
                {
                    "depth": [
                        {
                            "data": 40.0,
                            "expressedIn": {
                                "code": "mm"
                            }
                        }
                    ],
                    "dimensionType": {
                        "code": "IN_PACKAGE"
                    },
                    "height": [
                        {
                            "data": 100.0,
                            "expressedIn": {
                                "code": "mm"
                            }
                        }
                    ],
                    "width": [
                        {
                            "data": 40.0,
                            "expressedIn": {
                                "code": "mm"
                            }
                        }
                    ]
                }
            ],
            "isTestedOnAnimals": false,
            "isVariableUnit": false,
            "kind": {
                "code": "100993"
            },
            "labelDescription": [
                {
                    "data": "Musk perfume extra Civette",
                    "expressedIn": {
                        "code": "en-US"
                    }
                }
            ],
            "minimumAge": [
                {
                    "data": 12.0,
                    "expressedIn": {
                        "code": "y"
                    }
                }
            ],
            "minimumTradeItemLifespanFromTimeOfProduction": 1080,
            "nameLegal": [
                {
                    "data": "Perfume extra musk civette - 50 ML",
                    "expressedIn": {
                        "code": "en-US"
                    }
                }
            ],
            "namePublicLong": [
                {
                    "data": "Perfume extra musk civette - 50 ML",
                    "expressedIn": {
                        "code": "en-US"
                    }
                }
            ],
            "netContent": [
                {
                    "data": 50.0,
                    "expressedIn": {
                        "code": "mL"
                    }
                }
            ],
            "netWeight": [
                {
                    "data": "49",
                    "expressedIn": {
                        "code": "g"
                    }
                }
            ],
            "originCountry": {
                "code": "250"
            },
            "originText": [
                {
                    "data": "France",
                    "expressedIn": {
                        "code": "en-US"
                    }
                }
            ],
            "packaging": [
                {
                    "data": "50 ml",
                    "expressedIn": {
                        "code": "fr",
                        "label": "français"
                    }
                }
            ],
            "packagingInformationList": [
                {
                    "isPackagingExemptFromRefuseObligation": false,
                    "isPackagingReturnable": false,
                    "packageDepositList": [],
                    "packagingFeatureList": [],
                    "packagingFunctionList": [],
                    "packagingLevelNumber": "1",
                    "packagingMaterialList": [
                        {
                            "isPackagingMaterialRecoverable": false,
                            "packagingMaterialCompositionQuantityNumber": [],
                            "packagingMaterialTypeCode": null
                        }
                    ],
                    "packagingRefundObligationNameTextList": [],
                    "packagingRefuseObligationNameTextList": [],
                    "packagingTypeCode": {
                        "code": "TU"
                    },
                    "packagingTypeDescriptionTextList": [],
                    "platformTermsAndConditionsCode": null,
                    "platformTypeCode": null,
                    "returnableAssetList": []
                }
            ],
            "partyInformationList": [
                {
                    "partyAddressText": null,
                    "partyGLN": "3012827700101",
                    "partyNameText": "AmazingPerfumeBrand Head Office",
                    "partyRoleCode": {
                        "code": "HEAD_OFFICE"
                    },
                    "structuredAddressList": [
                        {
                            "cityText": "BOULOGNE BILLANCOURT",
                            "countryCode": {
                                "code": "250"
                            },
                            "postalCodeText": "92100",
                            "provinceStateCodeText": null,
                            "streetAddressText": "45 RUE DES CHENES"
                        }
                    ]
                },
                {
                    "partyAddressText": null,
                    "partyGLN": "3012827700101",
                    "partyNameText": "AmazingPerfumeBrand Head Office",
                    "partyRoleCode": {
                        "code": "INFORMATION_PROVIDER"
                    },
                    "structuredAddressList": [
                        {
                            "cityText": "BOULOGNE BILLANCOURT",
                            "countryCode": {
                                "code": "250"
                            },
                            "postalCodeText": "92100",
                            "provinceStateCodeText": null,
                            "streetAddressText": "45 RUE DES CHENES"
                        }
                    ]
                }
            ],
            "priceComparisonMeasurementNumber": [
                {
                    "data": 50.0,
                    "expressedIn": {
                        "code": "mL"
                    }
                }
            ],
            "priceComparisonType": {
                "code": "PER_L"
            },
            "productPropertiesCode": [],
            "productRangeText": "Body",
            "productTestedAnimalSpeciesList": [
                {
                    "productTestedAnimalSpeciesCode": {
                        "code": "NOT_TESTED_ON_ANIMALS"
                    }
                }
            ],
            "productTextureList": [],
            "productTreatmentList": [
                {
                    "productTreatmentCode": {
                        "code": "SMELL_GOOD"
                    }
                },
                {
                    "productTreatmentCode": {
                        "code": "SMELL_GOOD"
                    }
                }
            ],
            "recommendedUsageLocationText": [
                {
                    "data": "Apply on your wrist then your neck ",
                    "expressedIn": {
                        "code": "en-US"
                    }
                }
            ],
            "serves": [
                {
                    "data": "1",
                    "expressedIn": {
                        "code": "en-US"
                    }
                }
            ],
            "skinTypeList": [],
            "solarProtectionEfficiency": null,
            "sunburnProtectionFactor": null,
            "supplierCode": "236653",
            "synonyms": [
                {
                    "text": [
                        {
                            "data": "Hydratation",
                            "expressedIn": {
                                "code": "en-US"
                            }
                        }
                    ]
                },
                {
                    "text": [
                        {
                            "data": "Fragance",
                            "expressedIn": {
                                "code": "en-US"
                            }
                        }
                    ]
                },
                {
                    "text": [
                        {
                            "data": "high tolerance",
                            "expressedIn": {
                                "code": "en-us"
                            }
                        }
                    ]
                },
                {
                    "text": [
                        {
                            "data": "Something something",
                            "expressedIn": {
                                "code": "en-US"
                            }
                        }
                    ]
                },
                {
                    "text": [
                        {
                            "data": "Smells amazing",
                            "expressedIn": {
                                "code": "en-US"
                            }
                        }
                    ]
                },
                {
                    "text": [
                        {
                            "data": "No alcohol",
                            "expressedIn": {
                                "code": "en-US"
                            }
                        }
                    ]
                }
            ],
            "targetConsumerAgeList": [
                {
                    "targetConsumerAgeCode": {
                        "code": "ADOLESCENT"
                    }
                },
                {
                    "targetConsumerAgeCode": {
                        "code": "MIDDLE_ADULT"
                    }
                }
            ],
            "targetConsumerGender": {
                "code": "unisex"
            },
            "tradeItemConditionType": false,
            "tradeItemDateOnPackagingTypeCode": {
                "code": "best_before_date"
            },
            "typePackaging": {
                "code": "EACH"
            },
            "unitedNationsDangerousGoodsNumberCode": null,
            "validationRules": [
                {
                    "rule_id": 2193,
                    "type": "DeactivateValidationRule"
                },
                {
                    "rule_id": 21547,
                    "type": "DeactivateValidationRule"
                }
            ]
        }
    ]

API References

public/v1/products: Upload Products


What’s Next