Request a physical card for bulk delivery

Use this when you need to issue a physical card for an existing virtual card.

It requests a physical card for the virtual card identified by the id path parameter to a physical card and sends it as a bulk delivery.

Each request creates one physical card. The card is personalized and sealed in its own envelope, then grouped with other bulk orders into a parcel sent to one address. This is the processing address for the bulk delivery, e.g. your business address.

Orders are grouped into the same parcel when they are placed on the same day and have identical recipient names, address fields, and contact numbers. Keep these values identical across the batch. Differences, including formatting differences, split the orders into separate parcels.

Prerequisites

Before cards can be upgraded, a physical card programme must be set up and the card profile configuration updated accordingly.

Fields

Set bulkDelivery to true. The card must be linked to a user; bulk delivery isn't available for unlinked cards.

Address

deliveryAddress.name and deliveryAddress.surname identify the parcel recipient, such as an office manager. They aren't printed on the individual card carrier. The carrier uses the linked user's name and surname instead. The remaining deliveryAddress fields identify where the parcel is sent and are also printed on each card carrier inside it.

Delivery methods

Bulk delivery supports REGISTERED_MAIL and COURIER only. Other methods aren't supported. deliveryAddress.contactNumber is required when using COURIER; it isn't used for other delivery methods.

A REGISTERED_MAIL parcel can contain up to 90 cards, and a COURIER parcel can contain up to 200 cards. The fulfillment center splits larger groups across multiple parcels.

US deliveries must use COURIER. When deliveryAddress.country is US, any other deliveryMethod, or omitting it, is rejected with a REQUIRES syntax error on deliveryMethod, unless your programme is configured to convert the delivery method to COURIER automatically.

Tracking fulfillment

Once the request is accepted, Weavr sends the Physical card fulfillment status webhook (/managed_cards/physical_cards_upgrade/watch) each time physicalCardDetails.manufacturingState changes (REQUESTED → SENT_FOR_FULFILLMENT → DISPATCHED → DELIVERED). The same state is available on demand via Get a card.