Professional sellers
How to update your shipping templates in Trade Me API
This guide outlines how to use the new shipping templates with the Trade Me API.
This guide outlines how to use the new shipping templates with the Trade Me API.
We know that buyers want transparency across shipping time and costs. We’re confident that surfacing this info should lead to a better experience for buyers and a higher conversion rate for you.
By updating your shipping templates, you’ll be able to provide buyers with clarity about the delivery time and total cost of purchase, throughout the buying journey.
You can use a shipping template on multiple listings, which will make it easier to manage your shipping options if you have lots of products.
To use updated shipping templates, your listings need to meet the following criteria:
- You must be an in-trade seller
- It must be a Buy now only listing (i.e. no auctions)
- The item must be sent via courier (i.e. no freight or bulky items or items heavier than 25kg).
Creating a shipping template
There are two ways to create a shipping template:
1. Within the new ‘Shipping’ section of My Products
2. With the Trade Me API
Within the new ‘Shipping’ section of My Products
1. Login to My Products
2. Navigate to the Shipping section under the My Products tab
3. Click on “Create a shipping template” button – you will then be presented with a form to create your template.
How to create a shipping template
1. Give your template a name (e.g. ‘Small items’) and then select either ‘Free shipping’ or ‘Shipping costs by destination’:
- Free shipping - You offer nationwide free shipping on your item. You will need to provide the carrier product and handling times so that we can display time estimates for buyers.
- Shipping costs by destination - You offer paid shipping either nationwide or by destination. You will need to provide the carrier products, costs and handling times for your shipping options so that we can display time estimates for buyers.
Shipping template options on My Products
Shipping cost by destination templates:
a. Enter the cost (e.g. $5)
b. Select the carrier you’re using. Note that the carrier name doesn’t currently display to buyers.
c. Select the shipping destination. Destinations are based on a location tree/hierarchy. Buyers will see the shipping rates relevant to their location when they search - it is a good idea to have one nationwide option
d. Choose the carrier product (e.g. Standard (1-3 days))
f. Repeat the steps above if you want to add more than one option
2. If you would like to offer combined shipping (free or cheaper shipping for a second or subsequent item) then select the combined shipping option:
a. Similar to shipping options, set the price (enter $0 if you want it to be free)
b. There needs to be at least one non-combined shipping option
c. The combined shipping option will display on your listing page as “Combine with another item you've paid shipping on.”
3. Then select your handling time in business days. This is the amount of time it takes from the customer order to you giving the package to your carrier, in business days. Note that your handling time is added to the shipping option days to give the customer an estimate of the total number of days the item will take to arrive after purchase.
4. Next, select your order cut-off time.
5. Finally, select ‘Save & apply template’
When this is done, we’ll use this info to calculate and display the most appropriate shipping info to the buyer, alongside the full cost of purchase. This can be seen throughout the full buying process.
Create a Shipping Template with the Trade Me API
Documentation of all the new Shipping API endpoints can be found here.
Identify your Shipping Products
You can get a list of Regions, Carriers, and Carrier Products to determine your list of shipping options.
Get a list of Shipping Regions: Retrieves a list of valid shipping regions to be used when creating a Shipping Template.
Get a list of Shipping Carriers: Retrieves a list of valid Carriers to be used when creating a Shipping Template
Get a list of Carrier Products: Retrieves a list of Carrier Products from the provided Carrier ID
Creating a new template on the Trade Me API
You can find documentation on how to add shipping templates here.
This adds a Shipping Template and related options.
Output will give you your new shipping template ID. This is the ID that will be used to apply to your products.
Example output
Making updates to your template
If you need to make any changes to your template you can easily do so by providing the template ID in this request.
Documentation: Update a Shipping Template
Keep in mind that once you’ve added this template to your product, you’ll need to update your live listing for buyers to see this immediately. If you don’t, no worries, it will just appear when the listing is relisted.
Applying your Shipping Templates to Listings with the Trade Me API
Documentation: List an Item API Reference
Once you’ve created a shipping template you can apply it to your listings when you create, relist or update them using the ShippingTemplateId field on the list an item API.
Just copy in the Shipping Template ID into the “ShippingTemplateId” field. This value should be a long integer. An example request is:
Important caveats
For the shipping template to be successfully applied to the listing, there are some requirements to be met with the API request.
The listing must be a Buy Now Only listing:
- It must have:
- A quantity > 0
- A Buy Now price
- Shipping field = 0 (or the field not supplied)
It must not have:
- A reserve price
- A starting price
- Any custom shipping options supplied
- Pick-up only
The primary and/or secondary category must be Marketplace categories
When the above requirements are not met when specifying a ShippingTemplateId, the listing request will fail.
You can identify Marketplace categories by using this endpoint, where AreaOfBusiness = 1 (Marketplace category).
| Guide to shipping templates | |||
|---|---|---|---|
| Template name | Template name | Give the template an easily identifiable name. Can be alphabetical or numbers, no special characters. | Give the template an easily identifiable name. Can be alphabetical or numbers, no special characters. |
| Cost | Cost | Enter the cost for that particular shipping option. | Enter the cost for that particular shipping option. |
| Carrier | Carrier | Most NZ courier companies will be shown here. If you can’t find the courier you use, select ‘Generic’. Carrier is not shown on the listing page currently. | Most NZ courier companies will be shown here. If you can’t find the courier you use, select ‘Generic’. Carrier is not shown on the listing page currently. |
| Destination | Destination | You can specify that this option is only for a specific region. If the buyer is outside the specified region, then they will be shown Nationwide cost. Make sure you have at least one option with Nationwide cost. | You can specify that this option is only for a specific region. If the buyer is outside the specified region, then they will be shown Nationwide cost. Make sure you have at least one option with Nationwide cost. |
| Product | Product | Choose the carrier product, e.g. Standard (1-3 days). We will add the handling time to the days when displaying delivery times to buyers. | Choose the carrier product, e.g. Standard (1-3 days). We will add the handling time to the days when displaying delivery times to buyers. |
| Signature | Signature | If you select the 'With Signature' option, the customer will see two shipping options on the listing - the price without signature and the price with signature. They will be able to choose between the two. | If you select the 'With Signature' option, the customer will see two shipping options on the listing - the price without signature and the price with signature. They will be able to choose between the two. |
| Combined shipping | Combined shipping | If you would like to offer free or reduced shipping for additional items, select ‘Add combined shipping option’.Similar to shipping options, set the price (enter $0 if you want it to be free). This will display to buyers as “Combine with another item you've paid shipping on.” Shopping-cart combined shipping rules will not be affected by this template. | If you would like to offer free or reduced shipping for additional items, select ‘Add combined shipping option’.Similar to shipping options, set the price (enter $0 if you want it to be free). This will display to buyers as “Combine with another item you've paid shipping on.” Shopping-cart combined shipping rules will not be affected by this template. |
| Handling time | Handling time | Handling time is the time between when the buyer places the order and when you hand the order over to your carrier. This is added when showing estimated delivery time to buyers.Total Delivery Time = Handling Time + Courier Transit TimeIf you go on a holiday or if there’s a delay in the courier picking up the items, simply change this, and it will be reflected in estimated delivery times as soon as your products are relisted. | Handling time is the time between when the buyer places the order and when you hand the order over to your carrier. This is added when showing estimated delivery time to buyers.Total Delivery Time = Handling Time + Courier Transit TimeIf you go on a holiday or if there’s a delay in the courier picking up the items, simply change this, and it will be reflected in estimated delivery times as soon as your products are relisted. |
| Order cut-off | Order cut-off | Let customers know when an order needs to be placed for processing to begin on the same day. | Let customers know when an order needs to be placed for processing to begin on the same day. |
How will the shipping template display on your listings?
Once you’ve made changes to the template, you’ll need to update your live listing for buyers to see this immediately or it will just appear when the listing is relisted.
Here are some examples of how your listing page will look with the new shipping options:
