OffersV2

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

Resources

• Listings

  • Availability

  • MaxOrderQuantity

  • Message

  • MinOrderQuantity

  • Type

  • Condition

  • ConditionNote

  • SubCondition

  • Value

  • DealDetails

  • AccessType

  • Badge

  • EarlyAccessDurationInMilliseconds

  • EndTime

  • PercentClaimed

  • StartTime

  • IsBuyBoxWinner

  • LoyaltyPoints

  • Points

  • MerchantInfo

  • Name

  • Id

  • Price

  • Money

  • PricePerUnit

  • SavingBasis

  • Money

  • SavingBasisType

  • SavingBasisTypeLabel

  • Savings

  • Money

  • Percentage

  • Type

  • ViolatesMAP

Listings

Specifies the various offer listings associated with the product.

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

More detail on Availability Types:

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

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.

More detail on Deal Badge:

The deal Badge is a string that can be displayed to accompany the deal. It may describe the kind of deal (Ex: Limited Time Deal, Black Friday Deal), a particular aspect of the deal (Ex: With Prime on prime exclusive deals), or some other form of information about the deal. For deals that are ending soon, this badge will often display "Ends In" - this can be used in conjunction with the EndTime parameter if you wish to implement a countdown timer.

More detail on start/end time

There is no guarantee that there will be a start/end time specified in the response (as applies to any PA-API field, which may or may not be present). Deals that do not have a start/end time are running indefinitely, and do not have a pre-defined running duration. In this case, the existence of the DealDetails object in the response means that the deal is live at the time of the call.

Please note that a Prime Early Access Deal is only available to Prime customers for the specified early access duration, before becoming available to all customers specified by the StartTime when present.

Sample Response

Limited Time Deal

{
   "dealDetails": {
    "accessType": "ALL",
    "badge": "Limited time deal",
    "endTime": "2025-03-02T07:59:59Z",
    "startTime": "2025-02-16T08:00Z"
   }
}

Deal that is ending soon

{
  "dealDetails": {
    "accessType": "PRIME_EARLY_ACCESS",
    "badge": "Ends in ",
    "earlyAccessDurationInMilliseconds": 1800000,
    "endTime": "2025-02-21T05:35Z",
    "percentClaimed": 35,
    "startTime": "2025-02-20T18:05Z"
  }
}

LoyaltyPoints

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

Sample Response

{
  "loyaltyPoints": {
    "points": 10
  }
}

MerchantInfo

Sample Response

{
  "merchantInfo": {
    "id": "ATVPDKIKX0DER",
    "name": "Amazon.com"
  }
}

Price

Please note that the price served is a default based on an in-marketplace shipping address. The price returned by the API may differ from what any specific customer sees due to a variety of factors.

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

Sample Response

{
  "savingBasis": {
    "money": {
      "amount": 69.99,
      "currency": "USD",
      "displayAmount": "$69.99"
    },
    "savingBasisType": "LIST_PRICE",
    "savingBasisTypeLabel": "List Price"
  }
}

Savings

Savings of an Offer

Sample Response

{
  "savings": {
    "money": {
      "amount": 10.5,
      "currency": "USD",
      "displayAmount": "$10.50"
    },
    "percentage": 15
  }
}

Money

Common Struct used for representing money

Relevant Operations

Operations that can use these resources include:

• GetItems

• SearchItems

• GetVariations

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.

Offersv1 to Offersv2 Field Mapping

The following table provides a comprehensive mapping of all fields from the legacy Offers resource to the new OffersV2 resource. Fields marked as "Not Available" have been intentionally discontinued in OffersV2. OffersV2 provides only featured listings as shown to retail customers on Amazon Detail Page buybox, which represent the best overall offers for the product. If there are no featured offers, OffersV2 will show status as out of stock.