Square stops filling in Customer.cards on November 30. Find the code that still reads it this week
Nothing will throw an error on November 30. A field that used to hold a customer's saved cards will simply come back empty, and any code that trusts it will decide nobody has anything saved. Here is where to look this week.

Square will stop populating the cards field on the Customers API Customer object on November 30, 2026, including for integrations pinned to older API versions. Anything that reads it to find cards on file needs to call ListCards with the customer_id (or ListGiftCards for gift cards) instead. Search your code and your vendors' tools for the old field now, and test with a customer who has a card, a disabled card and no card.
What happens on November 30
Square's customer record has a field called cards, a list of the cards a customer has saved. It was marked deprecated in API version 2021-06-16 and retired in version 2025-01-23. Retired didn't mean gone: if your integration still sends an older version header, the field kept showing up. A Square solutions engineer posted on the developer forum on November 9 that this ends. From November 30, Square stops filling it in, for older versions too.
There's no error attached to this. The request still succeeds, the customer still comes back, and the list of cards is just missing or empty. That's the whole problem. Code written years ago, by someone who has since moved on, will read an empty list and conclude the customer has no card.
Where that goes wrong
We'd expect the damage to look like a business problem, not a technical one. These are illustrations of the pattern, not reports of anything that has happened:
- A loyalty or membership tool that charges "the card on file" finds none and skips the charge, so renewals quietly fail.
- A booking page stops showing "pay with your saved card" and asks everyone to type it in again.
- An invoicing script that picks the customer's card for a recurring bill sends a "please add a payment method" email to a hundred regulars.
- A report that counts "customers with a card on file" drops to zero on the first of December and someone spends a morning finding out why.
None of those would show up in an error log. They show up in a customer message or a revenue number.
A field that goes quiet is harder to catch than a call that fails. When an endpoint is switched off, monitoring notices within minutes because requests start failing. When a field stops being filled in, every request still returns a success code, every dashboard that tracks errors stays green, and the first person to notice is usually a customer, or whoever reconciles the payments at month end. The timing makes it worse: November 30 is the Monday after Thanksgiving weekend, when stores are busy and the people who would normally spot an odd number are busy too.
A field that goes quiet is harder to catch than a call that fails.
Three searches that take an afternoon
Search your own code. Look for the field name wherever you talk to Square: "customer.cards", ".cards", "cards[0]", "cards.length" and anything that loops over a customer's cards. Check the Square-Version header too. If it says 2021, 2022 or 2023, you're the person this announcement is written for.
Search your logs. If you log API responses, look for customer responses that include a cards list. If you see them, something is still reading them. If you can't tell, that's useful to know too, because it means the first sign of trouble will come from a customer rather than from your own records.
Ask your vendors. Anything that connects Square to something else (a loyalty app, a booking tool, a subscription billing add-on, a CRM sync, an accounting export) may be calling this field on your behalf. Send a short question: "Do you read Customer.cards from Square's Customers API? If so, when will you move to ListCards?" Keep the reply. If a vendor can't answer by the end of next week, that tells you something about the vendor.
Decision guide
The same question, asked two ways
| Consideration | Old: read it off the customer | New: ask for the cards |
|---|---|---|
| Credit and debit cards | Customer.cards on the Customers API response | ListCards with the customer_id parameter |
| Gift cards | Customer.cards on the Customers API response | ListGiftCards with the customer_id parameter |
| Disabled cards | Whatever the old field happened to include | Left out unless you ask with include_disabled |
| Long lists | All of them arrived inside the customer | Up to 25 per call, then follow the cursor |
The swap
For credit and debit cards, Square says to call ListCards with the customer_id query parameter, and for gift cards, ListGiftCards with customer_id. Two details are easy to miss.
ListCards returns at most 25 cards per call, with a cursor to fetch more, so code that assumed "all of them in one response" needs a loop. Most customers have two or three cards, but a long-standing business account with many saved cards is exactly the customer you least want to get wrong. And disabled cards are left out unless you ask for them with include_disabled. Decide whether your code should see them. A "card on file" check usually shouldn't count one that's been disabled; a support lookup might want to.
It's also worth writing the check so it fails loudly. If the new call errors or returns nothing, log it and alert someone instead of treating it as "no card".
Keep the swap in one place. If several parts of your code ask "does this customer have a saved card?", give them one shared function that calls ListCards, follows the cursor, applies your rule about disabled cards and returns a clear answer. The next time Square changes something, there is one function to update instead of five scattered lookups, and one place to add a log line when the answer looks wrong.
Test with three customers
Before November 30, run the new path against three people: one with a normal saved card, one whose card is disabled, and one with no card at all. Compare the result with what the old field returned for the same people today, while it still works. Where the answers differ, decide which one is right, and write that down. A card that the old field listed but the new call leaves out is usually a disabled card, which is the include_disabled decision from the previous section showing up in practice.
Then run the whole flow end to end in a Square sandbox, not just the lookup. A saved-card charge, a renewal and a "pay with saved card" page all depend on the same answer, and any of them can be the one that breaks.
Then pick one more check for December 1. Look at whatever number would move if this went wrong: renewals that failed, saved-card payments taken, customers asked to add a payment method. If it looks normal against the previous Monday, you're done. If it doesn't, you already know where to look.
Sequence of work
How the field got here
- API version 2021-06-16
The cards field on Customer is deprecated.
- API version 2025-01-23
The field is retired, but older pinned versions can still return it.
- Nov 9, 2026
Square announces it will stop filling it in for every version.
- Nov 30, 2026
Responses no longer include saved cards in that field.
If it's more than a one-line change
For most small businesses this is a few lines in one place, and an afternoon is plenty. It turns into a project when the code that reads the field is old, undocumented or owned by a vendor who has gone quiet. That's the situation our web applications work covers: reading an integration nobody wrote down, mapping what depends on it, and replacing it with something that fails loudly. If you'd like a second pair of eyes before the end of the month, talk to us.
Related work: Sutton|Place
We build alongside the people doing the work.
Bring us the problem you’re thinking about.