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.
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.
manufacturerProductId
EU only
The Non-Standardised Manufacturer Product Identifier (NS-PID). Required on B2C shipments to the EU valued at 150 EUR or less.
gtin
EU only
The Standardised Manufacturer Product Identifier (S-PID), digits only. Required on B2C shipments to the EU valued at 150 EUR or less, if the product has a barcode.
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.
Add EU product identifiers (PIDs)
If you ship to the EU with your Verified Account, the EU requires product identifiers (PIDs) on business-to-consumer (B2C) shipments valued at 150 EUR or less, starting November 1, 2026. Store them on your catalog items. For most Verified Accounts, your post sends Zonos the shipment data, and Zonos matches each item on the shipment to your catalog and applies the identifiers you saved, so you don't send anything extra at shipping time.
Send the identifiers with catalogItemCreate for new products. For products already in your catalog, send them with catalogItemUpdate, which takes the same fields. Match each item's sku to the SKU you use everywhere else, so Zonos can connect the two.
Send the gtin as digits only, with no dashes or spaces. UPC, EAN, JAN, and 13-digit ISBN values all go in this one field. If you hold a 10-digit ISBN, send the 13-digit version instead.
If a product has no barcode, leave gtin out rather than sending an empty string, reusing your SKU, or filling it with placeholder text such as N/A.
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.
How to format the identifier in the shipment data you send your carrier depends on your post, because each post matches shipments to your catalog differently. Go to all posts and select your post. Its page shows how matching works for that post and exactly what to send.
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 your post matches on is missing from the shipment data.
The identifier does not exactly match anything 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.
Update catalog items
catalogItemUpdate takes the same input type as create. Send only the fields you want to change.
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.
Read your items back
The catalogItem query accepts id, productId, or sku. Use it to confirm what Zonos holds for a product.
1queryCatalogItem($sku: String!){
2 catalogItem(sku:$sku) {
3 id
4 itemKey
5 name
6 customsDescription
7 hsCode
8 productId
9 sku
10 countryOfOrigin
11}
12}
Delete catalog items
catalogItemDelete takes Zonos catalog item IDs, not your SKUs or product IDs. Resolve the ID with the catalogItem query first.
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
skuproductIdmanufacturerProductIdgtinnamecustomsDescriptioncountryOfOriginmeasurementshsCodeamountcurrencyCodeamount.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.catalogItemUrlimageUrlAdd EU product identifiers (PIDs)
If you ship to the EU with your Verified Account, the EU requires product identifiers (PIDs) on business-to-consumer (B2C) shipments valued at 150 EUR or less, starting November 1, 2026. Store them on your catalog items. For most Verified Accounts, your post sends Zonos the shipment data, and Zonos matches each item on the shipment to your catalog and applies the identifiers you saved, so you don't send anything extra at shipping time.
skumanufacturerProductIdgtinSend the identifiers with
catalogItemCreatefor new products. For products already in your catalog, send them withcatalogItemUpdate, which takes the same fields. Match each item'sskuto the SKU you use everywhere else, so Zonos can connect the two.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {idskumanufacturerProductIdgtin}}Send the
gtinas digits only, with no dashes or spaces. UPC, EAN, JAN, and 13-digit ISBN values all go in this one field. If you hold a 10-digit ISBN, send the 13-digit version instead.If a product has no barcode, leave
gtinout rather than sending an empty string, reusing your SKU, or filling it with placeholder text such asN/A.If you call the Landed Cost API yourself, you can also include these identifiers in your landed cost request. Most Verified Accounts don't, because the post is the one sending Zonos the shipment data.
For what the regulation requires, see the EU product identifiers guide.
Make 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.
How to format the identifier in the shipment data you send your carrier depends on your post, because each post matches shipments to your catalog differently. Go to all posts and select your post. Its page shows how matching works for that post and exactly what to send.
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:
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?