Square Loyalty & Gift Cards
How many points does this client have, and what is left on their gift card? Look up Square Loyalty accounts by phone, add or adjust points, redeem rewards at checkout, and check, load or redeem gift card balances by card number (GAN).
Connect this API to an AI agent Browse all specs
What you can do with Square Loyalty & Gift Cards via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /v2/loyalty/programs/{program_id} |
retrieveLoyaltyProgram | Get the seller's loyalty program (use program_id main) |
| POST | /v2/loyalty/programs/{program_id}/calculate |
calculateLoyaltyPoints | Work out how many points an order or amount earns |
| GET | /v2/loyalty/programs/{program_id}/promotions |
listLoyaltyPromotions | List bonus-point promotions in the program |
| POST | /v2/loyalty/accounts/search |
searchLoyaltyAccounts | Find loyalty accounts by phone number or customer id |
| GET | /v2/loyalty/accounts/{account_id} |
retrieveLoyaltyAccount | Get a loyalty account and its point balance |
| POST | /v2/loyalty/accounts |
createLoyaltyAccount | Enroll a customer in the loyalty program by phone |
| POST | /v2/loyalty/accounts/{account_id}/accumulate |
accumulateLoyaltyPoints | Add points earned from a purchase |
| POST | /v2/loyalty/accounts/{account_id}/adjust |
adjustLoyaltyPoints | Manually add or remove points with a reason |
| POST | /v2/loyalty/events/search |
searchLoyaltyEvents | List point history (earned, redeemed, adjusted, expired) |
| POST | /v2/loyalty/rewards/search |
searchLoyaltyRewards | List rewards issued to a loyalty account |
| POST | /v2/loyalty/rewards |
createLoyaltyReward | Turn points into a reward for the customer |
| POST | /v2/loyalty/rewards/{reward_id}/redeem |
redeemLoyaltyReward | Mark a reward as used |
| GET | /v2/gift-cards |
listGiftCards | List gift cards, optionally by state or customer |
| GET | /v2/gift-cards/{id} |
retrieveGiftCard | Get a gift card and its balance by id |
| POST | /v2/gift-cards/from-gan |
retrieveGiftCardFromGan | Look up a gift card by the number printed on it (GAN) |
| GET | /v2/gift-cards/activities |
listGiftCardActivities | List a gift card's loads, redemptions and adjustments |
| POST | /v2/gift-cards/activities |
createGiftCardActivity | Activate, load, redeem or adjust a gift card balance |
| POST | /v2/gift-cards/{gift_card_id}/link-customer |
linkCustomerToGiftCard | Link a gift card to a customer profile |
| POST | /v2/customers/search |
searchCustomers | Find a customer by phone, email or other filters |
Authentication
squareToken
Bearer token — sent as Authorization: Bearer <token>
How to get a credential
- Sign in to the Square Developer Console with your Square account and create an application (free).
- Open the app, switch to Production, and copy the Production access token from Credentials. It acts for your own seller account with all permissions.
- To act for other sellers, use OAuth (authorization code) and request only the scopes below.
Permissions used
| Scope | Operations |
|---|---|
| LOYALTY_READ | retrieveLoyaltyProgram, calculateLoyaltyPoints, listLoyaltyPromotions, searchLoyaltyAccounts, retrieveLoyaltyAccount, searchLoyaltyEvents, searchLoyaltyRewards |
| LOYALTY_WRITE | createLoyaltyAccount, accumulateLoyaltyPoints, adjustLoyaltyPoints, createLoyaltyReward, redeemLoyaltyReward |
| GIFTCARDS_READ | listGiftCards, retrieveGiftCard, retrieveGiftCardFromGan, listGiftCardActivities |
| GIFTCARDS_WRITE | createGiftCardActivity, linkCustomerToGiftCard |
| CUSTOMERS_READ | searchCustomers |
Common errors
- 401 UNAUTHORIZED: wrong, expired or sandbox token used against production.
- 403 INSUFFICIENT_SCOPES: the OAuth token lacks a scope from the table.
- 400 BAD_REQUEST: missing
idempotency_keyon a write, or an invalid id or phone format (use E.164,+14155550123). - 404 NOT_FOUND: the seller has no loyalty program, or the account, reward or gift card id is wrong.
- 429 RATE_LIMITED: slow down and retry with backoff.
Store the token as a VX Agents bearer token credential.
Usage guide
Setup
- Credential: a Square production access token (or OAuth token with the scopes in Authentication).
- Worth pinning:
location_idof the shop (accumulate and redeem need it) and the loyaltyprogram_id. CallretrieveLoyaltyProgramwithprogram_id=mainonce and pin the returnedid. - Every write needs a fresh
idempotency_key(any unique string, such as a UUID). Reuse it only to retry the same request.
Points at the counter
searchLoyaltyAccountswithquery.mappings= the customer's phone in E.164 (+14155550123), orquery.customer_ids.- No account?
createLoyaltyAccountwithloyalty_account.mapping.phone_numberandprogram_id. calculateLoyaltyPointswith anorder_idortransaction_amount_moneyto see what a visit earns.accumulateLoyaltyPointswithlocation_idandaccumulate_points.order_id(orpoints) to add them. UseadjustLoyaltyPointswithadjust_points.points(negative removes) and areasonfor corrections.- Redeem:
createLoyaltyRewardwith thereward_tier_idfrom the program, thenredeemLoyaltyRewardwithlocation_idwhen it is used. searchLoyaltyEventsandsearchLoyaltyRewardsshow history when a client disputes a balance.
Gift cards
retrieveGiftCardFromGanwith the number on the card;balance_moneyis the remaining balance.listGiftCardActivitieswithgift_card_idfor its history.createGiftCardActivitywithtypeACTIVATE,LOAD,REDEEM,ADJUST_INCREMENTorADJUST_DECREMENTand the matching details object (amount,location_id).searchCustomersby phone or email, thenlinkCustomerToGiftCardto attach the card to their profile.
Before any write (points, rewards, gift card balances, enrollment), show the customer, amount and effect to the user and get a yes: these change real balances and cannot simply be undone.
Good to know
- Money is in the smallest unit:
{"amount": 2500, "currency": "USD"}is $25.00. - Times are RFC 3339 UTC. Search calls page with
cursor. - A 404 on the program means the seller has not set up Square Loyalty in the Seller Dashboard.
- Requests pin
Square-Version: 2026-09-16.
Source: Square Loyalty and Gift Cards API reference (https://developer.squareup.com/reference/square/loyalty-api), checked 2026-10-19.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Square Loyalty & Gift Cards” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.