Shipment

Shipment options for physical cards.

D1 supports selecting a shipment provider for physical card orders. D1 uses your D1 API request fields and shipment configuration set during D1 onboarding.

Shipment types

Two shipment types are available through shipment.type:

• INDIVIDUAL (default): Ship each card to the end user.
• BULK: Group multiple cards and ship them together (for example, to a branch).

Inputs used for personalization

Required D1 API inputs:

• services.delivery: Shipment method identifier configured during D1 onboarding.
• shipment.type: INDIVIDUAL or BULK.
• shipment.deliveryAddress: Delivery address used for the shipment.

Conditional D1 API inputs:

• shipment.individualAddress: Address of the card holder, usually printed onto the card carrier.

  • Required for INDIVIDUAL.

Optional D1 API inputs (BULK grouping):

• shipment.groupId: Groups cards into a first-level container.
• shipment.orderId: Groups multiple first-level containers into a second-level container.

Example (INDIVIDUAL)

{
  "services": {
    "delivery": "usps-imb"
  },
  "shipment": {
    "type": "INDIVIDUAL",
    "deliveryAddress": {
      "line1": "10 Main St",
      "zipCode": "10001",
      "city": "New York",
      "countryCode": "US"
    }
  }
}

Example (BULK)

{
  "services": {
    "delivery": "laposte-cip"
  },
  "shipment": {
    "type": "BULK",
    "groupId": "container-001",
    "orderId": "dispatch-2026-02-19",
    "deliveryAddress": {
      "line1": "Branch 12",
      "zipCode": "75001",
      "city": "Paris",
      "countryCode": "FR"
    }
  }
}

Shipment flows

Ship to the end user (INDIVIDUAL)

Typical flow:

1. The end user address is printed onto a card carrier.
2. The card is affixed to the card carrier.
3. The card carrier is folded.
4. The card carrier is placed in an envelope.
5. The envelope is shipped to the end user.

Ship to a branch (BULK)

You can group multiple cards and send them to a branch or a designated delivery location.

Enable this mode with shipment.type = "BULK".

Typical flow:

• The end user address is printed onto a card carrier.
• The card is affixed to the card carrier.
• The card carrier is folded.
• The card carrier is placed in an envelope.
• Several envelopes are grouped and packed in a box.
• The box is shipped to the branch.

In this mode, cards can be grouped into one to three levels.

One level of grouping

One‑level grouping: group by `deliveryAddress`.

Level 1: All cards with the same shipment.deliveryAddress are grouped and shipped together to that address.

Two levels of grouping

Two‑level grouping: `groupId` containers grouped by `deliveryAddress`.

Level 1: All cards with the same shipment.groupId are grouped together and placed in a container.

Level 2: All containers with the same shipment.deliveryAddress are grouped and shipped together to that address.

Three levels of grouping

Three‑level grouping: `groupId` → small containers, aggregated by `orderId`, then by `deliveryAddress`.

Level 1: All cards with the same shipment.groupId are grouped together and placed in a small container.

Level 2: All small containers with the same shipment.orderId are grouped together in a larger container.

Level 3: All large containers with the same shipment.deliveryAddress are grouped and shipped together to that address.

Shipment grouping reference

• deliveryAddress: Cards shipped together share the same delivery address (outermost grouping in one‑level mode).
• groupId: Groups cards into a first‑level container.
• orderId: Groups multiple first‑level containers into a second‑level container (used for three‑level grouping).

Typical patterns:

• One level: deliveryAddress only.
• Two levels: groupId + deliveryAddress.
• Three levels: groupId + orderId + deliveryAddress.

Carrier-specific services

Country	Carrier	Details
France	La Poste - CIP	Courrier Industriel Premium (CIP) Generates a unique smart data barcode to identify and track each envelope.
Netherlands	PostNL - KIX	KlantIndeX (KIX) Generates a unique barcode to identify and track each envelope.
US	USPS - IMB	Intelligent Mail Barcode (IMB) Generates a unique barcode to identify and track each envelope with IV-MTR.

Configuration in D1

During D1 onboarding, Thales configures:

• Allowed values for services.delivery.
• The mapping between shipment attributes and carrier options.
• Input validation rules (for example, phone number presence checks).