Buy Box event
The Buy Box webhook sends a notification when the Buy Box winner changes, the Buy Box price changes, or the price changes for competing offers on an item. Offers are ranked by landed price, where landed price equals the offer price plus shipping price when applicable. Sellers receive these notifications only for items where they currently have an active offer.
Event details
- Event Type: BUY_BOX_CHANGED
- Event Version: V1
- Resource Name: PRICE
Response parameters
Source (object)
Metadata about the event notification
source (object) — Metadata about the event notification.
eventType(string) — Type of event for which the notification is generated.eventTime(string) — Timestamp when the event occurred.eventId(string) — Unique identifier of the event.eventFilters(object) — Additional filters applicable to the event.
Payload (object)
Event details
Item information (itemInfo)
itemInfo)itemInfo (object) — Information about the item associated with the event.
itemId(string) — Unique identifier of the item.itemName(string) — Name of the item.category(string) — Category of the item.productType(string) — Product type of the item.brand(string) — Brand of the item.sku(string) — Seller's stock keeping unit (SKU).totalNumberOffers(integer) — Total number of offers for the item.
partnerID
partnerId (string) — Seller’s partner ID. offer (object) — Offer information.
currentOffer(object) — Seller’s current offer details.sellerName(string) — Name of the seller.sellerOfferPrice(double) — Seller’s offer price for the item.suggestedPrice(double) — Suggested price for the seller’s current offer. Available in Canada, Mexico, and Chile.sellerShippingSpeed(string) — Seller’s shipping speed. Available in Canada; disabled in Mexico and Chile.sellerShippingPrice(double) — Seller’s shipping price. Available in Canada; disabled in Mexico and Chile.proSellerBadge(boolean) — Indicates whether the seller has a Pro Seller badge.isWFS(boolean) — Indicates whether fulfillment method is WFS.isSuppressed(boolean) — Indicates whether Buy Box suppression is enabled.itemConditionName(string) — Condition of the item. Not available in Canada, Mexico, or Chile.
winningOffer (object) — Buy Box winning offer information.
sellerName(string) — Name of the Buy Box winning seller.sellerOfferPrice(double) — Buy Box winning seller’s offer price.sellerShippingSpeed(string) — Buy Box winning seller’s shipping speed. Available in Canada; disabled in Mexico and Chile.sellerShippingPrice(double) — Buy Box winning seller’s shipping price. Available in Canada; disabled in Mexico and Chile.proSellerBadge(boolean) — Indicates whether the winning seller has a Pro Seller badge.isWFS(boolean) — Indicates whether the winning seller uses WFS.isSuppressed(boolean) — Indicates whether Buy Box suppression applies.itemConditionName(string) — Condition of the item. Not available in Canada, Mexico, or Chile.
offers (array) — Array of competing offers for the item.
offers[].sellerName(string) — Name of the seller.offers[].sellerOfferPrice(double) — Seller’s offer price.offers[].sellerShippingSpeed(string) — Seller’s shipping speed. Available in Canada; disabled in Mexico and Chile.offers[].sellerShippingPrice(double) — Seller’s shipping price. Available in Canada; disabled in Mexico and Chile.offers[].proSellerBadge(boolean) — Indicates whether the seller has a Pro Seller badge.offers[].isWFS(boolean) — Indicates whether fulfillment method is WFS.offers[].isSuppressed(boolean) — Indicates whether Buy Box suppression is enabled.offers[].itemConditionName(string) — Condition of the item. Not available in Canada, Mexico, or Chile.
priceDifference
priceDifference (double) — Difference between the seller’s offer price and the Buy Box winning offer price.
International market field availability
The response parameter definitions above retain fields from the original Buy Box event documentation, including fields not available in every market. For Canada (CA), Mexico (MX), and Chile (CL), use the following availability rules when implementing the international payloads:
| Field | Canada (CA) | Mexico (MX) | Chile (CL) |
|---|---|---|---|
offer.currentOffer.suggestedPrice | Available | Available | Available |
sellerShippingSpeed in offer objects | Available | Disabled | Disabled |
sellerShippingPrice in offer objects | Available | Disabled | Disabled |
itemConditionName in offer objects | Disabled | Disabled | Disabled |
headers.WM_MARKET | ca | mx | cl |
For international payloads, suggestedPrice is documented only under offer.currentOffer. It is not a field of winningOffer or individual entries in offers[]. The international examples do not include itemConditionName. Shipping speed and shipping price are available for Canada and disabled for Mexico and Chile. The number of entries in offers[] is not stated as a fixed limit.
Sample payload: Buy Box event
{ "source": { "eventType": "BUY_BOX_CHANGED", "eventFilters": {}, "eventTime": "2026-02-26T17:02:00.448Z", "eventId": "ddbb9000-1334-11f1-8348-ade50743062f" }, "payload": { "partnerId": "11234567890", "itemInfo": { "itemId": "543208714", "itemName": "Bump Patrol Sensitive Formula Aftershave Razor Burn Treatment (2 oz) 2 Pack", "category": "Beauty, Personal Care, & Hygiene", "productType": "Aftershave Treatments", "brand": "Bump Patrol", "sku": "2209-2", "totalNumberOffers": 2 }, "offer": { "currentOffer": { "sellerName": "Seller name", "sellerOfferPrice": 12.09, "sellerShippingSpeed": "STANDARD", "sellerShippingPrice": 6.99, "isSuppressed": false, "proSellerBadge": false, "isWFS": false, "itemConditionName": "New" }, "winningOffer": { "sellerName": "Seller name", "sellerOfferPrice": 12.09, "sellerShippingSpeed": "STANDARD", "sellerShippingPrice": 6.99, "isSuppressed": false, "proSellerBadge": false, "isWFS": false, "itemConditionName": "New" }, "offers": [ { "sellerName": "Seller name", "sellerOfferPrice": 12.09, "sellerShippingSpeed": "STANDARD", "sellerShippingPrice": 6.99, "isSuppressed": false, "proSellerBadge": false, "isWFS": false, "itemConditionName": "New" }, { "sellerName": "Seller name", "sellerOfferPrice": 23.43, "sellerShippingSpeed": "STANDARD", "sellerShippingPrice": 6.99, "isSuppressed": false, "proSellerBadge": true, "isWFS": true, "itemConditionName": "New" } ], "priceDifference": 0 } }
}Market-specific sample payloads (proposed combined format)
The following examples retain the original source and payload notification structure and include the key and headers metadata supplied in the updated engineering samples. The data originally supplied under value is shown under payload to avoid duplicating the same content. This combined structure is proposed for documentation and must be confirmed with engineering before publication. The eventTime and eventId values were not supplied and are shown as placeholders. Identifying values in the Canada example have been replaced with placeholders, while the non-identifying numeric and shipping values are retained from the engineering sample.
Additional metadata
| Parameter | Type | Description |
|---|---|---|
key | string | Message key identifying the current offer, winning offer, and product. |
headers | object | Event metadata supplied with the updated engineering examples. |
headers.eventType | string | Event type. |
headers.partnerId | string | Partner identifier. |
headers.WM_MARKET | string | Market code (ca, mx, or cl). |
Canada (CA)
{ "key": "{currentOfferId:<currentOfferId>,winningOfferId:<winningOfferId>,productId:<productId>}", "headers": { "eventType": "BUY_BOX_CHANGED", "partnerId": "<partnerId>", "WM_MARKET": "ca" }, "source": { "eventType": "BUY_BOX_CHANGED", "eventFilters": {}, "eventTime": "<event timestamp>", "eventId": "<event ID>" }, "payload": { "partnerId": "<partnerId>", "itemInfo": { "itemId": "<itemId>", "itemName": "<itemName>", "category": "<category>", "productType": "<productType>", "brand": "<brand>", "sku": "<sku>", "totalNumberOffers": 6 }, "offer": { "currentOffer": { "sellerName": "<sellerName>", "sellerOfferPrice": 215, "suggestedPrice": 156, "sellerShippingSpeed": "STANDARD", "sellerShippingPrice": 19, "proSellerBadge": false, "isWFS": false }, "winningOffer": { "sellerName": "<winningSellerName>", "sellerOfferPrice": 177.93, "sellerShippingSpeed": "", "proSellerBadge": true, "isWFS": true }, "offers": [ { "sellerName": "<sellerName1>", "sellerOfferPrice": 177.93, "sellerShippingSpeed": "", "proSellerBadge": true, "isWFS": true }, { "sellerName": "<sellerName2>", "sellerOfferPrice": 177.94, "sellerShippingSpeed": "", "proSellerBadge": true, "isWFS": true }, { "sellerName": "<sellerName3>", "sellerOfferPrice": 179, "sellerShippingSpeed": "EXPEDITED", "sellerShippingPrice": 0, "proSellerBadge": false, "isWFS": false }, { "sellerName": "<sellerName4>", "sellerOfferPrice": 199.95, "sellerShippingSpeed": "", "proSellerBadge": false, "isWFS": true }, { "sellerName": "<sellerName5>", "sellerOfferPrice": 189.99, "sellerShippingSpeed": "STANDARD", "sellerShippingPrice": 10, "proSellerBadge": false, "isWFS": false }, { "sellerName": "<sellerName6>", "sellerOfferPrice": 215, "sellerShippingSpeed": "STANDARD", "sellerShippingPrice": 19, "proSellerBadge": false, "isWFS": false } ], "priceDifference": 37.07 } }
}Mexico (MX)
{ "key": "{currentOfferId:<currentOfferId>,winningOfferId:<winningOfferId>,productId:<productId>}", "headers": { "eventType": "BUY_BOX_CHANGED", "partnerId": "<partnerId>", "WM_MARKET": "mx" }, "source": { "eventType": "BUY_BOX_CHANGED", "eventFilters": {}, "eventTime": "<event timestamp>", "eventId": "<event ID>" }, "payload": { "partnerId": "<partnerId>", "itemInfo": { "itemId": "<itemId>", "itemName": "<itemName>", "category": "<category>", "productType": "<productType>", "brand": "<brand>", "sku": "<sku>", "totalNumberOffers": 6 }, "offer": { "currentOffer": { "sellerName": "<sellerName>", "sellerOfferPrice": 215, "suggestedPrice": 156, "proSellerBadge": false, "isWFS": false }, "winningOffer": { "sellerName": "<winningSellerName>", "sellerOfferPrice": 177.93, "proSellerBadge": true, "isWFS": true }, "offers": [ { "sellerName": "<sellerName1>", "sellerOfferPrice": 177.93, "proSellerBadge": true, "isWFS": true }, { "sellerName": "<sellerName2>", "sellerOfferPrice": 179, "proSellerBadge": false, "isWFS": false } ], "priceDifference": 37.07 } }
}Chile (CL)
{ "key": "{currentOfferId:<currentOfferId>,winningOfferId:<winningOfferId>,productId:<productId>}", "headers": { "eventType": "BUY_BOX_CHANGED", "partnerId": "<partnerId>", "WM_MARKET": "cl" }, "source": { "eventType": "BUY_BOX_CHANGED", "eventFilters": {}, "eventTime": "<event timestamp>", "eventId": "<event ID>" }, "payload": { "partnerId": "<partnerId>", "itemInfo": { "itemId": "<itemId>", "itemName": "<itemName>", "category": "<category>", "productType": "<productType>", "brand": "<brand>", "sku": "<sku>", "totalNumberOffers": 6 }, "offer": { "currentOffer": { "sellerName": "<sellerName>", "sellerOfferPrice": 215, "suggestedPrice": 156, "proSellerBadge": false, "isWFS": false }, "winningOffer": { "sellerName": "<winningSellerName>", "sellerOfferPrice": 177.93, "proSellerBadge": true, "isWFS": true }, "offers": [ { "sellerName": "<sellerName1>", "sellerOfferPrice": 177.93, "proSellerBadge": true, "isWFS": true }, { "sellerName": "<sellerName2>", "sellerOfferPrice": 179, "proSellerBadge": false, "isWFS": false } ], "priceDifference": 37.07 } }
}Updated 22 days ago

