Loyalty

const loyaltyApi = client.loyaltyApi;

Class Name

LoyaltyApi

Methods

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

Create Loyalty Account

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>>

Parameters

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.

Response Type

CreateLoyaltyAccountResponse

Example Usage

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;
  }
}

Search Loyalty Accounts

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>>

Parameters

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.

Response Type

SearchLoyaltyAccountsResponse

Example Usage

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;
  }
}

Retrieve Loyalty Account

Retrieves a loyalty account.

async retrieveLoyaltyAccount(
  accountId: string,
  requestOptions?: RequestOptions
): Promise<ApiResponse<RetrieveLoyaltyAccountResponse>>

Parameters

Parameter	Type	Tags	Description
`accountId`	`string`	Template, Required	The ID of the loyalty account to retrieve.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

RetrieveLoyaltyAccountResponse

Example Usage

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;
  }
}

Accumulate Loyalty Points

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.

async accumulateLoyaltyPoints(
  accountId: string,
  body: AccumulateLoyaltyPointsRequest,
  requestOptions?: RequestOptions
): Promise<ApiResponse<AccumulateLoyaltyPointsResponse>>

Parameters

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.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

AccumulateLoyaltyPointsResponse

Example Usage

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;
  }
}

Adjust Loyalty Points

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>>

Parameters

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.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

AdjustLoyaltyPointsResponse

Example Usage

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;
  }
}

Search Loyalty Events

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>>

Parameters

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.

Response Type

SearchLoyaltyEventsResponse

Example Usage

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;
  }
}

List Loyalty Programs

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>>

Parameters

Parameter	Type	Tags	Description
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

ListLoyaltyProgramsResponse

Example Usage

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;
  }
}

Retrieve Loyalty Program

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>>

Parameters

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.

Response Type

RetrieveLoyaltyProgramResponse

Example Usage

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;
  }
}

Calculate Loyalty Points

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, the tax_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.

async calculateLoyaltyPoints(
  programId: string,
  body: CalculateLoyaltyPointsRequest,
  requestOptions?: RequestOptions
): Promise<ApiResponse<CalculateLoyaltyPointsResponse>>

Parameters

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.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

CalculateLoyaltyPointsResponse

Example Usage

const programId = 'program_id0';
const contentType = null;
const body: CalculateLoyaltyPointsRequest = {};
body.orderId = 'RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY';
body.loyaltyAccountId = '79b807d2-d786-46a9-933b-918028d7a8c5';

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;
  }
}

List Loyalty Promotions

Lists the loyalty promotions associated with a loyalty program. Results are sorted by the created_at date in descending order (newest to oldest).

async listLoyaltyPromotions(
  programId: string,
  status?: string,
  cursor?: string,
  limit?: number,
  requestOptions?: RequestOptions
): Promise<ApiResponse<ListLoyaltyPromotionsResponse>>

