Create bulk card order

Action: POST
Endpoint: /bulkissuances

To create a bulk card order, send a POST request to the /bulkissuances endpoint and include the order details in JSON format in the body of the request. When you create any Marqeta resource, the system associates a token for referencing that resource. You can create your own token using any alpha-numeric characters, 36 chars max. If you do not include a token value, one is generated automatically.

Note: In order to create a bulk card order, the associated cardproduct's config.fulfillment.bulk_ship field must be set to true.

When you create a bulk card order, you must choose to 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 same-day processing and shipping of the cards.

Note: Contact Marqeta Customer Success for information regarding the cost of using this expedited service. This option is available only for cards that are fulfilled by Perfect Plastic Printing.
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) for which cards of this cardproduct type are valid. In other words, cards expire "unit x value" 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 Feb 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 service level. Values allowed depend on your fulfillment provider.

Perfect Plastic Printing:
USPS_REGULAR | FEDEX_EXPEDITED

Arroweye Solutions:
USPS_REGULAR | UPS_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

Name Type Required? Description
text object No This field's value is a Map object that contains an array of string-Map pairs. Each of the inner Map objects contains a field named value that takes a personalized string that will be printed on the card. The exact syntax is flexible but should look similar to this:

"text": {
   "name_line_1": {
     "value": "my_personalized_text_printed_on_card"
   },
   "name_line_2": {
     "value": "more_personalized_text_printed_on_card"
   },
   "custom_field_10": {
     "value": "and_more_personalized_text_printed_on_card"
   },
   "custom_field_11": {
     "value": "and_yet_more_personalized_text_printed_on_card"
    }
}

The name_line_1 and name_line_2 field names are literal. Do not change their spelling. The custom_field_10 and custom_field_11 field names are descriptive. You can substitute any names you like for these field names. You can also include any number of custom field names.
images object No Defines the images that appear on the card and card carrier.

The fulfillment.card_personalization.images object

Note: You must make prior arrangements with Marqeta to make use of this functionality.

Name Type Required? Description
card.name string No Specifies the image displayed on the card. This field contains the name of the image file and must match the file you send to your fulfillment provider.

The structure within the card_personalization object should look as follows, where my_card_image.png is the name of your image file:

 "images": {
     "card": {
         "name": "my_card_image.png"
      }
  }
card.thermal_color string No Specifies the color of the image displayed on the card. This field contains the name of the color, which must match one of the provider's predefined colors. Default: UG_BLACK.

If no image is provided, the color will be ignored.

The structure within the card_personalization object should look as follows, where my_card_image.png is the name of your image file:

 "images": {
     "card": {
         "name": "my_card_image.png"
         "thermal_color": "UG_BLACK"
      }
  }
carrier.name string No Specifies the image displayed on the card carrier. This field contains the name of the image file and must match the file you send to your fulfillment provider.

The structure within the card_personalization object should look as follows, where my_carrier_image.png is the name of your image file:

 "images": {
     "carrier": {
         "name": "my_carrier_image.png"
      }
  }
carrier.message_1 string No Specifies the custom message that appears on the card carrier. 60 char max.
carrier_return_window.name string No Specifies the image displayed in the return-address window of envelopes used for sending cards to card holders. This field contains the name of the image file and must match the file you send to your fulfillment provider.

The structure within the card_personalization object should look as follows, where my_return_address.png is the name of your image file:

 "images": {
     "carrier_return_window": {
         "name": "my_return_address.png"
      }
  }

Sample request body

{
"token": "bulk_04_token",
"card_product_token": "blue_cardproduct",
"card_allocation": 3,
"user_association": {
"single_inventory_user": false
},
"name_line_1_numeric_postfix": true,
"fulfillment": {
"shipping": {
"method": "UPS_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": "Emp account"
}
}
}
}
}

Sample response body

{
"token": "bulk_04_token",
"expedite": false,
"fulfillment": {
"shipping": {
"first_name": "Shipping",
"last_name": "R_US",
"method": "UPS_REGULAR",
"return_address": {
"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": "Emp account"
}
}
}
},
"card_product_token": "blue_cardproduct",
"card_allocation": 3,
"user_association": {
"single_inventory_user": false
},
"name_line_1_numeric_postfix": true,
"created_time": "2016-09-09T19:22:37Z"
}


Retrieve bulk card order

Action: GET
Endpoint: /bulkissuances/{token}

To retrieve a specific bulk card order, issue a GET request to the /bulkissuances/{token} endpoint and include the token path parameter to specify the bulk card order to return.

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 fields at the end of this sample response indicate that the bulk card order has been processed and sent for fulfillment (compare to the response when the order was created in the "Create Bulk Card Order" section). Note that the name_line1_start_index and name_line1_end_index fields enble you to identify the cards and users associated with the order. In this case, the card tokens are "card-1", "card-2", and "card-3", and the user tokens are "user-1", "user-2", and "user-3".

{
"token": "bulk_04_token",
"expedite": false,
"fulfillment": {
"shipping": {

"method": "UPS_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": "Emp account"
}
}
}
},
"card_product_token": "blue_cardproduct",
"card_allocation": 3,
"user_association": {
"single_inventory_user": false
},
"name_line_1_numeric_postfix": true,
"cards_processed": 3,
"created_time": "2016-09-09T19:22:37Z",
"name_line1_start_index": 1,
"name_line1_end_index": 3,
"card_fulfillment_time": "2016-09-10T23:59:44Z"
}


List bulk card orders

Action: GET
Endpoint: /bulkissuances

To list existing bulk card orders, issue a GET request to the /bulkissuances endpoint.

This endpoint supports pagination and sorting.

Sample response body

{
"count": 1,
"start_index": 0,
"end_index": 0,
"is_more": true,
"data": [
{
"token": "bulk_04_token",
"expedite": false,
"fulfillment": {
"shipping": {
"method": "UPS_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": "Emp account"
}
}
}
},
"card_product_token": "blue_cardproduct",
"card_allocation": 3,
"user_association": {
"single_inventory_user": false
},
"name_line_1_numeric_postfix": true,
"cards_processed": 3,
"created_time": "2016-09-09T19:22:37Z",
"name_line1_start_index": 1,
"name_line1_end_index": 3,
"card_fulfillment_time": "2016-09-10T23:59:44Z"
}
]
}