Marqeta.com
Support
/
15 minute read
January 15, 2021

Bulk Card Orders

Use the

/bulkissuances
endpoint to order physical payment cards in bulk.

For more information on cards, card products, and bulk card ordering, see About Cards.

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:

  • card

  • bulkissuance

  • 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 physical cards in bulk. A new bulk card order creates new cards or users, generally within about a day.

Before creating a bulk card order, set the

config.fulfillment.bulk_ship
field of the associated card product to
true
.

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
. Both the cards and their 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
.

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 of the order by your card fulfillment provider.

This expedited service is available for cards fulfilled by Perfect Plastic Printing, IDEMIA, and Arroweye Solutions.

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 2020 and

    value = 1
    , the cards expire on the last day of Jan 2021.

  • 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 2020 and

    value = 1
    , the cards expire on the last day of Feb 2020.

  • 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
Conditionally required

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
Fields Description

card_personalization

object
Required

Allows personalized attributes to be added to the card.

Allowable Values:

A valid

card_personalization
object

shipping

object
Optional

Specifies shipping details for the bulk card order.

Allowable Values:

A valid

shipping
object

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
Conditionally required

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:

Existing

fulfillment.shipping.recipient_address
object.

method

string
Optional

Specifies the shipping service.

Allowable Values:

These allowed values specify shipping services and providers offered by your card fulfillment provider.

Perfect Plastic Printing, IDEMIA, and Arroweye Solutions:

These generic options specify shipping companies and services available from the card provider. For details on the specific shipping companies and services offered by the card providers, contact your Marqeta representative.

  • LOCAL_MAIL
    (not available for bulk orders, tracking not included)

  • GROUND
    (bulk orders only, tracking included)

  • TWO_DAY
    (tracking included)

  • OVERNIGHT
    (tracking included)

  • INTERNATIONAL
    (tracking included)

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:

40 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:

The short English name. For example, for Spain, use the short English name "Spain".

The ISO maintains the full list of country codes.

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
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:

A valid

text
object.

carrier

object
Optional

Specifies attributes of the card carrier.

Allowable Values:

A valid

carrier
object.

images

object
Optional

Specifies personalized images that appear on the card. Also specifies attributes of the card carrier, if your fulfillment provider is Perfect Plastic Printing or IDEMIA.

Allowable Values:

A valid

images
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.

Allowable Values:

signature.name

string
Optional

Specifies a PNG image of the cardholder’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 cardholders.

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
Copied

Is this helpful?

Yes
No
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.

Copied

Is this helpful?

Yes
No

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 inclusion of the

name_line1_start_index
,
name_line1_end_index
, and
card_fulfillment_time
fields in the response, as at the end of the following sample response, indicates that the bulk card order has been processed. The inclusion of the
provider_ship_date
,
provider_shipping_method
, and
provider_tracking_number
fields indicates that the order has 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.

Copied

Is this helpful?

Yes
No

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
Copied

Is this helpful?

Yes
No

Feedback on this page?

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