Lookup keys

Lookup keys let you reference resources using various identifiers. Instead of always using the internal Propeller ID, you can look up resources by external ID, source combination, SKU or supplier code.

Lookup keys are case-sensitive. Use the exact casing shown here, for example sourceId (not sourceid).

Available lookup keys

Lookup key	Description	Uniqueness
id	Unique Propeller internal identifier	Always unique
sourceId/source	External system unique ID. sourceId always needs to be combined with a source	Unique in combination
sku	Stock-keeping unit code referencing a product	May not be unique
supplierCode/supplier	Code of a supplier referencing a product	May not be unique
externalId	External identifier	Always unique

URL patterns

For individual resource operations (GET, PATCH, DELETE), use the lookup key in the URL path:

GET /v2/products/id/481189

GET /v2/products/sourceId/NCABD70004

GET /v2/products/sku/PROD-001

GET /v2/products/supplierCode/ABC123

Uniqueness

A sku is not guaranteed to be unique in the catalog, as multiple products with the same sku can exist. The supplierCode/supplier combination also does not have to be unique. When multiple resources match a lookup key, the API returns an error:

{
  "error": {
    "code": 80005,
    "status": 400,
    "type": "ProductMultipleFound",
    "messages": ["Multiple products found. Please provide additional filters"]
  }
}

When no resource matches the lookup key, the API returns a 404:

{
  "error": {
    "code": 80006,
    "status": 404,
    "type": "ProductNotFound",
    "messages": ["Product with id [481189] not found"]
  }
}

The sourceId/source combination is the most important lookup key for integrations. See Sources for details.

Bulk operations

Bulk endpoints require sourceId combined with source for identifying resources:

POST /v2/products/bulk/sourceId

{
  "products": [
    {
      "sourceId": "NCABD70004",
      "source": "TECHDATA",
      "names": [{ "language": "EN", "value": "Product Name" }]
    }
  ]
}

Lookup keys must be unique within a single bulk request. The sourceId/source combination must be unique across the items in one request, and id values must be unique within one request. Requests that contain duplicate lookup keys are rejected, and the records array cannot be empty.

The /bulk/sourceId variant upserts: it creates records that do not yet exist and updates the ones that do. The /bulk/id variant is update-only and cannot create new records, since it requires the Propeller id to already exist.

Lookup keys per resource

Resource	Supported lookup keys
Products	id, sourceId, sku, supplierCode
Categories	id, sourceId
Companies	id, sourceId
Customers	id, sourceId
Contacts	id, sourceId
Clusters	id, sourceId, code
Cluster Config	id, name
Pricesheets	id, code
Attributes	id, name

See also

• Sources for details on source/sourceId combinations
• REST API Reference for the full endpoint specification