Trade Item API (1.0.0-Preview2)

Retrieve the complete trade item information for a specific supplier item combination.

This endpoint returns a single trade item identified by the composite key of supplierIdGln and supplierItemNumber. The trade item key is at the root level, with nested objects for each component:

• details: Identification and operational details (GTINs, status, condition, validity dates)
• descriptions: Multilingual item descriptions (nested array)
• ordering: Order unit, minimum order quantity, step size, lead time
• pricings: Pricing conditions with allowance/surcharges (nested array)
• relations: Accessories, spare parts, and other related items (nested array)
• logisticDetails: Dimensions, weights, and volumes (nested array)
• attachments: Images, documents, and certificates (nested array)
• packagingUnits: Packaging level information (nested array, aggregate root only)

Subresources: Most components are also available as dedicated subresources:

• /details - Trade item identification and operational details
• /descriptions - Multilingual descriptions with language filtering
• /ordering - Order unit configuration and lead time
• /pricings - Pricing conditions with allowance/surcharges
• /relations - Accessories, spare parts, and related items
• /logistic-details - Dimensions, weights, and volumes
• /attachments - Images, documents, and certificates
• /enclosed-items - Denormalized from packaging units (no corresponding aggregate root property)

Examples: Example payloads show documented fields only. Clients must accept and ignore additional fields, including nested fields, when they are added in backward-compatible updates.

No pagination - Returns exactly one trade item document or 404 if not found.

Composite Key: The combination of supplier GLN and item number uniquely identifies a trade item in the system.

ETIM xChange Path: Supplier[].Product[].TradeItem[]

Retrieve item identification and details for a specific trade item.

This endpoint returns comprehensive trade item information including:

• Alternative item numbers (supplier, manufacturer, buyer)
• Global Trade Item Numbers (GTINs)
• Discount and bonus group information
• Validity and obsolescence dates
• Item status and condition

Note: Item descriptions are available via the separate /descriptions endpoint.

The trade item key (supplierIdGln + supplierItemNumber) is at the root level, with details nested inside. This structure aligns with other single-item subresource responses.

Examples: Example payloads show documented fields only. Clients must accept and ignore additional fields, including nested fields, when they are added in backward-compatible updates.

No pagination - Returns exactly one trade item's details or 404 if not found.

Retrieve multilingual descriptions for a specific trade item.

This endpoint returns trade item descriptions including minimal and unique main descriptions for each available language.

Language filtering: Use the optional language query parameter to filter descriptions to specific language(s). If not specified, all available languages are returned.

Nested structure: Unlike the bulk endpoint /trade-items/bulk/descriptions which uses a flattened structure optimized for ETL, this single-item endpoint returns descriptions in their natural nested format for easier consumption.

No pagination - Returns all descriptions for the specified trade item.

Retrieve ordering information for a specific trade item.

This endpoint returns comprehensive ordering details including:

• Order unit and quantity constraints (minimum, step size)
• Standard lead time for orders
• Use unit conversions (for items sold in one unit but used in another)
• Alternative use unit conversions

The trade item key (supplierIdGln + supplierItemNumber) is at the root level, with ordering details nested inside. This structure aligns with other single-item subresource responses.

No pagination - Returns exactly one trade item's ordering information or 404 if not found.

ETIM xChange: Ordering Path: Supplier[].Product[].TradeItem[].Ordering

Retrieve pricing information for a specific trade item.

This endpoint returns comprehensive pricing details including:

• Price unit and quantity
• Gross list price, net price, and recommended retail price
• VAT percentage
• Price validity and expiry dates
• Currency code (catalog-level CurrencyCode)
• Allowances and surcharges (nested within each pricing entry)

A trade item may have multiple pricing entries for different conditions, customer groups, or validity periods.

The trade item key (supplierIdGln + supplierItemNumber) is at the root level, with pricings nested inside. This structure aligns with other single-item subresource responses.

Examples: Example payloads show documented fields only. Clients must accept and ignore additional fields, including nested fields, when they are added in backward-compatible updates.

No pagination - Returns exactly one trade item's pricing information or 404 if not found.

ETIM xChange: Pricing[] Path: Supplier[].Product[].TradeItem[].Pricing[]

Retrieve item relations for a specific trade item.

This endpoint returns all relationships the trade item has with other items, including accessories, spare parts, consumables, successors, and other relation types.

Nested structure: Unlike the bulk endpoint /trade-items/bulk/relations which uses a flattened structure optimized for ETL, this single-item endpoint returns relations in their natural nested format for easier consumption.

No pagination - Returns all relations for the specified trade item.

ETIM xChange: ItemRelations[] Path: Supplier[].Product[].TradeItem[].ItemRelations[]

Retrieve logistic details for a specific trade item.

This endpoint returns base item logistic measurements including net dimensions (length, width, height, diameter), weight, and volume with their respective units.

Nested structure: Unlike the bulk endpoint /trade-items/bulk/logistic-details which uses a flattened structure optimized for ETL, this single-item endpoint returns logistics in their natural nested format for easier consumption.

No pagination - Returns all logistics entries for the specified trade item.

ETIM xChange: ItemLogisticDetails[] Path: Supplier[].Product[].TradeItem[].ItemLogisticDetails[]

Retrieve attachments for a specific trade item.

This endpoint returns all attachments associated with the trade item, including product images, datasheets, technical drawings, certificates, manuals, and other document types.

Flat structure: Each attachment entry represents a single file with its type, specification, filename, URI, and metadata.

