Manage Product Listings with the Selling Partner API

Manage your product listing lifecycle using SP-API.

This guide describes the lifecycle of listings on Amazon and the Selling Partner APIs that can be used to manage it.

Product listings lifecycle

The lifecycle of creating and managing listings on Amazon typically involves the following:

Discovery
- Does Amazon already have the item I want to sell in its catalog?
- Where does my item fit within Amazon's catalog hierarchy?
- What is required to create items in the Amazon catalog?
- Am I eligible to list items in the Amazon catalog?
Creation
- Have I met the data requirements to create a new item or list an existing item?
- Was my submission accepted?
Maintenance
- What is the state of my listing? Is it buyable? Is it discoverable?
- Do I have any issues associated with my listing?
- Does my listing continue to meet Amazon data requirements?

Selling Partner APIs for Product Listings

The following Selling Partner APIs can help you manage your product listings:

Product Type Definitions API: get the requirements for listing an item.
Listings API: create and maintain listings.
Catalog Items API: discover the contents of the catalog.
Notifications API: receive updates about listings.

These APIs provide the following core capabilities for listing creation and management:

Querying data from the Amazon catalog (ASINs).
Querying and traversing the Amazon catalog hierarchy (classifications, browse nodes).
Retrieving schemas describing Amazon data requirements by product type.
Retrieving listings eligibility details by ASIN or product type.
Creating, querying, updating, and deleting listings (SKUs).

In addition, these APIs provide programmatic notifications that enable event-driven workflows for third-party developers and sellers.

Product Type Definitions API

The Selling Partner API for Product Type Definitions provides programmatic access to attribute and data requirements for product types in the Amazon catalog. With this API, you request requirements for a product type in a given marketplace and receive responses including a JSON schema that describes all requirements, attributes, and the conditionality of the requirements. You can use this JSON schema to either validate the payload you already have or map it to your ERPs (Enterprise Resource Planning).

The following example uses the getDefinitionsProductType operation to request the LUGGAGE product type in the NA marketplace in American English:

GET https://sellingpartnerapi-na.amazon.com/definitions/2020-09-01/productTypes/LUGGAGE
    ?marketplaceIds=ATVPDKIKX0DER
    &locale=en_US

The following example shows a response to the preceding request and provides the ProductTypeDefinition of the LUGGAGE listing:

{
  "metaSchema": {
    "link": {
      "resource": "https://...",
      "verb": "GET"
    },
    "checksum": "QFQDmPwMARO7vwMEyLhOtw=="
  },
  "schema": {
    "link": {
      "resource": "https://...",
      "verb": "GET"
    },
    "checksum": "TBr8ubaxXrUyay9hmxUXUw=="
  },
  "requirements": "LISTING",
  "requirementsEnforced": "ENFORCED",
  "propertyGroups": {
    "offer": {
      "title": "Offer",
      "description": "Product Offer",
      "propertyNames": [
        "fulfillment_channel_availability",
        "purchasable_offer",
        "condition_type",
        "condition_note",
        "list_price",
        "product_tax_code",
        "merchant_release_date",
        "merchant_shipping_group",
        "max_order_quantity",
        "gift_options",
        "main_offer_image_locator",
        "other_offer_image_locator_1",
        "other_offer_image_locator_2",
        "other_offer_image_locator_3",
        "other_offer_image_locator_4",
        "other_offer_image_locator_5"
      ]
    },
    "images": {
      "title": "Images",
      "description": "Physical imagess or URL's",
      "propertyNames": [
        "main_product_image_locator",
        "other_product_image_locator_1",
        "other_product_image_locator_2",
        "other_product_image_locator_3",
        "other_product_image_locator_4",
        "other_product_image_locator_5",
        "other_product_image_locator_6",
        "other_product_image_locator_7",
        "other_product_image_locator_8",
        "swatch_product_image_locator"
      ]
    },
    "shipping": {
      "title": "Shipping",
      "description": "Information to determine shipping and storage of your product (e.g., package dimensions, weight, volume)",
      "propertyNames": [
        "item_dimensions",
        "item_package_dimensions",
        "item_package_weight"
      ]
    },
    "variations": {
      "title": "Variations",
      "description": "Variations that product will use",
      "propertyNames": [
        "parentage_level",
        "child_parent_sku_relationship",
        "variation_theme"
      ]
    },
    "safety_and_compliance": {
      "title": "Safety & Compliance",
      "description": "Information to indicate product compliance, hazardous materials, and legal and safety warnings (e.g., lithium batteries, choking hazards, Consumer Product Safety Information Act (CPSIA))",
      "propertyNames": [
        "country_of_origin",
        "warranty_description",
        "batteries_required",
        "batteries_included",
        "battery",
        "num_batteries",
        "number_of_lithium_metal_cells",
        "number_of_lithium_ion_cells",
        "lithium_battery",
        "supplier_declared_dg_hz_regulation",
        "hazmat",
        "safety_data_sheet_url",
        "item_weight",
        "ghs",
        "supplier_declared_material_regulation",
        "california_proposition_65",
        "pesticide_marking"
      ]
    },
    "product_identity": {
      "title": "Product Identity",
      "description": "Information to uniquely identify your product (e.g., UPC, EAN, GTIN, Product Type, Brand)",
      "propertyNames": [
        "item_name",
        "brand",
        "supplier_declared_has_product_identifier_exemption",
        "externally_assigned_product_identifier",
        "merchant_suggested_asin",
        "item_type_keyword",
        "item_type_name",
        "model_number",
        "manufacturer"
      ]
    },
    "product_details": {
      "title": "Product Details",
      "description": "Information and characteristics to describe the product to support search, browse and detail page content (e.g., bullets, product features, model, style name)",
      "propertyNames": [
        "product_description",
        "bullet_point",
        "special_feature",
        "style",
        "department",
        "target_gender",
        "age_range_description",
        "material",
        "outer",
        "fabric_type",
        "lining_description",
        "number_of_items",
        "number_of_wheels",
        "wheel",
        "model_name",
        "color",
        "size",
        "size_map",
        "part_number",
        "compliance_media"
      ]
    }
  },
  "locale": "en_US",
  "marketplaceIds": [
    "ATVPDKIKX0DER"
  ],
  "productType": "LUGGAGE",
  "productTypeVersion": {
    "version": "U8L4z4Ud95N16tZlR7rsmbQ==",
    "latest": true,
    "releaseCandidate": false
  }
}

