DOCS

New!

/

15 minute read

October 2, 2019

Bulk Card Orders

Use the /bulkissuances endpoint to order payment cards in bulk.

The cards in a bulk card order are either all owned by a single specified user, or each is owned by a different, dynamically generated user. If you create a bulk card order with separate owners for each card, the cards are shipped directly to the card owners.

You can print personalized information on each card, along with a unique, identifying number that matches a numeric postfix from the token field of the card.

Some attributes of the bulkissuance object can also be defined in an associated card or cardproduct object. If you define one of these attributes in more than one object, the Marqeta platform applies an order of precedence to determine which attribute to use at fulfillment time. The order of precedence is as follows:

  1. card

  2. bulkissuance

  3. cardproduct

Defining an attribute in an object with higher precedence does not overwrite the same attribute in a lower-precedence object; the Marqeta platform ignores these lower-precedence attributes.

Note
For more information on cards, see About Cards.

Create bulk card order

Action: POST
Endpoint: /bulkissuances

Use this endpoint to order cards in bulk.

Note
Before creating a bulk card order, ensure that the config.fulfillment.bulk_ship field of the associated card product is set to true.

As part of creating a bulk card order, you either associate all cards with the same user or each card with a unique user.

To associate all cards with the same user:

  • Set user_association.single_inventory_user=true

  • Set user_association.single_inventory_user_token equal to the token of an existing user.

The bulk card order automatically populates the database with the specified card objects. Values for the card token fields are generated in the format "card-numericPostfix", where numericPostfix is a randomly generated number that is added for each new card that is generated.

To associate each card with a unique user:

Set user_association.single_inventory_user=false. In this case, both cards and associated users are automatically generated. Values for the user token fields are generated in the format "user-numericPostfix". The numericPostfix values for cards and their associated users match. This value is also printed on the physical cards if the name_line_1_numeric_postfix field is set to true.

Note
A new bulk card order creates new cards or users, generally within about a day.

Body field details

Fields Description

token

string, optional

The unique identifier of the bulk card order.

If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.

Allowable Values:

36 char max

card_product_token

string, required

Specifies the card product from which to create your cards.

Allowable Values:

Existing card product token.

Send a GET request to /cardproducts to retrieve card product tokens.

card_allocation

integer, required

The number of cards in the order.

Allowable Values:

Up to 50,000.

The actual number of cards processed per day depends on your fulfillment provider. Contact your Marqeta representative for more information.

user_association

object, optional

Associates each card with a user.

Allowable Values:

name_line_1_numeric_postfix

boolean, optional

If set to true, the unique numeric postfix appended to each card’s token field is also appended to the card’s fulfillment.card_personalization.text.name_line_1.value field.

Allowable Values:

true, false

Default value: false

fulfillment

object, required

Specifies certain physical characteristics of a card and bulk shipment information.

Allowable Values:

expedite

boolean, optional

Set to true to request expedited processing and shipping of the order. Expedited orders ignore the setting of the fulfillment.shipping.method field and always ship by FedEx Priority mail.

This expedited service is available only for cards fulfilled by Perfect Plastic Printing and IDEMIA. For other fulfillment providers, set this field to false.

Note
Contact your Marqeta representative for information regarding the cost of expedited service.

Allowable Values:

true, false

Default value: false

expiration_offset

object, optional

Specifies the length of time for which the cards are valid. In other words, cards expire this length of time after the date of issue.

If this field is not specified, the bulk card order uses the config.card_life_cycle.expiration_offset of the card product.

Allowable Values:

The expiration_offset object

Fields Description

unit

string, optional

Specifies the units for the value field.

Allowable Values:

YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS

Default value: YEARS

value

integer, optional

Specifies the number of time units (as defined by the unit field) that the cards are valid. In other words, cards expire value x unit after the date of issue.

This number is rounded as follows:

  • YEARS – Rounds up to the last second of the last day of the month of expiration. For example, if the issue date is 1 Jan 2015 and value=1, the cards expire on the last day of Jan 2016.

  • MONTHS – Rounds up to the last second of the last day of the month of expiration. For example, if the issue date is 1 Jan 2015 and value=1, the cards expire on the last day of Feb 2015.

  • DAYS – Rounds up to the last second of the day of expiration.

  • HOURS, MINUTES, SECONDS – No rounding.

Allowable Values:

Any positive integer

Default value: 4

The user_association object

Fields Description

single_inventory_user

boolean, optional

Set to true to associate all cards with the same user. Set to false to associate each card with a different user. When set to false, users are generated automatically and associated with the cards.

Allowable Values: true, false

Default value: false

single_inventory_user_token

string, optional

