Swap can write a JSON object into your Shopify order notes. This JSON contains pre-tax item values you can use as declared values on your commercial invoices or labels.
This flow is value-only. Swap does not generate labels in this step — you continue to use your WMS or carrier system for label creation.
Use this method if your WMS connects to Shopify and can read order notes. Avoid it if your system cannot read Shopify notes or if you need values in real time outside Shopify’s update events.
Before you start
Ask Swap support to enable JSON in Shopify notes for your brand
Make sure Shopify webhooks are enabled
Have access to the Shopify Admin API to check order data
Steps
Enable JSON notes
Email [email protected] with your shop domain, brand name, and environment (sandbox or live). Swap will enable swap_tax_json for your brand.
Create a test order
Place or select a recent order. Wait for Swap to enrich it (listen to orders/updated).
Verify the JSON blob exists
In Shopify Admin API, confirm that the order contains:
{
"name": "swap_tax_json",
"value": "<long json string>"
}See Example JSON for the full JSON
Parse and map values
Use JSON.parse(...) on the string. For each item line, read the taxableAmount from the VAT entry and pass this to your CI or label system as the declared value.
Fallback policy
If the JSON blob is missing or invalid, do not block fulfilment. Continue with your current Shopify logic and log the case for review.
Which field to use
Declared value: taxableAmount (per item, pre-tax).
This is the value expected by carriers and customs.
It prevents overstating values when storefront prices include VAT.
Where to find it
Location: order.note_attributes where name === "swap_tax_json"
Timing: use the orders/updated webhook (not just orders/create). Swap writes the JSON after duties and taxes are calculated.
Example JSON
Swap writes a compact JSON string to the order note. You will see a single long string; parse it into an object.
Only the per-line taxableAmount is required for CI or labels.
The rest of the data is optional for audit or reconciliation, or if your CI template supports duty and tax fields.
Shopify Order JSON Example
{
"...other-order-fields",
"note_attributes": [
{
"name": "swap_tax_json",
"value": "{\"orderTaxes\":[{\"countryCode\":\"CA\",\"taxType\":\"Customs\",\"taxName\":\"Canadian Import Fee\",\"taxRate\":0.18,\"taxableAmount\":312.45,\"taxCalculated\":56.24,\"bufferedTaxCalculated\":56.24,\"taxCollectedInProductPrice\":1}],\"itemLines\":[{\"id\":\"47589200111234\",\"taxes\":[{\"countryCode\":\"CA\",\"taxType\":\"Customs\",\"taxName\":\"Canadian Import Fee\",\"taxRate\":0.18,\"taxableAmount\":145.8,\"taxCalculated\":26.24,\"bufferedTaxCalculated\":26.24,\"taxCollectedInProductPrice\":1}]},{\"id\":\"47589200144567\",\"taxes\":[{\"countryCode\":\"CA\",\"taxType\":\"Customs\",\"taxName\":\"Canadian Import Fee\",\"taxRate\":0.18,\"taxableAmount\":166.65,\"taxCalculated\":29.99,\"bufferedTaxCalculated\":29.99,\"taxCollectedInProductPrice\":1}]}],\"shippingLines\":[{\"name\":\"EXPRESS | 2 - 4 business days (DDP) (Includes Taxes & Fees)\",\"rateAmount\":9.99,\"taxLines\":[],\"totalShippingTaxRate\":0.05,\"taxCalculated\":0.5}],\"pricingCoefficientRate\":1.08,\"currency\":\"CAD\"}"
}
]
}
Shopify Order JSON Parsed
{
"orderTaxes": [
{
"countryCode": "CA",
"taxType": "Customs",
"taxName": "Canadian Import Fee",
"taxRate": 0.18,
"taxableAmount": 312.45,
"taxCalculated": 56.24,
"bufferedTaxCalculated": 56.24,
"taxCollectedInProductPrice": 1
}
],
"itemLines": [
{
"id": "47589200111234",
"taxes": [
{
"countryCode": "CA",
"taxType": "Customs",
"taxName": "Canadian Import Fee",
"taxRate": 0.18,
"taxableAmount": 145.80,
"taxCalculated": 26.24,
"bufferedTaxCalculated": 26.24,
"taxCollectedInProductPrice": 1
}
]
},
{
"id": "47589200144567",
"taxes": [
{
"countryCode": "CA",
"taxType": "Customs",
"taxName": "Canadian Import Fee",
"taxRate": 0.18,
"taxableAmount": 166.65,
"taxCalculated": 29.99,
"bufferedTaxCalculated": 29.99,
"taxCollectedInProductPrice": 1
}
]
}
],
"shippingLines": [
{
"name": "EXPRESS | 2 - 4 business days (DDP) (Includes Taxes & Fees)",
"rateAmount": 9.99,
"taxLines": [],
"totalShippingTaxRate": 0.05,
"taxCalculated": 0.50
}
],
"pricingCoefficientRate": 1.08,
"currency": "CAD"
}
Tax JSON Schema
{
// Tax lines for the entire order
orderTaxes: {
countryCode: string;
taxType: string;
taxName: string;
taxRate: number;
taxableAmount: number;
taxCalculated: number;
// The amount of tax to collect after applying buffers
bufferedTaxCalculated: number;
// The amount of this tax that was already collected in the product price
taxCollectedInProductPrice: number;
}[],
// List of order items with tax lines for each
itemLines: {
// Item variant ID
id: string,
taxes: Same as orderTaxes
}[],
shippingLines: {
name: string;
// Amount charged for shipping
rateAmount: number;
taxLines: Same as orderTaxes;
totalShippingTaxRate: number;
taxCalculated: number;
}[],
// The pricing coefficient applied to product prices
pricingCoefficientRate: number
}
Troubleshooting and guardrails
No blob yet? Keep listening for updates — enrichment may not have landed.
Parse errors? Log the error and skip; do not generate synthetic values.
Cache results: store the parsed blob with the shipment record for consistency.
Retries: reuse your request ID on retries to avoid duplicate CI or labels.
Validation Checks
Single item, VAT-inclusive storefront: CI shows declared value equal to that line’s taxableAmount.
Multi-item order: each line uses its own taxableAmount; CI totals equal the sum of lines.
Retry: repeating the downstream call should not create duplicate CI or labels.
FAQ
Why do we only see “raw text” in Shopify?
This is expected. The note attribute value is a JSON string. Read swap_tax_json and parse it.
Which field matters most for CI accuracy?
The taxableAmount per item. This is the declared value.
Support
If you need help enabling or testing this flow, email [email protected] with your store ID.