Manage purchasable offer

This tutorial guides you through granularly updating and deleting sub-attributes of the purchasable_offer attribute using the Listings Items API. Learn how to modify individual offer properties, such as prices, dates, and pricing plans without deleting and recreating the entire offer.

Prerequisites

To complete this tutorial, you need:

• Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
• Approval for the Product Listing role in your developer profile.
• The Product Listing role selected in the App registration page for your application.
• For attribute updates, JSON-based listing attribute payloads adhering to the JSON Schema provided by the Selling Partner API for Product Type Definitions for the given selling partner, Amazon marketplace, Amazon product type, and attributes.
• For attribute deletes, JSON-based listing attribute payloads adhering to the JSON Schema provided by the Selling Partner API for Product Type Definitions for the given selling partner, Amazon marketplace, Amazon product type, and attributes with the selector properties of the attributes to delete. You cannot delete attributes by name alone. Use selector values to identify which attribute instance to delete.

Purchasable Offer

The purchasable_offer attribute defines the complete pricing and offer configuration for a product listing on Amazon. It is structured as an array of offer objects, with each offer uniquely identified by marketplace_id, currency, and audience.

Use the patchListingsItem operation for all granular updates.

❗

Important

The API derives selectors from the marketplace in the request. For better control, include the selector properties (currency, marketplace_id, and audience) within the payload to identify which offer instance to modify.

Supported operations for purchasable_offer

📘

Note

This guide uses op: "merge" for all examples. While replace works similarly for updates, consider using merge because it also supports deletion (using null) and behaves consistently with other structured attributes like fulfillment_availability.

Update a sub-attribute

To granularly update a sub-attribute, use op: "merge" and include only the sub-attribute you want to change.

Updatable sub-attributes and example values

Replace <sub_attribute> and <value> with values from the table:

{
    "productType": "PRODUCT",
    "patches": [
        {
            "op": "merge",
            "path": "/attributes/purchasable_offer",
            "value": [
                {
                    "currency": "USD",
                    "audience": "ALL",
                    "marketplace_id": "ATVPDKIKX0DER",
                    "<sub_attribute>": <value>
                }
            ]
        }
    ]
}

For example, to update the start_at date:

{
    "productType": "PRODUCT",
    "patches": [
        {
            "op": "merge",
            "path": "/attributes/purchasable_offer",
            "value": [
                {
                    "currency": "USD",
                    "audience": "ALL",
                    "marketplace_id": "ATVPDKIKX0DER",
                    "start_at": {"value": "2026-03-01"}
                }
            ]
        }
    ]
}

Delete an optional sub-attribute

To granularly delete an optional sub-attribute, use op: "merge" and set the sub-attribute to null. You can delete the following sub-attributes:

• map_price
• discounted_price
• minimum_seller_allowed_price
• maximum_seller_allowed_price
• maximum_retail_price
• quantity_discount_plan
• automated_pricing_merchandising_rule_plan
• start_at
• end_at

Replace <sub_attribute> with the sub-attribute to delete:

{
    "productType": "PRODUCT",
    "patches": [
        {
            "op": "merge",
            "path": "/attributes/purchasable_offer",
            "value": [
                {
                    "currency": "USD",
                    "audience": "ALL",
                    "marketplace_id": "ATVPDKIKX0DER",
                    "<sub_attribute>": null
                }
            ]
        }
    ]
}

For example, to delete the discounted_price:

{
    "productType": "PRODUCT",
    "patches": [
        {
            "op": "merge",
            "path": "/attributes/purchasable_offer",
            "value": [
                {
                    "currency": "USD",
                    "audience": "ALL",
                    "marketplace_id": "ATVPDKIKX0DER",
                    "discounted_price": null
                }
            ]
        }
    ]
}

To remove a B2B offer sub-attribute (e.g., quantity_discount_plan for the B2B audience), set it to null and specify the B2B audience selector:

{
    "productType": "PRODUCT",
    "patches": [
        {
            "op": "merge",
            "path": "/attributes/purchasable_offer",
            "value": [
                {
                    "currency": "USD",
                    "audience": "B2B",
                    "marketplace_id": "ATVPDKIKX0DER",
                    "quantity_discount_plan": null
                }
            ]
        }
    ]
}

❗

Important

The our_price sub-attribute cannot be deleted (set to null). To remove an offer entirely, use the delete operation instead of merge.