If single_inventory_user=true, use this field to specify the token of an existing user. All cards in the order will be associated with this user.

Allowable Values: 36 char max

The fulfillment object

Name Type Required? Description

card_personalization

object

Yes

Allows personalized attributes to be added to the card.

shipping

object

No

Specifies shipping details for the bulk card order.

The fulfillment.shipping object

Fields Description

return_address

object, optional

Address to which the bulk card order will be returned if shipping fails.

Allowable Values:

recipient_address

object, optional

Address to which the bulk card order will be shipped.

In order to generate cards, a valid shipping address must be provided by one of these:

  • The bulk card order’s fulfillment.shipping.recipient_address field

  • The users' address fields

  • The card product’s config.fulfillment.shipping.recipient_address field

The order of precedence from highest to lowest is card, user, card product. To be valid, an address must have the address1, city, state, and postal_code fields populated. The country field defaults to USA if unpopulated.

Allowable Values:

method

string, optional

Specifies the shipping company and shipping service level.

  • If your fulfillment provider is either Perfect Plastic Printing or IDEMIA and the expedite field is set to true, this field is ignored and the shipping method is implicitly FEDEX_EXPEDITED.

  • If your fulfillment provider is either Perfect Plastic Printing or IDEMIA and the expedite field is set to false, you must specify the shipping company and service level using the method field.

  • If your fulfillment provider is Arroweye Solutions, you must specify the shipping company and service level using the method field.

Allowable Values:

Values allowed depend on your fulfillment provider.

Perfect Plastic Printing and IDEMIA:
USPS_REGULAR , FEDEX_EXPEDITED

Arroweye Solutions:
UPS_REGULAR, UPS_EXPEDITED, USPS_REGULAR, USPS_EXPEDITED

care_of_line

string, optional

Adds the specified value as a C/O (care of) line to the mailing carrier.

Note
This field overrides the equivalent field on the associated card product.

Allowable Values:

255 char max

The fulfillment.shipping.return_address & recipient_address objects

Fields Description

address1

string, optional

Number and street.

Allowable Values: 255 char max, though lower limits may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

address2

string, optional

Additional address information.

Allowable Values: 255 char max, though lower limits may be imposed by providers. Perfect Plastic Printing and IDEMIA limit chars to 100, and Arroweye Solutions limits chars to 50.

city

string, optional

City.

Allowable Values: 50 char max

state

string, optional

State.

Allowable Values: 50 char max

postal_code

string, optional

Postal code.

Allowable Values: 50 char max

country

string, optional

Country.

Allowable Values: 40 char max

phone

string, optional

Telephone number.

Allowable Values: 50 char max

first_name

string, optional

First Name.

Allowable Values: 50 char max

middle_name

string, optional

Middle Name.

Allowable Values: 50 char max

last_name

string, optional

Last Name.

Allowable Values: 50 char max

The fulfillment.card_personalization object

Note
When the Marqeta platform fulfills a bulk card order, card personalization attributes defined at the bulk card order level override matching attributes of the associated card product. Contact your Marqeta representative to make use of card personalization.
Fields Description

text

object, optional

Specifies personalized text that appears on the card.

Allowable Values: carrier

object

No, optional

images

Allowable Values: object

The fulfillment.card_personalization.text object

Fields Description

name_line_1.value

string, required

First line of personalized text printed on the card.

Allowable Values: 21 char max; if name_line_1_numeric_postfix is true, 14 char max.

Strings longer than the character limit are truncated.

name_line_2.value

string, optional

Second line of personalized text printed on the card.

Allowable Values: 21 char max

Strings longer than the character limit are truncated.

The fulfillment.card_personalization.carrier object

Fields Description

template_id

string, optional

Specifies the card carrier template to use.

Allowable Values: A card carrier template ID.

logo_file

string, optional

Specifies an image to display on the card carrier.

Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

logo_thumbnail_file

string, optional

Specifies a thumbnail-sized rendering of the image specified in the logo_file field.

Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

message_file

string, optional

Specifies a text file containing a custom message to print on the card carrier.

Allowable Values: Contains the name of the text file and must match the name of the file you send to your fulfillment provider.

message_line

string, optional

Specifies a custom message that appears on the card carrier.

Allowable Values: 60 char max

The fulfillment.card_personalization.images object

Fields Description

card

object, optional

Specifies personalized images that appear on the card.

signature.name

string, optional

Specifies a PNG image of the card holder’s signature.

Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

Must end in .png.

carrier_return_window.name

string, optional

Specifies a PNG image to display in the return-address window of envelopes used for sending cards to card holders.

Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

Must end in .png.

The fulfillment.card_personalization.images.card object

Fields Description

name

string, optional

