Directives

Directives control how bulk endpoints handle data during import. They are only available on bulk endpoints and are specified in the request payload.

Available directives

Directive	Fields	Effect
skipIfNotEmpty	Array of field names	On update, skip updating fields of an existing resource that are not empty
skipMoveOnUpdate	Empty array []	On update, skip moving an existing resource in the parent resource provided
skipCreate	Empty array []	Skip creating new resources, only update existing ones
mergeTranslationsOnUpdate	Empty array []	On update, delete all translations for a resource that are not provided in the payload
resetOnUpdate	Array of field names	On update, empty the listed fields when the incoming record does not carry a value for them

Not every endpoint accepts every directive. The product and category bulk endpoints accept all five. The company, contact and customer bulk endpoints accept skipIfNotEmpty, skipCreate and skipMoveOnUpdate. The pricing bulk endpoints (prices, cost prices, bulk prices, bulk cost prices, pricesheets, discounts, taxes and zone tax codes) accept resetOnUpdate only.

Endpoint group	Accepted directives
Products, categories, clusters	skipIfNotEmpty, skipMoveOnUpdate, mergeTranslationsOnUpdate, resetOnUpdate, skipCreate
Companies, contacts, customers	skipIfNotEmpty, skipCreate, skipMoveOnUpdate
Prices, cost prices, pricesheets, discounts, taxes, zone tax codes	resetOnUpdate

skipIfNotEmpty

Preserve existing data by skipping updates to non-empty fields. Pass an array of field names to protect.

{
  "products": [
    {
      "sourceId": "PROD-001",
      "source": "ERP_SYSTEM",
      "names": [{ "language": "EN", "value": "Updated Product Name" }],
      "descriptions": [{ "language": "EN", "value": "Updated description" }]
    }
  ],
  "directives": [
    { "fields": ["names", "descriptions"], "operation": "skipIfNotEmpty" }
  ]
}

If names or descriptions already have content, they will not be overwritten. Empty fields will still be updated.

skipMoveOnUpdate

Prevent resources from being moved to a different parent. The product data gets updated but the product stays in its current category.

{
  "products": [
    {
      "sourceId": "PROD-001",
      "source": "ERP_SYSTEM",
      "parent": { "sourceId": "NEW_CATEGORY", "source": "ERP_SYSTEM" },
      "names": [{ "language": "EN", "value": "Updated Product" }]
    }
  ],
  "directives": [
    { "fields": [], "operation": "skipMoveOnUpdate" }
  ]
}

skipCreate

Only update existing resources. Resources in the payload that do not already exist in Propeller are skipped.

{
  "products": [
    {
      "sourceId": "EXISTING_PROD",
      "source": "ERP_SYSTEM",
      "names": [{ "language": "EN", "value": "Updated Name" }]
    },
    {
      "sourceId": "NEW_PROD",
      "source": "ERP_SYSTEM",
      "names": [{ "language": "EN", "value": "New Product" }]
    }
  ],
  "directives": [
    { "fields": [], "operation": "skipCreate" }
  ]
}

EXISTING_PROD will be updated. NEW_PROD will be skipped.

mergeTranslationsOnUpdate

Replace all translations with only those provided in the payload. Any language version not included gets deleted.

{
  "products": [
    {
      "sourceId": "PROD-001",
      "source": "ERP_SYSTEM",
      "names": [
        { "language": "EN", "value": "English Name" },
        { "language": "NL", "value": "Dutch Name" }
      ]
    }
  ],
  "directives": [
    { "fields": [], "operation": "mergeTranslationsOnUpdate" }
  ]
}

Only English and Dutch translations will remain. All other language translations will be deleted.

resetOnUpdate

Empty specific fields on update. List the field names in fields. When the incoming record does not carry a value for a listed field, the existing value is cleared instead of kept.

{
  "products": [
    {
      "sourceId": "PROD-001",
      "source": "ERP_SYSTEM",
      "names": [{ "language": "EN", "value": "Updated Product" }]
    }
  ],
  "directives": [
    { "fields": ["manufacturer"], "operation": "resetOnUpdate" }
  ]
}

The product keeps its new name and its manufacturer is emptied. Without the directive an omitted field keeps its current value, which is the default behavior of the bulk endpoints.

Use this when the external system owns a field and an empty value there should mean empty in Propeller. It clears plain fields such as manufacturer. It does not clear localized arrays such as names and descriptions, so check the behavior for the fields you rely on.

Combining directives

Multiple directives can be used together in a single request:

{
  "products": [],
  "directives": [
    { "fields": ["names", "descriptions"], "operation": "skipIfNotEmpty" },
    { "fields": [], "operation": "skipMoveOnUpdate" },
    { "fields": [], "operation": "mergeTranslationsOnUpdate" }
  ]
}

See also

• Sources for how bulk endpoints use source combinations
• REST API Reference for the full endpoint specification