Import Products with Attributes

Typically the base information of your products comes from an external source, often your ERP or your PIM. These systems contain the master data for your base product information, while enrichments are often done in Propeller. If you want to keep products in Propeller updated and create new products in bulk from an external source, the bulk products by source ID endpoint is the endpoint to use. This endpoint uses upsert operations to either create new products or update existing ones, depending on whether the product already exists in Propeller.

Endpoint

POST /v2/products/bulk/sourceId

You can also use the POST /v2/products/bulk/id endpoint, but this requires the external system to know the Propeller ID when updating products in bulk. The source ID variant is often the preferred choice.

Request body

{
  "products": [
    {
      "brand": "Garmin",
      "descriptions": [
        {
          "language": "NL",
          "value": "De high-end Edge 1030 fietscomputer van Garmin zit boordevol functies voor geweldige fietsavonturen. Met deze fietscomputer weet je niet alleen waar je bent en waar je naartoe moet, je weet ook welke routes populair zijn en wat je fietsmaten doen.<br />De Garmin Edge 1030 is uitgerust met Popularity Routing, dat de beste routes vindt, gebaseerd op miljoenen afgelegde fietskilometers in Garmin Connect. Bovendien kun je snel berichten sturen naar je fietsvrienden met rider-to-rider messaging. Je kunt bovendien live je prestaties analyseren dankzij de verbeterde realtime Strava integratie en de voorgeïnstalleerde TrainingPeaks Connect IQ app. Dit geeft je net dat duwtje in de rug om je persoonlijke records (of die van je vrienden) te verbrijzelen."
        },
        {
          "language": "EN",
          "value": "The high-end Garmin Edge 1030 bike computer is packed with features for great cycling adventures. With this cycling computer you not only know where you are and where you have to go, you also know which routes are popular and what your bike sizes are doing.<br />Garmin Edge 1030 features Popularity Routing, which finds the best routes based on millions of bike miles traveled in Garmin Connect. Plus, you can quickly message your cycling friends with rider-to-rider messaging. You can also analyze your performance live thanks to the improved real-time Strava integration and the pre-installed TrainingPeaks Connect IQ app. This gives you just that little push to shatter your personal bests (or those of your friends)."
        }
      ],
      "eanCode": "0753759256289",
      "language": "NL",
      "minimumQuantity": 1,
      "names": [
        {
          "language": "NL",
          "value": "Edge 1030 FietsComputer"
        },
        {
          "language": "EN",
          "value": "Edge 1030 Bike computer"
        }
      ],
      "notes": [
        {
          "language": "NL",
          "value": "Edge 1030 FietsComputer"
        },
        {
          "language": "EN",
          "value": "Edge 1030 Bike computer"
        }
      ],
      "oemCode": "NCABD70004",
      "package": "STK",
      "packageDescriptions": [
        {
          "language": "NL",
          "value": "Stuks"
        },
        {
          "language": "EN",
          "value": "Pieces"
        }
      ],
      "parent": {
        "source": "REST-API",
        "sourceId": "020100"
      },
      "shortDescriptions": [
        {
          "language": "NL",
          "value": "De high-end Edge 1030 fietscomputer van Garmin zit boordevol functies voor geweldige fietsavonturen. Met deze fietscomputer weet je niet alleen waar je bent en waar je naartoe moet, je weet ook welke routes populair zijn en wat je fietsmaten doen."
        },
        {
          "language": "EN",
          "value": "The high-end Garmin Edge 1030 bike computer is packed with features for great cycling adventures. With this cycling computer you not only know where you are and where you have to go, you also know which routes are popular and what your bike sizes are doing."
        }
      ],
      "shortName": "Edge 1030 FietsComputer",
      "sku": "NCABD70004",
      "source": "TECHDATA",
      "sourceId": "NCABD70004",
      "status": "A",
      "supplier": "TECHDATA",
      "supplierCode": "NCABD70004",
      "taxCode": "H",
      "unit": 1
    },
    {
      "brand": "Garmin",
      "descriptions": [
        {
          "language": "NL",
          "value": "De high-end Edge 1050 fietscomputer van Garmin zit boordevol functies voor geweldige fietsavonturen. Met deze fietscomputer weet je niet alleen waar je bent en waar je naartoe moet, je weet ook welke routes populair zijn en wat je fietsmaten doen.<br />De Garmin Edge 1030 is uitgerust met Popularity Routing, dat de beste routes vindt, gebaseerd op miljoenen afgelegde fietskilometers in Garmin Connect. Bovendien kun je snel berichten sturen naar je fietsvrienden met rider-to-rider messaging. Je kunt bovendien live je prestaties analyseren dankzij de verbeterde realtime Strava integratie en de voorgeïnstalleerde TrainingPeaks Connect IQ app. Dit geeft je net dat duwtje in de rug om je persoonlijke records (of die van je vrienden) te verbrijzelen."
        },
        {
          "language": "EN",
          "value": "The high-end Garmin Edge 1050 bike computer is packed with features for great cycling adventures. With this cycling computer you not only know where you are and where you have to go, you also know which routes are popular and what your bike sizes are doing.<br />Garmin Edge 1030 features Popularity Routing, which finds the best routes based on millions of bike miles traveled in Garmin Connect. Plus, you can quickly message your cycling friends with rider-to-rider messaging. You can also analyze your performance live thanks to the improved real-time Strava integration and the pre-installed TrainingPeaks Connect IQ app. This gives you just that little push to shatter your personal bests (or those of your friends)."
        }
      ],
      "eanCode": "0753759256211",
      "language": "NL",
      "minimumQuantity": 1,
      "names": [
        {
          "language": "NL",
          "value": "Edge 1050 FietsComputer"
        },
        {
          "language": "EN",
          "value": "Edge 1050 Bike computer"
        }
      ],
      "notes": [
        {
          "language": "NL",
          "value": "Edge 1050 FietsComputer"
        },
        {
          "language": "EN",
          "value": "Edge 1050 Bike computer"
        }
      ],
      "oemCode": "NCABD70005",
      "package": "STK",
      "packageDescriptions": [
        {
          "language": "NL",
          "value": "Stuks"
        },
        {
          "language": "EN",
          "value": "Pieces"
        }
      ],
      "parent": {
        "source": "REST-API",
        "sourceId": "020100"
      },
      "shortDescriptions": [
        {
          "language": "NL",
          "value": "De high-end Edge 1050 fietscomputer van Garmin zit boordevol functies voor geweldige fietsavonturen. Met deze fietscomputer weet je niet alleen waar je bent en waar je naartoe moet, je weet ook welke routes populair zijn en wat je fietsmaten doen."
        },
        {
          "language": "EN",
          "value": "The high-end Garmin Edge 1050 bike computer is packed with features for great cycling adventures. With this cycling computer you not only know where you are and where you have to go, you also know which routes are popular and what your bike sizes are doing."
        }
      ],
      "shortName": "Edge 1050 FietsComputer",
      "sku": "NCABD70005",
      "source": "TECHDATA",
      "sourceId": "NCABD70005",
      "status": "A",
      "supplier": "TECHDATA",
      "supplierCode": "NCABD70005",
      "taxCode": "H",
      "unit": 1
    }
  ],
  "directives": [
    {
      "fields": [
        "names",
        "descriptions"
      ],
      "operation": "skipIfNotEmpty"
    }
  ]
}

