Fulfillment and shipping tracking
Track a physical card from manufacturing through delivery, and give the cardholder a clear view of where it is.
Fulfillment tracking isn't available yet. A physical card can be requested and activated, but the API doesn't report where the card is between production and the cardholder, and there are no shipping events.
The exact fulfillment states, tracking fields, and events aren't published yet. Processors differ quite a bit in what they report while a card is in transit. One might provide several fulfillment states, a carrier, and a tracking number. Another might provide no tracking information at all and only tell you when the card has been delivered.
Before you begin
You'll need:
- A physical card. See issuing a physical card.
- A webhook endpoint. Fulfillment can take several days, so polling isn't a good fit. It uses your rate limit and can still leave the cardholder waiting for an update.
How it works
There are two status fields to keep separate:
| Field | Answers |
|---|---|
status | Can the card be used? |
fulfillment.status | Where is the physical card? |
These statuses describe different things. A card can be unusable because it's still being delivered, and that's expected.
For example, if status says the card isn't active yet but fulfillment.status
says it's in transit, show the cardholder that the card is on its way rather
than showing an error.
What to plan for
Manufacturing and delivery
Printing, dispatch, and delivery are handled by the card processor and carrier. There isn't an API call that moves a card through these steps.
Delivery can take several days, and the actual time varies by destination. Be careful about turning a dispatch date or tracking status into a guaranteed delivery date. A card that has shipped today may still arrive several days later than expected.
Returned cards
Some cards will be returned instead of delivered. It won't happen often, so it's easy to miss when designing the first version.
When a card is returned, the cardholder still needs a usable card. You'll usually need to confirm the delivery address and arrange a replacement.
Make sure returned cards generate an alert or another signal that your support team will actually see. A status sitting in a dashboard isn't much help if nobody checks it.
Activation
A physical card is activated with POST /v1/cards/{card_id}/activate. The call
doesn't check delivery, so keep your own activation action behind the delivery
state, and don't offer it for a card that is still in transit.
Webhook ordering
Webhook events can arrive out of order. The platform doesn't guarantee that fulfillment events will be delivered in the same order they were created.
If your handler applies every event as soon as it arrives, an older event can overwrite a newer state and make the card appear to move backwards.
Use the event's created_at when processing updates. If an event describes a
state older than the one you've already stored, ignore it.
Related
- Issuing a physical card
- Card lifecycle — the states the card itself moves through
- Webhooks — delivery and ordering guarantees