Retrieve Merchant Shipping Templates using the Product Type Definitions API

By Leonardo N., Solutions Architect, Selling Partner Developer Services | October 3, 2023

Overview

This blog post helps you to retrieve merchant shipping templates information, which is important when you have Selling Partners in the MFN (Merchant Fulfilled Network) program. Using Merchant Shipping Templates, Selling Partners are able to map a SKU directly to a shipping template and obtain the correct freight cost, depending on factors such as location, weight, and size. This workflow is not applicable for FBA items.

Tutorial

The Merchant Shipping Template is a table configured directly into Seller Central, where the Selling Partner is able to create rules of different types of freights depending on variables such as location, weight, and size. For example, the Selling Partner can create one table for heavy SKUs with higher shipping costs and another for lighter SKUs.

This tutorial helps you understand how to retrieve the Merchant Shipping Template names by utilizing the merchant_shipping_group attribute in the Product Definitions API. This attribute allows your application to have information about the shipping template that the merchant has registered and configured on their Seller Central account. With this information, you can direct your Selling Partners to map the correct shipping templates to the appropriate SKUs in your application.

Step 1. Set up your workspace

This step shows you how to import the Product Type definitions API and configure it to retrieve the required information.

1. Under the Listings Section in the SP-API documentation site, find the Product Type Definitions API. This API provides programmatic access to attribute and data requirements for product types in the Amazon catalog.
2. Import the Product Type Definitions API model.
3. Set up the workspace with the SellerId credentials.

Step 2. Set the parameters for your API call with the Product Type Definitions API

This step shows you how to set parameters to retrieve the data from Product Type Definitions API using Postman.

1. Import the Product Type Definitions API model into Postman and call the getDefinitionsProductType operation.

2. Set the variables using the following table:

3. After setting up the parameters, call the getDefinitionsProductType operation with the parameters above to retrieve an Amazon product type definition from the Product Type Definitions API. The response will include metaSchema and the product type schema.

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

getDefinitionsProductType response in Postman

Step 3. Understand the getDefinitionsProductType response

This section will walk you through the different components of the getDefinitionsProductType response.

• The metaSchema contains the link to retrieve the Amazon Product Type Definition Meta-Schema document. The link is valid for seven days.
• The checksum is a hash of the schema (Base64 MD5). It can be used to verify schema contents, identify changes between schema versions, and for caching.
• The schema contains the link to the JSON schema for the product type definition. The link is valid for seven days.
• For all response attributes, refer to the Product Type Definitions API v2020-09-01 Use Case Guide.

Step 4. Explore the schema usage

Now we are going to dive deep into the schema field.

1. Click the resource URL under the schema attribute from the previous step to retrieve a full schema which contains attributes for the requested Product Type. The URL will return a schema that looks like the following:

{
    "$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. Look up the array properties in the merchant_shipping_group to find the enum and enumNames that are available in the Merchant Shipping Templates.

🚧

Important values in the merchant_shipping_group attribute

• The enum attribute provides the merchant shipping templates keys.
• The enumNames are the Seller Central template values.
• The legacy-template-id indicates the first template created in a Selling Partner’s Seller Central account.

In the example below, the enum legacy-template-id is related to the enumNames Migrated Template. Likewise, the enum a5a0d872-be8c-4f0c-a51a-3647ae4bedf5 is related to the enumNames US Template.

"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"
]

You can find the corresponding enum and enumNames attributes using the following index value table:

By becoming familiar with these attributes, you will be able to list an offer. To ensure proper mapping between the Merchant Shipping Template and the SKU, make sure you are passing the enum key, not the enumNames value, into the PUT or PATCH listing item or JSON listings feed.

Conclusion

This blog walked you through on how to retrieve a Selling Partner’s merchant shipping information using the Merchant Shipping Templates. It also explained how you can enhance your Selling Partner’s experience by providing the correct shipping template information.

Refer to the following links for more resources on the Product Type Definitions API:
• Product Type Definitions API Use Case Guide
• Product Type Definitions API FAQs

👍

Have feedback on this post?

If you have questions or feedback on this post, we'd like to hear from you! Please vote and leave a comment using the tools at the bottom of this page.

Subscribe to updates via RSS feed.