Physical Card Ordering and Emboss Statuses

The emboss lifecycle

A physical card moves through three observable phases:

1. Pending emboss. The card exists but has not yet been picked up by the daily emboss process (or embossing is paused via the 'pause_emboss' account feature). In this phase, the embossedCards array returned by Get Card Info is empty.

2. Sent to emboss. An emboss record has been created and sent to our embossing partner. The record appears in embossedCards with status 'sent_to_emboss', and the card.shipped webhook fires. Its payload includes the ship type (for example "First Class Mail"), the shipping address, and the emboss UUID.

3. Card activated. The emboss record status updates to 'card_activated'. See the note below, because what triggers this depends on your card type.

There are no statuses between 'sent_to_emboss' and 'card_activated'. Once a card is with the embosser, delivery progress (in transit, delivered) is not reported back to Spidr, so we recommend pairing the 'sent_to_emboss' state with a static delivery estimate in your UI, such as "arrives in 7 to 10 business days".

Digital-First cards: activation is automatic for original & replaced cards

Digital-First cards are active upon creation. Because the physical card ships already active:

• For an original or replaced Digital-First card, the emboss record moves to 'card_activated' automatically as part of emboss processing. It does not indicate that your customer has received or activated the card. Do not use it as a "card in hand" signal.
• The card.activate webhook and the Activate Card endpoint only apply to reissued cards (and Physical-Only cards). A reissued card ships inactive; when your customer confirms receipt and you call Activate Card, the emboss record moves from 'sent_to_emboss' to 'card_activated' and card.activate fires. Do not call Activate Card for original or replaced Digital-First cards.
• Replaced Digital-First cards otherwise behave like originals, but physical transactions are blocked automatically while the card is in transit. Remove the block with Edit Account Features once your customer confirms receipt. See Activating Cards for details.

Recommended app screens

For an original or replaced Digital-First card:

For reissued cards, add an activation step (Activate Card endpoint) driven by your customer confirming receipt. For replaced Digital-First cards, add an unblock step instead (Edit Account Features). See Replacing and Reissuing Cards & Activating Cards.

Ordering flow with paused embossing

If your program creates accounts with embossing paused so no card ships automatically:

1. Create the account with 'pauseEmboss' enabled.
2. When your customer opts in to a physical card, call Edit Account Features with { feature: { type: "pause_emboss", value: "N" } }. The account.featureUpdate webhook confirms the change.
3. The next daily emboss run picks up the card and card.shipped fires.

Testing in sandbox

Sandbox and test environments do not produce physical cards. A simulation advances emboss records on a roughly 20 minute cycle, and original Digital-First cards may appear as 'card_activated' immediately, without an observable 'sent_to_emboss' phase. In production, emboss files are processed once per day and original cards may briefly show 'sent_to_emboss' before the automatic update.