Map product attributes for WooCommerce Checkout

Overview 

Map your WooCommerce product attributes (like color, size, and other customizations) in the Zonos extension to ensure orders are imported from Zonos into your WooCommerce store with the correct attributes.

Step 1: Find your product attributes

1. Navigate to the Products tab in your WordPress Admin.

2. From the left-hand navigation, click Attributes to view or manage your global product attributes. Attributes can also be set when adding a new product.

If you are using a third party app for custom attributes like Product Add-Ons for WooCommerce, follow the instructions in the app's documentation to locate the attributes.

Step 2: Identify the attribute path from Zonos

To map attributes in the Zonos extension, you'll first need to understand how they are passed to Zonos. To locate this data:

1. Create a test order for a product with the attribute you want to map.
2. Proceed through Zonos Checkout and select a service level. This will generate a landed cost quote. (You don't need to complete the order.)
3. In Dashboard, go to Quotes.
4. Find the quote for your test order and click into Quote Details.
5. In the API Details section on the right,expand the root-level dropdown, then expand:
   • items
   • metadata

This metadata block shows how product attributes are passed from WooCommerce to Zonos in the API request.

Step 3: Map the attribute in the Zonos extension

Once you've located the attribute in the metadata JSON, return to the Zonos Mapping settings in your WooCommerce extension.

1. Under Attribute field, select Custom Attribute.
2. In the Alias field, enter a descriptive label (e.g. Color, Size, or Custom Engraving).
3. In the Cart item path field, enter the path to the attribute's value, based on the structure you observed in the metadata.

Example of mapping custom attributes

Let's walk through how you can map a product that has a custom attribute for custom engraving, color, and size.

If you're using the Product Add-ons plugin from WooCommerce, attributes are sometimes passed inside an array under the addons key. The JSON block below shows the attributes that were passed to Zonos.

Example JSON block:

{
  "addons": [
    {
      "name": "Custom Engraving",
      "value": "Built to last",
      "price": 0,
      "field_name": "1226-1748963436",
      "field_type": "custom_text",
      "id": 1748963436,
      "price_type": "flat_fee"
    }
  ],
  "variation": {
    "attribute_pa_color": "blue",
    "attribute_size": "Large"
  }
}

In Mapping settings under Attributes, each of these attributes should be mapped as follows:

Note: The path format addons.0.value works like this:

• addons tells the system to look in the addons array
• .0 points to the first object in that array
• .value returns the value from that object's value field
• attribute_pa_color and attribute_size are objects that are not in an array and can be mapped directly.

Test the product attribute mapping

Once you have mapped the attribute, place a complete test order in Zonos Checkout. Once the order has been processed, check the order details in WooCommerce to ensure the product attributes were imported correctly.