Feeds JSON Schemas

Using Feeds JSON Schemas you can update individual listings in bulk. These schemas work with the Product Type Definitions API and allow integrators to create, edit, and delete Amazon listings (SKUs) with the same data format used by the Listings Items API. Listings data is interoperable between the Listings Items API and the JSON_LISTINGS_FEED feed type, allowing selling partners to use the mechanism or combination that works best for their listings workflows.

Listings Items API

The Selling Partner API for Listings Items provides programmatic access to selling partner listings on Amazon. With this API, you can can create and edit your listings on an individual basis. It has four operations:

putListingsItem allows you to create a given SKU and update attributes like price, inventory, or both.
patchListingsItem allows you to update the the attributes of a given SKU.
deleteListingsItem allows you to delete a given SKU.
getListingsItem returns information about a a given SKU.

The JSON listings feed is a new feed type. The JSON listings feed is the similar to the Listings API in that it allows you to update in bulk, use the Product Type Definitions API to get the schema, and put together a payload. This payload can either be submitted to the Listing Items API, or in bulk to the JSON listings feed.

The following example uses the getListingsItem operation to request an Item from a seller with a sellerId of AXXXXXXXXXXXX in the NA marketplace in American English. It requests summaries, attributes, issues, offers, and fulfillmentAvailability to be in the Item in the response:

GET https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXX/example-sku
  ?marketplaceIds=ATVPDKIKX0DER
  &issueLocale=en_US
  &includedData=summaries,attributes,issues,offers,fulfillmentAvailability

The response to this request is an Item with summaries, attributes, issues, offers, and fulfillmentAvailability:

