Overview
The ParcelPerform integration has two sides that work together:
- Outbound push — when a shipment is created in Luminous, Luminous immediately registers it with ParcelPerform so ParcelPerform knows to start tracking it.
- Inbound webhook — as the carrier scans the package, ParcelPerform sends those events back to Luminous, updating the delivery status on the shipment record.
Feature flag required. The ParcelPerform integration must be enabled for your account by the Luminous team before the steps below apply. Contact Luminous support to request activation.
What you need from ParcelPerform
Before starting, collect the following from your ParcelPerform portal:
| Item | Where to find it in ParcelPerform |
|---|---|
| Client ID | API / Developer settings |
| Client Secret | API / Developer settings |
| Webhook Authentication Key | Your chosen secret for signing webhook payloads (you set this; it must match what you enter in Luminous) |
| Carrier reference names | Settings → Carriers (the codes ParcelPerform uses for each carrier — these may differ from your shipping software's carrier codes) |
Step 1 — Add the integration account in Luminous
- In Luminous, go to Settings → Integrations.
- Click + Add Integration, then search for and select ParcelPerform.
- Enter your Client ID and Client Secret.
- Enter the Webhook Authentication Key you want to use.
- Click Save. Luminous tests your credentials by verifying they can authenticate with ParcelPerform. If the test passes, the account is active.
Step 2 — Register the Luminous webhook URL in ParcelPerform
After saving the integration account, Luminous has a unique inbound webhook endpoint for your account. Register this URL in the ParcelPerform portal under outgoing webhook / feed settings:
- Method: POST
- Authentication type: HMAC-SHA256
- Secret: the same Webhook Authentication Key you entered in Step 1
Contact Luminous support if you need the exact URL for your account.
Once registered, ParcelPerform will call this URL whenever a tracking event is available for one of your shipments.
Step 3 — Configure carrier reference mapping (if needed)
ParcelPerform identifies carriers by the reference names configured in your ParcelPerform Carriers list (e.g. FEDEX, UPS_GROUND). By default, Luminous sends your shipment's own carrier code as the carrier reference — this works automatically as long as your Luminous carrier codes are already named to match your ParcelPerform carrier references.
If your carrier codes don't match ParcelPerform's naming, a custom mapping is possible on the backend, but there is currently no self-service field for it. Note: this is NOT the same thing as the "Field Mappings" tab on the integration account (Settings → Integrations → [account] → Field Mappings) — that screen maps carrier/service-code values for TrackStar, Shopify, and inbound order normalization, but it is a separate table that ParcelPerform's push job never reads. Contact Luminous support to have a carrier reference mapping configured for your account.
Important: If a shipment is pushed with a carrier reference that isn't configured in your ParcelPerform portal, the push will fail permanently for that shipment. Add the carrier in ParcelPerform (Settings → Carriers) first, then contact Luminous support to re-push the affected shipments.
How the sync works day-to-day
| Event | What Luminous does |
|---|---|
| Shipment created in Luminous | Queues a push to ParcelPerform. Shipments without both a tracking number and a carrier code are skipped until the shipment is updated with that information. |
| ParcelPerform polls the carrier | No action needed — ParcelPerform handles carrier polling automatically. |
| Carrier scan event received by ParcelPerform | ParcelPerform calls the Luminous webhook; the event is stored against the shipment record. |
| Delivery status updated | Becomes one of: pre-transit, in transit, out for delivery, delivered, available for pickup, return to sender, failure, or cancelled. |
Monitoring sync health
Every push attempt and every webhook receipt is recorded in the standard integration sync log. Go to Settings → Integrations → ParcelPerform to see the last successful push, last webhook received, and any errors. See also: Why did a ParcelPerform shipment push fail, and how do I fix it?.