Specifies a PNG image to display on the card.

Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

Must end in .png.

thermal_color

string, optional

Specifies the color of the image displayed on the card.

Allowable Values: Contains the name of the color and must match one of the provider’s predefined colors.

Sample request body

{
  "token": "bulk_06_token",
  "card_product_token": "my_card_product_02",
  "card_allocation": 3,
  "user_association": {
    "single_inventory_user": false
  },
  "name_line_1_numeric_postfix": true,
  "fulfillment": {
    "shipping": {
      "method": "USPS_REGULAR",
      "return_address": {
        "address1": "1222 Blake Street",
        "city": "Berkeley",
        "state": "CA",
        "postal_code": "94702",
        "country": "USA",
        "phone": "510-222-2222",
        "first_name": "Shipping",
        "last_name": "R_US"
      },
      "recipient_address": {
        "address1": "1255 Lake Street",
        "city": "Oakland",
        "state": "CA",
        "postal_code": "94611",
        "country": "USA",
        "phone": "510-333-3333",
        "first_name": "Saki",
        "last_name": "Dogger"
      }
    },
    "card_personalization": {
      "text": {
          "name_line_1": {
            "value": "Saki Dogger"
          },
          "name_line_2": {
            "value": "Chicken Tooth Music"
          }
      },
      "carrier": {
        "name": "my_carrier_logo.png",
        "message_line": "my message"
      },
      "images": {
        "card": {
           "name": "my_card_logo.png",
           "thermal_color": "Black"
        },
        "signature": {
          "name": "my_signature.png"
        },
        "carrier_return_window": {
          "name": "my_return_address_image.png"
        }
      }
    }
  }
}

Is this helpful?

Sample response body

This sample shows the initial state of a successfully submitted bulk card order. Additional fields are present after the bulk order has been processed and shipped. To see a bulk card order with these additional fields, see Retrieve bulk card order.

{
    "token": "bulk_06_token",
    "expedite": false,
    "fulfillment": {
        "shipping": {
            "method": "USPS_REGULAR",
            "return_address": {
                "first_name": "Shipping",
                "last_name": "R_US",
                "address1": "1222 Blake Street",
                "city": "Berkeley",
                "state": "CA",
                "postal_code": "94702",
                "country": "USA",
                "phone": "510-222-2222"
            },
            "recipient_address": {
                "first_name": "Saki",
                "last_name": "Dogger",
                "address1": "1255 Lake Street",
                "city": "Oakland",
                "state": "CA",
                "postal_code": "94611",
                "country": "USA",
                "phone": "510-333-3333"
            }
        },
        "card_personalization": {
            "text": {
                "name_line_1": {
                    "value": "Saki Dogger"
                },
                "name_line_2": {
                    "value": "Chicken Tooth Music"
                }
                },
            "carrier": {
                "name": "my_carrier_logo.png",
                "message_line": "my message"
                },
            "images": {
                "card": {
                    "name": "my_card_logo.png",
                    "thermal_color": "Black"
                },
                "signature": {
                    "name": "my_signature.png"
                },
                "carrier_return_window": {
                    "name": "my_return_address_image.png"
                }
            }
        }
    },
    "card_product_token": "my_card_product_02",
    "card_allocation": 3,
    "user_association": {
        "single_inventory_user": false
    },
    "name_line_1_numeric_postfix": true,
    "expiration_offset": {
        "unit": "YEARS",
        "value": 10
    },
    "created_time": "2018-03-06T00:06:34Z"
}
{
    "api": "bulkissuances",
    "endpoint": "/bulkissuances",
    "method": "post",
    "cp_id": 1,
    "bc_id": 1
}

Is this helpful?

Retrieve bulk card order

Action: GET
Endpoint: /bulkissuances/{token}

Use this endpoint to retrieve a specific bulk card order.

URL path parameters

Fields Description

token

string, required

Identifies the bulk card order to retrieve.

Allowable Values: Existing bulk card order token.

Send a GET request to /bulkissuances to retrieve bulk card order tokens.

Sample response body

The existence of the name_line1_start_index, name_line1_end_index, and card_fulfillment_time fields at the end of the following sample response indicate that the bulk card order has been processed. The existence of the provider_ship_date, provider_shipping_method, and provider_tracking_number fields indicate that it has also been shipped. Compare this response to the response from when the order was created in the Create bulk card order section.

Note
The provider_tracking_number field is populated only if your fulfillment provider is Arroweye Solutions.

You can use the name_line1_start_index and name_line1_end_index fields to identify the cards and users associated with the order. In this case, because the starting index is "1" and the ending index is "3", the card tokens are "card-1", "card-2", and "card-3", and the user tokens are "user-1", "user-2", and "user-3". See Create bulk card order for more information about the automatic generation and naming of cards and users.