Parameters

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 \| undefined`	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 \| undefined`	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`	`number \| undefined`	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.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

ListLoyaltyPromotionsResponse

Example Usage

const programId = 'program_id0';
try {
  const { result, ...httpResponse } = await loyaltyApi.listLoyaltyPromotions(programId);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch(error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Create Loyalty Promotion

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.

async createLoyaltyPromotion(
  programId: string,
  body: CreateLoyaltyPromotionRequest,
  requestOptions?: RequestOptions
): Promise<ApiResponse<CreateLoyaltyPromotionResponse>>

Parameters

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.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

CreateLoyaltyPromotionResponse

Example Usage

const programId = 'program_id0';
const contentType = null;
const bodyLoyaltyPromotionIncentivePointsMultiplierData: LoyaltyPromotionIncentivePointsMultiplierData = {
  pointsMultiplier: 3,
};

const bodyLoyaltyPromotionIncentive: LoyaltyPromotionIncentive = {
  type: 'POINTS_MULTIPLIER',
};
bodyLoyaltyPromotionIncentive.pointsMultiplierData = bodyLoyaltyPromotionIncentivePointsMultiplierData;

const bodyLoyaltyPromotionAvailableTimeTimePeriods: string[] = ['BEGIN:VEVENT\nDTSTART:20220816T160000\nDURATION:PT2H\nRRULE:FREQ=WEEKLY;BYDAY=TU\nEND:VEVENT'];
const bodyLoyaltyPromotionAvailableTime: LoyaltyPromotionAvailableTimeData = {
  timePeriods: bodyLoyaltyPromotionAvailableTimeTimePeriods,
};

const bodyLoyaltyPromotionTriggerLimit: LoyaltyPromotionTriggerLimit = {
  times: 1,
};
bodyLoyaltyPromotionTriggerLimit.interval = 'DAY';

const bodyLoyaltyPromotionMinimumSpendAmountMoney: Money = {};
bodyLoyaltyPromotionMinimumSpendAmountMoney.amount = BigInt(2000);
bodyLoyaltyPromotionMinimumSpendAmountMoney.currency = 'USD';

const bodyLoyaltyPromotionQualifyingCategoryIds: string[] = ['XTQPYLR3IIU9C44VRCB3XD12'];
const bodyLoyaltyPromotion: LoyaltyPromotion = {
  name: 'Tuesday Happy Hour Promo',
  incentive: bodyLoyaltyPromotionIncentive,
  availableTime: bodyLoyaltyPromotionAvailableTime,
};
bodyLoyaltyPromotion.triggerLimit = bodyLoyaltyPromotionTriggerLimit;
bodyLoyaltyPromotion.minimumSpendAmountMoney = bodyLoyaltyPromotionMinimumSpendAmountMoney;
bodyLoyaltyPromotion.qualifyingCategoryIds = bodyLoyaltyPromotionQualifyingCategoryIds;

const body: CreateLoyaltyPromotionRequest = {
  loyaltyPromotion: bodyLoyaltyPromotion,
  idempotencyKey: 'ec78c477-b1c3-4899-a209-a4e71337c996',
};

try {
  const { result, ...httpResponse } = await loyaltyApi.createLoyaltyPromotion(programId, body);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch(error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Retrieve Loyalty Promotion

Retrieves a loyalty promotion.

async retrieveLoyaltyPromotion(
  promotionId: string,
  programId: string,
  requestOptions?: RequestOptions
): Promise<ApiResponse<RetrieveLoyaltyPromotionResponse>>

Parameters

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.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

RetrieveLoyaltyPromotionResponse

Example Usage

const promotionId = 'promotion_id0';
const programId = 'program_id0';
try {
  const { result, ...httpResponse } = await loyaltyApi.retrieveLoyaltyPromotion(promotionId, programId);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch(error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Cancel Loyalty Promotion

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

async cancelLoyaltyPromotion(
  promotionId: string,
  programId: string,
  requestOptions?: RequestOptions
): Promise<ApiResponse<CancelLoyaltyPromotionResponse>>

Parameters

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.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

CancelLoyaltyPromotionResponse

Example Usage

const promotionId = 'promotion_id0';
const programId = 'program_id0';
try {
  const { result, ...httpResponse } = await loyaltyApi.cancelLoyaltyPromotion(promotionId, programId);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch(error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Create Loyalty Reward

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>>

Parameters

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.

Response Type

CreateLoyaltyRewardResponse

Example Usage

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;
  }
}

Search Loyalty Rewards

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>>

Parameters

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.

Response Type

SearchLoyaltyRewardsResponse

Example Usage

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;
  }
}

Delete Loyalty Reward

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>>

Parameters

Parameter	Type	Tags	Description
`rewardId`	`string`	Template, Required	The ID of the loyalty reward to delete.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

DeleteLoyaltyRewardResponse

Example Usage

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;
  }
}

Retrieve Loyalty Reward

Retrieves a loyalty reward.

async retrieveLoyaltyReward(
  rewardId: string,
  requestOptions?: RequestOptions
): Promise<ApiResponse<RetrieveLoyaltyRewardResponse>>

Parameters

Parameter	Type	Tags	Description
`rewardId`	`string`	Template, Required	The ID of the loyalty reward to retrieve.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

RetrieveLoyaltyRewardResponse

Example Usage

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;
  }
}

Redeem Loyalty Reward

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>>

Parameters

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.

Response Type

RedeemLoyaltyRewardResponse

Example Usage

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;
  }
}

Files

loyalty.md

Latest commit

History

loyalty.md

File metadata and controls

Loyalty

Class Name

Methods

Create Loyalty Account

Parameters

Response Type

Example Usage

Search Loyalty Accounts

Parameters

Response Type

Example Usage

Retrieve Loyalty Account

Parameters

Response Type

Example Usage

Accumulate Loyalty Points

Parameters

Response Type

Example Usage

Adjust Loyalty Points

Parameters

Response Type

Example Usage

Search Loyalty Events

Parameters

Response Type

Example Usage

List Loyalty Programs

Parameters

Response Type

Example Usage

Retrieve Loyalty Program

Parameters

Response Type

Example Usage

Calculate Loyalty Points

Parameters

Response Type

Example Usage

List Loyalty Promotions

Parameters

Response Type

Example Usage

Create Loyalty Promotion

Parameters

Response Type

Example Usage

Retrieve Loyalty Promotion

Parameters

Response Type

Example Usage

Cancel Loyalty Promotion

Parameters

Response Type

Example Usage

Create Loyalty Reward

Parameters

Response Type

Example Usage

Search Loyalty Rewards

Parameters

Response Type

Example Usage

Delete Loyalty Reward

Parameters

Response Type

Example Usage

Retrieve Loyalty Reward

Parameters

Response Type

Example Usage

Redeem Loyalty Reward

Parameters

Response Type