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
name	Name referencing a cluster configuration or attribute description	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. Products, categories, clusters and Cluster Options refuse a sourceId lookup without ?source= with a 400, even when the id is unique. Products also refuse a supplierCode lookup without ?supplier=. Companies, contacts and customers accept a sourceId lookup without ?source=, but answer 400 as soon as two sources use the same sourceId, so pass ?source= for them as well.

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. The API does not detect these duplicates: when several products share a sku, or a supplierCode with the same supplier, a GET, PATCH or bulk request by that key uses one of them without an error, and not always the same one. Make sure these values are unique in your catalog before you use them as lookup keys, or use sourceId with source instead.

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. The product, category, price, cost price and inventory bulk endpoints also refuse an empty records array. The company, contact and customer bulk endpoints accept it and change nothing.

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 sku and supplierCode as the bulk lookup key. With supplierCode, send the supplier on each record. Clusters accept sku and code, which hold the same value on a cluster.

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