{
    "token": "bulk_06_token",
    "expedite": false,
    "fulfillment": {
        "shipping": {
            "method": "USPS_REGULAR",
            "return_address": {
                "first_name": "Shipping",
                "last_name": "R_US",
                "address1": "1222 Blake Street",
                "city": "Berkeley",
                "state": "CA",
                "postal_code": "94702",
                "country": "USA",
                "phone": "510-222-2222"
            },
            "recipient_address": {
                "first_name": "Saki",
                "last_name": "Dogger",
                "address1": "1255 Lake Street",
                "city": "Oakland",
                "state": "CA",
                "postal_code": "94611",
                "country": "USA",
                "phone": "510-333-3333"
            }
        },
        "card_personalization": {
            "text": {
                "name_line_1": {
                    "value": "Saki Dogger"
                },
                "name_line_2": {
                    "value": "Chicken Tooth Music"
                }
            },
            "carrier": {
                "name": "my_carrier_logo.png",
                "message_line": "my message"
                 },
            "images": {
                "card": {
                    "name": "my_card_logo.png",
                    "thermal_color": "Black"
                },
                "signature": {
                    "name": "my_signature.png"
                },
                "carrier_return_window": {
                    "name": "my_return_address_image.png"
                }
            }
        }
    },
    "card_product_token": "my_card_product_02",
    "card_allocation": 3,
    "user_association": {
        "single_inventory_user": false
    },
    "name_line_1_numeric_postfix": true,
    "expiration_offset": {
        "unit": "YEARS",
        "value": 10
    },
    "created_time": "2018-03-06T00:06:34Z",
    "name_line1_start_index": 1,
    "name_line1_end_index": 3,
    "card_fulfillment_time": "2018-03-07T23:59:44Z",
    "provider_ship_date": "2018-03-08T00:00:00Z",
    "provider_shipping_method": "US_Postal_Service",
    "provider_tracking_number": "982247"
}
{
    "api": "bulkissuances",
    "endpoint": "/bulkissuances/{token}",
    "method": "get",
    "cp_id": 1,
    "bc_id": 1
}

Is this helpful?

List bulk card orders

Action: GET
Endpoint: /bulkissuances

Use this endpoint to list existing bulk card orders.

This endpoint supports pagination and sorting.

Sample response body

{
  "count": 1,
  "start_index": 0,
  "end_index": 0,
  "is_more": true,
  "data": [
    {
        "token": "bulk_06_token",
        "expedite": false,
        "fulfillment": {
            "shipping": {
                "method": "USPS_REGULAR",
                "return_address": {
                    "first_name": "Shipping",
                    "last_name": "R_US",
                    "address1": "1222 Blake Street",
                    "city": "Berkeley",
                    "state": "CA",
                    "postal_code": "94702",
                    "country": "USA",
                    "phone": "510-222-2222"
                },
                "recipient_address": {
                    "first_name": "Saki",
                    "last_name": "Dogger",
                    "address1": "1255 Lake Street",
                    "city": "Oakland",
                    "state": "CA",
                    "postal_code": "94611",
                    "country": "USA",
                    "phone": "510-333-3333"
                }
            },
            "card_personalization": {
                "text": {
                    "name_line_1": {
                        "value": "Saki Dogger"
                    },
                    "name_line_2": {
                        "value": "Chicken Tooth Music"
                    }
                },
                "carrier": {
                    "name": "my_carrier_logo.png",
                    "message_line": "my message"
                },
                "images": {
                    "card": {
                        "name": "my_card_logo.png",
                        "thermal_color": "Black"
                    },
                    "signature": {
                        "name": "my_signature.png"
                    },
                    "carrier_return_window": {
                        "name": "my_return_address_image.png"
                    }
                }
            }
        },
        "card_product_token": "my_card_product_02",
        "card_allocation": 3,
        "user_association": {
            "single_inventory_user": false
        },
        "name_line_1_numeric_postfix": true,
        "expiration_offset": {
            "unit": "YEARS",
            "value": 10
        },
        "created_time": "2018-03-06T00:06:34Z",
        "name_line1_start_index": 1,
        "name_line1_end_index": 3,
        "card_fulfillment_time": "2018-03-07T23:59:44Z",
        "provider_ship_date": "2018-03-08T00:00:00Z",
        "provider_shipping_method": "US_Postal_Service",
        "provider_tracking_number": "982247"
    }
  ]
}
{
    "api": "bulkissuances",
    "endpoint": "/bulkissuances",
    "method": "get",
    "cp_id": 1,
    "bc_id": 1
}

Is this helpful?

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.