DOCS

Manage products

/

Manage Catalog

Create and modify products.

Learn how to add, modify, and delete your Zonos Catalog product(s) in Dashboard or via API. Use Catalog in Dashboard to avoid writing code or if you're making small changes. If you want to directly integrate with Catalog for production implementations, use the API.

Create a product

Dashboard
API

Create a product in Catalog:

  1. Go to Catalog and click on Add product in the top right-hand corner.
  2. Add your product details. The only field required to create a product is the SKU and/or product ID field(s). These fields will be used to reference your catalog products. Learn more about Catalog’s identifiers.
  3. Optional—Add your HS code(s).
  4. Optional—Add your shipping information (weight, dimensions, units of measure, etc.).
  5. Optional—Add restricted countries.
  6. Click save product.

Create multiple products in Catalog:

Upload multiple products or your entire product catalog at once.

Important: If you attempt to create a product that already exists, Catalog will recognize the product based on the SKU and/or product ID and override the original product's details with the new details.

Edit a product

Editing products allows you to update your existing products with additional or updated information efficiently. Instead of having to delete and re-upload the product, you can upload the updated information, and Catalog will match it with the existing product using the catalog identifier (SKU/Product ID). This way, you can keep your catalog up-to-date with minimal effort, whether you use the Dashboard or the API to create new products or edit existing products.

If you create/edit a catalog product that already exists in Catalog, expect the following:

Catalog will write over blank fields on existing items.

  • For example, if an existing product, SKU 321, didn't have a value for weight, and the same product, SKU 321, had a weight of 1.3 lbs in the new upload, the 1.3 lb weight would override the previously blank field.

Catalog will override existing fields with new field values.

  • For example, if an existing product, SKU 123, had a price of 18.99 USD and the same product, SKU 123, had an updated price of 22.99 USD, the new price of 22.99 USD would override the previous price.

Catalog will not override existing values with blank fields.

  • For example, if an existing product, SKU 456, had an HS code of 6109.10, but the HS code of the updated product, SKU 456, is blank, the existing HS code remains.
Dashboard
API

To edit a product:

  1. Click on the Products tab.
  2. Select the product you want to edit.
  3. Make your changes.
  4. Click save product.

To edit multiple or all products at once, just upload an updated CSV file to the Catalog, including your SKU/Product ID combinations. This will trigger automatic updates to your existing items.

Delete a product

Dashboard
API

To delete a product:

  1. Click the Products tab in Dashboard.
  2. Select the product(s) you want to delete. Once your product(s) are selected, a delete button will appear.
  3. Click Delete and then Delete all to confirm your deletion.

To delete all products:

  1. Select the Products tab in Dashboard.
  2. Click Manage Catalog in the top right corner and then Delete all.
  3. Click Delete all once more to confirm your deletion.

Note that if you are deleting a large quantity of items (more than 20,000 products or so), a notification will appear indicating that your deletion is in progress. During this time, you will be unable to interact with Catalog until the deletion is complete. However, you can dismiss the notification and navigate away without interrupting the deletion process.

Restrict a product

If you want to prevent shipments to a certain country (or countries), you can add restrictions when creating or updating a product.

Dashboard
API

To restrict a single product in Catalog:

  1. Click on the Products tab.
  2. Select the product you want to add a restriction to, which will open the edit page.
  3. Find the Restricted countries section at the bottom of the edit page.
  4. Add the countries you want to restrict your product to by selecting or typing the country name(s).
  5. Click save product.

To restrict multiple products in Catalog:

  1. Click on the Import/export tab.
  2. Download the Catalog template CSV.
  3. Fill out the template with your product details, including your SKU/Product ID and restricted countries. Input the 2-digit ISO code separated by vertical bars (e.g., AU|KR|MY|SG). To restrict all countries, simply input ALL as the value. If you want to restrict all countries except one or a few, input ALL- followed by the countries you'd like to unrestrict, separated by vertical bars (e.g., ALL-CA|FR|US). Learn more about CSV formatting. If you'd like to remove all existing restricted countries, input NONE as the value.
  4. Save your file as a CSV and upload to Catalog by dragging and dropping or selecting your file by clicking browse on the same page you downloaded the CSV from.
  5. Review your uploaded products in the preview screen and click upload.

Filtering restricted products:

You can filter restricted products directly in the catalog by downloading your entire catalog in CSV format from Dashboard and opening it in Excel or Google Sheets. From there, you can use the filtering feature to view only the restricted products. This allows you to easily locate and manage the restricted products in your catalog.

If you need to update your catalog after making changes to your CSV, reupload the file and any matching products will be replaced with the updated version. This is done by identifying and matching the SKU and/or product ID.

If you're using Checkout, a restricted message will be displayed in your checkout when a product is restricted to the customer's country. By default, the message will say "This item is restricted from import to your country," but you can customize your own restricted message by providing it in the restrictedCountriesMessage field when adding your country restrictions.

Filter a product

You can search for products in Catalog through Dashboard or via API using either the SKU or product ID. Note that only exact matches will return results; partial matches will not be recognized.

Dashboard
API

