Manage Amazon Haul, Advanced Multiple-Offer, and Multiple-Fulfillment Use Cases

Listings on Amazon typically contain offer (pricing) details for:

• A single buyer segment (for example, Amazon.com buyers)
• Fulfillment configuration (inventory) for a single fulfillment channel, MFN or FBA
  • MFN: Merchant-fulfilled (DEFAULT)
  • FBA: Amazon-fulfilled (for example, AMAZON_NA)

However, there are advanced selling partner use cases that support Amazon Haul, multiple offers or multiple fulfillment channels for an individual listing. Follow the guidance in this document to support these use cases with:

• Listings Items API
• JSON_LISTINGS_FEED feed type with the Feeds API

📘

Note

While the Listings Items API and JSON_LISTINGS_FEED feed type (Feeds API) support multiple offers and multiple fulfillment records, not all Selling Partner tools support these features. These are advanced use cases primarily available through APIs with limited (or no) support on Seller Central or other listings tools.

The use cases in this guide are:

• Amazon Haul
• Multiple offers with Amazon Business (B2B)
• Multiple Fulfillment Channels with Default MFN and FBA
• Multiple Fulfillment Channels with MFN Supply Sources
• Multiple offers with B2B Industry Vertical Pricing (IVP)

Purchasable offer attributes and audiences

The relationship between a listing and the one-to-many offers on a listing are described by the purchasable_offer attribute for the listing. The purchasable_offer attribute is an array that accepts one or more distinct offers, each keyed by the audience, currency, and marketplace_id to which the offer is applicable.

The following example describes a standard Sell on Amazon offer with a regular price and a sale price in the US marketplace:

{
  "purchasable_offer":[
    {
      "audience":"ALL",
      "currency":"USD",
      "marketplace_id":"ATVPDKIKX0DER",
      "our_price":[
        {
          "schedule":[
            {
              "value_with_tax":123.00
            }
          ]
        }
      ],
      "discounted_price":[
        {
          "schedule":[
            {
              "value_with_tax":110.00,
              "start_at":"2025-01-01",
              "end_at":"2025-01-31"
            }
          ]
        }
      ]
    }
  ]
}

The available audience values differ by selling partner and marketplace, based on the programs that a selling partner is enrolled in. To retrieve the list of available values for a given selling partner, use the Product Type Definitions API. Include the sellerId parameter to retrieve JSON schemas that contain the selling partner-specific audience values and the pricing information that is supported for each audience value. For example, quantity_discount_plan information is supported for Amazon Business offers, but is not supported for other offer types.

Common audience values

Fulfillment availability attributes and fulfillment channel codes

The relationship between a listing and the one-to-many fulfillment channels on a listing are described by the fulfillment_availability attribute for the listing. The fulfillment_availability attribute is an array that accepts one or more distinct fulfillment records, each keyed by the fulfillment_channel_code to which the fulfillment record is applicable.

The following example describes a standard MFN fulfillment record with a quantity, restock_date, and lead_time_to_ship_max_days:

{
  "fulfillment_availability":[
    {
      "fulfillment_channel_code":"DEFAULT",
      "quantity":10,
      "restock_date":"2025-01-01",
      "lead_time_to_ship_max_days":5
    }
  ]
}

The available fulfillment_channel_code values differ by selling partner and marketplace, based on the programs that a selling partner is enrolled in. To retrieve the list of available values for a given selling partner, use the Product Type Definitions API. Include the sellerId parameter to retrieve JSON schemas that contain the selling partner-specific fulfillment_channel_code values and the fulfillment information that is supported for each fulfillment_channel_code value. For example, quantity information is supported for MFN fulfillment, but not for Fulfillment by Amazon (FBA) fulfillment.

You can use the Supply Sources API to retrieve selling partner-specific fulfillment_channel_codes for location-specific inventory. For more information, refer to the Multi-Location Inventory Integration Guide.

Common fulfillment channel code values

Amazon Haul

Amazon Haul is a dedicated shopping experience for the Amazon US marketplace that allows customers to shop low-priced, generic fashion, home, and lifestyle products. You can sell your low-priced selection in the product types listed in selection allowed on the Amazon Haul.

To create an Amazon Haul listing, refer to Listing Items on Amazon.

