Every product and variant in DJUST carries multiple identifiers. Some are auto-generated by the platform, others are provided by the integrator or imported through Data Hub. Understanding which identifier to use — and when — is essential for a smooth integration.

Key concepts

Identifier categories

DJUST identifiers fall into two categories:

• Platform-generated: Created automatically by DJUST when a product or variant is created. These are immutable and cannot be set or modified by the caller.
• Integrator-provided: Supplied by the integrator at creation time (via API or Data Hub import). Some are required, others are optional.

The idType query parameter

Most product and variant endpoints accept an idType query parameter. This tells the API which identifier you are passing in the path:

GET /v1/products/{id}?idType=EXTERNAL_ID
GET /v1/product-variants/{id}?idType=SKU

If idType is omitted, the API defaults to DJUST_ID.

Product identifiers

id (DJUST_ID)

The platform-generated business identifier. It is assigned automatically when the product is created and is the default identifier used in all API calls.

sku

An auto-generated numeric identifier produced by a sequential counter (starting at 10000). It is unique and immutable. Useful for internal referencing and media association.

externalId

The primary identifier for integrators. It must be provided at creation, must be unique across all products, and cannot be changed after creation. This is typically your product ID from an external system (PIM, ERP, etc.).

Variant identifiers

id (DJUST_ID)

Same behavior as the product id — platform-generated, immutable, default identifier.

skuVariant

Auto-generated numeric identifier from the same sequential counter as product sku. Unique across all variants. Used for media association and direct lookups.

skuProduct

Automatically copied from the parent product's sku at variant creation time. It allows grouping variants by their parent product without an additional lookup.

externalId

Same behavior as the product externalId — integrator-provided, required, unique, and immutable.

externalSku

An optional identifier typically used to store a SKU from an external system (e.g., supplier catalog, Mirakl). Unlike externalId, it is mutable after creation and is not exposed in Shop APIs.

ean (European Article Number)

An optional industry-standard barcode identifier. Not enforced as unique — multiple variants may share the same EAN.

mpn (Manufacturer Part Number)

An optional manufacturer reference. Not enforced as unique. Not exposed in Shop APIs.

⚠️

Batch-only identifiers: EAN and MPN are only supported as idType values in list/batch queries. A single-entity lookup with idType=EAN or idType=MPN will return an error.

Supported idType values per context

Creation behavior

When a product or variant is created via the API, the following happens automatically:

✅

Tip: Always provide a meaningful externalId that maps to your source system. This is the key you will use most often to look up and synchronize data.

Immutability rules

Platform-generated identifiers (id, sku, skuVariant, skuProduct) and integrator-required identifiers (externalId) are immutable — they do not appear in update request payloads.

Only externalSku, ean, and mpn can be modified after creation.

Data Hub behavior

When products and variants are imported through Data Hub, the identifier handling depends on the source system.

⚠️

Mirakl-specific behavior: When importing from Mirakl, if the source product has no SKU value, Data Hub automatically generates a random UUID as externalSku. For FTP/CSV sources, externalSku remains empty if not explicitly mapped.

flowchart LR
  %% Styles (Readme)
  classDef create   fill:#e8f1ff,stroke:#2f6feb,stroke-width:2px,color:#0b3d91;
  classDef read     fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#1e1b4b;
  classDef update   fill:#e0f7fa,stroke:#06b6d4,stroke-width:2px,color:#0c4a6e;
  classDef decision fill:#fff4e5,stroke:#f59e0b,stroke-width:2px,color:#7a3e00;
  classDef place    fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d;
  classDef sys      fill:#f2f4f7,stroke:#475569,stroke-width:2px,color:#111827;

  A[📦 Source system<br>PIM / ERP / Mirakl] -->|externalId, externalSku,<br>ean, mpn| B[🔄 Data Hub<br>Field mapping]
  B --> C{externalSku<br>provided?}
  C -->|Yes| D[✅ Use provided value]
  C -->|No + Mirakl| E[🆕 Generate UUID]
  C -->|No + FTP/CSV| F[Leave empty]
  D --> G[📤 Send to platform]
  E --> G
  F --> G
  G -->|Platform generates<br>id, sku, skuVariant| H[✅ Product/Variant<br>created]

  class A sys
  class B update
  class C decision
  class D place
  class E create
  class F sys
  class G create
  class H place

Typical workflow

A typical product integration follows these steps:

1. Create a product via API or Data Hub, providing an externalId.
2. The platform generates id and sku automatically.
3. Create one or more variants for that product, each with its own externalId.
4. The platform generates id, skuVariant, and copies skuProduct from the parent.
5. Query products/variants using idType to specify which identifier you are passing.
6. Update variant metadata (externalSku, ean, mpn) as needed.

sequenceDiagram
  participant Integrator
  participant DJUST API

  Integrator->>DJUST API: POST /v1/products (externalId: "ERP-1001")
  DJUST API-->>Integrator: 201 Created (id: "abc123", sku: "10000")

  Integrator->>DJUST API: POST /v1/product-variants (externalId: "ERP-1001-BLUE-M")
  DJUST API-->>Integrator: 201 Created (id: "def456", skuVariant: "10001", skuProduct: "10000")

  Integrator->>DJUST API: GET /v1/products/ERP-1001?idType=EXTERNAL_ID
  DJUST API-->>Integrator: 200 OK (product details)

  Integrator->>DJUST API: GET /v1/product-variants/10001?idType=SKU
  DJUST API-->>Integrator: 200 OK (variant details)

Best practices

• Use externalId as your primary integration key. It maps directly to your source system and is supported in both Admin and Shop APIs.
• Do not store or rely on sku for external integrations. SKUs are platform-generated numeric values meant for internal use and media association.
• Always specify idType explicitly when not using DJUST_ID, to avoid ambiguity.
• Use externalSku for supplier-facing references when your variants have a different SKU in the supplier's system.
• Provide ean when available — it improves product identification and is exposed in Shop APIs for storefront use.

Common mistakes

Deprecated identifiers

⚠️

These fields may still appear in some API responses for backward compatibility, but they should not be used in new integrations.