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 appropriate card objects. Values for the card token fields are generated in the format "card-numericPostfix", where numericPostfix is a number that is incremented by 1 as each card is generated (for example, "card-1", "card-2", "card-3", etc.). The numericPostfix for subsequent bulk orders starts where the previous ended, +1.

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: Placing a bulk order does not immediately create cards or users. This action is performed later at an appropriate time. After the cards have processed, you can ascertain the range of the numericPostfix by retrieving the bulk order and examining the name_line1_start_index and name_line1_end_index fields. These fields delimit the range of numericPostfix values used in your order.

Body field details (Basic information)

Name Type Required? Description Allowable Values
token string No 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.
36 char max
card_product_token string Yes Specifies the card product from which to create your cards. Existing card product token.

Issue a GET to /cardproducts to retrieve card product tokens.
card_allocation integer Yes The number of cards in the order. 0–500 per day by default
user_association object No Associates each card with a user.
name_line_1_numeric_postfix boolean No 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. true | false

Default: false
fulfillment object Yes Specifies certain physical characteristics of a card and bulk shipment information.
expedite boolean No Set to true to request expedited processing and shipping of the order. Expedited orders ignore the setting of thefulfillment.shipping.method field and always ship by FedEx Priority mail.

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

Note: Contact Marqeta Customer Success for information regarding the cost of expedited service.
true | false;

Default: false
expiration_offset object No Specifies the length of time for which the cards are valid. In other words, cards expires 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.

The expiration_offset object

Name Type Required? Description Allowable Values
unit string No Specifies the units for the value field. YEARS | MONTHS | DAYS | HOURS | MINUTES | SECONDS

Default: YEARS
value integer No 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.
Any positive integer

Default: 4

The user_association object

Name Type Required? Description Allowable Values
single_inventory_user boolean No 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. true | false

Default: false
single_inventory_user_token string No 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. 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

Name Type Required? Description Allowable Values
return_address object No Address to which the bulk card order will be returned if shipping fails.
recipient_address object Conditional 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 zip fields populated. The country field defaults to USA if unpopulated.
method string No Specifies the shipping company and shipping service level.

This field is ignored if your fulfillment provider is either Perfect Plastic Printing or Oberthur Technologies and the expedite field is set to true. In this case, the shipping method is implicitly FEDEX_EXPEDITED.
Values allowed depend on your fulfillment provider.

Perfect Plastic Printing and Oberthur Technologies:
USPS_REGULAR | FEDEX_EXPEDITED

Arroweye Solutions:
UPS_REGULAR | UPS_EXPEDITED | USPS_REGULAR | USPS_EXPEDITED
care_of_line string No 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.
255 char max

The fulfillment.shipping.return_address & recipient_address objects

Name Type Required? Description Allowable Values
address1 string No Number and street. 50 char max
address2 string No Additional address information. 50 char max
city string No City. 50 char max
state string No State. 50 char max
zip string No ZIP code. 50 char max
country string No Country. 40 char max
phone string No Telephone number. 50 char max
first_name string No First Name. 50 char max
middle_name string No Middle Name. 50 char max
last_name string No Last Name. 50 char max

The fulfillment.card_personalization object

Note: You must make prior arrangements with Marqeta to make use of card personalization.

Name Type Required? Description
text object No Specifies personalized text that appears on the card.
carrier object No Specifies attributes of the card carrier (if your fulfillment provider is Arroweye Solutions).
images object No Specifies personalized images that appear on the card. Also specifies attributes of the card carrier (if your fulfillment provider is Perfect Plastic Printing or Oberthur Technologies).

The fulfillment.card_personalization.text object

Name Type Required? Description Allowable Values
name_line_1.value string Yes First line of personalized text printed on the card. 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 No Second line of personalized text printed on the card. 21 char max

Strings longer than the character limit are truncated.

The fulfillment.card_personalization.carrier object

Note: Use this carrier object if your fulfillment provider is Arroweye Solutions.

Name Type Required? Description Allowable Values
template_id string No Specifies the card carrier template to use. A card carrier template ID.
logo_file string No Specifies an image to display on the card carrier. 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 No Specifies a thumbnail-sized rendering of the image specified in the logo_file field. Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
message_file string No Specifies a text file containing a custom message to print on the card carrier. Contains the name of the text file and must match the name of the file you send to your fulfillment provider.

