Scenario: Using GTIN identifiers in promising calculations

Global Trade Item Numbers (GTINs) can be used as item identifiers in promising calculation and diagnostic API requests, enabling external commerce systems to pass GTINs directly without first translating them into internal SKU identifiers.

Business scenario

Many digital commerce channels, including online marketplaces and social commerce platforms, identify products by GTIN rather than by internal item identifiers. When a shopper clicks a Buy Now link from a social platform or marketplace listing, the cart line carries a GTIN. Your storefront must still provide an accurate Estimated Delivery Date (EDD) and a checkout shipment plan before the shopper confirms the order.

Previously, your integration layer had to look up the internal SKU for every GTIN before calling the Promising APIs, adding latency and complexity. Native GTIN support removes this intermediate step. You can pass the GTIN directly in the itemInfo object of the request, and the system resolves it to the mapped SKU and unit of measure (UOM) before running the promising calculation.

Supported APIs

The following Promising Calculation APIs accept a gtinId attribute in the itemInfo object:

The following Diagnostic APIs also accept a gtinId attribute in the itemInfo object:

Example: Single-item EDD request using a GTIN

A shopper browses a product on a marketplace listing. The listing identifies the product by the GTIN 00012345678905. Your storefront calls the Get EDD (Single item) API by passing the GTIN directly in itemInfo:

{
  "deliveryMethod": "SHP",
  "shippingGroupId": "2DayShipping",
  "itemInfo": {
    "gtinId": "00012345678905"
  },
  "destination": {
    "format": "ADDRESS",
    "value": {
      "countryCode": "US",
      "postalCode": "10001"
    }
  }
}

The system resolves the GTIN to the mapped SKU and UOM, looks up inventory availability for that SKU, and returns the earliest delivery date. The response structure is unchanged.

Example: Mixed cart checkout request

A shopper's cart contains two lines: one item identified by a GTIN (added from a social commerce link) and one item identified by its internal SKU (from a saved wish list). The Get Checkout Shipment Plan (Pre-purchase) API supports this mixed-cart pattern. Inventory attributes such as segment and segmentType can be passed alongside the gtinId in the same itemInfo object. Each cart line is resolved independently:

{
  "cartLines": [
    {
      "cartLineId": "line-1",
      "itemInfo": {
        "gtinId": "123456",
        "segment": "MERCH",
        "segmentType": "ONLINE"
      },
      "quantity": 1,
      "deliveryMethod": "SHP",
      "shippingGroupId": "2DayShipping"
    },
    {
      "cartLineId": "line-2",
      "itemInfo": {
        "itemId": "ITEM-ABC",
        "unitOfMeasure": "EACH"
      },
      "quantity": 2,
      "deliveryMethod": "SHP",
      "shippingGroupId": "2DayShipping"
    }
  ],
  "destination": {
    "format": "ADDRESS",
    "value": {
      "countryCode": "US",
      "postalCode": "10001"
    }
  }
}

The GTIN on line 1 is resolved to the mapped SKU and UOM. Line 2 is processed by using the provided SKU directly. Both lines are included in the same shipment plan response. The gtinId value is echoed back in the itemInfo of the response for lines that were submitted with a GTIN.

Important: If two cart lines contain GTINs that resolve to the same SKU, the request returns an error. Each unique SKU can appear on only one cart line.

GTIN resolution rules

The following rules apply when a GTIN is provided in an API request:

  • Only active GTINs are resolved. GTINs with an inactive or deprecated status are not considered valid and do not return a result.
  • A GTIN maps to exactly one SKU (item ID and UOM combination). If no mapping exists for the provided GTIN, no solution is returned for that line.
  • If both a gtinId and SKU details (itemId and unitOfMeasure) are provided in the same itemInfo object, the SKU details take precedence and the GTIN is ignored.