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. To stop a physical card from renewing without canceling it, call the cancelPhysicalCardRenewal mutation while the card is in ToRenew status. The card stays active until it expires, then isn't renewed.

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 will be 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

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"
        }
      }
    }
  }
}

Cancel a physical card renewal

To stop a physical card from being renewed without canceling it, call the cancelPhysicalCardRenewal mutation. The card stays active until its expiry date, then expires instead of renewing.

Before you cancel a renewal

• The card must be in ToRenew status when you call the mutation. If it isn't, Swan returns a PhysicalCardWrongStatusRejection.
• The card stays active until its expiry date. It isn't canceled immediately.
• This differs from cancelPhysicalCard, which cancels the card immediately and can't be reversed.
• Subscribe to the Card.Updated webhook to know when a card enters ToRenew status.

Guide

1. Call the cancelPhysicalCardRenewal mutation.
2. Add the cardId for the physical card whose renewal you're canceling (line 2).
3. Add the CancelPhysicalCardRenewalSuccessPayload, including any information you'd like to review (line 3).
4. Add rejections (not shown).

Mutation

Open in API Explorer

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

Payload

The physical card stays in ToRenew status (line 7). It stays active until its expiry date, then expires instead of being renewed.

{
  "data": {
    "cancelPhysicalCardRenewal": {
      "__typename": "CancelPhysicalCardRenewalSuccessPayload",
      "physicalCard": {
        "statusInfo": {
          "status": "ToRenew"
        }
      }
    }
  }
}