Print Physical Cards in Bulk

1. A Highnote account
2. An API key or the API Explorer
3. A virtual card

When a group order is first created, it has a status of NEW.

Group physical card orders are used to request an order for several physical cards at once. Group physical card orders are:

• Packaged individually in a card carrier and shipped together in a single shipment
• Shipped to one location

Some use cases for group orders include prepaid cards, preprinted physical cards, and fleet cards you want to distribute in bulk.

The order lifecycle for group physical card orders is as follows:

1. Create a group order
2. Add payment cards to the group order
3. Complete the order and send it to the vendor for printing

Highnote recommends that you use this mutation when creating group physical card order as it requires a response token from the validateAddress mutation. It does not accept the raw address itself (validated or not), nor does it perform a regular expression check to validate address format.

Use the following mutation to create a group physical card order with the response token from the validateAddress mutation.

1. Call validateAddress to check if the shipping address is valid.
2. Copy the response token representing the validated address.
3. Call createPhysicalCardGroupOrderWithValidatedAddress with the response token.

Note: For individual orders using a validated address token, see Print Physical Cards.

This mutation lets you use a validateAddress token or the validated address itself. For best results, Highnote recommends that you use the response token.

Use the following mutation to create a group physical card order.

1. Call validateAddress to check if the shipping address is valid.
2. Copy the response token representing the validated address or the address that you validated.
3. Call createPhysicalCardGroupOrder with either the token or the address.

Note: For individual card orders using a validated address token or raw validated address, see Print Physical Cards.

Note: The maximum number of cards you may add to a single group order is 500.

After creating a group order, you can add payment cards to it. Use the PhysicalCardGroupOrder.id field in the createPhysicalCardGroupOrder response payload to ensure you add payment cards to the correct group order.

Refer to the following guidelines when adding payment cards to a group order:

• You may specify card personalization values or leave the payment cards blank with no personalization
• If your card mailer includes address information for each card, you can specify addresses for each mailer when adding cards to the group order

You can complete the order after adding payment cards to your group order. Once a group order is completed, Highnote sends the group order to your chosen card printer and notifies you of the shipping status.

The cards will be packed in individual envelopes with card carriers and sent to the destination set on the group order in one shipment. At this point, the group order will have a SENT_TO_PRINTER status.

Use the following mutation to completed a group order:

You can cancel a payment card's fulfillment to remove the physical card from a group order if the order status is still in the NEW state. Once the order status has transitioned from a NEW state, you can't remove a card from a group order.

Use the following mutation to remove a payment card from a group order:

Note: If you need to edit group order attributes such as shipping address, you will need to create a new group order.

Canceling a group order cancels the entire group order, including the fulfillment of all payment cards associated with it. Group orders can only be canceled in the NEW state.

Use the following mutation to cancel a group order:

Use the following query to find group orders:

Use the following query to find individual payment cards in a group order:

You can use the Highnote API to search for group card orders for status tracking or display order history on your website or application. You can narrow search results using filters.

The following sections provide an overview of searching for group card orders. For information on individual card orders, see Print Physical Cards.

Group card order filters allow you to narrow search results based on information related to group card orders. These filters include the following:

The following query is an example search query that returns group card orders for an organization, filtered using group card order filters:

You can simulate group order fulfillment in the test environment without actually shipping cards. This is useful for simulating group order statuses and notifications.

You can use the mutations provided in this guide to create and complete a group order. A completed order will have a status of PENDING.

Use the following mutation to transition the group order to SENT_TO_PRINTER status:

Once the group order has been SENT_TO_PRINTER, you can change the status to APPROVED using the following mutation:

Note: For an overview of group order shipping methods, see Shipping Methods.

After a group order is approved, you can use the following mutation to transition to the SHIPPED status. The shipping method and tracking number (if available) will be returned in the response payload:

To design your system to handle failed Group Order shipments, you can simulate a status of SHIP_FAILED.