Lifecycle
A shipment moves through production at the factory, courier handoff, and delivery.DELIVERY_FAILED, EXCEPTION, and CANCELED can also occur from most non-terminal states. DELIVERY_FAILED and EXCEPTION are recoverable - the courier may re-attempt and the shipment can move forward.
Shipment statuses
Only
DELIVERED and CANCELED are terminal. Some carriers skip intermediate states (for example, OUT_FOR_DELIVERY), so do not assume every status is visited.
Per-card production status
Each card in the shipment carries its ownproductionStatus. This lets you tell which cards in a multi-card shipment are still being produced versus already complete.
Single card vs multi-card shipments
One endpoint covers both. A shipment with one card and a shipment with up to 200 cards use the same draft-first flow.
Use multi-card shipments when you are dispatching cards in bulk to a single hub (a corporate office, a regional distribution point). Use single-card shipments when each card goes directly to the cardholder.
Issue a shipment
1
Create a draft
Call Create a card shipment with the destination address, recipient details, courier choice, and one or more cards. The shipment is created with
status: DRAFT.Each card entry includes the cardId, cardDesignId, and a per-card shippingAddress. The per-card address is the final destination printed on the card mailer; it can differ from the box-level destination on multi-card shipments.2
Adjust the draft (optional)
Use Update shipment, Add a card, and Remove a card to edit a
DRAFT shipment. Once submitted, the shipment is frozen.3
Submit to the manufacturer
Call Submit shipment. The shipment transitions to
PLACED and the manufacturer starts production.For multi-card shipments, a cutoffDate is returned. Cards submitted after this cutoff roll into the next production batch. Plan submission with this in mind.On partial failure (some cards accepted, others rejected), the response returns HTTP 207 Multi-Status. The shipment still moves to PLACED with the surviving cards. Rejected cards appear in cards[] with productionStatus: BULK_SHIP_REJECTED and a rejectedAt timestamp.4
Track production and delivery
Subscribe to
CARD_SHIPMENT_STATUS_UPDATED for shipment-level status changes. The webhook fires on every transition (PLACED → IN_PRODUCTION, IN_TRANSIT, etc.) and whenever tracking details become available.To inspect per-card production progress, call Get shipment and read each cards[i].productionStatus.Tracking and webhooks
CARD_SHIPMENT_STATUS_UPDATED is the source of truth for shipment status. Do not poll.
When tracking becomes available, trackingNumber and trackingUrl are populated on the shipment payload. Pass the URL through to the cardholder so they can follow the delivery with the courier directly.
If you need the latest state on demand (e.g. a customer service agent looking up a specific shipment), call Get shipment. The response includes the full cards[] array with per-card production status.
Couriers and destinations
Set the courier on the draft:
Only
DHL, FEDEX, and POSTAL can be selected on create or update. After the shipment is placed, the courier on GET responses and shipping webhooks reflects the manufacturer’s assignment and may be SFEXPRESS for some manufacturer and destination combinations (for example cards shipped to Hong Kong), even if you requested DHL or FEDEX.
Some countries do not support physical card shipping or require additional fields. The API will reject a draft with a clear error if:
- The destination country is not supported (
SHIPPING_NOT_ALLOWED_FOR_COUNTRY) - A zone (state or province) is required for the destination (
ZONE_REQUIRED) or the supplied zone is invalid (INVALID_ZONE) - The chosen courier does not deliver to the destination (
COURIER_NOT_SUPPORTED) - The recipient phone number is invalid or its dial code does not match the destination country (
SHIPPING_PHONE_INVALID,SHIPPING_PHONE_DIAL_CODE_MISMATCH)