Square Loyalty API
The Loyalty API from Square — 16 operation(s) for loyalty.
Square Loyalty API is one of 45 APIs that Square publishes on the APIs.io network, described by a machine-readable OpenAPI specification and an AsyncAPI event-driven specification.
Tagged areas include Loyalty. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, an API reference, and an AsyncAPI specification.
This API exposes 18 operations across 16 paths, and defines 84 schemas. It is described by OpenAPI 3.2.0, at version 2.0.
Requests are made against a single base URL, https://connect.squareup.com.
18 operations
16 paths
84 schemas
1 DELETE6 GET11 POST
Metadata
The identity and technical contract details declared by the specification.
Authentication & Security 2
Square Loyalty API declares
2 security schemes
for authenticating requests.
It supports OAuth 2.0 (oauth2) using the authorizationCode flow, exposing 57 scopes.
An API key is passed in the header as Authorization (oauth2ClientSecret).
Paths & Operations 18
Across 16 paths, the API surfaces 18 operations — 1 DELETE, 6 GET, 11 POST. Each is listed below with its method, path, parameters, and response codes.
Loyalty 18
POST
/v2/loyalty/accounts
Square Create Loyalty Account
POST
/v2/loyalty/accounts/search
Square Search Loyalty Accounts
GET
/v2/loyalty/accounts/{account_id}
Square Retrieve Loyalty Account
POST
/v2/loyalty/accounts/{account_id}/accumulate
Square Accumulate Loyalty Points
POST
/v2/loyalty/accounts/{account_id}/adjust
Square Adjust Loyalty Points
POST
/v2/loyalty/events/search
Square Search Loyalty Events
GET
/v2/loyalty/programsdeprecated
Square List Loyalty Programs
GET
/v2/loyalty/programs/{program_id}
Square Retrieve Loyalty Program
POST
/v2/loyalty/programs/{program_id}/calculate
Square Calculate Loyalty Points
GET
/v2/loyalty/programs/{program_id}/promotions
Square List Loyalty Promotions
POST
/v2/loyalty/programs/{program_id}/promotions
Square Create Loyalty Promotion
GET
/v2/loyalty/programs/{program_id}/promotions/{promotion_id}
Square Retrieve Loyalty Promotion
POST
/v2/loyalty/programs/{program_id}/promotions/{promotion_id}/cancel
Square Cancel Loyalty Promotion
POST
/v2/loyalty/rewards
Square Create Loyalty Reward
POST
/v2/loyalty/rewards/search
Square Search Loyalty Rewards
DELETE
/v2/loyalty/rewards/{reward_id}
Square Delete Loyalty Reward
GET
/v2/loyalty/rewards/{reward_id}
Square Retrieve Loyalty Reward
POST
/v2/loyalty/rewards/{reward_id}/redeem
Square Redeem Loyalty Reward
Schemas 84
The contract defines 84 schemas that model the data the API accepts and returns. The most detailed are LoyaltyEvent (14 properties), LoyaltyPromotion (13 properties), LoyaltyAccount (10 properties), LoyaltyProgram (9 properties). Each schema is shown below with its type and property counts.
Currency
string
Indicates the associated currency for an amount of money. Values correspond to [ISO 4217](https://wikipedia.org/wiki/ISO4217).
AccumulateLoyaltyPointsRequest
object
Represents an [AccumulateLoyaltyPoints](api-endpoint:Loyalty-AccumulateLoyaltyPoints) request.
3 properties
3 required
RetrieveLoyaltyRewardResponse
object
A response that includes the loyalty reward.
2 properties
CatalogObjectReference
object
A reference to a Catalog object at a specific version. In general this is used as an entry point into a graph of catalog objects, where the objects exist at a…
2 properties
LoyaltyPromotionTriggerLimit
object
Represents the number of times a buyer can earn points during a [loyalty promotion](entity:LoyaltyPromotion). If this field is not set, buyers can trigger the…
2 properties
1 required
LoyaltyProgramAccrualRuleItemVariationData
object
Represents additional data for rules with the ITEMVARIATION accrual type.
1 property
1 required
LoyaltyProgramRewardDefinitionScope
string
Indicates the scope of the reward tier. DEPRECATED at version 2020-12-16. Discount details are now defined using a catalog pricing rule and other catalog objec…
LoyaltyRewardStatus
string
The status of the loyalty reward.
LoyaltyProgramAccrualRuleVisitData
object
Represents additional data for rules with the VISIT accrual type.
2 properties
1 required
LoyaltyReward
object
Represents a contract to redeem loyalty points for a [reward tier](entity:LoyaltyProgramRewardTier) discount. Loyalty rewards can be in an ISSUED, REDEEMED, or…
9 properties
2 required
RetrieveLoyaltyProgramResponse
object
A response that contains the loyalty program.
2 properties
LoyaltyPromotionStatus
string
Indicates the status of a [loyalty promotion](entity:LoyaltyPromotion).
LoyaltyEventDateTimeFilter
object
Filter events by date time range.
1 property
1 required
LoyaltyAccountExpiringPointDeadline
object
Represents a set of points for a loyalty account that are scheduled to expire on a specific date.
2 properties
2 required
LoyaltyPromotionIncentivePointsMultiplierData
object
Represents the metadata for a POINTSMULTIPLIER type of [loyalty promotion incentive](entity:LoyaltyPromotionIncentive).
2 properties
LoyaltyEventFilter
object
The filtering criteria. If the request specifies multiple filters, the endpoint uses a logical AND to evaluate them.
5 properties
CalculateLoyaltyPointsRequest
object
Represents a [CalculateLoyaltyPoints](api-endpoint:Loyalty-CalculateLoyaltyPoints) request.
3 properties
LoyaltyEventAdjustPoints
object
Provides metadata when the event type is ADJUSTPOINTS.
3 properties
1 required
CreateLoyaltyAccountRequest
object
A request to create a new loyalty account.
2 properties
2 required
RedeemLoyaltyRewardResponse
object
A response that includes the LoyaltyEvent published for redeeming the reward.
2 properties
ListLoyaltyPromotionsResponse
object
Represents a [ListLoyaltyPromotions](api-endpoint:Loyalty-ListLoyaltyPromotions) response. One of loyaltypromotions, an empty object, or errors is present in t…
3 properties
LoyaltyEventAccumulatePoints
object
Provides metadata when the event type is ACCUMULATEPOINTS.
3 properties
CreateLoyaltyPromotionRequest
object
Represents a [CreateLoyaltyPromotion](api-endpoint:Loyalty-CreateLoyaltyPromotion) request.
2 properties
2 required
RetrieveLoyaltyAccountResponse
object
A response that includes the loyalty account.
2 properties
LoyaltyProgram
object
Represents a Square loyalty program. Loyalty programs define how buyers can earn points and redeem points for rewards. Square sellers can have only one loyalty…
9 properties
LoyaltyEventAccumulatePromotionPoints
object
Provides metadata when the event type is ACCUMULATEPROMOTIONPOINTS.
4 properties
2 required
LoyaltyProgramRewardDefinition
object
Provides details about the reward tier discount. DEPRECATED at version 2020-12-16. Discount details are now defined using a catalog pricing rule and other cata…
6 properties
2 required
LoyaltyEventLocationFilter
object
Filter events by location.
1 property
1 required
LoyaltyProgramAccrualRuleTaxMode
string
Indicates how taxes should be treated when calculating the purchase amount used for loyalty points accrual. This setting applies only to SPEND accrual rules or…
SearchLoyaltyAccountsRequestLoyaltyAccountQuery
object
The search criteria for the loyalty accounts.
2 properties
LoyaltyProgramRewardDefinitionType
string
The type of discount the reward tier offers. DEPRECATED at version 2020-12-16. Discount details are now defined using a catalog pricing rule and other catalog…
CancelLoyaltyPromotionResponse
object
Represents a [CancelLoyaltyPromotion](api-endpoint:Loyalty-CancelLoyaltyPromotion) response. Either loyaltypromotion or errors is present in the response.
2 properties
SearchLoyaltyEventsRequest
object
A request to search for loyalty events.
3 properties
LoyaltyEventOrderFilter
object
Filter events by the order associated with the event.
1 property
1 required
DeleteLoyaltyRewardResponse
object
A response returned by the API call.
1 property
AdjustLoyaltyPointsRequest
object
Represents an [AdjustLoyaltyPoints](api-endpoint:Loyalty-AdjustLoyaltyPoints) request.
3 properties
2 required
LoyaltyEventRedeemReward
object
Provides metadata when the event type is REDEEMREWARD.
3 properties
1 required
LoyaltyAccountMapping
object
Represents the mapping that associates a loyalty account with a buyer. Currently, a loyalty account can only be mapped to a buyer by phone number. For more inf…
3 properties
CreateLoyaltyAccountResponse
object
A response that includes loyalty account created.
2 properties
LoyaltyProgramAccrualRule
object
Represents an accrual rule, which defines how buyers can earn points from the base [loyalty program](entity:LoyaltyProgram).
6 properties
1 required
LoyaltyProgramExpirationPolicy
object
Describes when the loyalty program expires.
1 property
1 required
SearchLoyaltyEventsResponse
object
A response that contains loyalty events that satisfy the search criteria, in order by the createdat date.
3 properties
RedeemLoyaltyRewardRequest
object
A request to redeem a loyalty reward.
2 properties
2 required
CreateLoyaltyRewardRequest
object
A request to create a loyalty reward.
2 properties
2 required
LoyaltyEventLoyaltyAccountFilter
object
Filter events by loyalty account.
1 property
1 required
RetrieveLoyaltyPromotionResponse
object
Represents a [RetrieveLoyaltyPromotionPromotions](api-endpoint:Loyalty-RetrieveLoyaltyPromotion) response.
2 properties
LoyaltyEventExpirePoints
object
Provides metadata when the event type is EXPIREPOINTS.
2 properties
2 required
LoyaltyEventQuery
object
Represents a query used to search for loyalty events.
1 property
SearchLoyaltyRewardsResponse
object
A response that includes the loyalty rewards satisfying the search criteria.
3 properties
LoyaltyProgramAccrualRuleCategoryData
object
Represents additional data for rules with the CATEGORY accrual type.
1 property
1 required
CalculateLoyaltyPointsResponse
object
Represents a [CalculateLoyaltyPoints](api-endpoint:Loyalty-CalculateLoyaltyPoints) response.
3 properties
Money
object
Represents an amount of money. Money fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered…
2 properties
LoyaltyEventTypeFilter
object
Filter events by event type.
1 property
1 required
SearchLoyaltyRewardsRequestLoyaltyRewardQuery
object
The set of search requirements.
2 properties
1 required
LoyaltyPromotionIncentiveType
string
Indicates the type of points incentive for a [loyalty promotion](entity:LoyaltyPromotion), which is used to determine how buyers can earn points from the promo…
CreateLoyaltyPromotionResponse
object
Represents a [CreateLoyaltyPromotion](api-endpoint:Loyalty-CreateLoyaltyPromotion) response. Either loyaltypromotion or errors is present in the response.
2 properties
ErrorCode
string
Indicates the specific error that occurred during a request to a Square API.
LoyaltyEventOther
object
Provides metadata when the event type is OTHER.
2 properties
2 required
AdjustLoyaltyPointsResponse
object
Represents an [AdjustLoyaltyPoints](api-endpoint:Loyalty-AdjustLoyaltyPoints) request.
2 properties
ErrorCategory
string
Indicates which high-level category of error has occurred during a request to the Connect API.
LoyaltyProgramRewardTier
object
Represents a reward tier in a loyalty program. A reward tier defines how buyers can redeem points for a reward, such as the number of points required and the v…
6 properties
2 required
LoyaltyPromotionIncentivePointsAdditionData
object
Represents the metadata for a POINTSADDITION type of [loyalty promotion incentive](entity:LoyaltyPromotionIncentive).
1 property
1 required
LoyaltyPromotionAvailableTimeData
object
Represents scheduling information that determines when purchases can qualify to earn points from a [loyalty promotion](entity:LoyaltyPromotion).
3 properties
1 required
LoyaltyEventDeleteReward
object
Provides metadata when the event type is DELETEREWARD.
3 properties
2 required
SearchLoyaltyAccountsResponse
object
A response that includes loyalty accounts that satisfy the search criteria.
3 properties
LoyaltyEventSource
string
Defines whether the event was generated by the Square Point of Sale.
LoyaltyProgramAccrualRuleSpendData
object
Represents additional data for rules with the SPEND accrual type.
4 properties
2 required
SearchLoyaltyRewardsRequest
object
A request to search for loyalty rewards.
3 properties
TimeRange
object
Represents a generic time range. The start and end values are represented in RFC 3339 format. Time ranges are customized to be inclusive or exclusive based on…
2 properties
LoyaltyPromotionIncentive
object
Represents how points for a [loyalty promotion](entity:LoyaltyPromotion) are calculated, either by multiplying the points earned from the base program or by ad…
3 properties
1 required
LoyaltyPromotionTriggerLimitInterval
string
Indicates the time period that the [trigger limit](entity:LoyaltyPromotionTriggerLimit) applies to, which is used to determine the number of times a buyer can…
LoyaltyEventCreateReward
object
Provides metadata when the event type is CREATEREWARD.
3 properties
2 required
ListLoyaltyProgramsResponse
object
A response that contains all loyalty programs.
2 properties
LoyaltyPromotion
object
Represents a promotion for a [loyalty program](entity:LoyaltyProgram). Loyalty promotions enable buyers to earn extra points on top of those earned from the ba…
13 properties
3 required
CreateLoyaltyRewardResponse
object
A response that includes the loyalty reward created.
2 properties
LoyaltyProgramAccrualRuleType
string
The type of the accrual rule that defines how buyers can earn points.
Error
object
Represents an error encountered during a request to the Connect API. See [Handling errors](https://developer.squareup.com/docs/build-basics/handling-errors) fo…
4 properties
2 required
AccumulateLoyaltyPointsResponse
object
Represents an [AccumulateLoyaltyPoints](api-endpoint:Loyalty-AccumulateLoyaltyPoints) response.
3 properties
SearchLoyaltyAccountsRequest
object
A request to search for loyalty accounts.
3 properties
LoyaltyEvent
object
Provides information about a loyalty event. For more information, see [Search for Balance-Changing Loyalty Events](https://developer.squareup.com/docs/loyalty-…
14 properties
5 required
LoyaltyProgramStatus
string
Indicates whether the program is currently active.
LoyaltyAccount
object
Describes a loyalty account in a [loyalty program](entity:LoyaltyProgram). For more information, see [Create and Retrieve Loyalty Accounts](https://developer.s…
10 properties
1 required
LoyaltyEventType
string
The type of the loyalty event.
LoyaltyProgramTerminology
object
Represents the naming used for loyalty points.
2 properties
2 required
Specification
The full machine-readable OpenAPI contract behind this narrative.
Source
More from Square 12
Other APIs Square publishes across the network.
Square Reporting API
Square Channels API
Square Transfer Orders API
Square ApplePay API
Square BankAccounts API
Square BookingCustomAttributes API
Square Bookings API
Square Cards API
Square CashDrawers API
Square Catalog API
Square Checkout API
Square CustomerCustomAttributes API
#Loyalty
Where this information came from
This is an independent, third-party profile of Square Loyalty API, published by API Evangelist. We do not operate, host, resell, or support these APIs, and we are not affiliated with or endorsed by the company unless stated above. Everything here is built from publicly available information — the company's own site, developer portal, documentation, public repositories, and the specifications it publishes for public use. Nothing is obtained by breaching a system, defeating an access control, or using credentials.
The Kin Score and Agent Readiness rating are independently calculated assessments of a company's public API artifacts, scored against a published rubric. They are not certifications, endorsements, security assessments, or audits.
Corrections, re-scores, and removal are free — no partnership or purchase required, and you do not need to justify the request. A removed company is recorded as unrated, never scored zero for having asked. Acknowledgement within one business day; removal within two.
info@apievangelist.com
·
Read the full data-sourcing policy →
On a security or compliance team? Put security in the subject line and
you will get a person, not a form — we will tell you exactly which public URLs this profile was built from.