Trade Item API (1.0.0-Preview1)

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 & Surcharges: The allowanceSurcharges property is always null in this response. Use the separate /{supplierIdGln}/{supplierItemNumber}/allowance-surcharges endpoint for flat retrieval, or the complete trade item endpoint for nested retrieval 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 allowances (discounts) and surcharges (additional charges) for a specific trade item.

This endpoint returns all allowances and surcharges associated with the trade item's pricing entries. Each allowance/surcharge includes a pricingRef to enable correlation with the corresponding pricing record from the /pricings endpoint.

Design Decision: Allowances and surcharges are provided in a separate endpoint to:

• Enable direct ETL/data warehouse fact table loading
• Provide predictable pagination for datasets with varying surcharge counts
• Support star schema design patterns (pricing fact table + surcharges fact table)

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

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

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 item logistics 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/logistics-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 in bulk with cursor-based pagination. Returns pricing details including net prices, gross list prices, recommended retail prices, VAT, price validity periods, and the catalog-level currency code.

Allowances & Surcharges: The allowanceSurcharges property is always null in this response. Use the separate /trade-items/bulk/allowance-surcharges endpoint for flat retrieval.

Flattened Structure: Each row represents a single price entry with embedded composite key (supplierIdGln + supplierItemNumber). This follows the same pattern as /products/bulk/etim-classifications - 1 row per data point.

A trade item with multiple price tiers (e.g., quantity breaks, validity periods) will have multiple rows with the same composite key but different pricing data.

This endpoint is optimized for:

• Predictable payload sizes per row
• Efficient cursor-based pagination
• ETL/data warehouse ingestion
• Price synchronization scenarios

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

Retrieve trade item allowances and surcharges in bulk with cursor-based pagination. Returns discount allowances and additional charge surcharges applied to trade item pricing.

Flattened Structure: Each row represents a single allowance/surcharge entry with embedded composite key (supplierIdGln + supplierItemNumber) and a pricingRef to correlate with the parent pricing entry.

Join Pattern: Use this endpoint in combination with /trade-items/bulk/pricings to build a complete pricing picture:

SELECT p.*, a.*
FROM pricings p
LEFT JOIN allowance_surcharges a
  ON p.supplierIdGln = a.supplierIdGln
 AND p.supplierItemNumber = a.supplierItemNumber
 AND p.pricingRef = a.pricingRef

This endpoint is optimized for:

• Predictable payload sizes per row
• Efficient cursor-based pagination
• ETL/data warehouse ingestion (star schema: pricing fact + surcharges fact)
• Price adjustment synchronization scenarios

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

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 logistics 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