How to include Swap duties and taxes in your Shopify reports

This article explains how to get the duties and taxes Swap Global calculates into your reporting, and why they don't appear in Shopify's own tax reports.

This article applies to Swap Global orders on Shopify. It doesn't cover taxes and duties calculated by Shopify's own tax engine.

Why Shopify's tax reports don't show your Swap duties

When Swap Global powers your international checkout, the taxes and duties your customer pays are calculated by Swap, not by Shopify's native tax engine.

That has one consequence for reporting: Shopify's built-in tax reports only understand Shopify's own tax lines, so they won't contain the import duties Swap calculated, and the tax figures may not match what Swap collected.

The Swap figures live in two other places instead:

On the Shopify order itself. Swap writes a breakdown back to each order after it's created.
In your Swap dashboard. Swap provides CSV exports built for reporting and for tax filing.

This article covers both, and shows you how to join the data back to your Shopify orders.

Actual, billed, and buffered amounts

Before you compare any two numbers, check which amount you're looking at. Swap tracks a separate actual and billed figure for every tax and duty line, and the two are often different.

Amount	What it means	When to use it
Actual	What customs and the tax authority actually assess. This is your true landed-cost figure.	Compliance, landed-cost analysis, understanding your real liability
Billed	What was charged to the customer at checkout, after your tax strategy is applied.	Reconciling what you collected from customers

The two diverge whenever your pricing includes tax or duty. Because Swap adds those amounts to your prices before checkout is reached, the amount added is unlikely to match the final calculation exactly — and in that case the customer is charged only the amount that was added.

Swap also applies a buffer to the billed figure. Duty estimates are consistently low, so a buffer is added on top to stop under-collection eating your margin. Duty and tax buffers are configured separately for your store, so the buffered amount is what actually hit the checkout total.

You can see both figures in your Swap dashboard on an individual order:

The Order Breakdown tab shows the order as it was charged to the customer — the billed amounts.
The Tax Details tab shows the actual calculations that customs will expect.

Swap also splits every tax line into two families, which is how the export columns are grouped:

Duties — customs import duties.
Taxes — VAT and sales tax.

If your numbers don't add up against Shopify, it's almost always because you're comparing an actual figure with a billed one, or because your store uses an inclusive tax strategy so part of the tax or duty is baked into the product price rather than shown as a separate line. See Understanding different tax strategies.

What Swap writes onto every Shopify order

The order note

Swap appends a breakdown of the shipping charge, taxes, and duties to the Shopify order note, so both you and the customer can read it on the order page. This is the quickest way to check a single order, but it's plain text and not suited to reporting at scale.

The note follows a fixed shape:

Swap Global Tax Breakdown: --------- Taxes: 12.40 USD Duties: 8.15 USD  Product taxes & duties included in prices  Swap Global Shipping Line Breakdown: --------- Shipping: 15.00 USD Taxes: 3.10 USD Duties & Fees: 8.15 USD

The Swap Global Tax Breakdown section gives the order-level totals for taxes and duties. The Swap Global Shipping Line Breakdown section shows what was owed at checkout on the shipping line. The "Product taxes & duties included in prices" line appears only when you use an inclusive pricing strategy.

For how the note relates to the checkout breakdown, see Tax Breakdown in Shopify Checkout.

The Swap Global order metafield

Swap writes a boolean metafield to every Shopify order it creates:

Namespace: swap
Key: isSwapGlobal
Value: true

This is a flag, not a figure — it identifies which of your Shopify orders went through Swap Global, so you can filter and segment reports by it. It contains none of the tax numbers themselves.

⚠️ The metafield is written at the point an order is created. Orders placed before this was introduced don't carry it, and they haven't been backfilled — so don't rely on it to identify historical Swap Global orders.

The structured tax breakdown (opt-in)

Swap can also write the full tax breakdown to each Shopify order as a note attribute called swap_tax_json, containing the complete breakdown as JSON. Shopify shows note attributes as Additional details on the order. This is the key to Shopify-side reporting, because note attributes are included in Shopify's native order export.

This is off by default. To turn it on, ask your Swap account manager or onboarding contact to enable the tax breakdown on order custom fields for your store. You can optionally also include platform variance — the difference between what Swap calculated and what Shopify actually charged — which is added to the first shipping line rather than reported as a separate figure.

The value is structured like this:

{   "currency": "USD",   "pricingCoefficientRate": 1,   "orderTaxes": [     {       "countryCode": "US",       "taxType": "IMPORT",       "taxName": "US Import Duties",       "taxRate": 0.05,       "taxableAmount": 163.0,       "taxCalculated": 8.15,       "bufferedTaxCalculated": 8.55,       "taxCollectedInProductPrice": 0     }   ],   "itemLines": [     { "id": "<shopify_line_item_id>", "taxes": [ ] }   ],   "shippingLines": [     {       "name": "Swap Global",       "rateAmount": 15.0,       "taxLines": [ ],       "totalShippingTaxRate": 0.076,       "taxCalculated": 3.10     }   ] }

