Introduction

Package Tracking lets your images show where a shopper's parcel is: its status, its latest scan and, when the carrier gives one, an estimated delivery date. Zembula gets this from the carrier accounts you connect, or from the order data your store already sends Zembula.

Zembula only reads tracking data. It never changes your shipments or your carrier accounts. A carrier that needs credentials uses your own account with that carrier and your own credentials. Zembula doesn't supply a carrier key of its own.

This page covers where Package Tracking lives, how it uses order data and carriers, how to add a carrier and how to use it in an image. Each carrier's guide has the full steps for getting its credentials.

Where to find it

In the Zembula platform, open Data Sync → Integrations and select the Data integrations tab. The Package Tracking tile shows Set up while it's off and Open once it's on. Its status line reads Not set up, Setting up…, Needs attention or Live, followed by the sources it uses.

Click Set up or Open on the tile to open the Package Tracking page. Below its header, the page has three sections: Carriers, Try it and Status.

Only account Admins can turn Package Tracking on and add carriers. Other users can open the page but can't change it. It shows Ask an Admin to set this up.

Order data and carriers

Package Tracking can answer from two kinds of source:

Order data: the fulfillments and tracking scans your connected order feeds send Zembula, for example from your Shopify store. The Order data row only appears if your account already has this data. With order data on, your content can send just an order ID. For Shopify, your app needs the read_fulfillments permission.
Carriers: a carrier account you connect, such as UPS or DHL. Zembula asks the carrier for a tracking number's scans. Your content sends the tracking number and the carrier's name.

In this release, order data and carriers can't run at the same time. If order data is live, a carrier you connect shows Connected — waiting: carriers and order data can't run together until the next release. To switch, click Use <carrier> instead on the carrier's row, for example Use UPS instead. This turns order data off and that carrier on. Content that sends only an order ID then shows your fallback.

If a carrier is live, the Order data switch is held instead and says Order data and carriers can't run together until the next release. Turn your carriers off first, or wait.

Supported carriers

Most carriers need your own account with that carrier and credentials from its developer site. InPost, LSO and Canpar need none. Each carrier's guide has every step.

UPS

What you need: a UPS.com ID linked to your UPS shipper account.
At UPS: sign in at developer.ups.com, create an app linked to your shipper account, and add the Tracking API to it.
What you paste in Zembula: the app's Client ID and Client Secret.
Limits: UPS sets a usage limit for each app. Check your app's plan on developer.ups.com before you go live.
Full guide: Creating UPS Tracking API Credentials

DHL

What you need: a free developer.dhl.com account with your company email and company name.
At DHL: add an app with the Shipment Tracking - Unified API. DHL reviews each new app before approving it.
What you paste in Zembula: the app's API Key (DHL's Shipment Tracking guide calls it the Consumer Key). You don't need a DHL account number.
Limits: new keys are capped at 250 calls a day and one call every five seconds. Click Request Upgrade on your app before you go live.
Full guide: Creating DHL Tracking API Credentials

Australia Post: also covers StarTrack.

What you need: an Australia Post eParcel or StarTrack contract, or tracking-only access from Australia Post.
At Australia Post: register for the Shipping and Tracking APIs at developers.auspost.com.au and choose Zembula as your eCommerce Partner. When Australia Post emails you, create a production API key with Track Items among its services. A test key won't work.
What you paste in Zembula: the API key and the secret you set for it (your API password). You also type your charge account number. It's not a password. Australia Post accounts are 10 digits (add leading zeroes if yours is shorter), and StarTrack accounts are 8 digits.
Limits: Australia Post allows 10 tracking calls a minute per key.
Delivery estimate: Australia Post doesn't give one, so Zembula shows none until the parcel is delivered.
Full guide: Creating Australia Post Tracking API Credentials

Royal Mail

What you need: a Royal Mail business account. Ask your Royal Mail account manager to start a Tracking API integration.
At Royal Mail: create an app under My Apps at developer.royalmail.net, subscribe it to the Royal Mail Tracking v2 API, and accept Royal Mail's Tracking API Terms & Conditions. Royal Mail approves new subscriptions, usually within a week.
What you paste in Zembula: the app's Client ID and Client Secret. Royal Mail shows the secret only once.
Limits: new subscriptions start on an Assessment plan of 25 calls per 12 hours. Ask Royal Mail to move you to a production plan before you go live.
Not covered: Parcelforce.
Full guide: Creating Royal Mail Tracking API Credentials

