Understanding the Request Engine

The Request Engine* enables you to ask for a specific set of products from your suppliers.
A request is a couple of product info + supplier Info: what do you ask and to whom do you ask.

Sending a request to a supplier will invite him to share with you the product -if already created on SupplierXM- or will invite him to create then share the product - if not created yet.

An up-to-date supplier reconciliation (via the supplier directory module) is the pre-requisite for sending requests. It is used to send your request to the adequate SupplierXM supplier organization.

You can import your data from your system to SupplierXM via a payload in JSON with the following format.

Please note that you need admin credentials to use this feature.

*formerly known as "Information Request"

Import format

Example of a payload:

  "products": [
      "gtin": "03037494555003",
      "primaryInternalReference": "123abc",
      "supplierInternalId": "33223",
      "categoryId": "PS_1234_12345_xxx",
      "isRequested": true,
      "namePublicLong": [
          "expressedIn": { "code": "fra-FR" },
          "data": "Hello, this is a requests!"
      "gtin": "03149170388000",
      "primaryInternalReference": "456def",
      "supplierInternalId": "33223",
      "categoryId": "PS_1234_12345_xxx",
      "isRequested": false,
      "namePublicLong": [
          "expressedIn": { "code": "fra-FR" },
          "data": "I am not requested"


gtinstring - compulsoryThe GTIN of the requested product.
supplierInternalIdstring- compulsoryYour internal id for the supplier to whom you are requesting the product.

NB: corresponds to the internalID of one of your suppliers imported via the supplier directory.
primaryInternalReferencestring - optionalYour internal reference for this product.
categoryIdstring - optionalThe short id of the category to which you want to link your product, if you are using a custom product hierarchy - also called retailer categories.
namePublicLongstring - optionalThe name of the product.
isRequestedboolean - optionaltrue by default

Can be used to remove a product from your catalog:
- True, your product is flagged as requested.
- False, your product is not flagged as requested.

NB: a request should always be created with the attribute set to true.

Import results

The import results give both statuses of the entire import and of each product imported.

Some products can be imported onto SupplierXM successfully while some others will be KO for reasons detailed below.

SUCCESSA product is considered as imported successfully when both GTIN and supplierInternalId where valid
EMPTYEquals to SUCCESS. It means that every product imported was already existing. Nothing changed with the payload.
ERRORSee the troubleshooting section for error details

Maximum import size & API calls

Maximum number of requests imported per day: 50000

Maximum size of the body payload for API calls: 10Mo

It is strongly recommended to make batches of your payload in one call (or a few), rather than make one call for each request.
Making one call for several requests will ease your platform import dashboard readability and the management of the error report files.


Import error messages

Import typeMessageDescriptionAction
XLSX + JSONInvalid check keyImporting a file with a GTIN not valid. The invalidity of a GTIN can come from many factors. (For instance, a character instead of a number or a GTIN with a size greater than 14).
GTIN cell is not in text format and is not interpreted well.
Check that the cell is in “text” format
Re-import the file with the corrected GTIN
XLSX + JSONMissing key: <name_key>The supplier has a mandatory field missing: <name_key>.Fill it and re-import the file.
XLSX + JSONInvalid type for key: . Expected <correct_type_field> got <wrong_type_field>The field is not filled properly.Change the type of this field to the one precised in the message: <correct_type_field>.
XLSX + JSONInvalid data {} does not belong to the available attributeA dynamic field is in the payload but this field is not available or not created for this organization.Check the columns and their "attributes" names.
XLSX + JSONInvalid data <name_field>. <error_msg>A dynamic field cannot be casted. This is a type error, for example a string instead of an integerCorrect the value accordingly
XLSX + JSONInvalid data <name_field>. {} is not a valid date expected format YYYY-MM-DDa date field does not have the good format. This is a “cast” error.Correct the value accordingly
XLSX + JSONThe token is not yet valid (nbf)It is a technical problem caused by a desynchronization between the services clocks.Contact support
XLSX + JSONmissing gtinNo gtin is given (and the row contains information for XLSX).Add the missing GTINs
XLSX + JSONGTIN-14 of a consumer unit or display unit must start with a '0'Importing an IR with a GTIN-14 valid but not starting with 0.
XLSX + JSONInvalid data: target market <tm_given> does not belong to the organization's target marketsThe Target Market is not valid.Put the Target Market set for the retailer organization (e.g. "250" for French Target Market)
XLSX + JSONthe type for attribute <name_dynamic_field> is not allowedThe field's type of <name_dynamic_field> is not availableCheck that you are importing the good field. If you are, contact support
XLSX + JSONattribute <name_dynamic_field> is not scoped as private for the retailer<name_dynamic_field> is not configured for your retailer organizationCheck that you are importing the good field. If you are, contact support
XLSX + JSONsome errors occured: supplier [name+ID] is reconciled with organizations [list of organization names+IDs] that all have the product [product GTIN]. Please check your reconciliation or contact the supportIf one request sent to one supplier points towards several reconciled SupplierXM organizations that share the requested product.

As 1 product is requested, this error aims to warn the retailer to verify the reconciliation instead of sending back 2 products in the catalog.
This error can be solved on the retailer side by changing the Supplier Directory reconciliation so that the request is sent to a supplier that is only linked to one of the SupplierXM organizations that share the product.

This way the retailer will be able to request one, or all the duplicated products, through different Information Requests to different suppliers.
XLSXInvalid file, mandatory columns are missing: <list_columns_missing>Global error. It means that there is at least one mandatory column missing in the sheet.Check the columns
JSONJSONDecodeError('Expecting property % enclosed in double quotes:)The imported JSON is not well formatted.Check your file for example with a tool like the JSONFormatter online to correct the file
JSONJSONDecodeError('Extra data: line 1 column 3 (char 2)',)The imported JSON is not well formatted.Check your file for example with a tool like the JSONFormatter online to correct the file
JSONInvalid data: <name_key> missing language codeThe key language code has no value for the key <name_key>Check that the language code is valid, for example EN and not ZZ.
JSONInvalid file format, missing key: productsThe root key products is missing in the json fileAdd the root key at the beginning of the file
JSONInvalid data: <name_key> element is not a valid dict<name_key> contains an element which is not a valid dict.Check that every pair name/value is valid. The name must belong to the authorized list.
XLSX + JSONInvalid data: [value] does not belong to the referential [Referential name]The value you submitted does not belong to the referential, thus is not authorised. Please check that the value is authorised, and contact the support if you think that a value is missing.Check that the value (the code) does belong to the referential. Contact the support if you think that a value is missing, so that the referential can be updated.