Tutorial: Retrieve Merchant Shipping Templates
Learn how to use the Product Type Definitions API to view Selling Partner Merchant Shipping Templates and enhance listing quality.
This tutorial explains how to use the Product Type Definitions API to retrieve Merchant Shipping Templates. The Merchant Shipping Template is a table in Seller Central that the Selling Partner can use to create freight rules. Selling Partners use Merchant Shipping Templates to map a SKU to a shipping template. Additionally, Selling Partners use Merchant Shipping Templates to get the correct freight cost, based on factors such as location, weight location, weight, and size. This workflow is not applicable for Fulfillment by Amazon (FBA) items. For more information on the Product Type Definitions API, refer to the following links:
The following steps outline how to use the merchant_shipping_group
attribute to retrieve Merchant Shipping Template names. This attribute contains information about the shipping template that the merchant has registered and configured in their Seller Central account. With this information, Selling Partners can map the correct shipping templates to the SKUs in your application.
Step 1. Set up your workspace
-
Import the Product Type Definitions API Model. This API provides programmatic access to attribute and data requirements for product types in the Amazon catalog.
-
Set up the workspace with the
SellerId
credentials.
Step 2. Use Product Type Definitions to set API call parameters
-
Import the Product Type Definitions API Model and call the
getDefinitionsProductType
operation. To set the variables, use the following table:Key Value sellerId
{{sellerId}}
marketplaceIds
{{marketplaceId}}
productTypeVersion
LATEST
requirements
LISTING
locale
DEFAULT
version
LATEST
productType
PRODUCT
-
To retrieve an Amazon product type definition from the Product Type Definitions API, call the
getDefinitionsProductType
operation and include the preceding parameters.{ "metaSchema":{ "link":{ "resource":"https://selling-partner-definitions-prod-iad.s3.amazonaws.com/schema/amazon-product-type-definition-meta-schema-v1.json/....... ", "verb":"GET" }, "checksum":"rZ/2Yep0np022S38ZdEiNQ==" }, "schema":{ "link":{ "resource":"https://selling-partner-definitions-prod-iad.s3.amazonaws.com/schema/PRODUCT.json/........", "verb":"GET" }, "checksum":"Hi42HJFOEDKOSFYO9SSje+Ibq5Xg==" } }
The
getDefinitionsProductType
response contains the following:metaSchema
: Contains the link to retrieve the Amazon Product Type Definition Meta-Schema document. The link works for seven days.schema
: Contains the JSON schema link for the product type definition. The link works for seven days.checksum
: A hash of the schema (Base64
,MD5
). Use it to verify schema contents, to identify changes between schema versions, and for caching.
For all response attributes, refer to the Product Type Definitions API v2020-09-01 Use Case Guide.
Step 3. Explore the schema usage
-
Choose the
resource
URL under the schema attribute from Step 2. This retrieves a full schema that contains attributes for the requested product type.{ "$schema":"https://schemas.amazon.com/selling-partners/definitions/product-types/meta-schema/v1", "$id":"https://schemas.amazon.com/selling-partners/definitions/product-types/schema/v1/PRODUCT", "$comment":"Amazon product type definition for PRODUCT product type", "$defs":{ "marketplace_id":{ "default":"ATVPDKIKX0DER", "editable":false, "hidden":true, "examples":[ "Amazon.com" ], "type":"string", "anyOf":[ { "type":"string" }, { "type":"string", "enum":[ "ATVPDKIKX0DER" ], "enumNames":[ "Amazon.com" ] } ] } } }
-
Search for the
merchant_shipping_group
attribute to find its requirements.{ "merchant_shipping_group": { "title": "Merchant Shipping Group", "description": "The ship configuration group for an offer. The ship configuration group is created and managed by the seller through the ship setting UI.", "examples": [ "\"Heavy Bulky Products\", \"CN ShunFeng Delivery\"" ], "type": "array", "minItems": 1, "minUniqueItems": 1, "maxUniqueItems": 1, "selectors": [ "marketplace_id" ], "items": { "type": "object", "required": [ "marketplace_id", "value" ], "properties": { "value": { "title": "Merchant Shipping Group", "description": "The ship configuration group for an offer. The ship configuration group is created and managed by the seller through the ship setting UI.", "editable": true, "hidden": false, "examples": [ "Heavy Bulky Products, NCR Large Appliance Delivery" ], "type": "string", "enum": [ "legacy-template-id", "9bc08e3b-0e9f-40c3-96c7-0098525b901b", "a5a0d872-be8c-4f0c-a51a-3647ae4bedf5", "64c92253-d0bf-4970-897c-98ba16eca63a" ], "enumNames": [ "Migrated Template", "Modelo dos EUA", "US Template", "US Template-16" ], "maxLength": 100 }, "marketplace_id": { "$ref": "#/$defs/marketplace_id" } }, "additionalProperties": false } } }
-
Review the array properties in the
merchant_shipping_group
to find theenum
andenumNames
that are available in the Merchant Shipping Templates.Important
The
merchant_shipping_group
attribute contains the following values:enum
: Provides the Merchant Shipping Templates keys.enumNames
: The Seller Central template values.legacy-template-id
: The first template created in a Selling Partner’s Seller Central account.
To find the corresponding
enum
andenumNames
attributes, use the following index value table:Index enum
enumNames
0 legacy-template-id
Migrated Template 1 9bc08e3b-0e9f-40c3-96c7-0098525b901b
Modelo dos EUA 2 a5a0d872-be8c-4f0c-a51a-3647ae4bedf5
US Template 3 64c92253-d0bf-4970-897c-98ba16eca63a
US Template-16
"enum": [ "legacy-template-id", "9bc08e3b-0e9f-40c3-96c7-0098525b901b", "a5a0d872-be8c-4f0c-a51a-3647ae4bedf5", "64c92253-d0bf-4970-897c-98ba16eca63a" ], "enumNames": [ "Migrated Template", "Modelo dos EUA", "US Template", "US Template-16" ]
To ensure proper mapping between the Merchant Shipping Template and the SKU, pass the
enum
key (not theenumNames
value) into thePUT
orPATCH
listing item, or theJSON
listings feed.
Updated about 2 months ago