Tutorial: Retrieve Merchant Shipping Templates

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:

• Product Type Definitions API Use Case Guide
• Product Type Definitions API FAQ

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

1. Import the Product Type Definitions API Model. This API provides programmatic access to attribute and data requirements for product types in the Amazon catalog.

2. Set up the workspace with the SellerId credentials.

Step 2. Use Product Type Definitions to set API call parameters

1. 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

2. To retrieve an Amazon product type definition from the Product Type Definitions API, call the getDefinitionsProductType operation and include the preceding parameters.

   JSON

   {
     "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 Use Case Guide.

Step 3. Explore the schema usage

1. Choose the resource URL under the schema attribute from Step 2. This retrieves a full schema that contains attributes for the requested product type.

   JSON

   {
     "$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"
             ]
           }
         ]
       }
     }
   }
   

2. Search for the merchant_shipping_group attribute to find its requirements.

   JSON

   {
     "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
       }
     }
   }
   

3. Review the array properties in the merchant_shipping_group to find the enum and enumNames 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 and enumNames 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

   JSON

   "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 the enumNames value) into the PUT or PATCH listing item, or the JSON listings feed.