Retrieve Merchant Shipping Templates using the Product Type Definitions API
This blog explains how developers can use the Product Type Definitions API to view Selling Partner Merchant Shipping Templates and enhance listing quality.
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.
- 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.
- Import the Product Type Definitions API model.
- 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.
- Import the Product Type Definitions API model into Postman and call the
getDefinitionsProductType
operation.
- Set the variables using the following table:
Key | Value |
---|---|
sellerId | {{SellerID}} |
marketplaceIds | {{marketplaceId}} |
productTypeVersion | LATEST |
requirements | LISTING |
locale | DEFAULT |
version | LATEST |
productType | PRODUCT |
- 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 includemetaSchema
and the product typeschema
.
{
"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
getDefinitionsProductType
responseThis 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.
- 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"
]
}
]
},
}
}
- 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
}
},
- Look up the array properties in the
merchant_shipping_group
to find theenum
andenumNames
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:
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 |
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.
Updated 7 months ago