OffersV2

The OffersV2 resource contains various resources related to offer listings for an item.

We recommend using OffersV2 over Offers where possible. Eventually, OffersV2 will completely replace the existing Offers API. All new Item Offer features will be added here. In addition to the data fields themselves, V2 also has increased reliability and data quality compared to V1.

This is a new API which will evolve over time - check this page for changes and updates.

We would love to hear your feedback on OffersV2, including asks for additional fields!

Resources

Listings

Specifies the various offer listings associated with the product.

Attribute Name Type Description
Availability Struct Specifies availability information about an offer
Condition Struct Specifies the condition of the offer
DealDetails Struct Specifies deal information of the offer
IsBuyBoxWinner Boolean Specifies whether the given offer is the winner of the BuyBox in the Detail Page Experience (DPX) of an item. This is the best offer recommended by Amazon for any product. This featured offer is seen on Detail Page on an ASIN.
LoyaltyPoints Struct Specifies loyalty points related information for an offer (Currently only supported in the Japan marketplace)
MerchantInfo Struct Specifies merchant information of an offer
Price Struct Specifies buying price of an offer
Type String Specifies the type of offer if there is a special distinction. Most listings will not have a type, such as regular listings and non-lightning deals.
Valid Values:
LIGHTNING_DEAL, SUBSCRIBE_AND_SAVE
ViolatesMAP Boolean Specifies whether an offer violates MAP policy or not. Please refer to this for more details

Sample Response

{
  "ItemsResult": {
    "Items": [
      {
        "ASIN": "B00MNV8E0C",
        "DetailPageURL": "https://www.amazon.com/dp/B00MNV8E0C?tag=example&linkCode=ogi&th=1&psc=1",
        "OffersV2": {
          "Listings": [
            {
              "Availability": {
                "MaxOrderQuantity": 1,
                "MinOrderQuantity": 1,
                "Type": "IN_STOCK"
              },
              "Condition": {
                "ConditionNote": "",
                "SubCondition": "Unknown",
                "Value": "New"
              },
              "DealDetails": {
                "AccessType": "PRIME_EXCLUSIVE",
                "EndTime": "2024-11-06T05:35Z",
                "PercentClaimed": 38,
                "StartTime": "2024-11-05T18:05Z"
              },
              "IsBuyBoxWinner": true,
              "MerchantInfo": {
                "Name": "Amazon.com"
              },
              "Price": {
                "Money": {
                  "Amount": 59.49,
                  "Currency": "USD",
                  "DisplayAmount": "$59.49"
                },
                "PricePerUnit": {
                  "Amount": 29.75,
                  "Currency": "USD",
                  "DisplayAmount": "$29.75 / Count"
                },
                "SavingBasis": {
                  "Money": {
                    "Amount": 69.99,
                    "Currency": "USD",
                    "DisplayAmount": "$69.99"
                  },
                  "SavingBasisType": "LIST_PRICE",
                  "SavingBasisTypeLabel": "List Price"
                },
                "Savings": {
                  "Money": {
                    "Amount": 10.5,
                    "Currency": "USD",
                    "DisplayAmount": "$10.50"
                  },
                  "Percentage": 15
                }
              },
              "Type": "LIGHTNING_DEAL",
              "ViolatesMAP": false
            }
          ]
        }
      }
    ]
  }
}

Availability

Attribute Name Type Description
MaxOrderQuantity Integer Specifies the maximum quantity of a product that can be purchased
Message String Specifies availability message of a product
MinOrderQuantity Integer Specifies minimum number of quantity needed to make purchase of a product
Type String Describe about the availability type of product.
Valid Values:
AVAILABLE_DATE, IN_STOCK, IN_STOCK_SCARCE, LEADTIME,
OUT_OF_STOCK, PREORDER, UNAVAILABLE, UNKNOWN

More detail on Availability Types:

Status Description
AVAILABLE_DATE The item is not available, but will be available on a future date.
IN_STOCK The item is in stock.
IN_STOCK_SCARCE The item is in stock, but stock levels are limited.
LEADTIME The item is only available after some amount of lead time (order received to order shipped time)
OUT_OF_STOCK The item is currently out of stock.
PREORDER The item is not yet available, but can be pre-ordered.
UNAVAILABLE The item is not available
UNKNOWN Unknown availability

Sample Response

{
  "Availability": {
    "MaxOrderQuantity": 30,
    "Message": "In Stock",
    "MinOrderQuantity": 1,
    "Type": "IN_STOCK"
  }
}

Condition

For Offers with value New, there will not be a specified ConditionNote and SubCondition will be Unknown

Attribute Name Type Description
ConditionNote String Specifies the product condition as provided by the seller. May be blank
Value String Specifies the offer condition.
Valid Values: New, Used, Refurbished, Unknown
SubCondition String Specifies the SubCondition of an offer
Valid Values: LikeNew, Good, VeryGood, Acceptable, Refurbished, OEM, OpenBox, Unknown

Sample Response

{
  "Condition": {
    "ConditionNote": "",
    "SubCondition": "Unknown",
    "Value": "New"
  }
}

DealDetails

This field will only be populated if there is a deal associated with the listing. The existence of this field (when requested) implies the existence of a deal.

