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 source combination, SKU, supplier code and a few other keys.

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 or cluster	May not be unique
supplierCode/supplier	Code of a supplier referencing a product	May not be unique
uuid	UUID of a product	Always unique
code	Code referencing a cluster	Always unique
name	Name referencing a cluster configuration or attribute description	Unique for cluster configurations. Attribute description names are unique per attribute class

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?source=TECHDATA

GET /v2/products/sku/PROD-001

GET /v2/products/supplierCode/ABC123?supplier=TECHDATA

A sourceId belongs to a source and a supplierCode belongs to a supplier, so pass that second half as a query parameter. Without it the lookup matches on the code alone, which fails as soon as two external systems use the same code.

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 take the lookup key in the path. sourceId combined with source is the usual choice for integrations:

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. Products also accept uuid, sku and supplierCode as the bulk lookup key. Clusters accept sku and code.

Lookup keys per resource

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

Pricesheets are not addressed with a lookup key. Their endpoints take the Propeller id in the path, as in GET /v2/pricesheets/{id}.

See also

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