Renew physical cards

Physical cards expire three years after they are printed. They're then automatically renewed for another three years unless the card is canceled.

If you want the renewed physical card to be delivered to a new address, call the confirmPhysicalCardRenewal mutation at least 8 weeks before the last day of the card's expiry month. If no action is taken, the renewed card is shipped to the original delivery address.

Prerequisites

1. Confirm that the card is in ToRenew status before calling this mutation. This status is automatically triggered 10 weeks before the last day of the card's expiry month, at midnight Coordinated Universal Time (UTC). If you're subscribed to the Card.Updated webhook, you'll receive a notification when the physical card status changes to ToRenew.
2. Verify the new physical card delivery address with the cardholder.

Original delivery address

While the physical card is in ToRenew status, you can query the original delivery address to display to cardholders for verification.

Query original delivery address

Open in API Explorer

query PhysicalCardAddress {
  card(cardId: "$YOUR_CARD_ID") {
    physicalCard {
      statusInfo {
        ... on PhysicalCardToRenewStatusInfo {
          address {
            addressLine1
            city
            postalCode
            country
          }
        }
      }
    }
  }
}

Guide

1. Call the confirmPhysicalCardRenewal mutation.
2. Add the cardId for the physical card you're renewing (line 4).
3. Add the updated physical card delivery address (line 5).
4. Add the ConfirmPhysicalCardRenewalSuccessPayload, including any information you'd like to review (line 8).
5. Add rejections (not shown).

Delivery address guidelines

You don't need to include the companyName in any address fields. Consult the guidelines for providing a card delivery address for more information.

Mutation

Open in API Explorer

mutation RenewPhysicalCard {
  confirmPhysicalCardRenewal(
    input: {
      cardId: "$YOUR_CARD_ID"
      address: { addressLine1: "10 Rue de la Paix", city: "Paris", postalCode: "75000", country: "FRA" }
    }
  ) {
    ... on ConfirmPhysicalCardRenewalSuccessPayload {
      __typename
      physicalCard {
        expiryDate
        statusInfo {
          status
        }
      }
    }
  }
}

Payload

The payload confirms that the physical card expires on 09/21 (line 6), and its renewal status is ToRenew (line 8).

{
  "data": {
    "confirmPhysicalCardRenewal": {
      "__typename": "ConfirmPhysicalCardRenewalSuccessPayload",
      "physicalCard": {
        "expiryDate": "09/21",
        "statusInfo": {
          "status": "ToRenew"
        }
      }
    }
  }
}

Stop the automatic renewal

To stop a physical card from renewing automatically, without canceling it, call the cancelPhysicalCardRenewal mutation while the card is in the ToRenew status. The card remains active until its expiry date, then expires rather than being renewed and reissued.

Open in API Explorer

mutation CancelPhysicalCardRenewal {
  cancelPhysicalCardRenewal(input: { cardId: "$YOUR_CARD_ID" }) {
    ... on CancelPhysicalCardRenewalSuccessPayload {
      __typename
      physicalCard {
        statusInfo {
          status
        }
      }
    }
    ... on PhysicalCardWrongStatusRejection {
      __typename
      currentStatus
    }
  }
}

If the card isn't in the ToRenew status, the mutation returns a PhysicalCardWrongStatusRejection.