{ "openapi": "3.0.0", "info": { "title": "External Promotions Protocol API", "description": "The External Promotions Protocol API allows merchants to integrate their own external promotions engine with VTEX, enabling native and external promotions to interact in the same Cart. This is a protocol, which means the merchant must implement the endpoints described in this documentation as a web API (REST) on their own infrastructure.\r\n\r\nVTEX will call these endpoints during the shopping cart calculation and order lifecycle to:\r\n\r\n- Calculate promotions and discounts for a given shopping cart.\r\n- Notify the external promotions provider when an order is created or cancelled, reporting which promotions were applied.\r\n\r\n>⚠️ **Supported promotion types:** this protocol currently supports **Nominal** external promotions only, a fixed monetary amount off the item price. **Percentual**, **Shipping**, and other promotion types are not supported. Providers must always return `type` as `Nominal`.\r\n\r\n>⚠️ This feature is in a closed beta testing phase. If you are interested in participating, open a ticket with the [VTEX Support](https://help.vtex.com/en/support) team.", "contact": {}, "version": "1.1.0" }, "servers": [ { "url": "https://{providerApiEndpoint}", "description": "External promotions provider endpoint URL.", "variables": { "providerApiEndpoint": { "description": "External promotions provider endpoint host, optionally followed by a path prefix (for example `provider.example.com/api/v1`). VTEX calls `calculatePromotion` and `notifyUsage` relative to this URL.", "default": "provider.example.com" } } } ], "paths": { "/calculatePromotion": { "post": { "tags": [ "External promotions" ], "summary": "Calculate promotions", "description": "Calculates the promotions and discounts applicable to a given shopping cart. VTEX calls this endpoint during the cart calculation process, sending the shopping cart data including items, coupon codes, UTM parameters, and sales channel information. The external promotions provider must return the calculated discounts for each item, along with a summary of all promotions considered.\r\n\r\nThis endpoint supports **hybrid** orchestration (protocol v1.1). When an account combines native VTEX promotions with an external provider, VTEX sends the cart **after** native evaluation: see `items[].price` (post-native per-unit price) and the optional per-line `items[].nativePromotionLayer`. The provider may also return `allPromotions[].qualificationProgress` describing promotions the shopper has **not yet unlocked**.\r\n\r\nIn hybrid mode, the provider can optionally return `nativePromotionRemovals` to ask VTEX to drop specific applied native promotions (by the ids exposed in `items[].nativePromotionLayer.appliedPromotions[].id`) from the merged result — either cart-wide or for selected lines — instead of only stacking discounts on top of them. Absent or empty `nativePromotionRemovals` is a no-op.\r\n\r\n## Supported promotion types\r\n\r\nThis protocol currently supports **Nominal** external promotions only: a fixed monetary amount off the item price, returned as `items[].promotions[].discount` with `type` set to `Nominal`. **Percentual** discounts, **Shipping** promotions, and other promotion types are not supported. Do not return those types; they are outside this contract and will not be applied.\r\n\r\n## How VTEX derives the discount\r\n\r\nThis is the single most important rule of the response contract:\r\n\r\n- The money VTEX applies comes **only** from `items[].promotions[].discount`, multiplied by `items[].quantity`. That `discount` is a **Nominal** (fixed) monetary amount per unit; percentual and shipping discounts are not applied.\r\n- A promotion produces a discount **only** if its `id` is also listed in `allPromotions`. VTEX builds the result by iterating `allPromotions` and matching each entry against `items[].promotions`.\r\n- `originalPrice`, `discountedPrice` and `externalPromotionLayer` are **informational**. They are used for tracing and diagnostics and never produce a discount on their own. Returning `externalPromotionLayer` without the matching `items[].promotions` entries results in **no discount being applied at all**.\r\n\r\n## Response requirements\r\n\r\nVTEX validates the body before merging it and discards the **entire** response when it is malformed. Specifically:\r\n\r\n- `items` must be present and must not contain `null` entries.\r\n- If any `items[].promotions` is present and non-empty, then `allPromotions` must also be present and non-empty. Item-level promotions without a catalog are rejected.\r\n- Every `allPromotions[].id` and every `items[].promotions[].id` must be a non-empty string.\r\n- Every `items[].id` must match an item id sent in the request.\r\n- Quantity fields under `qualificationProgress` must be whole numbers. A fractional value fails deserialization and discards the response.\r\n\r\nAn applied promotion id that is not listed in `allPromotions` is tolerated and does not fail the response, but no discount is produced for it.\r\n\r\n## Authentication\r\n\r\nVTEX authenticates with an API key sent in a header whose name is configured per account and defaults to `Authorization`, optionally with a prefix such as `Bearer `. VTEX does not send HTTP Basic credentials, and it does not send an `Accept` header. The provider should reject unauthenticated requests with `401 Unauthorized`.\r\n\r\n## Timeout\r\n\r\nThe call times out after 5000 ms by default (configurable per account) and is **not** retried.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "correlationId", "origin", "salesChannelId", "items" ], "description": "Request body for the calculate promotions endpoint.", "properties": { "correlationId": { "type": "string", "description": "Unique identifier for this `calculatePromotion` call, stable across client retries of the same cart step. VTEX links it to execution diagnostics; providers should log it and may use it for idempotency. Added in protocol v1.1." }, "origin": { "type": "string", "enum": [ "Marketplace", "Fulfillment" ], "description": "Origin of the shopping cart. Possible values are `Marketplace` and `Fulfillment`." }, "shopperProfileId": { "type": "string", "nullable": true, "description": "Unique identifier of the shopper's profile." }, "salesChannelId": { "type": "string", "description": "Identifier of the sales channel (trade policy) associated with the shopping cart, as configured on VTEX." }, "couponCodes": { "type": "array", "nullable": true, "description": "List of coupon codes added to the shopping cart.", "items": { "type": "string", "description": "Coupon code." } }, "utms": { "type": "object", "nullable": true, "description": "UTM tracking parameters associated with the shopping cart.", "properties": { "source": { "type": "string", "nullable": true, "description": "UTM source value." }, "medium": { "type": "string", "nullable": true, "description": "UTM medium value." }, "campaign": { "type": "string", "nullable": true, "description": "UTM campaign value." }, "internalCampaign": { "type": "string", "nullable": true, "description": "UTM internal campaign value." } } }, "customFields": { "type": "object", "nullable": true, "description": "Arbitrary custom data forwarded from the cart, grouped by app. The outer keys are app identifiers; each value is a map of field name to string value. Field values longer than 128 characters are dropped by VTEX before sending. Added in protocol v1.1.", "additionalProperties": { "type": "object", "description": "Custom fields for a single app, as a map of field name to value.", "additionalProperties": { "type": "string", "description": "Custom field value." } } }, "items": { "type": "array", "description": "List of items in the shopping cart.", "items": { "type": "object", "required": [ "id", "sellerId", "quantity", "price", "catalogInfo" ], "description": "Shopping cart item to be evaluated for promotions.", "properties": { "id": { "type": "string", "description": "SKU identifier of the item, as configured in the VTEX catalog." }, "sellerId": { "type": "string", "description": "Identifier of the seller, as configured on VTEX." }, "quantity": { "type": "integer", "format": "int32", "description": "Quantity of this item in the shopping cart." }, "price": { "type": "number", "format": "double", "description": "Per-unit selling price of the item before the external engine applies. In **hybrid** mode this is the per-unit price **after** native VTEX promotions, so the provider can stack on top." }, "catalogInfo": { "type": "object", "required": [ "brandId", "categoryId", "productId" ], "description": "Catalog information associated with this item.", "properties": { "brandId": { "type": "string", "description": "Brand identifier of the item, as configured in the VTEX catalog." }, "categoryId": { "type": "string", "description": "Category identifier of the item, as configured in the VTEX catalog." }, "productId": { "type": "string", "description": "Product identifier of the item, as configured in the VTEX catalog." }, "collectionIds": { "type": "array", "nullable": true, "description": "List of collection identifiers this item belongs to, as configured in the VTEX catalog.", "items": { "type": "string", "description": "Collection identifier." } }, "ean": { "type": "string", "nullable": true, "description": "EAN (barcode) of the item, when VTEX has it. Added in protocol v1.1." }, "refId": { "type": "string", "nullable": true, "description": "Merchant reference id (RefId) of the item, when VTEX has it. Added in protocol v1.1." } } }, "paymentInfo": { "type": "array", "nullable": true, "description": "List of payment methods applied to this item.", "items": { "type": "object", "required": [ "id", "value" ], "description": "Payment method information for an item.", "properties": { "id": { "type": "string", "description": "Identifier of the payment method, as configured on VTEX." }, "value": { "type": "number", "format": "double", "description": "Value paid with this payment method." } } } }, "nativePromotionLayer": { "type": "object", "nullable": true, "description": "Hybrid only. How native VTEX promotions changed this line before the external engine runs. When present, `priceAfterLayer` equals `price`. Added in protocol v1.1.", "required": [ "priceBeforeLayer", "priceAfterLayer" ], "properties": { "priceBeforeLayer": { "type": "number", "format": "double", "description": "Per-unit price before native promotions." }, "priceAfterLayer": { "type": "number", "format": "double", "description": "Per-unit price after native promotions (equals `price` in hybrid mode)." }, "appliedPromotions": { "type": "array", "nullable": true, "description": "Native promotions applied in this layer only.", "items": { "type": "object", "description": "Native promotion applied to this line.", "required": [ "id", "discount", "type" ], "properties": { "id": { "type": "string", "description": "Identifier of the native promotion." }, "discount": { "type": "number", "format": "double", "description": "Per-unit discount applied by this promotion." }, "type": { "type": "string", "enum": [ "Nominal" ], "description": "Type of discount applied. Must be `Nominal` (a fixed monetary amount off the item). **Percentual**, **Shipping**, and other promotion types are not supported." } } } } } } } } } } }, "example": { "correlationId": "7f3e2b10-2c5a-4a9e-bf6a-9b9d0c2f1a23", "customFields": { "myAppId": { "giftMessage": "Happy birthday" } }, "origin": "Marketplace", "shopperProfileId": "da1220f6-88ce-46a2-b466-7f311c5a1bf0", "salesChannelId": "3", "couponCodes": [ "coupon-code-1", "coupon-code-2" ], "utms": null, "items": [ { "id": "792", "sellerId": "1", "quantity": 3, "price": 2, "catalogInfo": { "brandId": "23", "categoryId": "43", "productId": "55", "collectionIds": [ "98", "11" ], "ean": "7891234567890", "refId": "SKU-ABC-001" }, "paymentInfo": [ { "id": "34", "value": 6.0 } ], "nativePromotionLayer": { "priceBeforeLayer": 2.5, "priceAfterLayer": 2.0, "appliedPromotions": [ { "id": "native-promo-1", "discount": 0.5, "type": "Nominal" } ] } } ] } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "description": "Response body for the calculate promotions endpoint.", "properties": { "items": { "type": "array", "description": "List of items with their calculated promotion results.", "items": { "type": "object", "required": [ "id", "quantity", "originalPrice" ], "description": "Item in the calculate promotions response.", "properties": { "id": { "type": "string", "description": "SKU identifier of the item in the shopping cart." }, "quantity": { "type": "integer", "format": "int32", "description": "Quantity of the item in the shopping cart." }, "promotions": { "type": "array", "nullable": true, "description": "Promotions applied by the external provider to this item. **This is the only field VTEX uses to compute the external discount**: the applied value is `discount` multiplied by this item's `quantity`, and only for promotions whose `id` is also listed in `allPromotions`. Omitting this array — even when `externalPromotionLayer` is populated — means no external discount is applied to the line. When both are present they must describe the same promotions; a mismatch is logged as a warning.", "items": { "type": "object", "required": [ "id", "discount", "type" ], "description": "Promotion applied to an item.", "properties": { "id": { "type": "string", "description": "Identifier of the applied promotion." }, "discount": { "type": "number", "format": "double", "description": "Per-unit monetary (Nominal) discount applied by this promotion. Because only `Nominal` promotions are supported, this is a fixed amount off the item, not a percentage, and it never applies to shipping." }, "type": { "type": "string", "enum": [ "Nominal" ], "description": "Type of discount applied. Must be `Nominal` (a fixed monetary amount off the item). **Percentual**, **Shipping**, and other promotion types are not supported." } } } }, "originalPrice": { "type": "number", "format": "double", "description": "Original per-unit price of this line before external deals. In hybrid mode, typically the per-unit price after native promotions (the pre-external price the provider augments). Informational only: VTEX does not derive the discount from this field." }, "discountedPrice": { "type": "number", "nullable": true, "format": "double", "description": "Per-unit price of the item after external promotions are applied. Informational only: VTEX does not derive the discount from this field, it uses `promotions[].discount`." }, "externalPromotionLayer": { "type": "object", "nullable": true, "description": "Hybrid: how the partner (external) promotion layer changed this line. Informational only — it is used for tracing and reconciliation and never produces a discount by itself; always send the corresponding `promotions` entries. When set, `priceBeforeLayer` SHOULD match `originalPrice` and `priceAfterLayer` SHOULD match `discountedPrice`; VTEX compares them with a tolerance of 0.01 and only logs a warning on divergence, without rejecting the response. Added in protocol v1.1.", "required": [ "priceBeforeLayer", "priceAfterLayer" ], "properties": { "priceBeforeLayer": { "type": "number", "format": "double", "description": "Per-unit price before the partner layer (post-native in hybrid)." }, "priceAfterLayer": { "type": "number", "format": "double", "description": "Per-unit price after the partner layer." }, "appliedPromotions": { "type": "array", "nullable": true, "description": "Partner deals applied in this layer only.", "items": { "type": "object", "description": "Partner promotion applied to this line.", "required": [ "id", "discount", "type" ], "properties": { "id": { "type": "string", "description": "Identifier of the applied promotion." }, "discount": { "type": "number", "format": "double", "description": "Per-unit monetary (Nominal) discount applied by this promotion. Percentage-based and shipping discounts are not supported." }, "type": { "type": "string", "enum": [ "Nominal" ], "description": "Type of discount applied. Must be `Nominal` (a fixed monetary amount off the item). **Percentual**, **Shipping**, and other promotion types are not supported." } } } } } } } } }, "allPromotions": { "type": "array", "nullable": true, "description": "Catalog of all promotions considered for this shopping cart, including those that were not applied. **Conditionally required**: whenever any `items[].promotions` entry is present, this array must be present and non-empty, otherwise VTEX rejects the whole response. It is also the catalog VTEX iterates to build discounts, so a promotion referenced in `items[].promotions` but missing here produces no discount. Every entry must carry a non-empty `id`.", "items": { "type": "object", "required": [ "id", "name", "description" ], "description": "Summary of a promotion.", "properties": { "id": { "type": "string", "description": "Identifier of the promotion." }, "name": { "type": "string", "description": "Name of the promotion." }, "description": { "type": "string", "description": "Description of the promotion." }, "couponCode": { "type": "string", "nullable": true, "description": "Coupon code that triggers this promotion. Returns `null` if no coupon code triggered the promotion." }, "qualificationProgress": { "type": "object", "nullable": true, "description": "For **not-yet-unlocked** promotions, structured qualification data VTEX maps to native teasers (\"almost there\" messaging). All properties are optional; omit the object (or send `{}`) when there is no structured progress. Added in protocol v1.1; not present in v1.0.", "properties": { "remainingCartWideAmount": { "type": "number", "nullable": true, "format": "double", "description": "Monetary amount still needed across the whole cart to meet a cart-wide spend threshold (the remaining gap, not the full threshold)." }, "orderSubtotalMustExceed": { "type": "number", "nullable": true, "format": "double", "description": "Cart items-subtotal floor the rule requires (the target threshold)." }, "remainingItemQuantity": { "type": "object", "nullable": true, "description": "Item/SKU quantity qualification context: optional aggregate and per-SKU rows.", "properties": { "totalUnitsRemaining": { "type": "integer", "nullable": true, "format": "int32", "description": "Aggregate extra units still needed across the qualifying SKU set. Must be a whole number: a fractional value fails deserialization and discards the whole response." }, "perSku": { "type": "array", "nullable": true, "description": "Per-SKU contribution toward the quantity conditions.", "items": { "type": "object", "description": "Quantity qualification progress for a single SKU.", "required": [ "skuId" ], "properties": { "skuId": { "type": "string", "description": "Cart/catalog line id, aligned with items[].id in the same request." }, "unitsInCart": { "type": "integer", "nullable": true, "format": "int32", "description": "Units of this SKU currently in the cart toward this promotion. Must be a whole number." }, "unitsRequiredForPromotion": { "type": "integer", "nullable": true, "format": "int32", "description": "Units of this SKU required by the rule. Must be a whole number: a fractional value fails deserialization and discards the whole response." }, "unitsRemaining": { "type": "integer", "nullable": true, "format": "int32", "description": "Units of this SKU still needed to satisfy its part of the condition. Must be a whole number: a fractional value fails deserialization and discards the whole response." } } } } } }, "minimumRuleQuantity": { "type": "integer", "nullable": true, "format": "int32", "description": "Minimum qualifying units the rule requires (e.g. buy-N / combo thresholds)." }, "contextTotalForQualifyingItems": { "type": "object", "nullable": true, "description": "Subtotal value range and item scope for total-value rules.", "properties": { "minValue": { "type": "number", "nullable": true, "format": "double", "description": "Minimum subtotal in cart currency." }, "maxValue": { "type": "number", "nullable": true, "format": "double", "description": "Maximum subtotal bound." }, "itemScope": { "type": "string", "nullable": true, "enum": [ "AllItems", "IncludeMatchedItems", "ExcludeMatchedItems", null ], "description": "Which line items' value participates in the subtotal check. Omit the property or send `null` when the rule does not define a scope." } } }, "itemUnitPriceBounds": { "type": "object", "nullable": true, "description": "Per-unit price band on a line.", "properties": { "minPrice": { "type": "number", "nullable": true, "format": "double", "description": "Minimum per-unit item price for qualification." }, "maxPrice": { "type": "number", "nullable": true, "format": "double", "description": "Maximum per-unit item price for qualification." } } }, "skuIdGroups": { "type": "object", "nullable": true, "description": "SKUs in scope of the rule. Use `allOf` for a single set; `group1`/`group2` for mix-and-match.", "properties": { "allOf": { "type": "array", "nullable": true, "items": { "type": "string", "description": "SKU identifier that participates in the single set." }, "description": "All listed SKUs participate in a single set." }, "group1": { "type": "array", "nullable": true, "items": { "type": "string", "description": "SKU identifier in the first group of a two-group rule." }, "description": "First SKU group in a two-group rule." }, "group2": { "type": "array", "nullable": true, "items": { "type": "string", "description": "SKU identifier in the second group of a two-group rule." }, "description": "Second SKU group in a two-group rule." } } }, "productCollectionIds": { "type": "array", "nullable": true, "items": { "type": "string", "description": "Collection or cluster identifier in scope." }, "description": "Collection / cluster ids in scope." }, "brandIds": { "type": "array", "nullable": true, "items": { "type": "string", "description": "Brand identifier in scope." }, "description": "Brand ids in scope." }, "categoryIds": { "type": "array", "nullable": true, "items": { "type": "string", "description": "Category identifier in scope." }, "description": "Category ids in scope." }, "zipCodeRangeSegments": { "type": "array", "nullable": true, "description": "Delivery CEP/zip gating ranges.", "items": { "type": "object", "description": "Delivery CEP/zip gating range.", "properties": { "from": { "type": "string", "description": "Range start, digits only (no mask)." }, "to": { "type": "string", "description": "Range end, digits only (no mask)." }, "inclusivity": { "type": "string", "enum": [ "inclusive", "exclusive" ], "description": "Whether the shopper's zip is included (`inclusive`) or excluded (`exclusive`)." } } } }, "paymentMethodIds": { "type": "array", "nullable": true, "items": { "type": "string", "description": "Payment method identifier the shopper must use." }, "description": "Payment method ids the shopper must use." }, "cardIssuerIds": { "type": "array", "nullable": true, "items": { "type": "string", "description": "Allowed card issuer identifier." }, "description": "Allowed card issuers." }, "cardBinPrefixRestrictions": { "type": "array", "nullable": true, "items": { "type": "string", "description": "Card BIN prefix pattern the card number must satisfy." }, "description": "Card BIN prefix patterns the card number must satisfy." }, "minInstallmentCount": { "type": "integer", "nullable": true, "format": "int32", "description": "Minimum installments required." }, "maxInstallmentCount": { "type": "integer", "nullable": true, "format": "int32", "description": "Maximum installments allowed." }, "teaserStyleHints": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "UpPrice", "Profiler", "Catalog", "ConditionalPrice" ], "description": "UI grouping hint for the teaser message." }, "description": "UI grouping hints for the teaser message." } } } } } }, "nativePromotionRemovals": { "type": "array", "nullable": true, "description": "Optional, hybrid-only. Native VTEX promotions the provider asks VTEX to remove from the merged cart result. Absent or empty is a strict no-op (same as the append-only merge). Reference each promotion by the id exposed in `items[].nativePromotionLayer.appliedPromotions[].id`. Only native promotions exposed via `nativePromotionLayer` (price and gift) are removable; unknown, non-applied, or non-removable ids (shipping, tax, reward) and malformed entries are silently ignored and never fail the calculation. Added in protocol v1.1.", "items": { "type": "object", "required": [ "promotionId" ], "description": "Request to remove an applied native VTEX promotion from the merged result.", "properties": { "promotionId": { "type": "string", "description": "Native promotion identifier to remove, matching `items[].nativePromotionLayer.appliedPromotions[].id` from the request. Ids that are not applied or not removable are silently ignored." }, "scope": { "type": "string", "enum": [ "cartWide", "perLine" ], "description": "Removal scope. `cartWide` and `perLine` are the canonical values and the only ones providers should send; VTEX additionally tolerates other casings at runtime, but they are not part of this contract and will fail schema validation. Use `cartWide` to remove the promotion from all lines, or `perLine` to remove it only from the cited `lineItemIds`. When omitted, defaults to `cartWide`. For the same `promotionId`, a `cartWide` entry absorbs any `perLine` entries; repeated `perLine` entries union their `lineItemIds`. Unrecognized values are discarded without failing the response." }, "lineItemIds": { "type": "array", "nullable": true, "description": "Cart item ids (`items[].id`) to strip when `scope` is `perLine`. Required and non-empty for `perLine`; ignored for `cartWide`. Cited lines the promotion did not touch are silently ignored.", "items": { "type": "string", "description": "Cart item identifier to strip, aligned with `items[].id` in the same calculate promotions call." } } } } } } }, "examples": { "stackedOnNativePromotion": { "summary": "Hybrid — external discount stacked on top of the native one", "description": "Answers the request example. The native promotion already took the unit price from 2.50 to 2.00, which is why the request carried `price: 2`. The provider stacks 0.25 per unit on top, so the line settles at 1.75 per unit and both promotions stay applied. Because there is no `nativePromotionRemovals`, the merge is purely additive. Note that `promotions[].discount` is what VTEX charges against the line: 0.25 × 3 units = 0.75 off this line.", "value": { "items": [ { "id": "792", "quantity": 3, "promotions": [ { "id": "promo-1", "discount": 0.25, "type": "Nominal" } ], "originalPrice": 2.0, "discountedPrice": 1.75, "externalPromotionLayer": { "priceBeforeLayer": 2.0, "priceAfterLayer": 1.75, "appliedPromotions": [ { "id": "promo-1", "discount": 0.25, "type": "Nominal" } ] } } ], "allPromotions": [ { "id": "promo-1", "name": "25 cents off on cokes", "description": "Buy at least 3 cokes and get 25 cents off on each", "couponCode": "25offCoke" }, { "id": "promo-2", "name": "5 dollars off over $50", "description": "Spend $50 or more to unlock $5 off", "couponCode": null, "qualificationProgress": { "remainingCartWideAmount": 44.0, "orderSubtotalMustExceed": 50.0, "teaserStyleHints": [ "UpPrice" ] } } ] } }, "replacingNativePromotion": { "summary": "Hybrid — external promotion replaces the native one", "description": "Answers the same request, but the provider does not want its deal to stack. It asks VTEX to drop `native-promo-1` cart-wide, so the native 0.50 per unit disappears from the merged result, and prices its own deal against the pre-native price of 2.50 exposed in `nativePromotionLayer.priceBeforeLayer`. The line settles at 2.20 per unit (2.50 − 0.30) and `native-promo-1` no longer appears in the cart.", "value": { "items": [ { "id": "792", "quantity": 3, "promotions": [ { "id": "promo-1", "discount": 0.3, "type": "Nominal" } ], "originalPrice": 2.5, "discountedPrice": 2.2, "externalPromotionLayer": { "priceBeforeLayer": 2.5, "priceAfterLayer": 2.2, "appliedPromotions": [ { "id": "promo-1", "discount": 0.3, "type": "Nominal" } ] } } ], "allPromotions": [ { "id": "promo-1", "name": "30 cents off on cokes", "description": "Buy at least 3 cokes and get 30 cents off on each, replacing any native coke discount", "couponCode": "30offCoke" } ], "nativePromotionRemovals": [ { "promotionId": "native-promo-1", "scope": "cartWide" } ] } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } } } }, "/notifyUsage": { "post": { "tags": [ "External promotions" ], "summary": "Notify promotion usage", "description": "Receives a notification when an order is created or cancelled, informing the external promotions provider which promotions and coupons were applied to the order. This allows the provider to track promotion usage, enforce usage limits, and maintain accurate promotion state.\r\n\r\nThe optional `correlationId` references the `calculatePromotion` evaluation that led to the order, when VTEX can supply it, for end-to-end tracing. Added in protocol v1.1.\r\n\r\nIn hybrid mode this notification carries **only the external provider's own promotions**. Native VTEX promotions applied to the same order are filtered out before sending, so `promotionUsages` never contains native ids. When no external promotion applied to the order, VTEX skips the call entirely.\r\n\r\n## Idempotency\r\n\r\nThe call times out after 5000 ms by default and is retried up to 3 times by default, with exponential backoff. The provider may therefore receive the same notification more than once and must process it idempotently, keyed by `orderId` and `type`. VTEX treats any 2xx as success and does not act on the response body.\r\n\r\n## Authentication\r\n\r\nVTEX authenticates with an API key sent in a header whose name is configured per account and defaults to `Authorization`, optionally with a prefix such as `Bearer `. VTEX does not send HTTP Basic credentials, and it does not send an `Accept` header. The provider should reject unauthenticated requests with `401 Unauthorized`.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "orderId", "type", "promotionUsages" ], "description": "Request body for the notify usage endpoint.", "properties": { "correlationId": { "type": "string", "nullable": true, "description": "When available, the `correlationId` of the `calculatePromotion` evaluation that led to this order, for end-to-end tracing. Added in protocol v1.1." }, "orderId": { "type": "string", "description": "Identifier of the order triggering this notification." }, "type": { "type": "string", "enum": [ "NewOrder", "OrderCancellation" ], "description": "Type of notification. `NewOrder` indicates a new order was placed, and `OrderCancellation` indicates an order was cancelled." }, "promotionUsages": { "type": "array", "description": "List of promotions used in this order.", "items": { "type": "object", "required": [ "promotionId", "discount" ], "description": "Details of a promotion applied to the order.", "properties": { "promotionId": { "type": "string", "description": "Identifier of the applied promotion." }, "discount": { "type": "number", "format": "double", "description": "Total discount value given by this promotion." }, "couponCode": { "type": "string", "nullable": true, "description": "Coupon code that triggered this promotion. Returns `null` if no coupon code triggered the promotion." } } } } } }, "example": { "correlationId": "7f3e2b10-2c5a-4a9e-bf6a-9b9d0c2f1a23", "orderId": "099823581-1", "type": "NewOrder", "promotionUsages": [ { "promotionId": "promo-1", "discount": 0.75, "couponCode": "coupon-code-1" } ] } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } } } } }, "security": [ { "apiKey": [] } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "name": "Authorization", "in": "header", "description": "API key configured for the account. The header name defaults to `Authorization` but is configurable per account, and the value may carry a configurable prefix such as `Bearer `. HTTP Basic authentication is not supported: VTEX never sends Basic credentials." } }, "parameters": { "Content-Type": { "name": "Content-Type", "in": "header", "description": "Type of the content being sent. VTEX always sends `application/json; charset=utf-8`, so the provider must not match this header exactly against `application/json`.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json; charset=utf-8" } } } }, "tags": [ { "name": "External promotions" } ] }