HomeDocumentationCode SamplesAnnouncementsModelsRelease NotesFAQGitHubVideos
Developer HubAPI StatusSupport
Documentation
Developer HubAPI StatusSupport

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

  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:

    KeyValue
    sellerId{{sellerId}}
    marketplaceIds{{marketplaceId}}
    productTypeVersionLATEST
    requirementsLISTING
    localeDEFAULT
    versionLATEST
    productTypePRODUCT
  2. 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

  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.

    {
      "$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.

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

    IndexenumenumNames
    0legacy-template-idMigrated Template
    19bc08e3b-0e9f-40c3-96c7-0098525b901bModelo dos EUA
    2a5a0d872-be8c-4f0c-a51a-3647ae4bedf5US Template
    364c92253-d0bf-4970-897c-98ba16eca63aUS 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 the enumNames value) into the PUT or PATCH listing item, or the JSON listings feed.