FedEx

What you need: a FedEx shipping account.
At FedEx: at developer.fedex.com, create an organization and a project with the Track API, and associate your FedEx shipping account with it.
What you paste in Zembula: the project's API Key and Secret Key.
Full guide: Creating FedEx Tracking API Credentials

USPS

What you need: postage bought under your own USPS Mailer ID (MID). USPS only returns tracking for packages mailed under a MID you're authorized for.
At USPS: create a free app in the USPS Business Portal.
What you paste in Zembula: the app's Consumer Key and Secret.
Limits: a new USPS app has a small hourly quota. Ask USPS for an increase before you go live.
Full guide: Creating USPS Tracking API Credentials

Canada Post

What you need: a Canada Post business profile with a customer number.
At Canada Post: in the Developer Portal, create a Production app (not a Test app) and add the Tracking API to it.
What you paste in Zembula: the app's API Key and Secret. Canada Post shows the secret only once.
Full guide: Creating Canada Post Tracking API Credentials

OnTrac

What you need: an OnTrac account with API access. Email softwaresupport@ontrac.com from your OnTrac account to request it.
What you paste in Zembula: the API password OnTrac issues. You also type your OnTrac account number.
Limits: OnTrac's Terms of Use allow at most five tracking calls per package per day.
Full guide: Creating OnTrac Tracking API Credentials

LSO (Lone Star Overnight)

What you need: nothing. LSO tracking needs no account, key or password.
Full guide: Connecting LSO tracking

Canpar

What you need: nothing. Canpar tracking needs no account, key or password.
Full guide: Connecting Canpar tracking

InPost: parcels in Poland.

What you need: nothing. InPost tracking needs no key.
Full guide: Connecting InPost tracking

Bring: also covers Posten parcels.

What you need: a Mybring user. Log in at mybring.com, or register one there.
At Bring: in your Mybring user settings, open API and create an API key.
What you paste in Zembula: the API key. You also type the email address you log in to Mybring with.
Full guide: Creating Bring Tracking API Credentials

PostNord

What you need: a PostNord customer number, and a developer.postnord.com account on the Customer plan.
At PostNord: PostNord emails you the production API key. You can also find it under Applications.
What you paste in Zembula: the API key.
Before you connect: PostNord's terms let you share your key with a service provider like Zembula only with PostNord's approval. Confirm this with your PostNord contact first.
Full guide: Creating PostNord Tracking API Credentials

If your carrier isn't listed, contact your Zembula team.

Turn on Package Tracking and add a carrier

Keep your carrier credentials private. Don't send them by email or chat. You enter them yourself in the Zembula platform.

In the Zembula platform, open Data Sync → Integrations, select Data integrations, and click Set up (or Open) on the Package Tracking tile.
If Package Tracking is off, click Turn on. The page shows Setting up the builder source… and then Use INTERFACES › Package Tracking in the builder.
Under Carriers, click Add next to your carrier. The row then lists the keys it needs by name, for example Client ID and Client Secret for UPS. Click Paste a key next to the first one. For a carrier that needs no key, such as InPost, LSO or Canpar, the row has a Connect button instead: click it and skip to the last step.
The dialog shows short setup steps for that carrier and one field for each value, named as the carrier names it. Paste each value you copied from the carrier into the field with its name. Some carriers also ask you to type an account number, for example Australia Post and OnTrac.
Click Connect.

Once it's connected, the carrier's row says Connected — starts answering within the hour.

Connecting doesn't prove that the carrier accepts your credentials. Before you use the carrier in live content, check it with Try it (see below).

If a carrier's row shows Not available yet., it can't be added to your account yet.

Use it in an image

Package Tracking appears in the image builder under INTERFACES.

