Build your Verified Account catalog programmatically, straight from your own system.
The Catalog API is one of three ways to build your Verified Account catalog, and it's the option for shippers with developer resources and a system that already holds their product data—an ERP, WMS, PIM, or shipping platform. That system stays the source of truth and writes products to Zonos directly, instead of syncing from a channel integration or uploading a CSV file. If you sell through a supported channel, or you'd rather not write code, those two options build the same catalog with less work.
Items created through the API are treated exactly like items from any other source—once an item is in your catalog, Zonos doesn't care how it got there. Each one is classified for customs if you didn't supply an HS code, screened for U.S. Partner Government Agency (PGA) requirements, and used to calculate duties and taxes on the shipments it appears on.
One part of that stays outside the API. When PGA screening flags an item as Needs attention, the compliance questionnaire behind that flag has to be answered and confirmed in Dashboard—there is no API for it, and Zonos pre-fills what it can so most of the work is reviewing and confirming. The person who builds this integration usually isn't the person who clears those flags, so plan on someone in your organization working through them in Dashboard after your catalog loads. Flagged items aren't blocked from shipping, but clearing them before you ship is what keeps a shipment from being held at the U.S. border.
If you send a product whose SKU or product ID already exists, Zonos updates that product rather than adding a second one. Retries and repeat runs are safe.
The flip side is that two different products sharing a SKU or product ID will be merged into one. Check your data for duplicates before a bulk load.
Fields
Field↕
Required↕
Description↕
sku
Yes*
Your unique identifier for the product. *Each product needs a SKU or a product ID, or both.
productId
Yes*
Your platform's identifier for the product. *Each product needs a SKU or a product ID, or both.
name
Yes
The product name.
customsDescription
Recommended
What the product is, in plain terms, for the customs declaration. Use "Cotton t-shirt", not "Summer Vibes Tee".
countryOfOrigin
Recommended
The 2-letter ISO code for where the product was manufactured. Needed to calculate duty accurately.
measurements
Recommended
Weight and dimensions, used for rating and customs filing.
hsCode
No
The universal 6-digit HS code. If you leave it out, Zonos classifies the product from its name and description.
amount
No
The product price as a number.
currencyCode
No
The 3-letter ISO code for the price currency. Required when you provide amount.
itemType
No
PHYSICAL_GOOD, DIGITAL_GOOD, SERVICE, SUBSCRIPTION, BUNDLE, or PARTIAL_ITEM. Keeps non-physical items from being declared as merchandise.
provinceOfOrigin
No
The state or province where the product originates. Required by some destination countries.
productComposition
No
A list of {material, percentage}. Textiles cannot be classified beyond 6 digits without it.
catalogItemUrl
No
A link to the product page on your site. Improves classification accuracy.
imageUrl
No
A publicly accessible URL for the product image. Improves classification accuracy.
Zonos links each shipment line back to a catalog item using your identifiers, in this order: product ID, then SKU, then name. Keep whichever identifiers you use accurate and consistent between your catalog and the data you send your carrier.
Postal shipments carry a further constraint. Zonos receives a limited field set from postal carriers, and on many lanes the customs description is the only field that arrives carrying anything product-specific. A description that is identical across your whole catalog cannot identify anything on its own.
Append your product ID or SKU to the customs description you send your carrier.
Men's bifold wallet, cowhide leather - 123456
The appended identifier must exactly match the productId or sku on the corresponding catalog item.
Description fields are short. Canada Post submissions, for example, allow roughly 49 characters, so shorten the descriptive portion if your identifiers are long. The identifier matters more than the prose.
Setting the item's customsDescription to the same string you send your carrier is not required, but it makes the two sides directly comparable when a line does not match and you need to work out why.
Matching commonly fails when:
The identifier is missing from the description.
The identifier does not correspond to any productId or sku in your catalog.
The identifier is truncated by the carrier's character limit.
Formatting changes between shipments.
This behavior is still being finalized and may change before launch.
Note: Omitted fields are left untouched, which makes partial updates safe. Sending null does not clear a value, it is ignored. You can overwrite a value with a different one, but you cannot empty it through the API. Contact your Zonos representative if you need a field cleared.
Catalog API
Catalog API
Build your Verified Account catalog programmatically, straight from your own system.
The Catalog API is one of three ways to build your Verified Account catalog, and it's the option for shippers with developer resources and a system that already holds their product data—an ERP, WMS, PIM, or shipping platform. That system stays the source of truth and writes products to Zonos directly, instead of syncing from a channel integration or uploading a CSV file. If you sell through a supported channel, or you'd rather not write code, those two options build the same catalog with less work.
Items created through the API are treated exactly like items from any other source—once an item is in your catalog, Zonos doesn't care how it got there. Each one is classified for customs if you didn't supply an HS code, screened for U.S. Partner Government Agency (PGA) requirements, and used to calculate duties and taxes on the shipments it appears on.
One part of that stays outside the API. When PGA screening flags an item as Needs attention, the compliance questionnaire behind that flag has to be answered and confirmed in Dashboard—there is no API for it, and Zonos pre-fills what it can so most of the work is reviewing and confirming. The person who builds this integration usually isn't the person who clears those flags, so plan on someone in your organization working through them in Dashboard after your catalog loads. Flagged items aren't blocked from shipping, but clearing them before you ship is what keeps a shipment from being held at the U.S. border.
How it works
Create a catalog item for each product you ship.
Make sure each item carries an identifier your postal carrier will pass along.
When your shipment data reaches Zonos, each line is matched back to your catalog item and that item's product data is applied to the calculation.
Create catalog items
catalogItemCreateaccepts a list, so you can send many products in a single request.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {iditemKeynameproductIdskuhsCodecustomsDescriptioncountryOfOrigin}}Sending the same product twice
If you send a product whose SKU or product ID already exists, Zonos updates that product rather than adding a second one. Retries and repeat runs are safe.
The flip side is that two different products sharing a SKU or product ID will be merged into one. Check your data for duplicates before a bulk load.
Fields
skuproductIdnamecustomsDescriptioncountryOfOriginmeasurementshsCodeamountcurrencyCodeamount.itemTypePHYSICAL_GOOD,DIGITAL_GOOD,SERVICE,SUBSCRIPTION,BUNDLE, orPARTIAL_ITEM. Keeps non-physical items from being declared as merchandise.provinceOfOriginproductComposition{material, percentage}. Textiles cannot be classified beyond 6 digits without it.catalogItemUrlimageUrlMake your items matchable
Zonos links each shipment line back to a catalog item using your identifiers, in this order: product ID, then SKU, then name. Keep whichever identifiers you use accurate and consistent between your catalog and the data you send your carrier.
Postal shipments carry a further constraint. Zonos receives a limited field set from postal carriers, and on many lanes the customs description is the only field that arrives carrying anything product-specific. A description that is identical across your whole catalog cannot identify anything on its own.
Append your product ID or SKU to the customs description you send your carrier.
The appended identifier must exactly match the
productIdorskuon the corresponding catalog item.Description fields are short. Canada Post submissions, for example, allow roughly 49 characters, so shorten the descriptive portion if your identifiers are long. The identifier matters more than the prose.
Setting the item's
customsDescriptionto the same string you send your carrier is not required, but it makes the two sides directly comparable when a line does not match and you need to work out why.Matching commonly fails when:
productIdorskuin your catalog.Update catalog items
catalogItemUpdatetakes the same input type as create. Send only the fields you want to change.mutation CatalogItemUpdate($input: [CatalogItemInput!]!) {catalogItemUpdate(input: $input) {iditemKeyhsCodecustomsDescription}}Read your items back
The
catalogItemquery acceptsid,productId, orsku. Use it to confirm what Zonos holds for a product.query CatalogItem($sku: String!) {catalogItem(sku: $sku) {iditemKeynamecustomsDescriptionhsCodeproductIdskucountryOfOrigin}}Delete catalog items
catalogItemDeletetakes Zonos catalog item IDs, not your SKUs or product IDs. Resolve the ID with thecatalogItemquery first.mutation CatalogItemDelete($input: [ID!]!) {catalogItemDelete(input: $input)}Related
CatalogItemInput
catalogItemCreate catalogItemDelete catalogItemUpdate
Was this page helpful?