Print Physical Cards in Bulk
Overview
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.
Prerequisites
- A Highnote account
- An API key or the API Explorer
- A virtual card
Create group physical card order
note
When a group order is first created, it has a status of NEW.
The order lifecycle for group physical card orders is as follows:
- Create a group order (ideally with an token).
- Add payment cards to the group order.
- Complete the order and send it to the vendor for printing.
Create group physical card order with token
tip
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.
- Call
validateAddressto check if the shipping address is valid. - Copy the response token representing the validated address.
- Call
createPhysicalCardGroupOrderWithValidatedAddresswith the response token.
For individual orders using a validated address token, see Print Physical Cards.
createPhysicalCardGroupOrderWithValidatedAddressToken
Query
mutation createPhysicalCardGroupOrderWithValidatedAddressToken(
$input: CreatePhysicalCardGroupOrderWithValidatedAddressTokenInput!
) {
createPhysicalCardGroupOrderWithValidatedAddressToken(input: $input) {
__typename
... on PhysicalCardGroupOrder {
__typename
id
orderState {
status
}
paymentCardShipment {
courier {
method
}
deliveryDetails {
address {
streetAddress
extendedAddress
locality
postalCode
region
countryCodeAlpha3
}
companyName
name {
givenName
familyName
}
validatedAddress {
id
labels
provided {
streetAddress
extendedAddress
locality
postalCode
region
countryCodeAlpha3
}
}
}
}
createdAt
updatedAt
}
... on UserError {
errors {
errorPath
code
}
}
}
}
Variables
{ "input": { "idempotencyKey": "IDEMPOTENCY_KEY", "cardProductId": "CARD_PRODUCT_ID", "courier": { "method": "USPS_GROUND", "signatureRequiredOnDelivery": false }, "deliveryDetails": { "name": { "givenName": "John", "familyName": "Doe" }, "validatedAddressId": "VALIDATED_ADDRESS_ID" } } }
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
"data": {
"createPhysicalCardGroupOrderWithValidatedAddressToken": {
"__typename": "PhysicalCardGroupOrder",
"id": "PHYSICAL_CARD_GROUP_ORDER_ID",
"orderState": {
"status": "NEW"
},
"paymentCardShipment": {
"courier": {
"method": "USPS_GROUND"
},
"deliveryDetails": {
"address": {
"streetAddress": "24 WILLIE MAYS PLZ",
"extendedAddress": "",
"locality": "SAN FRANCISCO",
"postalCode": "94107-2134",
"region": "CA",
"countryCodeAlpha3": "USA"
},
"companyName": null,
"name": {
"givenName": "John",
"familyName": "Doe"
},
"validatedAddress": {
"id": "ADDRESS_TOKEN_ID",
"labels": [
"BUSINESS"
],
"provided": {
"streetAddress": "24 Willie Mays Plz",
"extendedAddress": "",
"locality": "San Francisco",
"postalCode": "94107-2134",
"region": "CA",
"countryCodeAlpha3": "USA"
}
}
}
},
"createdAt": "2024-06-18T19:47:57.062Z",
"updatedAt": "2024-06-18T19:47:57.062Z"
}
},
"extensions": {
"requestId": "REQUEST_ID",
"rateLimit": {
"cost": 18,
"limit": 60060,
"remaining": 60040
}
}
}
Create group physical card order with token or address
tip
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.
- Call
validateAddressto check if the shipping address is valid. - Copy the response token representing the validated address or the address that you validated.
- Call
createPhysicalCardGroupOrderwith either the token or the address.
For individual card orders using a validated address token or raw validated address, see Print Physical Cards.
CreatePhysicalCardGroupOrder
Query
mutation CreatePhysicalCardGroupOrder(
$input: CreatePhysicalCardGroupOrderInput!
) {
createPhysicalCardGroupOrder(input: $input) {
__typename
... on PhysicalCardGroupOrder {
id
cardProductId
cardCount
paymentCardShipment {
courier {
method
signatureRequiredOnDelivery
tracking {
trackingNumber
actualShipDateLocal
}
}
requestedShipDate
deliveryDetails {
name {
givenName
middleName
familyName
suffix
title
}
companyName
address {
streetAddress
extendedAddress
postalCode
region
locality
countryCodeAlpha3
}
}
senderDetails {
name {
givenName
middleName
familyName
suffix
title
}
companyName
address {
streetAddress
extendedAddress
postalCode
region
locality
countryCodeAlpha3
}
}
}
orderState {
status
}
stateHistory {
previousStatus
newStatus
createdAt
}
createdAt
updatedAt
}
... on UserError {
errors {
errorPath
code
description
}
}
... on AccessDeniedError {
message
}
}
}
Variables
{ "input": { "cardProductId": "CARD_PRODUCT_ID", "deliveryDetails": { "name": { "givenName": "Homer", "middleName": "Jay", "familyName": "Simpson", "suffix": "Sr", "title": "Mr" }, "companyName": "Highnote", "address": { "streetAddress": "123 Main St", "extendedAddress": "APT 2", "postalCode": "60654", "locality": "Chicago", "region": "IL", "countryCodeAlpha3": "USA" } }, "courier": { "method": "USPS_PRIORITY", "signatureRequiredOnDelivery": false }, "requestedShipDate": "2022-08-03" } }
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
"data": {
"createPhysicalCardGroupOrder": {
"__typename": "PhysicalCardGroupOrder",
"id": "CARD_ORDER_ID",
"cardProductId": "CARD_PRODUCT_ID",
"cardCount": 0,
"paymentCardShipment": {
"courier": {
"method": "USPS_PRIORITY",
"signatureRequiredOnDelivery": false,
"tracking": null
},
"requestedShipDate": "2022-08-03",
"deliveryDetails": {
"name": {
"givenName": "Homer",
"middleName": "Jay",
"familyName": "Simpson",
"suffix": "Sr",
"title": "Mr"
},
"companyName": "Highnote",
"address": {
"streetAddress": "123 Main St",
"extendedAddress": "APT 2",
"postalCode": "60654",
"locality": "Chicago",
"region": "IL",
"countryCodeAlpha3": "USA"
}
},
"senderDetails": {
"name": {
"givenName": "James",
"middleName": "Jay",
"familyName": "Smith",
"suffix": "Jr",
"title": "Mr"
},
"companyName": "Givecard",
"address": {
"streetAddress": "888 Main St",
"extendedAddress": "APT 5",
"postalCode": "95121",
"locality": "San Jose",
"region": "CA",
"countryCodeAlpha3": "USA"
}
}
},
"orderState": {
"status": "NEW"
},
"stateHistory": [
{
"previousStatus": null,
"newStatus": "NEW",
"createdAt": "2022-08-03T20:16:40.580Z"
}
],
"createdAt": "2022-08-03T20:16:40.579Z",
"updatedAt": "2022-08-03T20:16:40.586Z"
}
},
"extensions": {
"requestId": "REQUEST_ID"
}
}
Add cards to group order
info
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
OrderPhysicalPaymentCardForGroup
Query
mutation OrderPhysicalPaymentCardForGroup(
$input: OrderPhysicalPaymentCardForGroupInput!
) {
orderPhysicalPaymentCardForGroup(input: $input) {
__typename
... on PhysicalPaymentCardOrder {
id
paymentCardShipment {
courier {
method
signatureRequiredOnDelivery
tracking {
trackingNumber
actualShipDateLocal
}
}
requestedShipDate
deliveryDetails {
name {
givenName
middleName
familyName
suffix
title
}
companyName
address {
streetAddress
extendedAddress
postalCode
region
locality
countryCodeAlpha3
}
}
senderDetails {
name {
givenName
middleName
familyName
suffix
title
}
companyName
address {
streetAddress
extendedAddress
postalCode
region
locality
countryCodeAlpha3
}
}
}
orderState {
status
}
cardPersonalization {
textLines {
line1
line2
}
}
stateHistory {
previousStatus
newStatus
createdAt
}
paymentCard {
id
bin
last4
expirationDate
expirationMonth
expirationYear
network
cardProduct {
id
}
cardProductApplication {
... on Node {
id
}
}
status
}
groupOrder {
id
cardCount
}
createdAt
updatedAt
}
... on UserError {
errors {
errorPath
code
description
}
}
... on AccessDeniedError {
message
}
}
}
Variables
{ "input": { "paymentCardId": "PAYMENT_CARD_ID", "groupOrderId": "CARD_ORDER_ID", "deliveryDetails": { "name": { "givenName": "Homer", "middleName": "Jay", "familyName": "Simpson", "suffix": "Sr", "title": "Mr" }, "companyName": "Highnote", "address": { "streetAddress": "123 Main St", "extendedAddress": "APT 2", "postalCode": "60654", "locality": "Chicago", "region": "IL", "countryCodeAlpha3": "USA" } }, "cardPersonalization": { "textLines": { "line1": "HOMER J SIMPSON", "line2": "line 2" } } } }
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
"data": {
"orderPhysicalPaymentCardForGroup": {
"__typename": "PhysicalPaymentCardOrder",
"id": "FULFILLMENT_ID",
"groupOrderId": "CARD_ORDER_ID",
"paymentCardShipment": {
"courier": {
"method": "USPS_PRIORITY",
"signatureRequiredOnDelivery": false,
"tracking": null
},
"deliveryDetails": {
"name": {
"givenName": "Homer",
"middleName": "Jay",
"familyName": "Simpson",
"suffix": "Sr",
"title": "Mr"
},
"companyName": "Highnote",
"address": {
"streetAddress": "123 Main St",
"extendedAddress": "APT 2",
"postalCode": "60654",
"locality": "Chicago",
"region": "IL",
"countryCodeAlpha3": "USA"
}
},
"senderDetails": {
"name": {
"givenName": "James",
"middleName": "Jay",
"familyName": "Smith",
"suffix": "Jr",
"title": "Mr"
},
"companyName": "CherityCard",
"address": {
"streetAddress": "888 Main St",
"extendedAddress": "APT 5",
"postalCode": "95121",
"locality": "San Jose",
"region": "CA",
"countryCodeAlpha3": "USA"
}
}
},
"orderState": {
"status": "NEW"
},
"cardPersonalization": {
"textLines": {
"line1": "HOMER J SIMPSON",
"line2": "line 2"
}
},
"stateHistory": [
{
"previousStatus": null,
"newStatus": "NEW",
"createdAt": "2022-08-03T20:16:40.580Z"
}
],
"paymentCard": {
"id": "PAYMENT_CARD_ID",
"bin": "547203",
"last4": "0589",
"expirationDate": "2025-01-01T23:59:59Z",
"expirationMonth": "01",
"expirationYear": "25",
"network": "MASTERCARD",
"cardProduct": {
"id": "CARD_PRODUCT_ID"
},
"cardProductApplication": {
"id": "APPLICATION_ID"
},
"status": "ACTIVE"
},
"groupOrder": {
"id": "CARD_ORDER_ID",
"cardCount": 1
},
"createdAt": "2022-08-03T20:16:40.579Z",
"updatedAt": "2022-08-03T20:16:40.586Z"
}
}
}
Complete 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:
CompletePhysicalCardGroupOrder
Query
mutation CompletePhysicalCardGroupOrder(
$input: CompletePhysicalCardGroupOrderInput!
) {
completePhysicalCardGroupOrder(input: $input) {
__typename
... on PhysicalCardGroupOrder {
id
cardProductId
cardCount
paymentCardShipment {
courier {
method
signatureRequiredOnDelivery
tracking {
trackingNumber
actualShipDateLocal
}
}
requestedShipDate
deliveryDetails {
name {
givenName
middleName
familyName
suffix
title
}
companyName
address {
streetAddress
extendedAddress
postalCode
region
locality
countryCodeAlpha3
}
}
senderDetails {
name {
givenName
middleName
familyName
suffix
title
}
companyName
address {
streetAddress
extendedAddress
postalCode
region
locality
countryCodeAlpha3
}
}
}
orderState {
status
}
stateHistory {
previousStatus
newStatus
createdAt
}
createdAt
updatedAt
}
... on UserError {
errors {
errorPath
code
description
}
}
... on AccessDeniedError {
message
}
}
}
Variables
{ "input": { "groupOrderId": "ORDER_ID" } }
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
"data": {
"completePhysicalCardGroupOrder": {
"__typename": "PhysicalCardGroupOrder",
"id": "ORDER_ID",
"cardProductId": "CARD_PRODUCT_ID",
"cardCount": 10,
"paymentCardShipment": {
"courier": {
"method": "USPS_PRIORITY",
"signatureRequiredOnDelivery": false,
"tracking": null
},
"requestedShipDate": "2022-08-03",
"deliveryDetails": {
"name": {
"givenName": "Homer",
"middleName": "Jay",
"familyName": "Simpson",
"suffix": "Sr",
"title": "Mr"
},
"companyName": "Highnote",
"address": {
"streetAddress": "123 Main St",
"extendedAddress": "APT 2",
"postalCode": "60654",
"locality": "Chicago",
"region": "IL",
"countryCodeAlpha3": "USA"
}
},
"senderDetails": {
"name": {
"givenName": "James",
"middleName": "Jay",
"familyName": "Smith",
"suffix": "Jr",
"title": "Mr"
},
"companyName": "CherityCard",
"address": {
"streetAddress": "888 Main St",
"extendedAddress": "APT 5",
"postalCode": "95121",
"locality": "San Jose",
"region": "CA",
"countryCodeAlpha3": "USA"
}
}
},
"orderState": {
"status": "NEW"
},
"stateHistory": [
{
"previousStatus": null,
"newStatus": "NEW",
"createdAt": "2022-08-03T20:16:40.580Z"
}
],
"createdAt": "2022-08-03T20:16:40.579Z",
"updatedAt": "2022-08-03T20:16:40.586Z"
}
},
"extensions": {
"requestId": "REQUEST_ID"
}
}
Remove card from 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:
CancelPhysicalPaymentCardOrder
Query
mutation CompletePhysicalCardGroupOrder(
$input: CompletePhysicalCardGroupOrderInput!
) {
completePhysicalCardGroupOrder(input: $input) {
__typename
... on PhysicalCardGroupOrder {
id
cardProductId
cardCount
paymentCardShipment {
courier {
method
signatureRequiredOnDelivery
tracking {
trackingNumber
actualShipDateLocal
}
}
requestedShipDate
deliveryDetails {
name {
givenName
middleName
familyName
suffix
title
}
companyName
address {
streetAddress
extendedAddress
postalCode
region
locality
countryCodeAlpha3
}
}
senderDetails {
name {
givenName
middleName
familyName
suffix
title
}
companyName
address {
streetAddress
extendedAddress
postalCode
region
locality
countryCodeAlpha3
}
}
}
orderState {
status
}
stateHistory {
previousStatus
newStatus
createdAt
}
createdAt
updatedAt
}
... on UserError {
errors {
errorPath
code
description
}
}
... on AccessDeniedError {
message
}
}
}
Variables
{ "input": { "groupOrderId": "ORDER_ID" } }
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
"data": {
"completePhysicalCardGroupOrder": {
"__typename": "PhysicalCardGroupOrder",
"id": "ORDER_ID",
"cardProductId": "CARD_PRODUCT_ID",
"cardCount": 10,
"paymentCardShipment": {
"courier": {
"method": "USPS_PRIORITY",
"signatureRequiredOnDelivery": false,
"tracking": null
},
"requestedShipDate": "2022-08-03",
"deliveryDetails": {
"name": {
"givenName": "Homer",
"middleName": "Jay",
"familyName": "Simpson",
"suffix": "Sr",
"title": "Mr"
},
"companyName": "Highnote",
"address": {
"streetAddress": "123 Main St",
"extendedAddress": "APT 2",
"postalCode": "60654",
"locality": "Chicago",
"region": "IL",
"countryCodeAlpha3": "USA"
}
},
"senderDetails": {
"name": {
"givenName": "James",
"middleName": "Jay",
"familyName": "Smith",
"suffix": "Jr",
"title": "Mr"
},
"companyName": "CherityCard",
"address": {
"streetAddress": "888 Main St",
"extendedAddress": "APT 5",
"postalCode": "95121",
"locality": "San Jose",
"region": "CA",
"countryCodeAlpha3": "USA"
}
}
},
"orderState": {
"status": "NEW"
},
"stateHistory": [
{
"previousStatus": null,
"newStatus": "NEW",
"createdAt": "2022-08-03T20:16:40.580Z"
}
],
"createdAt": "2022-08-03T20:16:40.579Z",
"updatedAt": "2022-08-03T20:16:40.586Z"
}
},
"extensions": {
"requestId": "REQUEST_ID"
}
}
Cancel a group order
info
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:
CancelPhysicalCardGroupOrder
Query
mutation CancelPhysicalPaymentCardOrder(
$input: CancelPhysicalPaymentCardOrderInput!
) {
cancelPhysicalPaymentCardOrder(input: $input) {
... on PhysicalPaymentCardOrder {
orderState {
status
}
}
}
}
Variables
{ "input": { "physicalPaymentCardOrderId": "PHYSICAL_PAYMENT_CARD_ORDER_ID" } }
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
"data": {
"cancelPhysicalPaymentCardOrder": {
"orderState": {
"status": "CANCELED"
}
}
}
}
Find a group order
Use the following query to find group orders:
GetPhysicalCardGroupsForProduct
Query
query GetPhysicalCardGroupsForProduct(
$cardProductId: ID!
$firstGroupOrders: Int
) {
node(id: $cardProductId) {
... on CardProduct {
__typename
id
name
usage
groupOrders(first: $firstGroupOrders) {
pageInfo {
startCursor
endCursor
hasNextPage
hasPreviousPage
}
edges {
cursor
node {
__typename
id
cardCount
}
}
}
}
}
}
Variables
{
"cardProductId": "CARD_PRODUCT_ID",
"firstGroupOrders": 1
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
"data": {
"node": {
"__typename": "CardProduct",
"id": "CARD_PRODUCT_ID",
"name": "AP Single Use product",
"usage": "MULTI_USE",
"groupOrders": {
"pageInfo": {
"startCursor": "start-cursor",
"endCursor": "end-curso",
"hasNextPage": false,
"hasPreviousPage": false
},
"edges": [
{
"__typename": "PhysicalCardGroupOrder",
"cursor": "some-cursor",
"node": {
"id": "ORDER_ID",
"cardCount": 1
}
}
]
}
}
},
"extensions": {
"requestId": "REQUEST_ID"
}
}
Find cards in a group order
Use the following query to find individual payment cards in a group order:
FindPhysicalPaymentCardGroupOrder
Query
query FindPhysicalPaymentCardGroupOrder($id: ID!) {
node(id: $id) {
... on PhysicalCardGroupOrder {
id
cardProductId
cardCount
paymentCardShipment {
courier {
method
signatureRequiredOnDelivery
tracking {
trackingNumber
actualShipDateLocal
}
}
requestedShipDate
deliveryDetails {
name {
givenName
middleName
familyName
suffix
title
}
companyName
address {
streetAddress
extendedAddress
postalCode
region
locality
countryCodeAlpha3
}
}
senderDetails {
name {
givenName
middleName
familyName
suffix
title
}
companyName
address {
streetAddress
extendedAddress
postalCode
region
locality
countryCodeAlpha3
}
}
}
orderState {
status
}
physicalPaymentCardOrders(first: 1) {
__typename
pageInfo {
endCursor
hasNextPage
hasPreviousPage
startCursor
}
edges {
cursor
node {
id
orderState {
status
}
}
}
}
stateHistory {
previousStatus
newStatus
createdAt
}
createdAt
updatedAt
}
}
}
Variables
{
"id": "ORDER_ID"
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
"data": {
"node": {
"id": "ORDER_ID",
"cardProductId": "CARD_PRODUCT_ID",
"cardCount": 3,
"paymentCardShipment": {
"courier": {
"method": "UPS_NEXT_DAY",
"signatureRequiredOnDelivery": false,
"tracking": null
},
"requestedShipDate": "2022-08-30",
"deliveryDetails": {
"name": {
"givenName": "Homer",
"middleName": "Jay",
"familyName": "Simpson",
"suffix": "Sr",
"title": "Mr"
},
"companyName": "Highnote",
"address": {
"streetAddress": "123 Main St",
"extendedAddress": "APT 2",
"postalCode": "60654",
"locality": "Chicago",
"region": "IL",
"countryCodeAlpha3": "USA"
}
},
"senderDetails": {
"name": {
"givenName": "James",
"middleName": "Jay",
"familyName": "Smith",
"suffix": "Jr",
"title": "Mr"
},
"companyName": "CherityCard",
"address": {
"streetAddress": "888 Main St",
"extendedAddress": "APT 5",
"postalCode": "95121",
"locality": "San Jose",
"region": "CA",
"countryCodeAlpha3": "USA"
}
}
},
"orderState": {
"status": "NEW"
},
"physicalPaymentCardOrders": {
"__typename": "PhysicalPaymentCardOrderConnection",
"pageInfo": {
"endCursor": "end-cursor",
"hasNextPage": true,
"hasPreviousPage": false,
"startCursor": "start-cursor"
},
"edges": [
{
"cursor": "some-cursor",
"node": {
"id": "FULFILLMENT_ID",
"orderState": {
"status": "NEW"
}
}
}
]
},
"stateHistory": [
{
"previousStatus": null,
"newStatus": "NEW",
"createdAt": "2022-08-30T18:22:02.624Z"
}
],
"createdAt": "2022-08-30T18:22:02.624Z",
"updatedAt": "2022-08-30T18:25:56.754Z"
}
},
"extensions": {
"requestId": "REQUEST_ID"
}
}
Search group orders
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
Group card order filters allow you to narrow search results based on information related to group card orders. These filters include the following:
| Filter | Description |
|---|---|
cardProductId | Input to filter by the ID of your card product |
groupOrderId | Input to filter by the ID of the group order |
groupOrderState | Input to filter by physical card group order status |
shippingMethod | Input to filter by the shipping method of the group order |
createdAt | Input to filter by the creation date of the group order |
actualShipDateLocal | Input to filter by the actual shipping date of the group order; in YYYY-MM-DD format |
Example search query
The following query is an example search query that returns group card orders for an organization, filtered using group card order filters:
nodeOrganizationWithPhysicalPaymentCardGroupOrders
Query
query nodeOrganizationWithPhysicalPaymentCardGroupOrders(
$id: ID!
$first: Int
$after: String
$filterBy: PhysicalPaymentCardGroupOrderFilterInput
) {
node(id: $id) {
__typename
... on Organization {
id
physicalPaymentCardGroupOrders(
first: $first
after: $after
filterBy: $filterBy
) {
pageInfo {
startCursor
endCursor
hasNextPage
hasPreviousPage
}
edges {
cursor
node {
...physicalCardGroupOrder
}
}
}
}
}
}
fragment physicalCardGroupOrder on PhysicalCardGroupOrder {
__typename
id
cardProductId
cardCount
paymentCardShipment {
courier {
method
signatureRequiredOnDelivery
tracking {
trackingNumber
actualShipDateLocal
}
}
requestedShipDate
deliveryDetails {
name {
givenName
middleName
familyName
suffix
title
}
companyName
address {
streetAddress
extendedAddress
postalCode
region
locality
countryCodeAlpha3
}
}
senderDetails {
name {
givenName
middleName
familyName
suffix
title
}
companyName
address {
streetAddress
extendedAddress
postalCode
region
locality
countryCodeAlpha3
}
}
}
orderState {
status
}
stateHistory {
previousStatus
newStatus
createdAt
}
createdAt
updatedAt
}
Variables
{
"id": "ORGANIZATION_ID",
"first": 10,
"filterBy": {
"cardProductId": {
"equals": "CARD_PRODUCT_ID"
},
"groupOrderId": {
"equals": "GROUP_ORDER_ID"
},
"groupOrderState": {
"equals": "SENT_TO_PRINTER"
},
"shippingMethod": {
"equals": "USPS_GROUND"
}
}
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
"data": {
"node": {
"__typename": "Organization",
"id": "og_bs019b83eff09bseed10a6720f37682ftest",
"physicalPaymentCardGroupOrders": {
"pageInfo": {
"startCursor": "start-cursor",
"endCursor": "end-cursor",
"hasNextPage": false,
"hasPreviousPage": false
},
"edges": [
{
"cursor": "some-cursor",
"node": {
"__typename": "PhysicalCardGroupOrder",
"id": "GROUP_CARD_ORDER_ID",
"cardProductId": "CARD_PRODUCT_ID",
"cardCount": 0,
"paymentCardShipment": {
"courier": {
"method": "USPS_PRIORITY",
"signatureRequiredOnDelivery": false,
"tracking": null
},
"requestedShipDate": "2000-01-01",
"deliveryDetails": {
"name": {
"givenName": "Business User",
"middleName": "Jay",
"familyName": "BUS",
"suffix": "",
"title": ""
},
"companyName": "Highnote",
"address": {
"streetAddress": "123 Main St",
"extendedAddress": "",
"postalCode": "60654",
"region": "IL",
"locality": "Chicago",
"countryCodeAlpha3": "USA"
}
},
"senderDetails": {
"name": {
"givenName": "",
"middleName": "",
"familyName": "",
"suffix": "",
"title": ""
},
"companyName": null,
"address": {
"streetAddress": "",
"extendedAddress": "",
"postalCode": "",
"region": "",
"locality": "",
"countryCodeAlpha3": ""
}
}
},
"orderState": {
"status": "NEW"
},
"stateHistory": [
{
"previousStatus": null,
"newStatus": "NEW",
"createdAt": "2024-04-16T23:51:19.034Z"
}
],
"createdAt": "2024-04-16T23:51:19.032Z",
"updatedAt": "2024-04-16T23:51:19.122Z"
}
}
]
}
}
},
"extensions": {
"requestId": "REQUEST_ID",
"rateLimit": {
"cost": 113,
"limit": 60060,
"remaining": 59947
}
}
}
Simulate group order fulfillment
You can simulate group order fulfillment in the Test environment without actually shipping cards. This is useful for simulating group order statuses and notifications.
Send order to printer
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:
SimulatePhysicalCardGroupOrderSendToPrinter
Query
mutation CancelPhysicalCardGroupOrder(
$input: CancelPhysicalCardGroupOrderInput!
) {
cancelPhysicalCardGroupOrder(input: $input) {
__typename
... on PhysicalCardGroupOrder {
id
cardProductId
cardCount
paymentCardShipment {
courier {
method
signatureRequiredOnDelivery
tracking {
trackingNumber
actualShipDateLocal
}
}
requestedShipDate
deliveryDetails {
name {
givenName
middleName
familyName
suffix
title
}
companyName
address {
streetAddress
extendedAddress
postalCode
region
locality
countryCodeAlpha3
}
}
senderDetails {
name {
givenName
middleName
familyName
suffix
title
}
companyName
address {
streetAddress
extendedAddress
postalCode
region
locality
countryCodeAlpha3
}
}
}
orderState {
status
}
stateHistory {
previousStatus
newStatus
createdAt
}
createdAt
updatedAt
}
... on UserError {
errors {
errorPath
code
description
}
}
... on AccessDeniedError {
message
}
}
}
Variables
{ "input": { "groupOrderId": "ORDER_ID" } }
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
"data": {
"cancelPhysicalCardGroupOrder": {
"__typename": "PhysicalCardGroupOrder",
"id": "ORDER_ID",
"cardProductId": "CARD_PRODUCT_ID",
"cardCount": 10,
"paymentCardShipment": {
"courier": {
"method": "USPS_PRIORITY",
"signatureRequiredOnDelivery": false,
"tracking": null
},
"requestedShipDate": "2022-08-03",
"deliveryDetails": {
"name": {
"givenName": "Homer",
"middleName": "Jay",
"familyName": "Simpson",
"suffix": "Sr",
"title": "Mr"
},
"companyName": "Highnote",
"address": {
"streetAddress": "123 Main St",
"extendedAddress": "APT 2",
"postalCode": "60654",
"locality": "Chicago",
"region": "IL",
"countryCodeAlpha3": "USA"
}
},
"senderDetails": {
"name": {
"givenName": "James",
"middleName": "Jay",
"familyName": "Smith",
"suffix": "Jr",
"title": "Mr"
},
"companyName": "CherityCard",
"address": {
"streetAddress": "888 Main St",
"extendedAddress": "APT 5",
"postalCode": "95121",
"locality": "San Jose",
"region": "CA",
"countryCodeAlpha3": "USA"
}
}
},
"orderState": {
"status": "NEW"
},
"stateHistory": [
{
"previousStatus": null,
"newStatus": "NEW",
"createdAt": "2022-08-03T20:16:40.580Z"
}
],
"createdAt": "2022-08-03T20:16:40.579Z",
"updatedAt": "2022-08-03T20:16:40.586Z"
}
},
"extensions": {
"requestId": "REQUEST_ID"
}
}
Approve shipment
Once the group order has been SENT_TO_PRINTER, you can change the status to APPROVED using the following mutation:
SimulatePhysicalCardGroupOrderApproval
Query
mutation SimulatePhysicalCardGroupOrderSendToPrinter(
$input: SimulatePhysicalCardGroupOrderSendToPrinterInput!
) {
simulatePhysicalCardGroupOrderSendToPrinter(input: $input) {
__typename
... on PhysicalCardGroupOrder {
id
cardProductId
cardCount
paymentCardShipment {
courier {
method
signatureRequiredOnDelivery
tracking {
trackingNumber
actualShipDateLocal
}
}
requestedShipDate
deliveryDetails {
name {
givenName
middleName
familyName
suffix
title
}
companyName
address {
streetAddress
extendedAddress
postalCode
region
locality
countryCodeAlpha3
}
}
senderDetails {
name {
givenName
middleName
familyName
suffix
title
}
companyName
address {
streetAddress
extendedAddress
postalCode
region
locality
countryCodeAlpha3
}
}
}
orderState {
status
}
stateHistory {
previousStatus
newStatus
createdAt
}
createdAt
updatedAt
}
... on UserError {
errors {
errorPath
code
description
}
}
... on AccessDeniedError {
message
}
}
}
Variables
{ "input": { "groupOrderId": "ORDER_ID" } }
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
"data": {
"simulatePhysicalCardGroupOrderSendToPrinter": {
"__typename": "PhysicalCardGroupOrder",
"id": "ORDER_ID",
"cardProductId": "CARD_PRODUCT_ID",
"cardCount": 10,
"paymentCardShipment": {
"courier": {
"method": "USPS_PRIORITY",
"signatureRequiredOnDelivery": false,
"tracking": null
},
"requestedShipDate": "2022-08-03",
"deliveryDetails": {
"name": {
"givenName": "Homer",
"middleName": "Jay",
"familyName": "Simpson",
"suffix": "Sr",
"title": "Mr"
},
"companyName": "Highnote",
"address": {
"streetAddress": "123 Main St",
"extendedAddress": "APT 2",
"postalCode": "60654",
"locality": "Chicago",
"region": "IL",
"countryCodeAlpha3": "USA"
}
},
"senderDetails": {
"name": {
"givenName": "James",
"middleName": "Jay",
"familyName": "Smith",
"suffix": "Jr",
"title": "Mr"
},
"companyName": "CherityCard",
"address": {
"streetAddress": "888 Main St",
"extendedAddress": "APT 5",
"postalCode": "95121",
"locality": "San Jose",
"region": "CA",
"countryCodeAlpha3": "USA"
}
}
},
"orderState": {
"status": "SENT_TO_PRINTER"
},
"stateHistory": [
{
"previousStatus": "NEW",
"newStatus": "SENT_TO_PRINTER",
"createdAt": "2022-08-03T20:16:40.580Z"
},
{
"previousStatus": null,
"newStatus": "NEW",
"createdAt": "2022-08-03T20:16:40.580Z"
}
],
"createdAt": "2022-08-03T20:16:40.579Z",
"updatedAt": "2022-08-03T20:16:40.586Z"
}
},
"extensions": {
"requestId": "REQUEST_ID"
}
}
Ship order
info
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:
SimulatePhysicalCardGroupOrderShipped
Query
mutation SimulatePhysicalCardGroupOrderApproval(
$input: SimulatePhysicalCardGroupOrderApprovalInput!
) {
simulatePhysicalCardGroupOrderApproval(input: $input) {
__typename
... on PhysicalCardGroupOrder {
id
cardProductId
cardCount
paymentCardShipment {
courier {
method
signatureRequiredOnDelivery
tracking {
trackingNumber
actualShipDateLocal
}
}
requestedShipDate
deliveryDetails {
name {
givenName
middleName
familyName
suffix
title
}
companyName
address {
streetAddress
extendedAddress
postalCode
region
locality
countryCodeAlpha3
}
}
senderDetails {
name {
givenName
middleName
familyName
suffix
title
}
companyName
address {
streetAddress
extendedAddress
postalCode
region
locality
countryCodeAlpha3
}
}
}
orderState {
status
}
stateHistory {
previousStatus
newStatus
createdAt
}
createdAt
updatedAt
}
... on UserError {
errors {
errorPath
code
description
}
}
... on AccessDeniedError {
message
}
}
}
Variables
{ "input": { "groupOrderId": "ORDER_ID" } }
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
"data": {
"simulatePhysicalCardGroupOrderApproval": {
"__typename": "PhysicalCardGroupOrder",
"id": "ORDER_ID",
"cardProductId": "CARD_PRODUCT_ID",
"cardCount": 10,
"paymentCardShipment": {
"courier": {
"method": "USPS_PRIORITY",
"signatureRequiredOnDelivery": false,
"tracking": null
},
"requestedShipDate": "2022-08-03",
"deliveryDetails": {
"name": {
"givenName": "Homer",
"middleName": "Jay",
"familyName": "Simpson",
"suffix": "Sr",
"title": "Mr"
},
"companyName": "Highnote",
"address": {
"streetAddress": "123 Main St",
"extendedAddress": "APT 2",
"postalCode": "60654",
"locality": "Chicago",
"region": "IL",
"countryCodeAlpha3": "USA"
}
},
"senderDetails": {
"name": {
"givenName": "James",
"middleName": "Jay",
"familyName": "Smith",
"suffix": "Jr",
"title": "Mr"
},
"companyName": "CherityCard",
"address": {
"streetAddress": "888 Main St",
"extendedAddress": "APT 5",
"postalCode": "95121",
"locality": "San Jose",
"region": "CA",
"countryCodeAlpha3": "USA"
}
}
},
"orderState": {
"status": "APPROVED"
},
"stateHistory": [
{
"previousStatus": "SENT_TO_PRINTER",
"newStatus": "APPROVED",
"createdAt": "2022-08-03T20:16:40.580Z"
},
{
"previousStatus": "NEW",
"newStatus": "SENT_TO_PRINTER",
"createdAt": "2022-08-03T20:16:40.580Z"
},
{
"previousStatus": null,
"newStatus": "NEW",
"createdAt": "2022-08-03T20:16:40.580Z"
}
],
"createdAt": "2022-08-03T20:16:40.579Z",
"updatedAt": "2022-08-03T20:16:40.586Z"
}
},
"extensions": {
"requestId": "REQUEST_ID"
}
}
Fail order
To design your system to handle failed Group Order shipments, you can simulate a status of SHIP_FAILED.
SimulatePhysicalCardGroupOrderShipmentFailed
Query
mutation SimulatePhysicalCardGroupOrderShipped(
$input: SimulatePhysicalCardGroupOrderShippedInput!
) {
simulatePhysicalCardGroupOrderShipped(input: $input) {
__typename
... on PhysicalCardGroupOrder {
id
cardProductId
cardCount
paymentCardShipment {
courier {
method
signatureRequiredOnDelivery
tracking {
trackingNumber
actualShipDateLocal
}
}
requestedShipDate
deliveryDetails {
name {
givenName
middleName
familyName
suffix
title
}
companyName
address {
streetAddress
extendedAddress
postalCode
region
locality
countryCodeAlpha3
}
}
senderDetails {
name {
givenName
middleName
familyName
suffix
title
}
companyName
address {
streetAddress
extendedAddress
postalCode
region
locality
countryCodeAlpha3
}
}
}
orderState {
status
}
stateHistory {
previousStatus
newStatus
createdAt
}
createdAt
updatedAt
}
... on UserError {
errors {
errorPath
code
description
}
}
... on AccessDeniedError {
message
}
}
}
Variables
{ "input": { "groupOrderId": "ORDER_ID", "trackingNumber": "1Z1111110311111111", "actualShipDate": "2022-08-03" } }
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
"data": {
"simulatePhysicalCardGroupOrderShipped": {
"__typename": "PhysicalCardGroupOrder",
"id": "ORDER_ID",
"cardProductId": "CARD_PRODUCT_ID",
"cardCount": 10,
"paymentCardShipment": {
"courier": {
"method": "USPS_PRIORITY",
"signatureRequiredOnDelivery": false,
"tracking": {
"trackingNumber": "1Z1111110311111111",
"actualShipDateLocal": "2022-08-03"
}
},
"requestedShipDate": "2022-08-03",
"deliveryDetails": {
"name": {
"givenName": "Homer",
"middleName": "Jay",
"familyName": "Simpson",
"suffix": "Sr",
"title": "Mr"
},
"companyName": "Highnote",
"address": {
"streetAddress": "123 Main St",
"extendedAddress": "APT 2",
"postalCode": "60654",
"locality": "Chicago",
"region": "IL",
"countryCodeAlpha3": "USA"
}
},
"senderDetails": {
"name": {
"givenName": "James",
"middleName": "Jay",
"familyName": "Smith",
"suffix": "Jr",
"title": "Mr"
},
"companyName": "CherityCard",
"address": {
"streetAddress": "888 Main St",
"extendedAddress": "APT 5",
"postalCode": "95121",
"locality": "San Jose",
"region": "CA",
"countryCodeAlpha3": "USA"
}
}
},
"orderState": {
"status": "SHIPPED"
},
"stateHistory": [
{
"previousStatus": "SHIPPED",
"newStatus": "SENT_TO_PRINTER",
"createdAt": "2022-08-03T20:16:40.580Z"
},
{
"previousStatus": "SENT_TO_PRINTER",
"newStatus": "APPROVED",
"createdAt": "2022-08-03T20:16:40.580Z"
},
{
"previousStatus": "NEW",
"newStatus": "SENT_TO_PRINTER",
"createdAt": "2022-08-03T20:16:40.580Z"
},
{
"previousStatus": null,
"newStatus": "NEW",
"createdAt": "2022-08-03T20:16:40.580Z"
}
],
"createdAt": "2022-08-03T20:16:40.579Z",
"updatedAt": "2022-08-03T20:16:40.586Z"
}
},
"extensions": {
"requestId": "REQUEST_ID"
}
}