To filter by SKU or product ID:

  1. Click on the Products tab.
  2. Select SKU or Product ID in the top left corner of your Catalog.
  3. Enter your SKU or product ID.
  4. Click Apply to view your filtered product(s).

Export your products

If you choose 50 or fewer items from the Catalog table, your catalog will be downloaded directly from Dashboard. However, if you select Export all or more than 50 items, your CSV will be exported via email.

To export 50 items or fewer, follow these steps:

  1. Select 50 or fewer items directly from the Catalog table.
  2. Click Export in the top right corner.
  3. Locate your CSV file directly in your downloads.

To export all products:

Dashboard
API
  1. Go to Dashboard -> Products -> Catalog.
  2. Click the Manage Catalog dropdown next to Add product and click Export all.
  3. Find your catalog file in your downloads.

Trouble downloading from your email?

If you're having trouble downloading the CSV from the email link, this may be due to your browser blocking the download. If so, follow these steps:

  1. Right-click on the "Download" button in your email.
  2. Select "Copy link address" to copy the download URL.
  3. Paste the copied URL into your browser and click enter.
  4. Your catalog will then download directly from your browser.

Classify a product

You can classify a product from your catalog with the API by using the catalogItemId in the ClassificationsCreateFromCatalog mutation.

Note that a name is required to classify a product from your catalog. Consult the GraphQL API reference for a complete catalog and classification fields list.

To create and classify a catalog product simultaneously, add the ClassificationsCreateFromCatalog mutation below to your CatalogItemsCreate mutation.

Classify a catalog product to the 8+ digit (country-specific)

When the shipToCountries field is populated, the classification will be 8+ digit (country-specific) HS code. If no shipToCountries are provided, the classification will default to a 6-digit (universal) HS code. Learn more about the distinctions between universal and country-specific HS codes.

In the example below, the shipToCountries field is provided to generate a country-specific code for Canada.

Mutation

1
2
3
4
5
6
7
8
9
10
11
12
13
14
mutation ClassificationsCreateFromCatalog(
  $catalogItemToClassify: [ClassificationFromCatalogInput!]!
) {
  classificationsCalculateFromCatalog(input: $catalogItemToClassify) {
    id
    configuration {
      shipToCountries
    }
    hsCode {
      code
    }
    name
  }
}

Here’s an example of a request. While Zonos Classify will generate a classification with just a name, we strongly recommend adding as many details as possible for the best classification results.

Variables

1
2
3
4
5
6
7
8
9
10
{
  "catalogItemToClassify": [
    {
      "catalogItemId": "catalog_item_893jkdkllg03k9khjd9",
      "configuration": {
        "shipToCountries": ["CA"]
      }
    }
  ]
}

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "data": {
    "classificationsCreateFromCatalog": [
      {
        "id": "classification_8C49fk2945jmm232CcQtHtXdu",
        "configuration": {
          "shipToCountries": ["CA"]
        },
        "countryOfOrigin": "US",
        "hsCode": {
          "code": "6116.10.0020"
        },
        "name": "Cozy Design Women's Knitted Gloves with Roll Up Cuffs for Winter"
      }
    ]
  }
}

API errors and resolutions

ErrorResolution
A SKU or product ID is required to create a productAn identifier (SKU/product ID) is required to create, edit, or delete a catalog item. To resolve this, add a SKU and/or product ID.
The product you are trying to edit does not exist*You cannot edit a product that does not exist. To resolve this, create a new product with your desired SKU and/or product ID.
Customs description exceeds character limit of 30 characters.By default, customs descriptions are limited to 30 characters, which aligns with the most common character limit for commercial invoices.
Product type invalid. Catalog supports the following product types: digital_good. For physical goods, leave it blank.Catalog only supports the following product types: digital_good and physical_good. If your product is a physical good (most common), leave this field blank.
Packing preference invalid. Catalog supports the following packing preferences: ships_alone and consolidated. If your product can be consolidated with other products, leave blank.Packing preference invalid. Catalog supports the following packing preferences: ships_alone and consolidated. If your product can be consolidated with other products, you can leave it blank as consolidated is the default.
Country must be specified when providing an HS codeIf you provide a country-specific HS code when creating an item, a ship-to-country is required. To resolve this, add a ship-to country.
Price must be greater than 0Catalog does not support negative price values. To resolve this, add a price greater than zero.
Currency code must be provided when a price value is suppliedIf you supply a price, a currency code is required. To resolve this, add a currency code.
Price must be provided when a currency code is suppliedIf you supply a currency code, a price is required. To resolve this, add a price.
The accompanying dimensional field cannot be left blankIf one dimensional field is provided, the other two are required. E.g., if you supply a width of “8 inches,” then the height and length would be required.
Measurement value must be greater than 0Catalog does not support negative or zero measurement values. To resolve this, add a value greater than zero.
When providing a dimensional value, dimensional units cannot be left emptyIf you supply a dimensional value, a dimensional unit is required. To resolve this, add a dimensional unit.
When providing a weight value, the weight unit cannot be left emptyIf you supply a weight value, a weight unit is required. To resolve this, add a weight unit.

* API error only

Was this page helpful?