const loyaltyApi = client.loyaltyApi;
LoyaltyApi
- Create Loyalty Account
- Search Loyalty Accounts
- Retrieve Loyalty Account
- Accumulate Loyalty Points
- Adjust Loyalty Points
- Search Loyalty Events
- List Loyalty Programs
- Retrieve Loyalty Program
- Calculate Loyalty Points
- Create Loyalty Reward
- Search Loyalty Rewards
- Delete Loyalty Reward
- Retrieve Loyalty Reward
- Redeem Loyalty Reward
Creates a loyalty account. To create a loyalty account, you must provide the program_id
and a mapping
with the phone_number
of the buyer.
async createLoyaltyAccount(
body: CreateLoyaltyAccountRequest,
requestOptions?: RequestOptions
): Promise<ApiResponse<CreateLoyaltyAccountResponse>>
Parameter | Type | Tags | Description |
---|---|---|---|
body |
CreateLoyaltyAccountRequest |
Body, Required | An object containing the fields to POST for the request. See the corresponding object definition for field details. |
requestOptions |
RequestOptions | undefined |
Optional | Pass additional request options. |
const contentType = null;
const bodyLoyaltyAccountMapping: LoyaltyAccountMapping = {};
bodyLoyaltyAccountMapping.phoneNumber = '+14155551234';
const bodyLoyaltyAccount: LoyaltyAccount = {
programId: 'd619f755-2d17-41f3-990d-c04ecedd64dd',
};
bodyLoyaltyAccount.mapping = bodyLoyaltyAccountMapping;
const body: CreateLoyaltyAccountRequest = {
loyaltyAccount: bodyLoyaltyAccount,
idempotencyKey: 'ec78c477-b1c3-4899-a209-a4e71337c996',
};
try {
const { result, ...httpResponse } = await loyaltyApi.createLoyaltyAccount(body);
// Get more response info...
// const { statusCode, headers } = httpResponse;
} catch(error) {
if (error instanceof ApiError) {
const errors = error.result;
// const { statusCode, headers } = error;
}
}
Searches for loyalty accounts in a loyalty program.
You can search for a loyalty account using the phone number or customer ID associated with the account. To return all loyalty accounts, specify an empty query
object or omit it entirely.
Search results are sorted by created_at
in ascending order.
async searchLoyaltyAccounts(
body: SearchLoyaltyAccountsRequest,
requestOptions?: RequestOptions
): Promise<ApiResponse<SearchLoyaltyAccountsResponse>>
Parameter | Type | Tags | Description |
---|---|---|---|
body |
SearchLoyaltyAccountsRequest |
Body, Required | An object containing the fields to POST for the request. See the corresponding object definition for field details. |
requestOptions |
RequestOptions | undefined |
Optional | Pass additional request options. |
const contentType = null;
const bodyQueryMappings: LoyaltyAccountMapping[] = [];
const bodyQuerymappings0: LoyaltyAccountMapping = {};
bodyQuerymappings0.phoneNumber = '+14155551234';
bodyQueryMappings[0] = bodyQuerymappings0;
const bodyQuery: SearchLoyaltyAccountsRequestLoyaltyAccountQuery = {};
bodyQuery.mappings = bodyQueryMappings;
const body: SearchLoyaltyAccountsRequest = {};
body.query = bodyQuery;
body.limit = 10;
try {
const { result, ...httpResponse } = await loyaltyApi.searchLoyaltyAccounts(body);
// Get more response info...
// const { statusCode, headers } = httpResponse;
} catch(error) {
if (error instanceof ApiError) {
const errors = error.result;
// const { statusCode, headers } = error;
}
}
Retrieves a loyalty account.
async retrieveLoyaltyAccount(
accountId: string,
requestOptions?: RequestOptions
): Promise<ApiResponse<RetrieveLoyaltyAccountResponse>>
Parameter | Type | Tags | Description |
---|---|---|---|
accountId |
string |
Template, Required | The ID of the loyalty account to retrieve. |
requestOptions |
RequestOptions | undefined |
Optional | Pass additional request options. |
RetrieveLoyaltyAccountResponse
const accountId = 'account_id2';
try {
const { result, ...httpResponse } = await loyaltyApi.retrieveLoyaltyAccount(accountId);
// Get more response info...
// const { statusCode, headers } = httpResponse;
} catch(error) {
if (error instanceof ApiError) {
const errors = error.result;
// const { statusCode, headers } = error;
}
}
Adds points earned from the base loyalty program to a loyalty account.
- If you are using the Orders API to manage orders, you only provide the
order_id
. The endpoint reads the order to compute points to add to the buyer's account. - If you are not using the Orders API to manage orders,
you first perform a client-side computation to compute the points.
For spend-based and visit-based programs, you can first call CalculateLoyaltyPoints to compute the points
that you provide to this endpoint.
This endpoint excludes additional points earned from loyalty promotions.
async accumulateLoyaltyPoints(
accountId: string,
body: AccumulateLoyaltyPointsRequest,
requestOptions?: RequestOptions
): Promise<ApiResponse<AccumulateLoyaltyPointsResponse>>
Parameter | Type | Tags | Description |
---|---|---|---|
accountId |
string |
Template, Required | The loyalty account ID to which to add the points. |
body |
AccumulateLoyaltyPointsRequest |
Body, Required | An object containing the fields to POST for the request. See the corresponding object definition for field details. |
requestOptions |
RequestOptions | undefined |
Optional | Pass additional request options. |
AccumulateLoyaltyPointsResponse
const accountId = 'account_id2';
const contentType = null;
const bodyAccumulatePoints: LoyaltyEventAccumulatePoints = {};
bodyAccumulatePoints.orderId = 'RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY';
const body: AccumulateLoyaltyPointsRequest = {
accumulatePoints: bodyAccumulatePoints,
idempotencyKey: '58b90739-c3e8-4b11-85f7-e636d48d72cb',
locationId: 'P034NEENMD09F',
};
try {
const { result, ...httpResponse } = await loyaltyApi.accumulateLoyaltyPoints(accountId, body);
// Get more response info...
// const { statusCode, headers } = httpResponse;
} catch(error) {
if (error instanceof ApiError) {
const errors = error.result;
// const { statusCode, headers } = error;
}
}
Adds points to or subtracts points from a buyer's account.
Use this endpoint only when you need to manually adjust points. Otherwise, in your application flow, you call AccumulateLoyaltyPoints to add points when a buyer pays for the purchase.
async adjustLoyaltyPoints(
accountId: string,
body: AdjustLoyaltyPointsRequest,
requestOptions?: RequestOptions
): Promise<ApiResponse<AdjustLoyaltyPointsResponse>>
Parameter | Type | Tags | Description |
---|---|---|---|
accountId |
string |
Template, Required | The ID of the loyalty account in which to adjust the points. |
body |
AdjustLoyaltyPointsRequest |
Body, Required | An object containing the fields to POST for the request. See the corresponding object definition for field details. |
requestOptions |
RequestOptions | undefined |
Optional | Pass additional request options. |
const accountId = 'account_id2';
const contentType = null;
const bodyAdjustPoints: LoyaltyEventAdjustPoints = {
points: 10,
};
bodyAdjustPoints.reason = 'Complimentary points';
const body: AdjustLoyaltyPointsRequest = {
idempotencyKey: 'bc29a517-3dc9-450e-aa76-fae39ee849d1',
adjustPoints: bodyAdjustPoints,
};
try {
const { result, ...httpResponse } = await loyaltyApi.adjustLoyaltyPoints(accountId, body);
// Get more response info...
// const { statusCode, headers } = httpResponse;
} catch(error) {
if (error instanceof ApiError) {
const errors = error.result;
// const { statusCode, headers } = error;
}
}
Searches for loyalty events.
A Square loyalty program maintains a ledger of events that occur during the lifetime of a buyer's loyalty account. Each change in the point balance (for example, points earned, points redeemed, and points expired) is recorded in the ledger. Using this endpoint, you can search the ledger for events.
Search results are sorted by created_at
in descending order.
async searchLoyaltyEvents(
body: SearchLoyaltyEventsRequest,
requestOptions?: RequestOptions
): Promise<ApiResponse<SearchLoyaltyEventsResponse>>
Parameter | Type | Tags | Description |
---|---|---|---|
body |
SearchLoyaltyEventsRequest |
Body, Required | An object containing the fields to POST for the request. See the corresponding object definition for field details. |
requestOptions |
RequestOptions | undefined |
Optional | Pass additional request options. |
const contentType = null;
const bodyQueryFilterOrderFilter: LoyaltyEventOrderFilter = {
orderId: 'PyATxhYLfsMqpVkcKJITPydgEYfZY',
};
const bodyQueryFilter: LoyaltyEventFilter = {};
bodyQueryFilter.orderFilter = bodyQueryFilterOrderFilter;
const bodyQuery: LoyaltyEventQuery = {};
bodyQuery.filter = bodyQueryFilter;
const body: SearchLoyaltyEventsRequest = {};
body.query = bodyQuery;
body.limit = 30;
try {
const { result, ...httpResponse } = await loyaltyApi.searchLoyaltyEvents(body);
// Get more response info...
// const { statusCode, headers } = httpResponse;
} catch(error) {
if (error instanceof ApiError) {
const errors = error.result;
// const { statusCode, headers } = error;
}
}
This endpoint is deprecated.
Returns a list of loyalty programs in the seller's account. Loyalty programs define how buyers can earn points and redeem points for rewards. Square sellers can have only one loyalty program, which is created and managed from the Seller Dashboard. For more information, see Loyalty Program Overview.
Replaced with RetrieveLoyaltyProgram when used with the keyword main
.
async listLoyaltyPrograms(
requestOptions?: RequestOptions
): Promise<ApiResponse<ListLoyaltyProgramsResponse>>
Parameter | Type | Tags | Description |
---|---|---|---|
requestOptions |
RequestOptions | undefined |
Optional | Pass additional request options. |
try {
const { result, ...httpResponse } = await loyaltyApi.listLoyaltyPrograms();
// Get more response info...
// const { statusCode, headers } = httpResponse;
} catch(error) {
if (error instanceof ApiError) {
const errors = error.result;
// const { statusCode, headers } = error;
}
}
Retrieves the loyalty program in a seller's account, specified by the program ID or the keyword main
.
Loyalty programs define how buyers can earn points and redeem points for rewards. Square sellers can have only one loyalty program, which is created and managed from the Seller Dashboard. For more information, see Loyalty Program Overview.
async retrieveLoyaltyProgram(
programId: string,
requestOptions?: RequestOptions
): Promise<ApiResponse<RetrieveLoyaltyProgramResponse>>
Parameter | Type | Tags | Description |
---|---|---|---|
programId |
string |
Template, Required | The ID of the loyalty program or the keyword main . Either value can be used to retrieve the single loyalty program that belongs to the seller. |
requestOptions |
RequestOptions | undefined |
Optional | Pass additional request options. |
RetrieveLoyaltyProgramResponse
const programId = 'program_id0';
try {
const { result, ...httpResponse } = await loyaltyApi.retrieveLoyaltyProgram(programId);
// Get more response info...
// const { statusCode, headers } = httpResponse;
} catch(error) {
if (error instanceof ApiError) {
const errors = error.result;
// const { statusCode, headers } = error;
}
}
Calculates the points a purchase earns from the base loyalty program.
- If you are using the Orders API to manage orders, you provide the
order_id
in the request. The endpoint calculates the points by reading the order. - If you are not using the Orders API to manage orders, you provide the purchase amount in the request for the endpoint to calculate the points.
An application might call this endpoint to show the points that a buyer can earn with the specific purchase.
For spend-based and visit-based programs, the tax_mode
setting of the accrual rule indicates how taxes should be treated for loyalty points accrual.
async calculateLoyaltyPoints(
programId: string,
body: CalculateLoyaltyPointsRequest,
requestOptions?: RequestOptions
): Promise<ApiResponse<CalculateLoyaltyPointsResponse>>
Parameter | Type | Tags | Description |
---|---|---|---|
programId |
string |
Template, Required | The loyalty program ID, which defines the rules for accruing points. |
body |
CalculateLoyaltyPointsRequest |
Body, Required | An object containing the fields to POST for the request. See the corresponding object definition for field details. |
requestOptions |
RequestOptions | undefined |
Optional | Pass additional request options. |
CalculateLoyaltyPointsResponse
const programId = 'program_id0';
const contentType = null;
const body: CalculateLoyaltyPointsRequest = {};
body.orderId = 'RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY';
try {
const { result, ...httpResponse } = await loyaltyApi.calculateLoyaltyPoints(programId, body);
// Get more response info...
// const { statusCode, headers } = httpResponse;
} catch(error) {
if (error instanceof ApiError) {
const errors = error.result;
// const { statusCode, headers } = error;
}
}
Creates a loyalty reward. In the process, the endpoint does following:
- Uses the
reward_tier_id
in the request to determine the number of points to lock for this reward. - If the request includes
order_id
, it adds the reward and related discount to the order.
After a reward is created, the points are locked and not available for the buyer to redeem another reward.
async createLoyaltyReward(
body: CreateLoyaltyRewardRequest,
requestOptions?: RequestOptions
): Promise<ApiResponse<CreateLoyaltyRewardResponse>>
Parameter | Type | Tags | Description |
---|---|---|---|
body |
CreateLoyaltyRewardRequest |
Body, Required | An object containing the fields to POST for the request. See the corresponding object definition for field details. |
requestOptions |
RequestOptions | undefined |
Optional | Pass additional request options. |
const contentType = null;
const bodyReward: LoyaltyReward = {
loyaltyAccountId: '5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd',
rewardTierId: 'e1b39225-9da5-43d1-a5db-782cdd8ad94f',
};
bodyReward.orderId = 'RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY';
const body: CreateLoyaltyRewardRequest = {
reward: bodyReward,
idempotencyKey: '18c2e5ea-a620-4b1f-ad60-7b167285e451',
};
try {
const { result, ...httpResponse } = await loyaltyApi.createLoyaltyReward(body);
// Get more response info...
// const { statusCode, headers } = httpResponse;
} catch(error) {
if (error instanceof ApiError) {
const errors = error.result;
// const { statusCode, headers } = error;
}
}
Searches for loyalty rewards. This endpoint accepts a request with no query filters and returns results for all loyalty accounts.
If you include a query
object, loyalty_account_id
is required and status
is optional.
If you know a reward ID, use the RetrieveLoyaltyReward endpoint.
Search results are sorted by updated_at
in descending order.
async searchLoyaltyRewards(
body: SearchLoyaltyRewardsRequest,
requestOptions?: RequestOptions
): Promise<ApiResponse<SearchLoyaltyRewardsResponse>>
Parameter | Type | Tags | Description |
---|---|---|---|
body |
SearchLoyaltyRewardsRequest |
Body, Required | An object containing the fields to POST for the request. See the corresponding object definition for field details. |
requestOptions |
RequestOptions | undefined |
Optional | Pass additional request options. |
const contentType = null;
const bodyQuery: SearchLoyaltyRewardsRequestLoyaltyRewardQuery = {
loyaltyAccountId: '5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd',
};
const body: SearchLoyaltyRewardsRequest = {};
body.query = bodyQuery;
body.limit = 10;
try {
const { result, ...httpResponse } = await loyaltyApi.searchLoyaltyRewards(body);
// Get more response info...
// const { statusCode, headers } = httpResponse;
} catch(error) {
if (error instanceof ApiError) {
const errors = error.result;
// const { statusCode, headers } = error;
}
}
Deletes a loyalty reward by doing the following:
- Returns the loyalty points back to the loyalty account.
- If an order ID was specified when the reward was created (see CreateLoyaltyReward), it updates the order by removing the reward and related discounts.
You cannot delete a reward that has reached the terminal state (REDEEMED).
async deleteLoyaltyReward(
rewardId: string,
requestOptions?: RequestOptions
): Promise<ApiResponse<DeleteLoyaltyRewardResponse>>
Parameter | Type | Tags | Description |
---|---|---|---|
rewardId |
string |
Template, Required | The ID of the loyalty reward to delete. |
requestOptions |
RequestOptions | undefined |
Optional | Pass additional request options. |
const rewardId = 'reward_id4';
try {
const { result, ...httpResponse } = await loyaltyApi.deleteLoyaltyReward(rewardId);
// Get more response info...
// const { statusCode, headers } = httpResponse;
} catch(error) {
if (error instanceof ApiError) {
const errors = error.result;
// const { statusCode, headers } = error;
}
}
Retrieves a loyalty reward.
async retrieveLoyaltyReward(
rewardId: string,
requestOptions?: RequestOptions
): Promise<ApiResponse<RetrieveLoyaltyRewardResponse>>
Parameter | Type | Tags | Description |
---|---|---|---|
rewardId |
string |
Template, Required | The ID of the loyalty reward to retrieve. |
requestOptions |
RequestOptions | undefined |
Optional | Pass additional request options. |
const rewardId = 'reward_id4';
try {
const { result, ...httpResponse } = await loyaltyApi.retrieveLoyaltyReward(rewardId);
// Get more response info...
// const { statusCode, headers } = httpResponse;
} catch(error) {
if (error instanceof ApiError) {
const errors = error.result;
// const { statusCode, headers } = error;
}
}
Redeems a loyalty reward.
The endpoint sets the reward to the REDEEMED
terminal state.
If you are using your own order processing system (not using the Orders API), you call this endpoint after the buyer paid for the purchase.
After the reward reaches the terminal state, it cannot be deleted. In other words, points used for the reward cannot be returned to the account.
async redeemLoyaltyReward(
rewardId: string,
body: RedeemLoyaltyRewardRequest,
requestOptions?: RequestOptions
): Promise<ApiResponse<RedeemLoyaltyRewardResponse>>
Parameter | Type | Tags | Description |
---|---|---|---|
rewardId |
string |
Template, Required | The ID of the loyalty reward to redeem. |
body |
RedeemLoyaltyRewardRequest |
Body, Required | An object containing the fields to POST for the request. See the corresponding object definition for field details. |
requestOptions |
RequestOptions | undefined |
Optional | Pass additional request options. |
const rewardId = 'reward_id4';
const contentType = null;
const body: RedeemLoyaltyRewardRequest = {
idempotencyKey: '98adc7f7-6963-473b-b29c-f3c9cdd7d994',
locationId: 'P034NEENMD09F',
};
try {
const { result, ...httpResponse } = await loyaltyApi.redeemLoyaltyReward(rewardId, body);
// Get more response info...
// const { statusCode, headers } = httpResponse;
} catch(error) {
if (error instanceof ApiError) {
const errors = error.result;
// const { statusCode, headers } = error;
}
}