The fulfillment.card_personalization.images object

Name Type Required? Description Allowable Values
card object No Specifies personalized images that appear on the card.
carrier object No Specifies personalized images and text that appear on the card carrier (if your fulfillment provider is Perfect Plastic Printing or Oberthur Technologies).
signature.name string No Specifies a PNG image of the card holder's signature. 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 No Specifies a PNG image to display in the return-address window of envelopes used for sending cards to card holders. 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

Name Type Required? Description Allowable Values
name string No Specifies a PNG image to display on the card. 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 No Specifies the color of the image displayed on the card. Contains the name of the color and must match one of the provider's predefined colors.

The fulfillment.card_personalization.images.carrier object

Note: Use this carrier object if your fulfillment provider is Perfect Plastic Printing or Oberthur Technologies.

Name Type Required? Description Allowable Values
name string No Specifies a PNG image to display on the card carrier. Contains the name of the image file and must match the file you send to your fulfillment provider.

Must end in .png.
message_1 string No Specifies a custom message that appears on the card carrier. 60 char max

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",
"zip": "94702",
"country": "USA",
"phone": "510-222-2222",
"first_name": "Shipping",
"last_name": "R_US"
},
"recipient_address": {
"address1": "1255 Lake Street",
"city": "Oakland",
"state": "CA",
"zip": "94611",
"country": "USA",
"phone": "510-333-3333",
"first_name": "Saki",
"last_name": "Dogger"
}
},
"card_personalization": {
"text": {
"name_line_1": {
"value": "my line 1 text"
},
"name_line_2": {
"value": "my line 2 text"
}
},
"images": {
"card": {
"name": "my_card_logo.png",
"thermal_color": "Black"
},
"carrier": {
"name": "my_carrier_logo.png",
"message_1": "my message"
},
"signature": {
"name": "my_signature.png"
},
"carrier_return_window": {
"name": "my_return_address_image.png"
}
}
}
}
}

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",
"zip": "94702",
"country": "USA",
"phone": "510-222-2222"
},
"recipient_address": {
"first_name": "Saki",
"last_name": "Dogger",
"address1": "1255 Lake Street",
"city": "Oakland",
"state": "CA",
"zip": "94611",
"country": "USA",
"phone": "510-333-3333"
}
},
"card_personalization": {
"text": {
"name_line_1": {
"value": "my line 1 text"
},
"name_line_2": {
"value": "my line 2 text"
}
},
"images": {
"card": {
"name": "my_card_logo.png",
"thermal_color": "Black"
},
"carrier": {
"name": "my_carrier_logo.png",
"message_1": "my message"
},
"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"
}


Retrieve bulk card order

Action: GET
Endpoint: /bulkissuances/{token}

Use this endpoint to retrieve a specific bulk card order.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the bulk card order to retrieve. Existing bulk card order token.

Issue a GET 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",
"zip": "94702",
"country": "USA",
"phone": "510-222-2222"
},
"recipient_address": {
"first_name": "Saki",
"last_name": "Dogger",
"address1": "1255 Lake Street",
"city": "Oakland",
"state": "CA",
"zip": "94611",
"country": "USA",
"phone": "510-333-3333"
}
},
"card_personalization": {
"text": {
"name_line_1": {
"value": "my line 1 text"
},
"name_line_2": {
"value": "my line 2 text"
}
},
"images": {
"card": {
"name": "my_card_logo.png",
"thermal_color": "Black"
},
"carrier": {
"name": "my_carrier_logo.png",
"message_1": "my message"
},
"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"
}


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",
"zip": "94702",
"country": "USA",
"phone": "510-222-2222"
},
"recipient_address": {
"first_name": "Saki",
"last_name": "Dogger",
"address1": "1255 Lake Street",
"city": "Oakland",
"state": "CA",
"zip": "94611",
"country": "USA",
"phone": "510-333-3333"
}
},
"card_personalization": {
"text": {
"name_line_1": {
"value": "my line 1 text"
},
"name_line_2": {
"value": "my line 2 text"
}
},
"images": {
"card": {
"name": "my_card_logo.png",
"thermal_color": "Black"
},
"carrier": {
"name": "my_carrier_logo.png",
"message_1": "my message"
},
"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"
}
]
}