orderTaxes holds the order-level tax lines.
itemLines holds the same tax lines broken down per Shopify line item.
shippingLines holds the tax lines on the shipping charge.

Every tax line in the breakdown carries the same set of fields:

Field	Meaning
`countryCode`	The destination country the tax or duty applies to
`taxType`	`IMPORT` for duties, or `VAT`, `SALES`, `EXPORT`, `FEES` and `UNKNOWN` for everything else
`taxName`	The human-readable label, for example "US Import Duties"
`taxRate`	The rate as a decimal, so 0.05 is 5%
`taxableAmount`	The base the rate was applied to
`taxCalculated`	The actual computed amount
`bufferedTaxCalculated`	The amount charged at checkout, including Swap's buffer
`taxCollectedInProductPrice`	The portion already built into the product price under an inclusive strategy

💡 On a line covered by an inclusive tax strategy, bufferedTaxCalculated is 0. That means nothing further was charged at checkout — not that no tax applies. The tax is in taxCollectedInProductPrice instead.

swap_tax_json reports the actual tax lines — what customs and the tax authority will expect. For what the customer was billed, use the Swap dashboard orders export, which shows billed amounts in their own columns.

Choosing your reporting route

There are three practical approaches, depending on how close to Shopify's native tooling you want to stay.

Route A — Join the Swap export to your Shopify export

This is the most robust option and the one to reach for if finance owns the report. It needs no setup and no parsing.

Export your Shopify orders from Orders → Export in your Shopify admin.
Export your Swap Global orders from Global → Orders → Download CSV in your Swap dashboard. See How to export global orders for the full column list.
Join the two files on the Shopify order name (Name in Shopify, Platform order name in Swap) or on the numeric order ID (Id in Shopify, Platform order ID in Swap).

You now have Shopify's order and financial columns alongside Swap's Billed VAT, Billed sales tax, Billed import duties and Tax strategy in one table, ready for a pivot table or a BI dashboard.

Route B — Export from Shopify and expand the tax breakdown

Use this if the report has to originate in Shopify.

Ask Swap to enable swap_tax_json for your store.
Export your orders from Orders → Export in your Shopify admin.
Find the Note Attributes column in the CSV. The swap_tax_json value appears there as a JSON string.
Parse it in your spreadsheet or BI tool to pull out taxCalculated or bufferedTaxCalculated from each line, splitting by taxType — IMPORT for duties, VAT and SALES for taxes.

Two things to know. Note attributes are order-level, so the whole JSON blob lands in a single cell for the order — per-item detail is inside it under itemLines, but you have to parse it out. And Shopify's native export puts every note attribute into that one column, so if you'd rather not parse by hand, a third-party export app can split swap_tax_json into its own column and flatten specific fields for you.

Route C — Segment Shopify reports using the metafield

Shopify's own analytics can't sum Swap's duties, because they aren't Shopify tax lines. What it can do is let you filter and segment your existing Shopify reports down to Swap Global orders.

To do that, create an order metafield definition for swap.isSwapGlobal and activate Use in analytics on it. Shopify supports true/false order metafields as report dimensions and filters — see Shopify's guidance on using metafields as dimensions or filters in your reports and on activating metafield options.

Two limits are worth knowing before you plan a report around this:

Shopify reports support only simple metafield values as dimensions. The full duty and tax breakdown is structured data, so it can't be summed natively. Use Route A or Route B for the totals themselves.
Shopify's default Finance reports can't be filtered or edited at all, so you can't apply the segment there.

Reconciliation checks

What you're seeing	Likely cause
Shopify's tax report shows no duties at all	Expected. Shopify's tax engine never sees Swap's duties.
Swap's tax figure doesn't match Shopify's tax line	You're comparing different amounts. Match billed against billed, and actual against actual.
Product prices look like they already include tax	Your tax strategy is inclusive, so part of the tax or duty sits in the product price rather than on a separate line.
The checkout total is slightly higher than actual tax plus duty	Swap applies a buffer to protect against estimation error.
A low-value order shows zero duty	The destination's de minimis threshold wasn't exceeded, so no duty was due. See Understanding de minimis thresholds.
The `swap_tax_json` attribute isn't on your orders	It's opt-in. Ask your Swap contact to enable it.
An older order has no Swap Global metafield	The metafield is only written on orders created since it was introduced, and historical orders haven't been backfilled.
Duties are missing from your tax liability figure	By design. Total tax liability covers VAT and sales tax only, because duties aren't a filing liability.

Which source to use

One order's duties and taxes — open the order in Shopify and read the order note.
A spreadsheet across many orders — the Swap Global orders CSV export. Easiest and cleanest.
Inside a Shopify-exported file — enable swap_tax_json and parse the Note Attributes column, or join the two exports.
VAT and sales tax filing — the tax liability report. See Understanding tax liability reports.
Filtering Shopify reports to Swap orders — the swap.isSwapGlobal order metafield.