Product payload format

Our product APIs return standard JSON product payloads. An example of this payload can be downloaded on this page Attributes documentation.

On top of the attributes describing normal product characteristics that are described on this page Attributes documentation, the returned product payload contains the following structuring key elements.

Key elements

Description

_jsonVersion

Version of the returned product payload.

_type

Always ProductVersion for products payload.

updatedAt

Date of the last update on the product payload. Recipient can also make updates on product payload if internal recipient attributes have been created on SupplierXM.

createdAt

Date when the product was created on SupplierXM.
For recipients, this date can correspond to:

  • the date when an active range containing this product has been uploaded by the recipient.
  • the date when the product was shared by the source (if no active range is uploaded or if the shared product is not part of the uploaded recipient active range)

hasTags

Used to tag products. One of the main used tag is the exportable tag, it is used by retailer to tag products ready to be exported in their system.

When a product is exportable, hasTags is populated with the date the product was flagged as exportable and the exportable flag.

"hasTags": [
{
"createdAt": "2017-03-01T17:36:53",
"tag": "exportable"
}
],

brand

On SupplierXM, normalised list of brands are maintained by source organisations. Recipients can benefit from this list of normalised brands when products are shared by the source organisations.

A normalised brand is described by the following attributes
code/id: SupplierXM id of the brand
description/label: name of the brand. Can correspond to brand, sub brand depending on how source organisations maintain their list of brands.
pictureUrl: Link to the brand logo when uploaded by the source organisation.

lastRequest

When a product has been shared with a recipient who has neither accepted or rejected the product yet, product attributes are not merged in the product version of the recipient but are contained in the lastRequest element.

lastRequest element is also used to store product updates that are not yet accepted or rejected by the recipient

lastRequest contains the same attributes than the normal product payload, except the elements described in this chart

logisticalHierarchies

see Logistical hierarchies

sharingUnits

see Sharing unit

isSharedFrom

Available for the recipient only

Contains following information on the product sharing made by the source:

  • status : product sharing status. Possible status are the following :
    DRAFT : Product is part of the recipient active range, has been created by the source but is not yet shared.
    PENDING : Product sharing has been received by the source but no business decision was made by the recipient.
    ACCEPTED : Product sharing has been accepted by the recipient
    REFUSED : Product sharing has been refused by the recipient

  • lastShareDate : Last time a product update was pushed by the source to the recipient

  • firstShareDate : Date when the source initiated the product sharing with the recipient.

isSharedWith

Available for the source only

Contains following information on the product sharings made with the different recipients:

  • status : product sharing status. Possible status are the following :
    DRAFT: Product is part of the recipient active range, has been created by the source but is not yet shared.
    PENDING : Product sharing has been received by the source but no business decision was made by the recipient.
    ACCEPTED: Product sharing has been accepted by the recipient
    REFUSED: Product sharing has been refused by the recipient

  • statusUpdatedAt : Last time the product status was updated.

  • lastShareDate : Last time a product update was pushed by the source to the recipient

  • firstShareDate : Date when the source initiated the product sharing with the recipient.

  • targetOrganisation : Identifies the recipient organisation with which the product was shared

  • validation : Gives the data quality status in regards of the validation rules that been implemented in SupplierXM as requested by the recipient organisation.

isClassifiedIn

In SupplierXM, source and recipient organisations can materialise their internal product classification/hierarchy/nomenclature and can classify their products within this internal product classification. SupplierXM' permission system is based on this internal product classification.

isClassifiedIn indicates in which node the product was classified.

primaryInternalReference

In SupplierXM, recipient organisation can enrich the received product with their internal id. Internal product id of the recipient is contained in this element.

expressedIn

Indicates all the declinable units that are part of the product payload. Declinable units can belong to following dimensions (this list is not exhaustive):

  • languages
  • currencies
  • weights
  • dimensions
  • lengths
  • times
  • temperatures

specificData

Available for the source only

If the data can be adapted to a retailer, the data is seen as specific and can be added to this node.
See the section Upload specific data to import and update specific data.