Skip to main content

Labels & Commercial Invoices: Get Item Values from Shopify Notes

G
Written by Guido Kaspers
Updated over a month ago

When an order is placed, Swap calculates the total duties and taxes for that shipment and writes this information back into Shopify as a JSON payload in the order note field.

If your WMS or label generation system reads this JSON, you can automatically pull this data and populate commercial invoices and shipping labels with the correct customs-compliant values from Swap.

How it works

Swap calculates landed costs and writes a JSON payload to the order’s note field. When the note is updated, Shopify emits an orders/updated webhook. Your integration should listen for this webhook, read the note, parse the JSON, and pass the values to your labelling and invoice workflows.

When the JSON Becomes Available

  • As soon as an order is created in Shopify, Swap calculates duties & taxes.

  • Swap then writes the results to the Shopify order note field.

  • You should configure your system to listen for order update webhooks from Shopify (not just order creation) so you pick up the Swap-enriched data.

How to Access It

  • Subscribe to Shopify’s orders/updated webhook. [Shopify Official Ref.]

  • In the webhook payload, read the note field.

  • Parse the JSON object inside this note.

Example JSON from Swap

⚠️ Note: In Shopify’s admin, you’ll see the Swap JSON as a single long string in the note field. It’s recommended to script this string through JSON.parse() (or your language’s equivalent) so you can work with it as structured JSON in your integration.

Here’s how it looks as a single-line JSON string (highlighted on the right):

Here’s how it looks beautified for clarity:

JSON
{
  "swap_version": "1.0",
  "currency": "USD",
  "duty": 12.50,
  "tax": 5.20,
  "total_landed_cost": 17.70,
  "hs_codes": [
    {"sku": "SKU123", "hs_code": "640411", "description": "Footwear"},
    {"sku": "SKU456", "hs_code": "420222", "description": "Handbag"}
  ],
  "country_of_origin": "CN"
}

How to Use the Data

  • Label Generation: When sending the create label request to the shipping carrier, pass the taxableAmount values as the item value for each SKU. Do this for each line item.

  • (Optional) Duties, Taxes, and Shipping Costs: Depending on the shipping carrier and how you are creating labels, you may want to pass taxCalculated, taxCollectedInProductPrice, importDuties, or rateAmount (from shipping) within the create label request so that these values appear on the Commercial Invoice as well.

  • Commercial Invoice: Populate HS codes and country of origin in the create label request as you normally would. Both values are required to meet customs compliance.

  • Audit & Compliance: Store the parsed JSON alongside your shipment record for proof of calculation source.

Implementation Steps for Your Dev Team

  1. Subscribe to orders/updated in Shopify Admin → Notifications → Webhooks.

  2. Parse the JSON string from the note field in the payload.

  3. Validate currency & amounts before sending to carriers.

  4. Map HS codes & COO to your WMS product records if needed.

  5. Push values into label generation and invoice creation calls.

Best Practices

  • Make sure to read the JSON both at AND after order creation, to retrieve the Swap data.

  • Log the raw JSON before parsing in case of downstream system errors.

Did this answer your question?