Labels & Commercial Invoices: Get Item Values from Swap API

Your WMS or middleware calls Swap’s /invoices endpoint directly. Swap responds with duty, tax, HS codes, country of origin (COO), and other customs compliance fields—including the pre-tax declared item values. You use those values in your CI/label flow without relying on storefront price or Shopify notes.

These values let you populate commercial invoices and shipping labels for cross-border shipments using Swap, ensuring the declared values are compliant and accurate.

When to Call

Just before you generate labels or commercial invoices in your WMS.
To ensure carrier labels and commercial invoices meet border compliance.
Always work with Swap-calculated customs values as the source of truth.

TL;DR

Call POST /shipping/v1/public/invoices/<PROVIDER_CODE> (after getting API credentials).
Extract itemList[].productPrice → this is the per-unit, pre-tax declared value.
Use productPrice in your CI/label payload for each line.
Swap also returns duties, taxes, HS codes, and COO, where supported.

Before you start

Obtain Swap API credentials (sandbox/live) for your account and provider code (e.g. glassbox, shipbob).
Ensure your WMS can handle HTTP POST, parse JSON, and map line items by SKU or ID.
Be ready to fallback if the Swap API call fails (don’t block fulfilment).

API Details

Endpoint

Pattern (sandbox or production)

POST https://{environment}-apigw.swap-os.com/shipping/v1/public/invoices/<PROVIDER_CODE>

Headers

x-api-key: <YOUR_API_KEY>
Content-Type: application/json
Idempotency-Key: <uuid> (recommended for dedupe / retries)

Request mapping

You will map your order data to fields like:

Your field	Swap field	Required?
order.id or orderName	orderId / orderName	Yes
store or shop identifier	storeId	Yes
line item SKU	items[].sku	Yes
line item quantity	items[].quantity	Yes
(optional) description etc.	items[].description, variantTitle etc.	If needed by your carrier or tax logic

Example request (minimal)

{
  "orderId": "458529483",
  "storeId": "your-store-id",
  "items": [
    {
      "sku": "PRODUCT-SKU-001"
    }
  ]
}

Sample Response (truncated)

{
  "orderId": "458529483",
  "orderName": "#1001",
  "storeId": "asjmid0jd",
  "currency": "GBP",
  "mode": "B2C",
  "totalPaid": 120,
  "totalVatPaid": 10,
  "totalDutiesPaid": 10,
  "itemList": [
    {
      "sku": "PRODUCT-SKU-001",
      "variantId": "variant-456",
      "productPrice": 50,   // per-unit, pre-tax declared value
      "productVat": 5,
      "productDuties": 5,
      "quantity": 2,
      "linePrice": 100,    // quantity × productPrice
      "lineVat": 10,
      "lineDuties": 10
    }
  ],
  "exporter": {
    "name": "Your Store Name",
    "vatId": null,
    "taxId": null
  },
  "importer": {
    "countryCode": "GB"
  },
  "consignee": {
    "email": null,
    "phone": null
  }
}

Field guide

What you need	Field to use
Declared item value (per unit, pre-tax)	itemList[i].productPrice
Line total value	itemList[i].linePrice
Currency	Top-level currency field
Optional: duties / VAT breakdown	itemList[i].productDuties, productVat

Fallback & Error Handling

HTTP Status	Error / Meaning	What you should do
400	Request validation error	Fix payload (e.g. missing required fields)
401	Authentication error	Confirm API key, credentials
404	Order or store not found	Verify order/store identifiers
422	Business validation (e.g. missing data)	Enrich order lines (description, COO etc.)
500	Internal server error	Retry with same Idempotency-Key, fallback if persists

Validation Checks

Single item order: declared value = productPrice of that line
Multi-item order: each line uses its own productPrice, line totals match sum of lines
Retry behavior: using same Idempotency-Key should not generate duplicate declared values or CI/labels

Best Practices

Call this /invoices endpoint just before generating the label or CI to get latest compliance-values.
Cache responses to ensure consistency for reprints.
Treat Swap values (declared values, duty, tax, HS, COO) as the source of truth — do not recompute or mix with storefront pricings or tax_lines.
If order details change (items, quantities, etc.), re-call the API to get fresh values.

Support

If you’d like help reviewing a sample payload, contact [email protected] and include your store ID, provider code, and a test order ID.