While creating Amazon Haul listings, call the getDefinitionsProductType operation to retrieve the JSON Schema describing the attributes and constraints for the product type. You must include the sellerId parameter to retrieve the JSON schema. The schema contains the selling partner-specific is_value_stores_item attribute and the Value Store (BZR) offer audience for the Haul-enabled stores. If you are creating listings for the first time, ensure that you set the attribute is_value_store_item to true and audience attribute to BZR. This ensures that the ASIN is created for the Haul program and offer details are handled correctly.

📘

Note

The following parameters are not supported for Haul listings:

• fulfillment_availability
• externally_assigned_product_identifier
• merchant_suggested_asin

For an example, refer to the following sample code.

{
"purchasable_offer":[
  {
    "audience":"BZR",
    "currency":"USD",
    "marketplace_id":"ATVPDKIKX0DER",
    "our_price":[
      {
        "schedule":[
          {
            "value_with_tax":30.0
          }
        ]
      }
    ]
  }
]
}

{
  "is_value_stores_item":[
    {
      "value":true,
      "marketplace_id":"ATVPDKIKX0DER"
    }
  ]
}

Multiple offers with B2B

Selling partners enrolled in the Amazon Business (B2B) program can create multiple offers on a listing, which creates differential pricing between regular buyers on Amazon websites (such as Amazon.com) and business buyers on Amazon Business websites.

The following example describes a standard offer and a business offer with percent-based quantity discounts for the US marketplace:

{
  "purchasable_offer":[
    {
      "audience":"ALL",
      "currency":"USD",
      "marketplace_id":"ATVPDKIKX0DER",
      "our_price":[
        {
          "schedule":[
            {
              "value_with_tax":30.0
            }
          ]
        }
      ]
    },
    {
      "audience":"B2B",
      "currency":"USD",
      "marketplace_id":"ATVPDKIKX0DER",
      "our_price":[
        {
          "schedule":[
            {
              "value_with_tax":28.0
            }
          ]
        }
      ],
      "quantity_discount_plan":[
        {
          "schedule":[
            {
              "discount_type":"fixed",
              "levels":[
                {
                  "lower_bound":5,
                  "value":25.0
                },
                {
                  "lower_bound":10,
                  "value":20.0
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

📘

Note

Using the patchListingsItem operation to update an Amazon Business (B2B) offer doesn't affect existing Sell on Amazon offers. When you PATCH a listing, only the offer record that matches the specified audience, currency, and marketplace_id is updated.

Multiple offers with B2B Industry Vertical Pricing (IVP)

Selling partners who are enrolled in the Industry Vertical Pricing (IVP) program can create offers that target specific B2B buyer segments, such as education institutions. IVP offers extend the existing B2B offer model by allowing sellers to set differentiated pricing for specific industry verticals.

❗

Important

If you have automated pricing rules configured for IVP in the Custom Pricing section of the Seller Central, those rules take priority over IVP offers submitted through the Listings API. To avoid pricing conflicts, delete any automated IVP pricing rules from the Custom Pricing page before you submit IVP offers through the API.

📘

Note

IVP audiences are currently available in the US marketplace only.

IVP audience values

Create an IVP offer using PATCH

Use the patchListingsItem operation to publish an IVP offer for an existing listing. PATCH is the recommended operation for publishing or updating IVP offer prices.

The following example creates offers for three audiences — standard (ALL), business (B2B) with quantity discounts, and education (B2B_EDUCATION) with quantity discounts in a single PATCH request:

{
    "productType": "PRODUCT",
    "patches": [
        {
            "op": "replace",
            "path": "/attributes/purchasable_offer",
            "value": [
             {
                "currency": "USD",
                "audience": "ALL",
                "our_price": [
                    {
                        "schedule": [
                            {
                                "value_with_tax":200.00
                            }
                        ]
                    }
                ],              
                "marketplace_id": "ATVPDKIKX0DER"
            },               
             {
                "currency": "USD",
                "audience": "B2B",
                "our_price": [
                    {
                        "schedule": [
                            {
                                "value_with_tax":190.00
                            }
                        ]
                    }
                ],
                "quantity_discount_plan": [
                    {
                        "schedule": [
                            {
                                "discount_type": "percent",
                                "levels": [
                                    {
                                        "lower_bound": 4,
                                        "value": 1.1
                                    },
                                    {
                                        "lower_bound": 9,
                                        "value": 1.2
                                    }
                                ]
                            }
                        ]
                    }
                ],
                "marketplace_id": "ATVPDKIKX0DER"
            },               
             {
                "currency": "USD",
                "audience": "B2B_EDUCATION",
                "our_price": [
                    {
                        "schedule": [
                            {
                                "value_with_tax": 185.00
                            }
                        ]
                    }
                ],
                "quantity_discount_plan": [
                    {
                        "schedule": [
                            {
                                "discount_type": "percent",
                                "levels": [
                                    {
                                        "lower_bound": 10,
                                        "value": 2.5
                                    },
                                    {
                                        "lower_bound": 25,
                                        "value": 5
                                    }
                                ]
                            }
                        ]
                    }
                ],
                "marketplace_id": "ATVPDKIKX0DER"
            }
            ]
        }
        
    ]
}

When your request is accepted, you receive a response similar to the following:

{
  "sku": "my_sku",
  "status": "ACCEPTED",
  "submissionId": "57e9ba4579db4815a273338266dee396",
  "issues": []
}

Retrieve IVP offers using GET

When you call the getListingsItem operation with offers in the includedData parameter, IVP offers are returned with the audience object containing the IVP audience value and a localized display name. The offerType for IVP offers is B2B.

{
  "offers": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "offerType": "B2B",
      "audience": {
        "value": "B2B_EDUCATION",
        "displayName": "Amazon Business (B2B) Education"
      }
    }
  ]
}

📘

Note

The audience.value field always returns the seller-facing audience name (for example, B2B_EDUCATION).

📘

Note

Using the patchListingsItem operation to update an IVP offer does not affect existing Sell on Amazon or Amazon Business (B2B) offers. When you PATCH a listing, only the offer record that matches the specified audience, currency, and marketplace_id is updated.

Multiple fulfillment channels with default MFN and FBA

Selling partners who are enrolled in FBA typically create listings that are MFN or FBA-enabled. Through the SP-API, you can configure both options on a listing. When FBA inventory is available, it is used first. MFN inventory is used after the FBA inventory is depleted.

❗️

Important

When updating the inventory through the Listings Items v2021-08-01 API or JSON_LISTING_FEED, you no longer need to include the lead_time_to_ship_max_days value to maintain the handling time defined at the SKU-level.
You can now use a JSON patch merge operation with the Listings Items v2021-08-01 API and JSON_LISTING_FEED to update the quantity field without specifying other optional fields such as restock_date and lead_time_to_ship_max_days. For more information, refer to the announcement.

The following example describes fulfillment records that enable MFN and FBA on a listing:

{
  "fulfillment_availability":[
    {
      "fulfillment_channel_code":"DEFAULT",
      "quantity":10,
      "restock_date":"2025-01-01",
      "lead_time_to_ship_max_days":5
    },
    {
      "fulfillment_channel_code":"AMAZON_NA"
    }
  ]
}

Multiple fulfillment channels with MFN supply sources

Selling partners who are enrolled in multi-location inventory management with the Supply Sources API can submit location-specific inventory information using the Supply Source identifier as the fulfillment_channel_code.

The following example describes fulfillment records for two supply sources:

{
  "fulfillment_availability":[
    {
      "fulfillment_channel_code":"0cfcbed2-fab2-4777-9fd2-aa83c7f2c25",
      "quantity":10
    },
    {
      "fulfillment_channel_code":"47b36dc3-1178-43e8-8c78-881c6038650d",
      "quantity":20
    }
  ]
}

You can provide multiple offer records and fulfillment records together in a single PATCH operation. The following example includes updates for two fulfillment channel codes (DEFAULT and a Supply Source API location):

{
  "productType":"PRODUCT",
  "patches":[
    {
      "op":"replace",
      "path":"/attributes/fulfillment_availability",
      "value":[
        {
          "fulfillment_channel_code":"DEFAULT",
          "quantity":3
        },
        {
          "fulfillment_channel_code":"0cfcbed2-fab2-4777-9fd2-aa83c7f2c25",
          "quantity":7
        }
      ]
    }
  ]
}

For more information, refer to the Multi-Location Inventory Integration Guide.