The easiest way to find deals on Amazon is by visiting https://www.amazon.com/deals, or the appropriate equivalent in your marketplace of choice.

Attribute Name Type Description
AccessType String Specifies which customers can claim the deal (everyone or only Prime members).
Prime Early Access is available to Prime members first (for time specified by EarlyAccessDurationInMilliseconds) before becoming available to everyone.
Valid Values: ALL, PRIME_EARLY_ACCESS, PRIME_EXCLUSIVE.
EarlyAccessDurationInMilliseconds Integer Specifies the number of milliseconds that a deal is first available to Prime members only, if applicable
EndTime String Specifies the UTC deal end time. It is possible for the deal to end sooner (For example: sold out)
PercentClaimed String Specifies how much capacity of a deal is already consumed. Not available on all deal types.
StartTime String Specifies the UTC deal start time

Sample Response

{
  "DealDetails": {
    "AccessType": "PRIME_EXCLUSIVE",
    "EndTime": "2024-11-06T05:35Z",
    "PercentClaimed": 38,
    "StartTime": "2024-11-05T18:05Z"
  }
}

LoyaltyPoints

Loyalty Points is an Amazon Japan only program. See https://www.amazon.co.jp/-/en/gp/help/customer/display.html?nodeId=GGB6FCM85P9UKC7T

Attribute Name Type Description
Points Integer Specifies loyalty points associated with an offer

Sample Response

{
  "LoyaltyPoints": {
    "Points": 10
  }
}

MerchantInfo

Attribute Name Type Description
Id String Unique identifier for merchant/seller
Name String The name of merchant/seller

Sample Response

{
  "MerchantInfo": {
    "Id": "ATVPDKIKX0DER",
    "Name": "Amazon.com"
  }
}

Price

Please note that the price served represents the price shown for a logged-in Amazon user with an in-marketplace shipping address.

Attribute Name Type Description
Money Money Specifies buying amount of an offer
PricePerUnit Money Specifies price per unit. DisplayAmount includes unit formatting
SavingBasis Struct Specifies the currency associate with the buying amount
Savings Struct Specifies savings on an offer. This is the difference between the Price Money and the SavingBasis Money

Sample Response

{
  "Price": {
    "Money": {
      "Amount": 59.49,
      "Currency": "USD",
      "DisplayAmount": "$59.49"
    },
    "PricePerUnit": {
      "Amount": 29.75,
      "Currency": "USD",
      "DisplayAmount": "$29.75 / Count"
    },
    "SavingBasis": {
      "Money": {
        "Amount": 69.99,
        "Currency": "USD",
        "DisplayAmount": "$69.99"
      },
      "SavingBasisType": "LIST_PRICE",
      "SavingBasisTypeLabel": "List Price"
    },
    "Savings": {
      "Money": {
        "Amount": 10.5,
        "Currency": "USD",
        "DisplayAmount": "$10.50"
      },
      "Percentage": 15
    }
  }
}

SavingBasis

Reference Value Which is used to calculate savings against

Attribute Name Type Description
Money Money Specifies saving basis money information
SavingBasisType String Specifies type of saving basis.
Valid Values: LIST_PRICE, LOWEST_PRICE, LOWEST_PRICE_STRIKETHROUGH, WAS_PRICE
SavingBasisTypeLabel String Label String that can be included next to the saving basis amount.

Sample Response

{
  "SavingBasis": {
    "Money": {
      "Amount": 69.99,
      "Currency": "USD",
      "DisplayAmount": "$69.99"
    },
    "SavingBasisType": "LIST_PRICE",
    "SavingBasisTypeLabel": "List Price"
  }
}

Savings

Savings of an Offer

Attribute Name Type Description
Money Money Specifies savings money information
Percentage Integer Specifies savings percentage on an offer

Sample Response

{
  "Savings": {
    "Money": {
      "Amount": 10.5,
      "Currency": "USD",
      "DisplayAmount": "$10.50"
    },
    "Percentage": 15
  }
}

Money

Common Struct used for representing money

Attribute Name Type Description
Amount BigDecimal Specifies amount
Currency String Specifies the currency associate with the buying amount
DisplayAmount String Specifies formatted amount

Relevant Operations

Operations that can use these resources include:

Changelog

2/11/2025

Based on customer feedback, added the following features:

  • Availability now has a Message Field
  • Availability Type has been expanded to more possible values
  • Merchant Id field added
  • Prime Early Access Deal Support in DealDetails
    • new AccessType
    • new EarlyAccessDurationInMilliseconds

11/05/2024

Not currently supported request parameters

  • Condition (only returning NEW as of today)
  • Merchant (returns all offerings regardless of merchant, does not support Amazon only)
  • OfferCount (returns all offers that would appear on detail page)
    • tends to be 1-3 offers

Appendix

Minimum Advertising Price

Some manufacturers have a minimum advertised price (MAP) that can be displayed on Amazon.com. When the Amazon price is lower than the MAP, the manufacturer does not allow the price to be shown until the customer takes further action, such as placing the item in their shopping cart, or in some cases, proceeding to the final checkout stage. Customers need to go to Amazon to see the price on the retail website, but won't be required to purchase the product.

results matching ""

    No results matching ""