Amazon Selling Partner API - spapi.cyou

列表项API v2021-08-01用例指南

亚马逊SPAPI

# 什么是listings items API?

使用Listings Items的销售伙伴API(Listings Items API)，您可以创建、编辑、删除和检索销售伙伴的亚马逊列表(SKU)的详细信息.，这包括产品事实，如项目标题，以及销售条款，如价格和库存.，请参阅Listings Items API Reference (opens new window)，了解有关Listings Items API操作和相关数据类型和模式的细节.

提交给Listings Items API的列表数据符合Selling Partner API for Product Type Definitions (opens new window).提供的JSON模式格式，关于检索支持的亚马逊产品类型的模式以及在使用Listings Items API提交给亚马逊之前验证数据的细节，请参见产品类型定义API文档.

主要特点

检索关于列表的详细信息Listings Items API接受 "GET "操作，以返回有关现有清单的详细信息.

创建或全面更新列表Listings Items API接受PUT操作来创建一个新的列表或完全替换现有列表的数据.

部分更新列表Listings Items API接受 "PATCH "操作来更新现有列表的一个或多个单独属性，例如更新价格和数量.此外，Listings Items API接受 "PATCH "操作来删除现有列表的一个或多个单独属性.

删除列表Listings Items API接受`DELETE'操作，以删除一个现有的列表.

本地化的问题消息列表项目API提供本地化的问题信息，可以是调用应用程序指定的语言，也可以是亚马逊市场的默认语言.

提交验证Listings Items API在接受提交处理之前对提交数据进行验证.阻止进一步处理的验证错误会同步提供给调用的应用程序.

术语

清单亚马逊清单是一个销售伙伴在亚马逊上列出销售的商品，由库存单位(SKU).包含在亚马逊清单中的产品事实被调和到亚马逊目录商品中，由亚马逊标准识别号(ASINs).识别

全面更新对亚马逊清单的全面更新会对提交的数据进行全面的数据要求验证，并创建一个新的清单或替换现有清单的数据.

部分更新对亚马逊列表的部分更新导致对所提供的属性进行部分数据要求的验证，并更新现有列表的一个或多个属性.

产品类型亚马逊产品类型是亚马逊目录中物品的分级分类.物品数据要求与物品的相关产品类型相联系.

考虑到的问题

1x1更新Listings Items API接受一次一个的列表更新. 对于更适合批量上传的使用-情况，JSON_LISTINGS_FEED馈送类型可与Selling Partner API for Feeds一起使用. JSON_LISTINGS_FEED是Listings Items API的批量等同物，提供与Selling Partner API提供的产品类型定义相同的功能和模式.

完全支持的产品类型Listings Items API还不完全支持所有的亚马逊产品类型.支持的亚马逊产品类型因销售伙伴类型(商家或供应商)和亚马逊市场的不同而不同.请参考销售伙伴API的产品类型定义，了解最新的可用亚马逊产品类型.

部分支持的产品类型对于列表项目API尚未完全支持的亚马逊产品类型，通过使用 "PRODUCT "产品类型，支持对现有ASIN的报价-仅提交和部分更新.

结果和问题Listings Items putListingsItem、patchListingsItem和deleteListingsItem操作的响应表明是否接受提交的处理，以及任何阻止提交被接受的问题.响应不包括接受提交处理后发生的问题.Listings Items getListingsItem操作的响应可以包括提交被处理后发生的问题.

# Tutorial: 检索一个列表的详细信息

使用本教程来返回某个销售伙伴和亚马逊市场的亚马逊listing的详细信息.返回的详细信息可以包括一些可选的数据集，提供关于listing状态的重要信息.

重要的是以下段落中提到的新的LISTINGS_ITEM_ISSUES_CHANGE和LISTINGS_ITEM_STATUS_CHANGE通知目前只对卖家有效.

例如，如果您使用[Selling Partner API for Notifications](https，订阅了接收LISTINGS_ITEM_ISSUES_CHANGE通知 //spapi.cyou/zh/references/notifications-api-v1-reference.html) (Notifications API)而你收到通知你可以调用Listings Item API的getListingsItem操作来获得更多的细节. LISTINGS_ITEM_ISSUES_CHANGE通知不包括与API相同的关于问题的详细信息. 要返回更详细的信息，调用getListingsItem并在includedData参数中指定issues来获得问题数据集.

同样，如果你使用Notifications API订阅了LISTINGS_ITEM_STATUS_CHANGE通知，并且你收到了通知，你可以调用getListingsItem操作来获得更详细的信息. 例如，如果一个列表不再是通知中指出的DISCOVERABLE，你可能想获得问题数据集来查看搜索被抑制的原因.

另一个例子，如果LISTINGS_ITEM_STATUS_CHANGE通知没有表明该列表是可购买的(i.e.状态不包括BUYABLE)，一个常见的原因可能是缺乏库存.在这种情况下，调用getListingsItem操作并在includedData参数中包括fulfillmentAvailability以返回 fulfillmentAvailability数据集.

一般来说，通过includedData参数获得的数据集将帮助你更好地了解列表的状态. 可用的数据集包括摘要信息、贡献属性、问题、报价信息(sellers)、履行可用性(sellers)，以及采购细节(vendors).

先决条件

要完成本教程，你需要

*来自你为之调用的销售伙伴的授权.更多信息请参见销售伙伴API开发者指南 (opens new window).

  • 在您的开发者档案中对产品列表角色的批准.

  • 在应用程序注册页面中为您的应用程序选择的产品列表角色.

# 步骤1：提交列表项目获取请求

调用getListingsItem (opens new window)操作来返回一个列表项的详细信息，并传递以下参数

请求参数

路径参数

Parameter Example Description Required
sellerId AXXXXXXXXXXXXX 一个销售伙伴的标识符，如商家账户或供应商代码.

类型: string

 是的
sku ABC123 标识符(库存保持单位)，是销售伙伴独有的列表项目.

类型：字符串

 是的

查询参数

Parameter Example Description Required
marketplaceIds ATVPDKIKX0DER Comma-delimited list of Amazon marketplace identifiers.

参见Selling Partner API Developer Guide中的Amazon marketplace identifiers.

Type< string > array(csv)

 是的
issueLocale en_US 问题本地化的Locale.

默认当没有提供locale时，使用第一个市场的默认locale.当指定的locale中没有本地化的信息时，本地化默认为en_US.

Type: string

 No
includedData summaries A comma-delimited list of data sets to include in response. See IncludedData in the API reference for the list of available data sets.

Default: summaries.

Type: < enum (IncludedData) > array(csv)

 没有

示例请求

GET https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXX/50-TS3D-QEPT
  .marketplaceIds=ATVPDKIKX0DER
  &amp;issueLocale=en_US
  &amp;includedData=问题,属性,摘要,报价,履行可用性
1
2
3
4

响应

一个成功的响应包括以下一项或多项内容

Name Example Description
sku ABC123 标识符(库存保管单位)，是销售伙伴独有的列表项目.

类型：字符串

summaries See Example Response 列表项目的摘要细节.

类型ItemSummaries

attributes 参见响应实例 JSON对象，包含结构化的列表项目属性数据，以属性名称为关键.

类型ItemAttributes

issues 参见响应实例 与房源相关的问题 item.

Type: ItemIssues

offers 参见响应示例 列表中的优惠详情 item.

Type: ItemOffers

fulfillmentAvailability See Example Response 清单项目的履行情况 item.

Type: < FulfillmentAvailability > array

procurement See Example Response 供应商采购信息的列表项目.

类型ItemProcurement

示例响应

卖方(商人)的示例响应，包括摘要、属性、问题、报价和履行可用性数据集.

{
  "sku": "50-TS3D-QEPT",
  "summaries": [
    {
      "marketplaceId": "atvpdkikx0der",
      "asin": "B08YRD1CNN",
      "产品类型": "drinking_cup",
      "conditionType": "new_new",
      "状态": [
        "BUYABLE",
        "可发现的"
      ],
      "itemName": "6包咖啡杯套装，Farielyn-X 16盎司陶瓷咖啡杯，黑色大咖啡杯，餐厅咖啡杯，适合喝咖啡，茶，卡布奇诺，可可，麦片，外面是亚光黑，里面是彩色的"
      "createdDate": "2021-07-14T19:57:02.327Z",
      "lastUpdatedDate": "2021-07-14T19:57:10.637Z",
      "mainImage":
      {
        "链接": "https://m.media-amazon.com/images/I/41epVg7mZoS.jpg",
        "高度": 500,
        "宽度": 500
      }
    }
  ],
  "属性":
  {
    "condition_type": [
      {
        "值": "new_new",
        "marketplace_id": "atvpdkikx0der"
      }
    ],
    " merchant_shipping_group": [
      {
        "值": "legacy-template-id",
        "marketplace_id": "atvpdkikx0der"
      }
    ],
    " merchant_suggested_asin": [
      {
        "值": "B08YRD1CNN",
        "marketplace_id": "atvpdkikx0der"
      }
    ],
    "purchasable_offer": [
      {
        "货币": "USD",
        "start_at":
        {
          "值": "2021-07-14T19:56:57.717Z"
        },
        "our_price": [
          {
            "时间表": [
              {
                "含税价值": 30.0
              }
            ]
          }
        ],
        "marketplace_id": "atvpdkikx0der"
      }
    ],
    "履行_可用性": [
      {
        " fulfillment_channel_code": "DEFAULT",
        "数量": 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"
      }
    ]
  },
  "问题": [
    {
      "消息": "被标记为相关属性的属性不完整. 为以下属性提供数值(s): item_weight, theme, item_dimensions, item_diameter",
      "严重程度": "警告"
      " attributeName": "item_diameter"
      "attributeNames": [
        " item_diameter",
        "item_dimensions",
        "item_weight",
        "主题"
      ]
    },
    {
      "消息": "标记为customer_returns的属性不完整. 为以下属性提供数值(s)：颜色、物品尺寸、物品重量"
      "严重程度": "警告"
      " attributeName": "颜色"
      " attributeNames": [
        "颜色",
        "item_dimensions",
        "物品重量"
      ]
    }
  ],
  "报价": [
    {
      "marketplaceId": "atvpdkikx0der",
      "offerType": "B2C",
      "价格":
      {
        "currency": "USD",
        "金额": "30.0"
      }
    }
  ],
  "facilitmentAvailability": [
    {
      " fulfillmentChannelCode": "DEFAULT",
      "数量": 1
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

对一个供应商的请求和响应示例，包括摘要、采购和问题数据集.

示例请求

GET https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXX/example-sku
  ?marketplaceIds=ATVPDKIKX0DER
  &amp;issueLocale=en_US
  &amp;includedData=summaries,采购,问题
1
2
3
4

示例响应

{
  "sku": "example-sku",
  "summaries": [
    {
      "marketplaceId": "atvpdkikx0der",
      "asin": "B071VG5N9D",
      "productType": "LUGGAGE",
      "conditionType": "new_new",
      "状态": [
        "DISCOVERABLE"
      ],
      "itemName": "Hardide Carry-On Spinner Suitcase Luggage",
      "createdDate": "2021-02-01T00:00:00Z",
      "lastUpdatedDate": "2021-03-01T00:00:00Z",
      "mainImage":
      {
        "链接": "https://www.example.com/luggage.png",
        "高度": 500,
        "宽度": 500
      }
    }
  ],
  "采购": [
    {
      "costPrice":
      {
        "currencyCode": "USD",
        "金额": "100.00"
      }
    }
  ],
  "问题": [
    {
      "消息": "被标记为相关的属性不完整. 为以下属性提供数值(s): item_weight, theme, item_dimensions, item_diameter",
      "严重程度": "警告"
      " attributeName": "item_diameter"
      "attributeNames": [
        " item_diameter",
        "item_dimensions",
        "item_weight",
        "主题"
      ]
    },
    {
      "消息": "标记为customer_returns的属性不完整. 为以下属性提供数值(s)：颜色、物品尺寸、物品重量"
      "严重程度": "警告"
      " attributeName": "颜色"
      " attributeNames": [
        "颜色",
        "item_dimensions",
        "物品重量"
      ]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

# Tutorial: 创建或全面更新一个清单

使用本教程为给定的销售伙伴和亚马逊市场创建或完全更新一个亚马逊列表.

先决条件

要完成本教程，你需要

*来自您为之调用的销售伙伴的授权.更多信息请参见销售伙伴API开发者指南 (opens new window).

# 步骤1.提交列表物品投放请求

调用putListingsItem (opens new window)操作来创建或完全更新一个列表，并传递以下参数

请求参数

路径参数

Parameter Example Description Required
sellerId AXXXXXXXXXXXXX 一个销售伙伴的标识符，如商家账户或供应商代码.

类型: string

 是的
sku ABC123 标识符(库存保持单位)，是销售伙伴独有的列表项目.

类型：字符串

 是的

查询参数

Parameter Example Description Required
marketplaceIds ATVPDKIKX0DER Comma-delimited list of Amazon marketplace identifiers.

参见Selling Partner API Developer Guide中的Amazon marketplace identifiers.

Type< string > array(csv)

 是的
issueLocale en_US 问题本地化的Locale.

默认当没有提供locale时，使用第一个市场的默认locale.当指定的locale中没有本地化的信息时，本地化默认为en_US.

Type: string

 No

主体参数

Parameter Example Description Required
body 见请求实例 putListingsItem操作的请求体模式.

类型ListingsItemPutRequest

 是的

请求示例

PUT https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123
	? marketplaceIds=ATVPDKIKX0DER
	&amp;issueLocale=en_US
1
2
3
{
  "productType": "LUGGAGE",
  "要求": "LISTING",
  "属性": {
    "condition_type": [
      {
        "值": "new_new",
        "marketplace_id": "atvpdkikx0der"
      }
    ],
    "item_name": [
      {
        "价值": "AmazonBasics 16\" Underseat Spinner Carry-On",
        "language_tag": "en_US",
        "marketplace_id": "atvpdkikx0der"
      }
    ],
    ...
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

响应

一个成功的响应包括以下内容

Name Example Description
sku ABC123 标识符(库存保管单位)，是销售伙伴独有的列表项目.

类型：字符串

status ACCEPTED 列表项目的提交状态.

Type: enum(Status)

submissionId f1dc291475dd11eabc550242ac130003 清单项目提交的独特标识符.

类型: string

issues See Example Response 与列表项目提交有关的问题.

Type < Issue> array

示例响应

{
  "sku": "ABC123",
  "status": "INVALID",
  "submissionId": "f1dc291475dd11eabc550242ac130003",
  "问题": [
    {
      "代码": "90220",
      "消息": "'product_description'是必需的，但没有提供."
      "严重程度": "ERROR"
      "attributeNames": [
        "product_description"
      ]
    }
    ...
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# Tutorial: 部分更新一个清单

使用本教程为指定的销售伙伴和亚马逊市场使用Listings Items API.部分更新亚马逊清单

部分更新是以JSON补丁文件的形式提交的.关于JSON补丁文件的更多细节，请参见https://tools.ietf.org/html/rfc6902 (opens new window)_对于亚马逊列表，JSON补丁文件可以添加、替换或删除整个属性.不支持在属性中修补内容.

先决条件

要完成这个教程，你需要

*来自你为之调用的销售伙伴的授权.更多信息请参见销售伙伴API开发者指南 (opens new window).

  • 在您的开发者档案中对产品列表角色的批准.

  • 在应用程序注册页面中为您的应用程序选择的产品列表角色.

  • 对于属性更新，基于JSON-的列表属性有效载荷，遵守Selling Partner API for Product Type Definitions (opens new window)提供的JSON Schema，用于指定的销售伙伴、亚马逊市场、亚马逊产品类型和属性.

  • 对于属性删除，基于JSON-的列表属性有效载荷，遵守Selling Partner API for Product Type Definitions (opens new window)为给定的销售伙伴、亚马逊市场、亚马逊产品类型和属性提供的JSON模式，并带有要删除的属性的选择器属性.属性不能仅通过名称删除，选择器值确定要删除的属性实例.

# 步骤1.提交列表项目补丁请求

调用patchListingsItem (opens new window)操作来部分更新一个列表，传递以下参数

请求参数

路径参数

Parameter Example Description Required
sellerId AXXXXXXXXXXXXX 一个销售伙伴的标识符，如商家账户或供应商代码.

类型: string

 是的
sku ABC123 标识符(库存保持单位)，是销售伙伴独有的列表项目.

类型：字符串

 是的

查询参数

Parameter Example Description Required
marketplaceIds ATVPDKIKX0DER Comma-delimited list of Amazon marketplace identifiers.

参见Selling Partner API Developer Guide中的Amazon marketplace identifiers.

Type< string > array(csv)

 是的
issueLocale en_US 问题本地化的Locale.

默认当没有提供locale时，使用第一个市场的默认locale.当指定的locale中没有本地化的信息时，本地化默认为en_US.

类型: string

 No

主体参数

Parameter Example Description Required
body See Example Request patchListingsItem操作的请求体模式.

类型ListingsItemPatchRequest

 是的

示例请求

PATCH https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123
	.marketplaceIds=ATVPDKIKX0DER
	&amp;issueLocale=en_US
1
2
3
{
  "productType": "LUGGAGE",
  "补丁":[
    {
      "操作": "替换"
      "path":"/attributes/item_name",
      "值":[
        {
          "值": "AmazonBasics 16\" Underseat Spinner Carry-On"
          "language_tag": "en_US",
          "marketplace_id": "atvpdkikx0der"
        }
      ]
    },
    {
      "操作": "替换"
      "path":"/attributes/purchasable_offer",
      "值":[
        {
          "marketplace_id": "atvpdkikx0der",
          "货币": "USD",
          "our_price": [
            {
              "时间表": [
                {
                  "含税价值": 15.00
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "操作": "删除"
      "路径":"/attributes/item_type_name"
      "值":[
        {
          "marketplace_id": "atvpdkikx0der",
          "language_tag": "en_US"
        }
      ]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

响应

一个成功的响应包括以下内容

Name Example Description
sku ABC123 标识符(库存保管单位)，是销售伙伴独有的列表项目.

类型：字符串

status ACCEPTED 列表项目的提交状态.

Type: enum(Status)

submissionId f1dc291475dd11eabc550242ac130003 清单项目提交的独特标识符.

类型: string

issues See Example Response 与列表项目提交有关的问题.

Type < Issue> array

示例响应

{
  "sku": "ABC123",
  "status": "ACCEPTED",
  "submissionId": "f1dc291475dd11eabc550242ac130003",
  "问题": []
}
1
2
3
4
5
6

# Tutorial: 删除一个清单

使用本教程为指定的销售伙伴和亚马逊市场使用Listings Items API删除一个亚马逊列表.

先决条件

要完成本教程，你需要

*来自你为之调用的销售伙伴的授权.更多信息请参见销售伙伴API开发者指南 (opens new window)

  • 在您的开发者档案中对产品列表角色的批准.

  • 在应用程序注册页面中为您的应用程序选择的产品列表角色.

# 步骤1.提交列表项目删除请求

调用deleteListingsItem (opens new window)操作来删除一个列表，传递以下参数

请求参数

路径参数

Parameter Example Description Required
sellerId AXXXXXXXXXXXXX 一个销售伙伴的标识符，如商家账户或供应商代码.

类型: string

 是的
sku ABC123 标识符(库存保持单位)，是销售伙伴独有的列表项目.

类型：字符串

 是的

查询参数

Parameter Example Description Required
marketplaceIds ATVPDKIKX0DER Comma-delimited list of Amazon marketplace identifiers.

参见Selling Partner API Developer Guide中的Amazon marketplace identifiers.

Type< string > array(csv)

 是的
issueLocale en_US 问题本地化的Locale.

默认当没有提供locale时，使用第一个市场的默认locale.当指定的locale中没有本地化的信息时，本地化默认为en_US.

类型: string

 No

示例请求

DELETE https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123
	.marketplaceIds=ATVPDKIKX0DER
	&amp;issueLocale=en_US
1
2
3

响应

一个成功的响应包括以下内容

Name Example Description
sku ABC123 标识符(库存保管单位)，是销售伙伴独有的列表项目.

类型：字符串

status ACCEPTED 列表项目的提交状态.

Type: enum(Status)

submissionId f1dc291475dd11eabc550242ac130003 清单项目提交的独特标识符.

类型: string

issues See Example Response 与列表项目提交有关的问题.

Type < Issue> array

示例响应

{
  "sku": "ABC123",
  "status": "ACCEPTED",
  "submissionId": "f1dc291475dd11eabc550242ac130003",
  "问题": []
}
1
2
3
4
5
6

# 提交图片和其他媒体属性

Listings Items API接受来自以下来源的产品图片和其他媒体内容属性

-通过HTTP或HTTPS URL下载的可公开访问的Amazon S3桶内容

  • 通过HTTP或HTTPS URL下载的可公开访问的亚马逊CloudFront分发内容
  • 通过S3 URL下载的私有亚马逊S3桶内容(例如，s3://bucket-name/object-name.jpg)

不支持托管在第三-方服务器上的图像.

如果您使用私有的亚马逊S3桶，您还必须配置您的亚马逊S3桶策略，以允许对访问该桶的IAM角色进行GetObject和ListBucket操作(arn:aws:iam::368641386589:role/Media-Download-Role).见以下S3桶策略的例子.

私有的Amazon S3内容被视为不可改变的，这意味着你不能改变Amazon S3对象键的内容.新的媒体内容需要一个新的Amazon S3对象键.这种惯例提供了改善处理时间的好处，并避免了在列表提交被重新-处理的情况下的冗余下载成本.

下面是一个亚马逊S3桶策略的例子，在一个名为bucket-name的桶上启用所需的操作

{
    "版本": "2012-10-17",
    "声明": [
        {
            "Sid": "",
            "行动": [
                "s3:GetObject",
                "s3:ListBucket"
            ],
            "效果": "允许"
            "资源": [
                "arn:aws:s3::bucket-name/*"
                "arn:aws:s3::bucket-name"
            ],
            "校长"{
                "AWS": [
                    "arn:aws:iam::368641386589:role/Media-Download-Role"
                ]
            }
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

Listings Restrictions API v2021-08-01