Overview

The Create Bulk Order endpoint will create a bulk_order_token to us as an identifier to ship multiple physical cards together. The bulk_order_token will be added when creating cards that need to go into the bulk order. Once all cards are created, you can update the bulk_order_status to LOCKED so it can be added to the daily issuance file.

🚧

Please work with your Customer Success Manager and card personalization bureau to ensure bulk shipping is supported for your program.

Bulk Shipping Process

1. Start a bulk order by calling the Create Bulk Order endpoint (POST /v1/card_bulk_orders)
   1. Provide the bulk shipping_method and the shipping_address details for the order.
      1. Note: Each fulfillment house has different capabilities for shipping. If an unsupported shipping method is submitted the request will be rejected.
   2. Provide the product_id for cards in the bulk order. All cards in one bulk order must be the sameproduct_id.
   3. An external_id maybe provided for your own reference for the bulk order.
2. In the response Lithic will return a bulk_order_token token.
3. Next, use the Create Account Holder endpoint to create the business or individual account record.
4. After an Account Holder is created, use the Create Card endpoint (POST /v1/cards bulk_order_token) to associate the card to the bulk order by providing the previously created bulk_order_token.
   1. Note: The shipping type should be BULK and the product_id must match what was submitted in the Create Bulk Order request.
5. Continue to create cards supplying the the same bulk_order_token in the API request for all cards that will be included in the same shipment.
6. Once all cards in the bulk order are created with same bulk_order_token call the Patch Bulk Order endpoint (PATCH /v1/card_bulk_order/{token}) to update the bulk order status to LOCKED.
7. This process can be repeated with additional bulk orders or you can create individual cards throughout the day.
8. At the standard issuance file processing time, Lithic will gather all direct to customer cards created for the day along with all cards with the bulk order status as LOCKED. Lithic will create the issuance file and send to the fulfillment house and change the bulk order status as FULFILLED.
   1. Note: Cards that have an OPEN bulk order status will not be included in the issuance file.

Create Bulk Order

POST /v1/card_bulk_orders

{
  "shipping_address": {
    "address1": "string",
    "address2": "string",
    "city": "string",
    "country": "string",
    "first_name": "string",
    "last_name": "string", 
    "postal_code": "string",
    "state": "string",
    "email": "string",
    "phone_number": "string"
  },
  "shipping_method": "string",
  "external_id": "string", 
  "product_id": "string"
}

{
  "token": "uuid",
  "status": "string",
  "external_id": "string",
  "product_id": "string",
  "card_tokens": [
    "uuid",
    ...
  ],
  "shipping_method": "string",
  "shipping_address": {
    "address1": "string",
    "address2": "string",
    "city": "string",
    "country": "string",
    "first_name": "string",
    "last_name": "string",
    "postal_code": "string",
    "state": "string",
    "email": "string",
    "phone_number": "string"
  },
}

Bulk Shipping Types

The following bulk shipping_methods are available. During fulfillment the type maybe changed due to a service not being available for that location.

• BULK_EXPEDITED - Available for Tag Systems (FedEx Overnight or DHL International Expedited) and Perfect Plastic (UPS Next Day Saver).

Patch Bulk Order

PATCH /v1/card_bulk_order/{token}

{  
  "type": "string"  // LOCKED  
}

{
  "token": "uuid",
  "status": "string",
  "external_id": "string",
  "product_id": "string",
  "card_tokens": [
    "uuid",
    ...
  ],
  "shipping_method": "string",
  "shipping_address": {
    "address1": "string",
    "address2": "string",
    "city": "string",
    "country": "string",
    "first_name": "string",
    "last_name": "string",
    "postal_code": "string",
    "state": "string"
  },
}

Bulk Order Status

Bulk Orders can have the following status.

• OPEN- Physical cards can be created and added to the Bulk Order.
• LOCKED- Physical cards can no longer be created and added to the Bulk Order. Bulk Order will be fulfilled at next fulfillment window.
• FULFILLED - Bulk Order has been submitted to manufacturing house.

Get Bulk Order

GET /v1/card_bulk_order/{token}

{
  "token": "uuid",
  "status": "string",
  "external_id": "string",
  "product_id": "string",
  "card_tokens": [
    "uuid",
    ...
  ],
  "shipping_method": "string",
  "shipping_address": {
    "address1": "string",
    "address2": "string",
    "city": "string",
    "country": "string",
    "first_name": "string",
    "last_name": "string",
    "postal_code": "string",
    "state": "string"
  },
}