Unlike the bulk endpoint /trade-items/bulk/attachments which adds trade item identification keys to each row for ETL optimization, this single-item endpoint returns attachments scoped to the specified trade item.

No pagination - Returns all attachments for the specified trade item.

ETIM xChange: ItemAttachments[] Path: Supplier[].Product[].TradeItem[].ItemAttachments[]

Retrieve enclosed items for a specific trade item.

This endpoint returns all items enclosed within the trade item's packaging units. Each enclosed item includes a packagingTypeCode to identify which packaging unit contains it, enabling correlation with packaging data from the main trade item response.

No pagination - Returns all enclosed items for the specified trade item.

ETIM xChange: TradeItemEnclosed[] Path: Supplier[].Product[].TradeItem[].PackagingUnit[].TradeItemEnclosed[]

Retrieve trade item identification and details in bulk with cursor-based pagination.

Returns a flat structure where each item includes its composite key (supplierIdGln + supplierItemNumber) along with all identification and details fields:

• Alternative item numbers (supplier, manufacturer, buyer)
• Global Trade Item Numbers (GTINs)
• Discount and bonus group information
• Validity and obsolescence dates
• Item status and condition

Note: Item descriptions are available via /trade-items/bulk/descriptions endpoint.

Use this endpoint for:

• Initial data synchronization
• Incremental updates (using mutationDateTime filter)
• Filtered data retrieval (using selectionId or supplierIdGln)

Pagination: Use the cursor from the response meta to retrieve subsequent pages. Examples: Example payloads show documented fields only. Clients must accept and ignore additional fields, including nested fields, when they are added in backward-compatible updates.

Retrieve trade item descriptions in bulk with cursor-based pagination. Returns a flattened structure where each row represents a single language description with the trade item identifier (supplierIdGln + supplierItemNumber).

A trade item with descriptions in 3 languages will result in 3 rows.

This flattened structure is optimized for:

• Predictable payload sizes per row
• Efficient cursor-based pagination
• ETL/data warehouse ingestion
• Streaming data processing
• Language filtering at row level

Retrieve trade item ordering information in bulk with cursor-based pagination. Returns ordering details including order units, minimum/maximum quantities, order step sizes, lead times, and unit conversions.

Each item in the response includes its composite key (supplierIdGln + supplierItemNumber) along with all ordering fields in a flat structure.

This endpoint is optimized for scenarios where only ordering data is needed, such as inventory management or order processing systems.

ETIM xChange: Bulk retrieval of Ordering data
Path: Supplier[].Product[].TradeItem[].Ordering

Retrieve trade item pricing information with allowances/surcharges in bulk, using cursor-based pagination. Returns pricing details including net prices, gross list prices, recommended retail prices, VAT, price validity periods, currency code, and any associated allowances or surcharges.

Flattened Structure (LEFT JOIN): Each row represents a single pricing × allowance/surcharge combination with embedded composite key (supplierIdGln + supplierItemNumber).

• A pricing with N allowances/surcharges produces N rows (pricing fields repeated).
• A pricing without surcharges produces 1 row with all allowanceSurcharge* fields as null.

This follows the same denormalization pattern as /products/bulk/etim-classifications — every row is the same shape, no nesting, no artificial keys.

Required field relaxation: allowanceSurchargeIndicator and allowanceSurchargeType are required in the domain model but nullable here because rows for pricings without surcharges carry null for all allowance/surcharge fields.

This endpoint is optimized for:

• Predictable payload sizes per row (uniform shape)
• Efficient cursor-based pagination
• ETL/data warehouse ingestion (single flat fact table)
• Price synchronization scenarios

ETIM xChange: Bulk retrieval of Pricing[] × AllowanceSurcharge[] data
Path: Supplier[].Product[].TradeItem[].Pricing[]

Retrieve trade item relations in bulk with cursor-based pagination. Returns a flattened structure where each row represents a single relation with the trade item identifier (supplierIdGln + supplierItemNumber).

A trade item with 5 relations (e.g., 2 accessories, 2 spare parts, 1 successor) will result in 5 rows.

This flattened structure is optimized for:

• Predictable payload sizes per row
• Efficient cursor-based pagination
• ETL/data warehouse ingestion
• Streaming data processing

Retrieve trade item logistic details in bulk with cursor-based pagination. Returns a flattened structure where each row represents a single logistics entry with the trade item identifier (supplierIdGln + supplierItemNumber).

A trade item typically has 0 or 1 logistics entries containing base item net dimensions (length, width, height, diameter), weight, and volume.

This flattened structure is optimized for:

• Predictable payload sizes per row
• Efficient cursor-based pagination
• ETL/data warehouse ingestion
• Streaming data processing

Retrieve trade item attachments in bulk with cursor-based pagination. Returns a flattened structure where each row represents a single attachment with the trade item identifier (supplierIdGln + supplierItemNumber).

A trade item with 3 attachments (e.g., 1 image, 1 datasheet, 1 certificate) will result in 3 rows.

This flattened structure is optimized for:

• Predictable payload sizes per row
• Efficient cursor-based pagination
• ETL/data warehouse ingestion
• Streaming data processing

Retrieve trade item enclosed items in bulk with cursor-based pagination. Returns a flattened structure where each row represents a single enclosed item within a packaging unit, with the trade item identifier (supplierIdGln + supplierItemNumber) and packaging context (packagingTypeCode).

A trade item with 2 packaging units, each containing 3 enclosed items, will result in 6 rows.

This flattened structure is optimized for:

• Predictable payload sizes per row
• Efficient cursor-based pagination
• ETL/data warehouse ingestion
• Streaming data processing