Voila calls Swap behind the scenes to enrich customs values (pre-tax item values, duties/taxes, HS, COO), then calls the carrier (e.g. FedEx) and returns the label + CI to you.
You remain responsible for the routing, printer selection, rates/void calls, and write-backs to your WMS/OMS.
When to use this path (vs. others)
Choose this path when:
Your WMS doesn’t integrate with Voila, or
You want tighter control of rates, voids, printer routing, or
You run a custom middleware and prefer to act as a proxy WMS.
Use Swap’s plug-and-play integration with Voila when:
Your WMS already has a Voila connector, and you want a lighter operational setup.
Currently available for Mintsoft, PeopleVox, and Synergy.
Use value-only paths (Shopify Notes or the Swap API) when:
Your existing label system can ingest pre-tax item values + HS/COO, and you need compliant numbers (no label here).
Onboarding & Access
You’ll need:
Voila endpoint access (API credentials, courier key).
Voila per-brand credentials (account number + password per brand; provided/mapped by Swap Onboarding).
Request access: [email protected]
Include: company name, brands supported, technical contact.
High-Level Flow (who calls whom)
Your middleware → Voila → Swap → Voila → Carrier → Your middleware
You call Voila to create a label.
Voila calls Swap to fetch compliant values.
Voila calls the carrier (e.g. FedEx).
Voila returns label + CI (and tracking) to you.
You post back tracking/docs to your WMS/OMS (if present).
If you bypass your WMS for label creation, post-back is essential so ops, finance, and CS have visibility on the shipment state.
Endpoint & Auth
Create label (Voila)
POST https://app.heyvoila.io/api/couriers/v1/{{courier-key}}/create-labelReplace {{courier-key}} with the key issued to you during onboarding (often brand-specific).
Use a unique request_id per request for idempotency (safe retries).
Send credentials as headers if supported (avoid secrets in body).
Request Structure
Essentials
shipment block: service, dates, parcels (dims/weight), items, ship_from, ship_to.
items: include description, sku, origin_country, quantity, value (pre-tax item value), value_currency, weight, hs_code (if you have it).
Recommended metadata (parsed by Swap for audit/debug):
order_id, order_name, store_id inside shipment.
Sample request
{
"request_id": "REQ_2025_000123",
"testing": false,
"shipment": {
"dc_service_id": "FEDEX-IP-DDP",
"label_size": "6x4",
"label_format": "pdf",
"collection_date": "2025-06-08T15:00:00.000Z",
"order_id": "12345678910",
"order_name": "US123456",
"store_id": "abcde12345fgh67890",
"parcels": [
{
"dim_length": 10,
"dim_width": 40,
"dim_height": 30,
"dim_unit": "CM",
"weight": 0.5,
"weight_unit": "KG",
"items": [
{
"sku": "TEE-MESH-001",
"description": "Mesh Back Performance Tee",
"origin_country": "CN",
"quantity": 1,
"value": 59.99,
"value_currency": "GBP",
"hs_code": "6109902000"
}
]
}
],
"ship_from": {
"name": "Demo Fulfillment Center",
"company_name": "Demo WMS Ltd",
"address_1": "Warehouse A",
"city": "Manchester",
"postcode": "M1 2AB",
"country_iso": "GB",
"tax_id": "GB123456789",
"eori_id": "GB987654321000"
},
"ship_to": {
"name": "Jane Doe",
"address_1": "Sample Street 5",
"city": "Berlin",
"postcode": "10115",
"country_iso": "DE",
"email": "[email protected]"
}
}
}Tip: If you don’t have HS/COO for all items, Voila will still call Swap for enrichment. Missing fundamentals (e.g., no item value/description) can block label creation, so validate early.
Response (what you’ll get back)
Typical success payload includes:
Label: uri (PDF/PNG URL), type, label_size
Tracking: tracking_codes, tracking_urls
Commercial invoice: commercial_invoice.url
Carrier meta: courier, dc_service_id, courier_specifics
You should:
Print/route the label to the correct floor printer.
Attach/pack the CI when required (DDP/DDU rules vary).
Post back tracking, label URL, CI URL, ship date to WMS/OMS.
Post-Back (if WMS is bypassed)
Minimum fields to write back:
orderId / shipmentId
carrier, serviceCode
trackingNumber, trackingUrl
labelUrl (or base64)
commercialInvoiceUrl
shipDate
Optional (recommended): declaredValues, duty, tax for audit.
Operations Guardrails
Idempotency: Use a stable request_id per {order, parcel set}; retry with the same ID.
Retries: Exponential backoff; surface 4xx validation errors to ops; auto-retry 5xx/timeouts.
Void: Call Voila’s void endpoint before first scan to avoid charges (per-carrier policy).
Observability: Log raw request/response; store doc URLs; alert on CI/value mismatches.
Immutability: Treat CI values as immutable post-label. If the order changes, create a new label/CI.
Security: Keep API keys in a secrets manager; avoid logging PII and tokens.
FAQs
Do brands call Swap directly?
No. In label flows, brands connect to Voila; Voila calls Swap for values.
Can I call Swap /invoices first, then Voila?
You can, but it’s not required. Voila will call Swap for enrichment anyway.
Support
Email: [email protected]
Include the brand and environment (sandbox/production).