The request includes:

• products[] contains the products to create or update
• source and sourceId identify each product in the external system
• parent references the category to place the product in, using the source and sourceId of that category
• names, descriptions and shortDescriptions accept multiple languages
• directives[] controls how updates are handled (see Directives below)

Source identification

The source field should clearly refer to the origin of the product data, for example "MyERP" or "MyPIM". The sourceId is the unique identifier of that product in the source system, usually a product number, SKU or product ID from the ERP or PIM. This combination allows you to update the product information later using the same endpoint. See Sources for more on how source combinations work.

Product fields

You can find a description of all available fields in the REST API Reference. There are a few fields that are good to highlight.

parent: here you can specify the source and sourceId of the category that you want the product to end up in. This is particularly useful if the source system is also leading in creating the category or catalog structure of the products. If this information is not available in the source system then you typically map all products to one specific parent folder where you import all your new products and combine that with the skipMoveOnUpdate directive (see Directives below).

status: there are multiple statuses available in Propeller. Typically the status A (for available) is used for all products that need to be shown and sold on the various frontends or channels. If you use any of the other statuses like N (for not available), S (for presales) or P (for phase out) then realise that unless you specifically request these product statuses in your GraphQL product queries it will only return the ones with status A. It is always important to make a good mapping of the product statuses that you use in your ERP or PIM and the statuses in Propeller, in combination with the behavior you expect from your frontends with regards to these products and statuses. Do this early in your implementation project to prevent surprises later on.

Localized fields: names, shortName, descriptions and shortDescriptions can all be imported as localized strings, so you can import this data in multiple languages if the source system contains this information. See Localized Strings for the multi-language field format.

Attributes

Your products will typically have multiple product attributes. In the bulk products by source ID endpoint you can include the attributes in the same payload. Make sure the attribute descriptions already exist in Propeller, then you can safely send all product attribute values with the product payload, regardless of the attribute type (text, enum, integer, etc.). For more information on product attributes see the REST API Reference.

Directives

Directives are optional but can be useful when the external system and Propeller each own different parts of the product data.

skipIfNotEmpty: in a lot of cases the ERP contains the master data of your products. Product numbers, IDs, maybe names, supplier codes and price groups should come from the ERP. But enriching the product data with nice titles often happens in Propeller or comes from an external PIM. In those cases the skipIfNotEmpty directive can be very useful. You import the names or descriptions of the products from the ERP, but your content team might want to enhance or beautify those in Propeller before publishing on the websites. You send the skipIfNotEmpty directive and in the fields section you specify the fields that you do not want to have overwritten on updates. This way you can keep your ERP as the master of your core product data, but specify those specific fields that it may not overwrite on updates so you can manage those in Propeller or update via an integration with yet another external source like a PIM.

skipMoveOnUpdate: if your ERP is maintaining the master product data but you want to create your commercial catalog structure in Propeller and not maintain this in your ERP then this directive comes in handy. You can import all products in one parent folder but use the skipMoveOnUpdate directive. In that case you are free to move products under different categories in Propeller after they have been imported and create a solid catalog structure. The directive will prevent product updates from your ERP from moving them back to the import folder where newly created products will be placed by the import. This way you are completely free to choose where you manage your product and catalog structure: in Propeller, in your ERP or in your external PIM.

See Directives for the full list of available directives.

Batch size

You are using a bulk endpoint meaning you can send payloads with multiple products. We advise a batch size of roughly 100 products per payload. This depends on the amount of data and attributes you send with each payload.

Response

Each product in the batch returns a result:

{
  "Success": true,
  "Key": "NCABD70005",
  "Id": 14773,
  "Action": "update",
  "lookupKey": "sourceId"
}

• Success indicates whether the operation succeeded
• Key is the sourceId of the product
• Id is the Propeller internal product ID
• Action is create or update depending on whether the product already existed
• lookupKey confirms the identifier type used

The overall response includes a Messages field (with value "Completed" on success) and a Total count of processed products.

See also

• Sources for how source combinations work in bulk operations
• Directives for all available directive types
• Localized Strings for the multi-language field format
• REST API Reference for the full endpoint specification