Include additional seller input data

Learn how to use the Merchant Fulfillment API to include additional seller input data. The getAdditionalSellerInputs operation returns a list of additional inputs that are required from the seller to purchase shipping for some shipping services. It is only required for shipment services that require additional seller inputs.

Prerequisites

To complete this tutorial, you need:

• Authorization from the selling partner for whom you are making calls. For more information, refer to Authorizing Selling Partner API applications.
• The Direct-to-Consumer Shipping (Restricted) role assigned to your developer profile.
• The Direct-to-Consumer Shipping (Restricted) role selected in the app registration page for your application.

Step 1. Determine if the shipment service requires additional seller inputs

1. Call the getEligibleShipmentServices operation.
2. Retrieve the list of ShippingServices returned by the operation.
3. Check for the RequiresAdditionalSellerInputs attribute.
4. If RequiresAdditionalSellerInputs is true, it means the shipment service requires additional seller inputs.

Step 2. Call the getAdditionalSellerInputs operation

If the shipment service requires additional seller inputs, call the getAdditionalSellerInputs operation and include all required parameters. The response includes a list of required parameters that a seller must include if they want to purchase shipping services.

Step 3. Review the additional seller inputs required

1. Examine the response from the getAdditionalSellerInputs operation.
2. Identify the specific additional seller inputs that are required.

Step 4. Provide the required seller inputs

1. Collect the necessary information based on the additional seller inputs identified in the response.
2. Ensure the information provided meets the syntax requirements specified in the response.
3. Prepare the required seller inputs for the next step.

Step 5. Create the shipment

1. If the required seller inputs are collected and prepared, call the createShipment operation.
2. Use the necessary parameters and seller inputs with the createShipment operation.
3. Follow the appropriate syntax requirements for the seller inputs in the getAdditionalSellerInputs response.

Step 6: (Optional) Retrieve saved values

The getAdditionalSellerInputs operation returns saved values previously provided to Amazon. To access these saved values, examine the response from the getAdditionalSellerInputs operation.

Example: EU customs product identifiers for cross-border shipments

📘

EU customs requirement

Starting November 1, 2026, EU customs requires product identifiers for business-to-consumer (B2C) goods shipped into the EU from outside the EU. The UK counts as non-EU for this requirement. This requirement does not apply to EU-to-EU shipments. For background on the regulation, refer to the European Commission: EU customs guidance.

For shipments to the EU from outside the EU, Amazon Buy Shipping collects item-level product identifiers through the same additional seller inputs mechanism described in this guide. The identifiers map to the following customs categories:

📘

Note

NS-PID, S-PID, and M-PID are customs categories, not SP-API field names. Use the AdditionalInputFieldName values that getAdditionalSellerInputs returns for the selected shipping service, and don't hardcode field names, because required inputs vary by shipping service, address, and parcel contents.

Where to find product identifier values

Look up identifiers for each item before you call getAdditionalSellerInputs, so that label purchase doesn't fail at checkout:

• Catalog data: Call searchCatalogItems or getCatalogItem with includedData=identifiers to retrieve EAN, GTIN, UPC, and ISBN values. Add attributes (includedData=identifiers,attributes) to also retrieve part_number and model_number where the product has them.
• Listing attributes: Read the part_number, model_number, and externally_assigned_product_identifier attributes using the Listings Items API. Availability varies by product type, so check the live schema with the Product Type Definitions API.
• Seller or supplier systems: Product information management (PIM) and enterprise resource planning (ERP) tools often hold part numbers that aren't in the Amazon catalog. If a value is missing everywhere else, ask the seller to supply it before they buy the label.

🚧

Important

Only send a code that is printed on or assigned to the exact product. Don't create a placeholder value or reuse a seller SKU as a product identifier — this can cause rejected labels or customs declarations.

Request example

The following example shows a getAdditionalSellerInputs response for a shipment from outside the EU to an EU address, requesting an item-level manufacturer product ID, followed by the matching ItemLevelSellerInputsList entry sent in the createShipment request.

getAdditionalSellerInputs response:

{
    "payload": {
        "ItemLevelFieldsList": [{
            "Asin": "ASIN_ID_200",
            "AdditionalInputs": [{
                "AdditionalInputFieldName": "ITEM_MANUFACTURER_PRODUCT_ID",
                "SellerInputDefinition": {
                    "IsRequired": true,
                    "DataType": "String",
                    "InputDisplayText": "Manufacturer part number or model number",
                    "InputTarget": "ITEM_LEVEL",
                    "Constraints": []
                }
            }]
        }]
    }
}

createShipment request excerpt:

{
    "ItemList": [{
        "OrderItemId": "52986411826454",
        "Quantity": 1,
        "ItemLevelSellerInputsList": [{
            "AdditionalInputFieldName": "ITEM_MANUFACTURER_PRODUCT_ID",
            "AdditionalSellerInput": {
                "DataType": "String",
                "ValueAsString": "MX-4420-BLK"
            }
        }]
    }]
}

Handle missing product identifiers

If a shipment to the EU is missing a required identifier, createShipment fails with an InvalidRequest error similar to the following:

Required attribute missing ITEM_MANUFACTURER_PRODUCT_ID at level ITEM_LEVEL

Surface this error to the seller so they can supply the missing value, for example: "Enter the manufacturer's part number or model number for [item name], then buy the label again." Don't retry the call silently, send a placeholder value, or hide the error response from the seller.