LoyaltyApi loyaltyApi = client.getLoyaltyApi();
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
- List Loyalty Promotions
- Create Loyalty Promotion
- Retrieve Loyalty Promotion
- Cancel Loyalty Promotion
- 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.
CompletableFuture<CreateLoyaltyAccountResponse> createLoyaltyAccountAsync(
final CreateLoyaltyAccountRequest body)
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. |
CreateLoyaltyAccountRequest body = new CreateLoyaltyAccountRequest.Builder(
new LoyaltyAccount.Builder(
"d619f755-2d17-41f3-990d-c04ecedd64dd"
)
.mapping(new LoyaltyAccountMapping.Builder()
.phoneNumber("+14155551234")
.build())
.build(),
"ec78c477-b1c3-4899-a209-a4e71337c996"
)
.build();
loyaltyApi.createLoyaltyAccountAsync(body).thenAccept(result -> {
// TODO success callback handler
System.out.println(result);
}).exceptionally(exception -> {
// TODO failure callback handler
exception.printStackTrace();
return null;
});
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.
CompletableFuture<SearchLoyaltyAccountsResponse> searchLoyaltyAccountsAsync(
final SearchLoyaltyAccountsRequest body)
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. |
SearchLoyaltyAccountsRequest body = new SearchLoyaltyAccountsRequest.Builder()
.query(new SearchLoyaltyAccountsRequestLoyaltyAccountQuery.Builder()
.mappings(Arrays.asList(
new LoyaltyAccountMapping.Builder()
.phoneNumber("+14155551234")
.build()
))
.build())
.limit(10)
.build();
loyaltyApi.searchLoyaltyAccountsAsync(body).thenAccept(result -> {
// TODO success callback handler
System.out.println(result);
}).exceptionally(exception -> {
// TODO failure callback handler
exception.printStackTrace();
return null;
});
Retrieves a loyalty account.
CompletableFuture<RetrieveLoyaltyAccountResponse> retrieveLoyaltyAccountAsync(
final String accountId)
Parameter | Type | Tags | Description |
---|---|---|---|
accountId |
String |
Template, Required | The ID of the loyalty account to retrieve. |
RetrieveLoyaltyAccountResponse
String accountId = "account_id2";
loyaltyApi.retrieveLoyaltyAccountAsync(accountId).thenAccept(result -> {
// TODO success callback handler
System.out.println(result);
}).exceptionally(exception -> {
// TODO failure callback handler
exception.printStackTrace();
return null;
});
Adds points earned from a purchase to a loyalty account.
-
If you are using the Orders API to manage orders, provide the
order_id
. Square reads the order to compute the points earned from both the base loyalty program and an associated loyalty promotion. For purchases that qualify for multiple accrual rules, Square computes points based on the accrual rule that grants the most points. For purchases that qualify for multiple promotions, Square computes points based on the most recently created promotion. A purchase must first qualify for program points to be eligible for promotion points. -
If you are not using the Orders API to manage orders, provide
points
with the number of points to add. You must first perform a client-side computation of the points earned from the loyalty program and loyalty promotion. For spend-based and visit-based programs, you can call CalculateLoyaltyPoints to compute the points earned from the base loyalty program. For information about computing points earned from a loyalty promotion, see Calculating promotion points.
CompletableFuture<AccumulateLoyaltyPointsResponse> accumulateLoyaltyPointsAsync(
final String accountId,
final AccumulateLoyaltyPointsRequest body)
Parameter | Type | Tags | Description |
---|---|---|---|
accountId |
String |
Template, Required | The ID of the target loyalty account. |
body |
AccumulateLoyaltyPointsRequest |
Body, Required | An object containing the fields to POST for the request. See the corresponding object definition for field details. |
AccumulateLoyaltyPointsResponse
String accountId = "account_id2";
AccumulateLoyaltyPointsRequest body = new AccumulateLoyaltyPointsRequest.Builder(
new LoyaltyEventAccumulatePoints.Builder()
.orderId("RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY")
.build(),
"58b90739-c3e8-4b11-85f7-e636d48d72cb",
"P034NEENMD09F"
)
.build();
loyaltyApi.accumulateLoyaltyPointsAsync(accountId, body).thenAccept(result -> {
// TODO success callback handler
System.out.println(result);
}).exceptionally(exception -> {
// TODO failure callback handler
exception.printStackTrace();
return null;
});
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.
CompletableFuture<AdjustLoyaltyPointsResponse> adjustLoyaltyPointsAsync(
final String accountId,
final AdjustLoyaltyPointsRequest body)
Parameter | Type | Tags | Description |
---|---|---|---|
accountId |
String |
Template, Required | The ID of the target loyalty account. |
body |
AdjustLoyaltyPointsRequest |
Body, Required | An object containing the fields to POST for the request. See the corresponding object definition for field details. |
String accountId = "account_id2";
AdjustLoyaltyPointsRequest body = new AdjustLoyaltyPointsRequest.Builder(
"bc29a517-3dc9-450e-aa76-fae39ee849d1",
new LoyaltyEventAdjustPoints.Builder(
10
)
.reason("Complimentary points")
.build()
)
.build();
loyaltyApi.adjustLoyaltyPointsAsync(accountId, body).thenAccept(result -> {
// TODO success callback handler
System.out.println(result);
}).exceptionally(exception -> {
// TODO failure callback handler
exception.printStackTrace();
return null;
});
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.
CompletableFuture<SearchLoyaltyEventsResponse> searchLoyaltyEventsAsync(
final SearchLoyaltyEventsRequest body)
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. |
SearchLoyaltyEventsRequest body = new SearchLoyaltyEventsRequest.Builder()
.query(new LoyaltyEventQuery.Builder()
.filter(new LoyaltyEventFilter.Builder()
.orderFilter(new LoyaltyEventOrderFilter.Builder(
"PyATxhYLfsMqpVkcKJITPydgEYfZY"
)
.build())
.build())
.build())
.limit(30)
.build();
loyaltyApi.searchLoyaltyEventsAsync(body).thenAccept(result -> {
// TODO success callback handler
System.out.println(result);
}).exceptionally(exception -> {
// TODO failure callback handler
exception.printStackTrace();
return null;
});
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
.
CompletableFuture<ListLoyaltyProgramsResponse> listLoyaltyProgramsAsync()
loyaltyApi.listLoyaltyProgramsAsync().thenAccept(result -> {
// TODO success callback handler
System.out.println(result);
}).exceptionally(exception -> {
// TODO failure callback handler
exception.printStackTrace();
return null;
});
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.
CompletableFuture<RetrieveLoyaltyProgramResponse> retrieveLoyaltyProgramAsync(
final String programId)
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. |
RetrieveLoyaltyProgramResponse
String programId = "program_id0";
loyaltyApi.retrieveLoyaltyProgramAsync(programId).thenAccept(result -> {
// TODO success callback handler
System.out.println(result);
}).exceptionally(exception -> {
// TODO failure callback handler
exception.printStackTrace();
return null;
});
Calculates the number of points a buyer can earn from a purchase. Applications might call this endpoint to display the points to the buyer.
-
If you are using the Orders API to manage orders, provide the
order_id
and (optional)loyalty_account_id
. Square reads the order to compute the points earned from the base loyalty program and an associated loyalty promotion. -
If you are not using the Orders API to manage orders, provide
transaction_amount_money
with the purchase amount. Square uses this amount to calculate the points earned from the base loyalty program, but not points earned from a loyalty promotion. For spend-based and visit-based programs, thetax_mode
setting of the accrual rule indicates how taxes should be treated for loyalty points accrual. If the purchase qualifies for program points, call ListLoyaltyPromotions and perform a client-side computation to calculate whether the purchase also qualifies for promotion points. For more information, see Calculating promotion points.
CompletableFuture<CalculateLoyaltyPointsResponse> calculateLoyaltyPointsAsync(
final String programId,
final CalculateLoyaltyPointsRequest body)
Parameter | Type | Tags | Description |
---|---|---|---|
programId |
String |
Template, Required | The ID of the loyalty program, 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. |
CalculateLoyaltyPointsResponse
String programId = "program_id0";
CalculateLoyaltyPointsRequest body = new CalculateLoyaltyPointsRequest.Builder()
.orderId("RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY")
.loyaltyAccountId("79b807d2-d786-46a9-933b-918028d7a8c5")
.build();
loyaltyApi.calculateLoyaltyPointsAsync(programId, body).thenAccept(result -> {
// TODO success callback handler
System.out.println(result);
}).exceptionally(exception -> {
// TODO failure callback handler
exception.printStackTrace();
return null;
});
Lists the loyalty promotions associated with a loyalty program.
Results are sorted by the created_at
date in descending order (newest to oldest).
CompletableFuture<ListLoyaltyPromotionsResponse> listLoyaltyPromotionsAsync(
final String programId,
final String status,
final String cursor,
final Integer limit)
Parameter | Type | Tags | Description |
---|---|---|---|
programId |
String |
Template, Required | The ID of the base loyalty program. To get the program ID, call RetrieveLoyaltyProgram using the main keyword. |
status |
String |
Query, Optional | The status to filter the results by. If a status is provided, only loyalty promotions with the specified status are returned. Otherwise, all loyalty promotions associated with the loyalty program are returned. |
cursor |
String |
Query, Optional | The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see Pagination. |
limit |
Integer |
Query, Optional | The maximum number of results to return in a single paged response. The minimum value is 1 and the maximum value is 30. The default value is 30. For more information, see Pagination. |
String programId = "program_id0";
loyaltyApi.listLoyaltyPromotionsAsync(programId, null, null, null).thenAccept(result -> {
// TODO success callback handler
System.out.println(result);
}).exceptionally(exception -> {
// TODO failure callback handler
exception.printStackTrace();
return null;
});
Creates a loyalty promotion for a loyalty program. A loyalty promotion enables buyers to earn points in addition to those earned from the base loyalty program.
This endpoint sets the loyalty promotion to the ACTIVE
or SCHEDULED
status, depending on the
available_time
setting. A loyalty program can have a maximum of 10 loyalty promotions with an
ACTIVE
or SCHEDULED
status.
CompletableFuture<CreateLoyaltyPromotionResponse> createLoyaltyPromotionAsync(
final String programId,
final CreateLoyaltyPromotionRequest body)
Parameter | Type | Tags | Description |
---|---|---|---|
programId |
String |
Template, Required | The ID of the loyalty program to associate with the promotion. To get the program ID, call RetrieveLoyaltyProgram using the main keyword. |
body |
CreateLoyaltyPromotionRequest |
Body, Required | An object containing the fields to POST for the request. See the corresponding object definition for field details. |
CreateLoyaltyPromotionResponse
String programId = "program_id0";
CreateLoyaltyPromotionRequest body = new CreateLoyaltyPromotionRequest.Builder(
new LoyaltyPromotion.Builder(
"Tuesday Happy Hour Promo",
new LoyaltyPromotionIncentive.Builder(
"POINTS_MULTIPLIER"
)
.pointsMultiplierData(new LoyaltyPromotionIncentivePointsMultiplierData.Builder()
.multiplier("3.0")
.build())
.build(),
new LoyaltyPromotionAvailableTimeData.Builder(
Arrays.asList(
"BEGIN:VEVENT\nDTSTART:20220816T160000\nDURATION:PT2H\nRRULE:FREQ=WEEKLY;BYDAY=TU\nEND:VEVENT"
)
)
.build()
)
.triggerLimit(new LoyaltyPromotionTriggerLimit.Builder(
1
)
.interval("DAY")
.build())
.minimumSpendAmountMoney(new Money.Builder()
.amount(2000L)
.currency("USD")
.build())
.qualifyingCategoryIds(Arrays.asList(
"XTQPYLR3IIU9C44VRCB3XD12"
))
.build(),
"ec78c477-b1c3-4899-a209-a4e71337c996"
)
.build();
loyaltyApi.createLoyaltyPromotionAsync(programId, body).thenAccept(result -> {
// TODO success callback handler
System.out.println(result);
}).exceptionally(exception -> {
// TODO failure callback handler
exception.printStackTrace();
return null;
});
Retrieves a loyalty promotion.
CompletableFuture<RetrieveLoyaltyPromotionResponse> retrieveLoyaltyPromotionAsync(
final String promotionId,
final String programId)
Parameter | Type | Tags | Description |
---|---|---|---|
promotionId |
String |
Template, Required | The ID of the loyalty promotion to retrieve. |
programId |
String |
Template, Required | The ID of the base loyalty program. To get the program ID, call RetrieveLoyaltyProgram using the main keyword. |
RetrieveLoyaltyPromotionResponse
String promotionId = "promotion_id0";
String programId = "program_id0";
loyaltyApi.retrieveLoyaltyPromotionAsync(promotionId, programId).thenAccept(result -> {
// TODO success callback handler
System.out.println(result);
}).exceptionally(exception -> {
// TODO failure callback handler
exception.printStackTrace();
return null;
});
Cancels a loyalty promotion. Use this endpoint to cancel an ACTIVE
promotion earlier than the
end date, cancel an ACTIVE
promotion when an end date is not specified, or cancel a SCHEDULED
promotion.
Because updating a promotion is not supported, you can also use this endpoint to cancel a promotion before
you create a new one.
This endpoint sets the loyalty promotion to the CANCELED
state
CompletableFuture<CancelLoyaltyPromotionResponse> cancelLoyaltyPromotionAsync(
final String promotionId,
final String programId)
Parameter | Type | Tags | Description |
---|---|---|---|
promotionId |
String |
Template, Required | The ID of the loyalty promotion to cancel. You can cancel a promotion that has an ACTIVE or SCHEDULED status. |
programId |
String |
Template, Required | The ID of the base loyalty program. |
CancelLoyaltyPromotionResponse
String promotionId = "promotion_id0";
String programId = "program_id0";
loyaltyApi.cancelLoyaltyPromotionAsync(promotionId, programId).thenAccept(result -> {
// TODO success callback handler
System.out.println(result);
}).exceptionally(exception -> {
// TODO failure callback handler
exception.printStackTrace();
return null;
});
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.
CompletableFuture<CreateLoyaltyRewardResponse> createLoyaltyRewardAsync(
final CreateLoyaltyRewardRequest body)
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. |
CreateLoyaltyRewardRequest body = new CreateLoyaltyRewardRequest.Builder(
new LoyaltyReward.Builder(
"5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd",
"e1b39225-9da5-43d1-a5db-782cdd8ad94f"
)
.orderId("RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY")
.build(),
"18c2e5ea-a620-4b1f-ad60-7b167285e451"
)
.build();
loyaltyApi.createLoyaltyRewardAsync(body).thenAccept(result -> {
// TODO success callback handler
System.out.println(result);
}).exceptionally(exception -> {
// TODO failure callback handler
exception.printStackTrace();
return null;
});
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.
CompletableFuture<SearchLoyaltyRewardsResponse> searchLoyaltyRewardsAsync(
final SearchLoyaltyRewardsRequest body)
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. |
SearchLoyaltyRewardsRequest body = new SearchLoyaltyRewardsRequest.Builder()
.query(new SearchLoyaltyRewardsRequestLoyaltyRewardQuery.Builder(
"5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd"
)
.build())
.limit(10)
.build();
loyaltyApi.searchLoyaltyRewardsAsync(body).thenAccept(result -> {
// TODO success callback handler
System.out.println(result);
}).exceptionally(exception -> {
// TODO failure callback handler
exception.printStackTrace();
return null;
});
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).
CompletableFuture<DeleteLoyaltyRewardResponse> deleteLoyaltyRewardAsync(
final String rewardId)
Parameter | Type | Tags | Description |
---|---|---|---|
rewardId |
String |
Template, Required | The ID of the loyalty reward to delete. |
String rewardId = "reward_id4";
loyaltyApi.deleteLoyaltyRewardAsync(rewardId).thenAccept(result -> {
// TODO success callback handler
System.out.println(result);
}).exceptionally(exception -> {
// TODO failure callback handler
exception.printStackTrace();
return null;
});
Retrieves a loyalty reward.
CompletableFuture<RetrieveLoyaltyRewardResponse> retrieveLoyaltyRewardAsync(
final String rewardId)
Parameter | Type | Tags | Description |
---|---|---|---|
rewardId |
String |
Template, Required | The ID of the loyalty reward to retrieve. |
String rewardId = "reward_id4";
loyaltyApi.retrieveLoyaltyRewardAsync(rewardId).thenAccept(result -> {
// TODO success callback handler
System.out.println(result);
}).exceptionally(exception -> {
// TODO failure callback handler
exception.printStackTrace();
return null;
});
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.
CompletableFuture<RedeemLoyaltyRewardResponse> redeemLoyaltyRewardAsync(
final String rewardId,
final RedeemLoyaltyRewardRequest body)
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. |
String rewardId = "reward_id4";
RedeemLoyaltyRewardRequest body = new RedeemLoyaltyRewardRequest.Builder(
"98adc7f7-6963-473b-b29c-f3c9cdd7d994",
"P034NEENMD09F"
)
.build();
loyaltyApi.redeemLoyaltyRewardAsync(rewardId, body).thenAccept(result -> {
// TODO success callback handler
System.out.println(result);
}).exceptionally(exception -> {
// TODO failure callback handler
exception.printStackTrace();
return null;
});