{
  "sku": "example-aku",
  "summaries": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "asin": "XXXASINXXX",
      "productType": "DRINKING_CUP",
      "conditionType": "new_new",
      "status": [
        "BUYABLE",
        "DISCOVERABLE"
      ],
      "itemName": "6 Pack Coffee Mug Set, Farielyn-X 16 Ounce Ceramic Coffee Cups, Black Large Coffee mugs, Restaurant Coffee Cups for Coffee, Tea, Cappuccino, Cocoa, Cereal, Matte Black Outside and Colorful Inside",
      "createdDate": "2021-07-14T19:57:02.327Z",
      "lastUpdatedDate": "2021-07-14T19:57:10.637Z",
      "mainImage":
      {
        "link": "https://m.media-amazon.com/images/I/41epVg7mZoS.jpg",
        "height": 500,
        "width": 500
      }
    }
  ],
  "attributes":
  {
    "condition_type": [
      {
        "value": "new_new",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "merchant_shipping_group": [
      {
        "value": "legacy-template-id",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "merchant_suggested_asin": [
      {
        "value": "XXXASINXXX",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "purchasable_offer": [
      {
        "currency": "USD",
        "start_at":
        {
          "value": "2021-07-14T19:56:57.717Z"
        },
        "our_price": [
          {
            "schedule": [
              {
                "value_with_tax": 30.0
              }
            ]
          }
        ],
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "fulfillment_availability": [
      {
        "fulfillment_channel_code": "DEFAULT",
        "quantity": 1,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "main_product_image_locator": [
      {
        "media_location": "https://media-origin-na-ssl.integ.amazon.com/images/I/xxxx1.jpg",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "other_product_image_locator_1": [
      {
        "media_location": "https://media-origin-na-ssl.integ.amazon.com/images/I/xxxxx2.jpg",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "other_product_image_locator_2": [
      {
        "media_location": "https://media-origin-na-ssl.integ.amazon.com/images/I/xxxxx3.jpg",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ]
  },
  "issues": [
    {
      "message": "Attributes tagged as relevant_attributes are incomplete. Provide values for the following attribute(s): item_weight, theme, item_dimensions, item_diameter",
      "severity": "WARNING",
      "attributeName": "item_diameter",
      "attributeNames": [
        "item_diameter",
        "item_dimensions",
        "item_weight",
        "theme"
      ]
    },
    {
      "message": "Attributes tagged as customer_returns are incomplete. Provide values for the following attribute(s): color, item_dimensions, item_weight",
      "severity": "WARNING",
      "attributeName": "color",
      "attributeNames": [
        "color",
        "item_dimensions",
        "item_weight"
      ]
    }
  ],
  "offers": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "offerType": "B2C",
      "price":
      {
        "currency": "USD",
        "amount": "30.0"
      }
    }
  ],
  "fulfillmentAvailability": [
    {
      "fulfillmentChannelCode": "DEFAULT",
      "quantity": 1
    }
  ]
}

Catalog Items API

The Selling Partner API for Catalog Items provides programmatic access to information about items in the Amazon catalog. In other words, you can search Amazon's catalog for products, match your products to the existing product listings on Amazon, and then make sourcing and pricing decisions for listing those products. The Catalog Items API is similar to the MWS Products API section's GetMatchingProduct operation.

The following example uses the getCatalogItem operation to request an item with ASIN XXXXXXXXXX in the NA marketplace. It requests a response with an Item that contains attributes, identifiers, images, productTypes, salesRanks, summaries, variations, and vendorDetails:

GET https://sellingpartnerapi-na.amazon.com/catalog/2022-04-01/items/XXXXXXXXXX
   ?marketplaceIds=ATVPDKIKX0DER
   &includedData=attributes,identifiers,images,productTypes,salesRanks,summaries,variations,vendorDetails

The response to this request contains an Item with all the requested information:

{
  "asin": "XXXXXXXXXX",
  "attributes": {
    "total_hdmi_ports": [
      {
        "value": 4,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "resolution": [
      {
        "language_tag": "en_US",
        "value": "4K",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "item_weight": [
      {
        "unit": "pounds",
        "value": 107.6,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "product_subcategory": [
      {
        "value": "50400150",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "item_dimensions": [
      {
        "width": {
          "unit": "inches",
          "value": 72.4
        },
        "length": {
          "unit": "inches",
          "value": 2.4
        },
        "height": {
          "unit": "inches",
          "value": 41.4
        },
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "brand": [
      {
        "language_tag": "en_US",
        "value": "Samsung Electronics",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "control_method": [
      {
        "value": "voice",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "item_package_dimensions": [
      {
        "length": {
          "unit": "centimeters",
          "value": ###
        },
        "width": {
          "unit": "centimeters",
          "value": ### 
        },
        "height": {
          "unit": "centimeters",
          "value": ###
        },
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "image_aspect_ratio": [
      {
        "language_tag": "en_US",
        "value": "##:#",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "part_number": [
      {
        "value": "XXX",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "includes_remote": [
      {
        "value": true,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "item_type_name": [
      {
        "language_tag": "en_US",
        "value": "TV",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "battery": [
      {
        "cell_composition": [
          {
            "value": "XXX"
          }
        ],
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "manufacturer": [
      {
        "language_tag": "en_US",
        "value": "XXX",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "number_of_boxes": [
      {
        "value": #,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "total_usb_ports": [
      {
        "value": #,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "model_number": [
      {
        "value": "XXX",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "supplier_declared_dg_hz_regulation": [
      {
        "value": "not_applicable",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "num_batteries": [
      {
        "quantity": 2,
        "type": "aaa",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "california_proposition_65": [
      {
        "compliance_type": "on_product_combined_cancer_reproductive",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "compliance_type": "chemical",
        "chemical_names": [
          "xxx"
        ],
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "display": [
      {
        "resolution_maximum": [
          {
            "unit": "pixels",
            "language_tag": "en_US",
            "value": "XX x XX"
          }
        ],
        "size": [
          {
            "unit": "inches",
            "value":##
          }
        ],
        "type": [
          {
            "language_tag": "en_US",
            "value": "****"
          }
        ],
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "item_name": [
      {
        "language_tag": "en_US",
        "value": "XXX",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "list_price": [
      {
        "currency": "USD",
        "value": $$$,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "batteries_required": [
      {
        "value": false,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "includes_rechargable_battery": [
      {
        "value": false,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "product_site_launch_date": [
      {
        "value": "2019-03-11T08:00:01.000Z",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "product_category": [
      {
        "value": "50400100",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "batteries_included": [
      {
        "value": false,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "connectivity_technology": [
      {
        "language_tag": "en_US",
        "value": "Bluetooth",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "USB",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "Wireless",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "HDMI",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "included_components": [
      {
        "language_tag": "en_US",
        "value": "XXX",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "XXX",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "XXX",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "XXX",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "specification_met": [
      {
        "language_tag": "en_US",
        "value": "",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "cpsia_cautionary_statement": [
      {
        "value": "XXX",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "item_type_keyword": [
      {
        "value": "XXX",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "number_of_items": [
      {
        "value": 1,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "warranty_description": [
      {
        "language_tag": "en_US",
        "value": "1 year manufacturer",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "max_resolution": [
      {
        "unit": "pixels",
        "value": 8.3,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "item_package_weight": [
      {
        "unit": "kilograms",
        "value": 62.142,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "supported_internet_services": [
      {
        "language_tag": "en_US",
        "value": "Amazon Instant Video",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "YouTube",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "Netflix",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "Hulu",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "Browser",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "tuner_technology": [
      {
        "language_tag": "en_US",
        "value": "Analog Tuner",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "wireless_communication_technology": [
      {
        "language_tag": "en_US",
        "value": "Wi-Fi::Wi-Fi Direct::Bluetooth",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "model_year": [
      {
        "value": 2019,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "power_source_type": [
      {
        "language_tag": "en_US",
        "value": "Corded Electric",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "street_date": [
      {
        "value": "2019-03-21T00:00:01Z",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "refresh_rate": [
      {
        "unit": "hertz",
        "language_tag": "en_US",
        "value": "120",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ]
  },
  "identifiers": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "identifiers": [
        {
          "identifier": "0887276302195",
          "identifierType": "EAN"
        },
        {
          "identifier": "00887276302195",
          "identifierType": "GTIN"
        },
        {
          "identifier": "887276302195",
          "identifierType": "UPC"
        }
      ]
    }
  ],
  "images": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "images": [
        {
          "variant": "MAIN",
          "link": "https://m.media-amazon.com/images/I/51DZzp3w3vL.jpg",
          "height": 333,
          "width": 500
        }
      ]
    }
  ],
  "productTypes": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "productType": "TELEVISION"
    }
  ],
  "ranks": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "ranks": [
        {
          "title": "Electronics",
          "link": "http://www.amazon.com/gp/bestsellers/electronics",
          "value": 61667
        },
        {
          "title": "QLED TVs",
          "link": "http://www.amazon.com/gp/bestsellers/electronics/21489946011",
          "value": 84
        }
      ]
    }
  ],
  "summaries": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "brandName": "Samsung Electronics",
      "colorName": "Black",
      "itemName": "Samsung QN82Q60RAFXZA Flat 82-Inch QLED 4K Q60 Series (2019) Ultra HD Smart TV with HDR and Alexa Compatibility",
      "manufacturer": "Samsung",
      "modelNumber": "QN82Q60RAFXZA",
      "sizeName": "82-Inch",
      "styleName": "TV only"
    }
  ],
  "variations": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "asins": [
        "B08J7TQ9FL"
      ],
      "variationType": "CHILD"
    }
  ],
  "vendorDetails": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "brandCode": "SAMF9",
      "categoryCode": "50400100",
      "manufacturerCode": "SAMF9",
      "manufacturerCodeParent": "SAMF9",
      "productGroup": "Home Entertainment",
      "replenishmentCategory": "OBSOLETE",
      "subcategoryCode": "50400150"
    }
  ]
}

Notifications API

The Selling Partner API for Notifications lets you subscribe to various notifications that are relevant to a selling partner's business. The following notifications provide useful information for listing items:

ITEM_PRODUCT_TYPE_CHANGE: Sent when there is a change to the product type of any item that the selling partner has a brand relationship with.
LISTINGS_ITEM_STATUS_CHANGE: Sent when the status of a listings item changes for a selling partner. This notification is published when a listings item is created, deleted, or its buyability changes.
LISTINGS_ITEM_ISSUES_CHANGE: Sent when there is a change to the issues associated with a listings item that the selling partner owns. Issues point out that the listings item has problems which cause listings to go inactive, search suppression, or other quality problems.
PRODUCT_TYPE_DEFINITIONS_CHANGE: Sent when there is a new product type or product type version.

For more information on subscribing to notifications, refer to the Notifications Use Case Guide and the createSubscription operation.

Updated about 2 months ago