Provider requirements

Guided Onboarding tracks progress. LumaSwift is preferred; RouteSense labels are United States only (not EU). Fund the Luma wallet before the first label. These are the exact fields and webhook clicks.

Shopify store

Shopify Admin → Apps → Forbinde. Approve orders, fulfillments, and product/location scopes. Reconnect if Shopify asks for new permissions after an app update. Variant SKUs should be set; blank SKUs become UNKNOWN-<variantId>. Checkout carrier rates are optional and register in Settings → Stores after ship-from is saved.

Create the LumaSwift API key

Sign up or log in at https://lumaswift.com. In Luma open Configurations → API Keys (some accounts label this Integrations or Developer). Click Generate / Create API key and copy it immediately. Note the Client ID shown with the key or on the API page, and the Warehouse ID from Warehouses / Inventory.

Paste credentials in Forbinde Destinations

Destinations → LumaSwift → Production. Set Base URL to https://www.lumaswift.com (host only, no /api path). Paste Client ID, API key (Forbinde sends this as x-api-key), and Warehouse ID. Fill ship-from: warehouse name, street, city, state, and ZIP — ZIP is required for RouteSense quotes. Leave API secret blank. Click Save, then Test connection.

Fund the LumaSwift wallet

RouteSense labels charge the Luma wallet, not Forbinde. In Luma open Account → Wallet Overview. Add a wallet if none exists, assign it to the client, then Add Funds. Save a payment method and enable Auto Reload so the balance does not hit $0 mid-day. If Current Wallet Balance is $0 or Health shows enough funds for +0 additional shipments, Forbinde cannot buy labels — quotes may still succeed.

Register the Forbinde webhook in LumaSwift

After Save, Destinations → Destination events shows the Webhook URL (https://api.forbinde.com/api/v1/wms/<id>/webhook). Copy it. In Luma open Configurations → Webhooks → create an endpoint. Paste that exact URL and subscribe it to order.shipped (Luma sends x-lumaswift-event). Forbinde only uses order.shipped for tracking writeback.

Leave the Forbinde webhook secret empty

Luma does not HMAC-sign webhooks today. Do not click Generate webhook secret unless Luma shows a signing secret and sends x-lumaswift-signature. If a secret is stored in Forbinde and Luma posts unsigned, tracking is rejected. Anyone with the webhook URL can post — do not share it.

SKU and catalog

Not required for LumaSwift

Labels use the store SKU as-is plus weight and L×W×H from the product (or the connection ship carton). Do not sync Catalog or map SKUs for the default labels path.

Blank store SKUs

A missing variant SKU becomes UNKNOWN-<variantId>. Add a SKU on the product in the store, then retry. That is a store data fix, not a Forbinde mapping task.

Labels-only vs WMS

Labels-only is the default

Forbinde quotes RouteSense and buys a US shipping label. Luma cannot buy EU labels. The Luma wallet must be funded (or Auto Reload enabled) or label purchase fails. Forbinde does not POST /orders to Luma unless you opt into warehouse fulfillment on the connection. No Luma product catalog and no Forbinde inventory.

After a paid order

Do not buy a storefront shipping label. If weight and L×W×H are set, Forbinde waits ~15 minutes (cancel window) then buys the label. If L×W×H is missing, the order stays held until you confirm carton or set ship carton on the connection. Tracking writes back when Luma posts order.shipped to the webhook you registered.

Shopify-only extras

Admin Package picker dimensions are not readable by apps — set ship carton L×W×H on the connection, or product metafields length / width / height. Tag a test order bridge-live to skip the cancel window. Checkout rates are optional after ship-from is saved.

Troubleshooting

Save & Test fails

Recheck Base URL (https://www.lumaswift.com), API key, Client ID, and Warehouse ID. Rotate any key that was pasted into chat, then save only the new key.

Quote works, label will not buy

Almost always the Luma wallet. Open Luma Account → Wallet Overview. Add Funds, or save a payment method and Enable Auto Reload. A $0 balance or “+0 additional shipments” blocks label-purchases even when Test connection and RouteSense quotes succeed. Retry the order in Forbinde after the wallet has funds.

Label bought, no tracking on the store

Confirm the Destination events webhook URL is pasted in Luma as order.shipped. In Luma, webhook deliveries should return HTTP 200. If you generated a Forbinde webhook secret, clear it unless Luma is signing with x-lumaswift-signature. Then check the order in Events for writeback errors.

Held — missing carton

Weight and/or L×W×H are missing. Enter carton on the order, or set ship carton once on Connections. This is not a failed install.

Held — cancel window

Weight and dims are already set. Forbinde waits ~15 minutes so the customer can cancel, then buys the label. Normal, not a failure.

What Held means

Usually unpaid order, missing product data, plan limit, destination cooldown, or a required manual fix. Open Needs Attention for the exact next action.

Known limitations

Labels are United States only

LumaSwift RouteSense quotes and label purchase do not cover the EU. Luma cannot buy European shipping labels. Warehouse / WMS fulfillment through Luma is still available. For EU pick/pack, use Picqer or Ongoing.

Forbinde never invents a typical box

Carriers refuse or rebill invented dimensions. Confirm weight and L×W×H from catalog or ship carton.

Line edits after send

Qty changes and removed lines update LumaSwift. Adding a new SKU after send is not published — fix that in the warehouse.

Webhook URL is the only gate

Until Luma signs webhooks, anyone with the URL can post a shipment event. Treat it like a secret.