Open a draft image in the builder and add INTERFACES › Package Tracking.
Send the tracking number in tracking_number and the carrier's name in carrier. With order data on, you can send order_id instead. The builder lists what it needs, for example Inputs — send at least one of: tracking_number and Recommended: carrier.
Add the Tracking fields you want to show to your image.

Zembula picks the carrier from the carrier value. It finds the carrier's name anywhere in the value, in any case, so UPS Ground and dhl_ecommerce both work. StarTrack goes to Australia Post. Always send the carrier: Zembula doesn't work out the carrier from the tracking number.

Fields you'll use most:

Tracking.status: the overall status: pending, in_transit, out_for_delivery, delivered, attempted_delivery, failure or returned. It's empty when the carrier has no scans for the parcel.
Tracking.Activities.Current.label, .location and .status_at: the latest scan's status, place and time.
Tracking.Estimated.description and Tracking.Estimated.estimated_at.disp: the carrier's delivery estimate, when it gives one. After delivery, they read Delivered with the delivery time.
Tracking.Progress.steps_3, steps_4 and steps_5: how far along the parcel is, as a percentage, for a progress bar with 3, 4 or 5 steps.
Tracking.tracking_url: a link to the carrier's own tracking page. Tracking.manage_delivery_url links to a carrier page where the shopper can manage the delivery, while the parcel is still on its way. Not every carrier has one. For UPS, it's the same ups.com tracking page.
Tracking.Events: every scan, newest first.
Tracking.API.error: reads not_found when the carrier has no record of the tracking number. Use it to show fallback content.

Two optional inputs change how dates read: date_format (default MMM Do, LT) and estimated_date_format (default dddd, MMM Do, LT). Another, custom_status, puts statuses in your own words, for example {"label_created": "We are working on it!"}.

To try it, add INTERFACES › Package Tracking to a draft image in the builder, turn on Simulate, and preview it with an order ID or a tracking number.

Zembula asks the carrier for tracking when the image loads, so the image shows the latest scan the carrier reports at that moment. Each time an email is opened, the image can make a new call to the carrier. Those calls count against your carrier's limits, so check them before a large send.

What shoppers can see

Zembula shows each carrier scan as one of these statuses:

Label: Label Created, Ready for Carrier Pickup, Carrier Pickup Attempted.
Shipped: Processed, Shipped, Picked Up by Carrier.
In transit: In Transit, Delivery Scheduled, Delayed, Exception, Delivery Attempted.
Out for delivery: Out for Delivery, Ready for Pickup.
Final: Delivered, Failure, Return Requested, Returning to Sender, Returned to Sender.

Delayed, Exception, Delivery Attempted, Failure and the three return statuses are alerts: Tracking.Activities.Current.is_alert is true for them. A scan Zembula can't classify reads In Transit.

Where your credentials are kept

Carrier keys and secrets are saved encrypted and can't be read back. Zembula only shows their last four characters. They're listed under Data Sync → Secrets & Configs, and each one can only be sent to that carrier's API.

Account numbers you type, such as an Australia Post charge account number, are saved as configs that belong to the connection.

To replace a carrier's credentials, open the Package Tracking page and click Replace key next to each key you're changing on the carrier's row. To stop using a carrier, click Disconnect. The carrier still accepts the credentials until you delete or reset them on its developer site.

Turn off deletes this setup's carrier names, lookup order and settings. Your carrier connections and your order data stay. Turning it on again starts from the defaults.

More detail: Shared Secrets and Configs.

Troubleshooting

There's no Turn on or Add button: only Admins can set up Package Tracking. Ask an Admin on your Zembula account.
A carrier shows Connected — waiting: order data is live, and order data and carriers can't run together yet. Click Use <carrier> instead to switch, or keep order data.
Status says Not live: add a source.: connect a carrier, or turn on order data.
Status says Blocked: connect <carrier>.: add the carrier it names under Carriers and paste its credentials.
The image shows no tracking: check that your content sends both the tracking number and the carrier. Preview it with Try it. Then check your credentials in the carrier's guide: some carriers only accept production keys, or need the tracking API added to your app.
Tracking stops showing during a send: your carrier's call limit may be used up. Each carrier's guide covers its limits.

Package Tracking: show shipment status in your emails