Your WMS or middleware calls Swap’s /invoices endpoint directly. Swap will respond with duty, tax, HS codes, country of origin, and other customs compliance fields, already formatted for your target carrier, without relying on Shopify’s note field timing.
These values will allow you to populate commercial invoices and shipping labels for cross-border shipments made using Swap.
When to Call
Trigger: Just before you generate labels or commercial invoices in your WMS.
Purpose:
Ensure carrier labels and commercial invoices meet border compliance.
Always work with Swap-calculated customs values as the source of truth for merchants.
Endpoint (Sandbox)
POST
<https://sandbox-apigw.swap-os.com/shipping/v1/invoices/>
Headers:
Authorization: Bearer <API_KEY>Content-Type: application/jsonIdempotency-Key: <uuid>← prevents duplicate invoice creation on retries
Request Body
Build the request from your WMS order data — Swap handles HS code classification and duty/tax calculation.
Example:
JSON
{
"order_id": "1000456",
"currency": "USD",
"ship_from": {},
"ship_to": {},
"items": [
{
"sku": "SKU123",
"description": "Footwear",
"quantity": 1,
"unit_value": 120
}
]
}
Swap enriches the above with:
hs_codecountry_of_origindutytaxtotal_landed_cost
Response
Desired response
200/201: Compliance invoice payload with enriched compliance fields (some carriers also return a PDF or URL).
Error responses
4xx: Validation error (e.g., missing description, unclassifiable SKU).
5xx: Retry with the same Idempotency-Key.
Best Practices
Call the endpoint just before carrier submission — ensures the latest values and compliance.
Cache successful responses in case of reprints (compliance consistency).
Validate order data early — missing descriptions or COO (country of origin) will block generation.
Treat compliance values as immutable. If an order changes, re-call the API for a new invoice.
Support
Do you have any questions or issues? You can email [email protected] or contact your Swap technical contact.