Skip to content
This repository has been archived by the owner on Apr 23, 2021. It is now read-only.

Latest commit

 

History

History
664 lines (438 loc) · 23.9 KB

LoyaltyApi.md

File metadata and controls

664 lines (438 loc) · 23.9 KB
Raw

SquareConnect.LoyaltyApi

All URIs are relative to https://connect.squareup.com

Method HTTP request Description
accumulateLoyaltyPoints POST /v2/loyalty/accounts/{account_id}/accumulate AccumulateLoyaltyPoints
adjustLoyaltyPoints POST /v2/loyalty/accounts/{account_id}/adjust AdjustLoyaltyPoints
calculateLoyaltyPoints POST /v2/loyalty/programs/{program_id}/calculate CalculateLoyaltyPoints
createLoyaltyAccount POST /v2/loyalty/accounts CreateLoyaltyAccount
createLoyaltyReward POST /v2/loyalty/rewards CreateLoyaltyReward
deleteLoyaltyReward DELETE /v2/loyalty/rewards/{reward_id} DeleteLoyaltyReward
listLoyaltyPrograms GET /v2/loyalty/programs ListLoyaltyPrograms
redeemLoyaltyReward POST /v2/loyalty/rewards/{reward_id}/redeem RedeemLoyaltyReward
retrieveLoyaltyAccount GET /v2/loyalty/accounts/{account_id} RetrieveLoyaltyAccount
retrieveLoyaltyReward GET /v2/loyalty/rewards/{reward_id} RetrieveLoyaltyReward
searchLoyaltyAccounts POST /v2/loyalty/accounts/search SearchLoyaltyAccounts
searchLoyaltyEvents POST /v2/loyalty/events/search SearchLoyaltyEvents
searchLoyaltyRewards POST /v2/loyalty/rewards/search SearchLoyaltyRewards

accumulateLoyaltyPoints

Note: This endpoint is in beta.

AccumulateLoyaltyPointsResponse accumulateLoyaltyPoints(accountId, body)

AccumulateLoyaltyPoints

Adds points 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 call CalculateLoyaltyPoints to compute the points. For more information, see Loyalty Program Overview. You then provide the points in a request to this endpoint.

Example

var SquareConnect = require('square-connect');
var defaultClient = SquareConnect.ApiClient.instance;

// Configure OAuth2 access token for authorization: oauth2
var oauth2 = defaultClient.authentications['oauth2'];
oauth2.accessToken = 'YOUR ACCESS TOKEN';

var apiInstance = new SquareConnect.LoyaltyApi();

var accountId = SquareConnect.LoyaltyApi.constructFromObject({}); // String | The `loyalty account` ID to which to add the points.

var body = SquareConnect.LoyaltyApi.constructFromObject({}); // AccumulateLoyaltyPointsRequest | An object containing the fields to POST for the request.  See the corresponding object definition for field details.

apiInstance.accumulateLoyaltyPoints(accountId, body).then(function(data) {
  console.log('API called successfully. Returned data: ' + data);
}, function(error) {
  console.error(error);
});

Parameters

Name Type Description Notes
accountId String The `loyalty account` ID to which to add the points.
body AccumulateLoyaltyPointsRequest An object containing the fields to POST for the request. See the corresponding object definition for field details.

Return type

AccumulateLoyaltyPointsResponse

Authorization

oauth2

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

adjustLoyaltyPoints

Note: This endpoint is in beta.

AdjustLoyaltyPointsResponse adjustLoyaltyPoints(accountId, body)

AdjustLoyaltyPoints

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.

Example

var SquareConnect = require('square-connect');
var defaultClient = SquareConnect.ApiClient.instance;

// Configure OAuth2 access token for authorization: oauth2
var oauth2 = defaultClient.authentications['oauth2'];
oauth2.accessToken = 'YOUR ACCESS TOKEN';

var apiInstance = new SquareConnect.LoyaltyApi();

var accountId = SquareConnect.LoyaltyApi.constructFromObject({}); // String | The ID of the `loyalty account` in which to adjust the points.

var body = SquareConnect.LoyaltyApi.constructFromObject({}); // AdjustLoyaltyPointsRequest | An object containing the fields to POST for the request.  See the corresponding object definition for field details.

apiInstance.adjustLoyaltyPoints(accountId, body).then(function(data) {
  console.log('API called successfully. Returned data: ' + data);
}, function(error) {
  console.error(error);
});

Parameters

Name Type Description Notes
accountId String The ID of the `loyalty account` in which to adjust the points.
body AdjustLoyaltyPointsRequest An object containing the fields to POST for the request. See the corresponding object definition for field details.

Return type

AdjustLoyaltyPointsResponse

Authorization

oauth2

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

calculateLoyaltyPoints

Note: This endpoint is in beta.

CalculateLoyaltyPointsResponse calculateLoyaltyPoints(programId, body)

CalculateLoyaltyPoints

Calculates the points a purchase earns. - If you are using the Orders API to manage orders, you provide `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.

Example

var SquareConnect = require('square-connect');
var defaultClient = SquareConnect.ApiClient.instance;

// Configure OAuth2 access token for authorization: oauth2
var oauth2 = defaultClient.authentications['oauth2'];
oauth2.accessToken = 'YOUR ACCESS TOKEN';

var apiInstance = new SquareConnect.LoyaltyApi();

var programId = SquareConnect.LoyaltyApi.constructFromObject({}); // String | The `loyalty program` ID, which defines the rules for accruing points.

var body = SquareConnect.LoyaltyApi.constructFromObject({}); // CalculateLoyaltyPointsRequest | An object containing the fields to POST for the request.  See the corresponding object definition for field details.

apiInstance.calculateLoyaltyPoints(programId, body).then(function(data) {
  console.log('API called successfully. Returned data: ' + data);
}, function(error) {
  console.error(error);
});

Parameters

Name Type Description Notes
programId String The `loyalty program` ID, which defines the rules for accruing points.
body CalculateLoyaltyPointsRequest An object containing the fields to POST for the request. See the corresponding object definition for field details.

Return type

CalculateLoyaltyPointsResponse

Authorization

oauth2

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

createLoyaltyAccount

Note: This endpoint is in beta.

CreateLoyaltyAccountResponse createLoyaltyAccount(body)

CreateLoyaltyAccount

Creates a loyalty account.

Example

var SquareConnect = require('square-connect');
var defaultClient = SquareConnect.ApiClient.instance;

// Configure OAuth2 access token for authorization: oauth2
var oauth2 = defaultClient.authentications['oauth2'];
oauth2.accessToken = 'YOUR ACCESS TOKEN';

var apiInstance = new SquareConnect.LoyaltyApi();

var body = SquareConnect.LoyaltyApi.constructFromObject({}); // CreateLoyaltyAccountRequest | An object containing the fields to POST for the request.  See the corresponding object definition for field details.

apiInstance.createLoyaltyAccount(body).then(function(data) {
  console.log('API called successfully. Returned data: ' + data);
}, function(error) {
  console.error(error);
});

Parameters

Name Type Description Notes
body CreateLoyaltyAccountRequest An object containing the fields to POST for the request. See the corresponding object definition for field details.

Return type

CreateLoyaltyAccountResponse

Authorization

oauth2

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

createLoyaltyReward

Note: This endpoint is in beta.

CreateLoyaltyRewardResponse createLoyaltyReward(body)

CreateLoyaltyReward

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.

Example

var SquareConnect = require('square-connect');
var defaultClient = SquareConnect.ApiClient.instance;

// Configure OAuth2 access token for authorization: oauth2
var oauth2 = defaultClient.authentications['oauth2'];
oauth2.accessToken = 'YOUR ACCESS TOKEN';

var apiInstance = new SquareConnect.LoyaltyApi();

var body = SquareConnect.LoyaltyApi.constructFromObject({}); // CreateLoyaltyRewardRequest | An object containing the fields to POST for the request.  See the corresponding object definition for field details.

apiInstance.createLoyaltyReward(body).then(function(data) {
  console.log('API called successfully. Returned data: ' + data);
}, function(error) {
  console.error(error);
});

Parameters

Name Type Description Notes
body CreateLoyaltyRewardRequest An object containing the fields to POST for the request. See the corresponding object definition for field details.

Return type

CreateLoyaltyRewardResponse

Authorization

oauth2

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

deleteLoyaltyReward

Note: This endpoint is in beta.

DeleteLoyaltyRewardResponse deleteLoyaltyReward(rewardId)

DeleteLoyaltyReward

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

Example

var SquareConnect = require('square-connect');
var defaultClient = SquareConnect.ApiClient.instance;

// Configure OAuth2 access token for authorization: oauth2
var oauth2 = defaultClient.authentications['oauth2'];
oauth2.accessToken = 'YOUR ACCESS TOKEN';

var apiInstance = new SquareConnect.LoyaltyApi();

var rewardId = SquareConnect.LoyaltyApi.constructFromObject({}); // String | The ID of the `loyalty reward` to delete.

apiInstance.deleteLoyaltyReward(rewardId).then(function(data) {
  console.log('API called successfully. Returned data: ' + data);
}, function(error) {
  console.error(error);
});

Parameters

Name Type Description Notes
rewardId String The ID of the `loyalty reward` to delete.

Return type

DeleteLoyaltyRewardResponse

Authorization

oauth2

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

listLoyaltyPrograms

Note: This endpoint is in beta.

ListLoyaltyProgramsResponse listLoyaltyPrograms()

ListLoyaltyPrograms

Returns a list of loyalty programs in the seller's account. Currently, a seller can only have one loyalty program.

Example

var SquareConnect = require('square-connect');
var defaultClient = SquareConnect.ApiClient.instance;

// Configure OAuth2 access token for authorization: oauth2
var oauth2 = defaultClient.authentications['oauth2'];
oauth2.accessToken = 'YOUR ACCESS TOKEN';

var apiInstance = new SquareConnect.LoyaltyApi();
apiInstance.listLoyaltyPrograms().then(function(data) {
  console.log('API called successfully. Returned data: ' + data);
}, function(error) {
  console.error(error);
});

Parameters

This endpoint does not need any parameter.

Return type

ListLoyaltyProgramsResponse

Authorization

oauth2

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

redeemLoyaltyReward

Note: This endpoint is in beta.

RedeemLoyaltyRewardResponse redeemLoyaltyReward(rewardId, body)

RedeemLoyaltyReward

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.

Example

var SquareConnect = require('square-connect');
var defaultClient = SquareConnect.ApiClient.instance;

// Configure OAuth2 access token for authorization: oauth2
var oauth2 = defaultClient.authentications['oauth2'];
oauth2.accessToken = 'YOUR ACCESS TOKEN';

var apiInstance = new SquareConnect.LoyaltyApi();

var rewardId = SquareConnect.LoyaltyApi.constructFromObject({}); // String | The ID of the `loyalty reward` to redeem.

var body = SquareConnect.LoyaltyApi.constructFromObject({}); // RedeemLoyaltyRewardRequest | An object containing the fields to POST for the request.  See the corresponding object definition for field details.

apiInstance.redeemLoyaltyReward(rewardId, body).then(function(data) {
  console.log('API called successfully. Returned data: ' + data);
}, function(error) {
  console.error(error);
});

Parameters

Name Type Description Notes
rewardId String The ID of the `loyalty reward` to redeem.
body RedeemLoyaltyRewardRequest An object containing the fields to POST for the request. See the corresponding object definition for field details.

Return type

RedeemLoyaltyRewardResponse

Authorization

oauth2

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

retrieveLoyaltyAccount

Note: This endpoint is in beta.

RetrieveLoyaltyAccountResponse retrieveLoyaltyAccount(accountId)

RetrieveLoyaltyAccount

Retrieves a loyalty account.

Example

var SquareConnect = require('square-connect');
var defaultClient = SquareConnect.ApiClient.instance;

// Configure OAuth2 access token for authorization: oauth2
var oauth2 = defaultClient.authentications['oauth2'];
oauth2.accessToken = 'YOUR ACCESS TOKEN';

var apiInstance = new SquareConnect.LoyaltyApi();

var accountId = SquareConnect.LoyaltyApi.constructFromObject({}); // String | The ID of the `loyalty account` to retrieve.

apiInstance.retrieveLoyaltyAccount(accountId).then(function(data) {
  console.log('API called successfully. Returned data: ' + data);
}, function(error) {
  console.error(error);
});

Parameters

Name Type Description Notes
accountId String The ID of the `loyalty account` to retrieve.

Return type

RetrieveLoyaltyAccountResponse

Authorization

oauth2

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

retrieveLoyaltyReward

Note: This endpoint is in beta.

RetrieveLoyaltyRewardResponse retrieveLoyaltyReward(rewardId)

RetrieveLoyaltyReward

Retrieves a loyalty reward.

Example

var SquareConnect = require('square-connect');
var defaultClient = SquareConnect.ApiClient.instance;

// Configure OAuth2 access token for authorization: oauth2
var oauth2 = defaultClient.authentications['oauth2'];
oauth2.accessToken = 'YOUR ACCESS TOKEN';

var apiInstance = new SquareConnect.LoyaltyApi();

var rewardId = SquareConnect.LoyaltyApi.constructFromObject({}); // String | The ID of the `loyalty reward` to retrieve.

apiInstance.retrieveLoyaltyReward(rewardId).then(function(data) {
  console.log('API called successfully. Returned data: ' + data);
}, function(error) {
  console.error(error);
});

Parameters

Name Type Description Notes
rewardId String The ID of the `loyalty reward` to retrieve.

Return type

RetrieveLoyaltyRewardResponse

Authorization

oauth2

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

searchLoyaltyAccounts

Note: This endpoint is in beta.

SearchLoyaltyAccountsResponse searchLoyaltyAccounts(body)

SearchLoyaltyAccounts

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.

Example

var SquareConnect = require('square-connect');
var defaultClient = SquareConnect.ApiClient.instance;

// Configure OAuth2 access token for authorization: oauth2
var oauth2 = defaultClient.authentications['oauth2'];
oauth2.accessToken = 'YOUR ACCESS TOKEN';

var apiInstance = new SquareConnect.LoyaltyApi();

var body = SquareConnect.LoyaltyApi.constructFromObject({}); // SearchLoyaltyAccountsRequest | An object containing the fields to POST for the request.  See the corresponding object definition for field details.

apiInstance.searchLoyaltyAccounts(body).then(function(data) {
  console.log('API called successfully. Returned data: ' + data);
}, function(error) {
  console.error(error);
});

Parameters

Name Type Description Notes
body SearchLoyaltyAccountsRequest An object containing the fields to POST for the request. See the corresponding object definition for field details.

Return type

SearchLoyaltyAccountsResponse

Authorization

oauth2

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

searchLoyaltyEvents

Note: This endpoint is in beta.

SearchLoyaltyEventsResponse searchLoyaltyEvents(body)

SearchLoyaltyEvents

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.

Example

var SquareConnect = require('square-connect');
var defaultClient = SquareConnect.ApiClient.instance;

// Configure OAuth2 access token for authorization: oauth2
var oauth2 = defaultClient.authentications['oauth2'];
oauth2.accessToken = 'YOUR ACCESS TOKEN';

var apiInstance = new SquareConnect.LoyaltyApi();

var body = SquareConnect.LoyaltyApi.constructFromObject({}); // SearchLoyaltyEventsRequest | An object containing the fields to POST for the request.  See the corresponding object definition for field details.

apiInstance.searchLoyaltyEvents(body).then(function(data) {
  console.log('API called successfully. Returned data: ' + data);
}, function(error) {
  console.error(error);
});

Parameters

Name Type Description Notes
body SearchLoyaltyEventsRequest An object containing the fields to POST for the request. See the corresponding object definition for field details.

Return type

SearchLoyaltyEventsResponse

Authorization

oauth2

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

searchLoyaltyRewards

Note: This endpoint is in beta.

SearchLoyaltyRewardsResponse searchLoyaltyRewards(body)

SearchLoyaltyRewards

Searches for loyalty rewards in a loyalty account. In the current implementation, the endpoint supports search by the reward `status`. If you know a reward ID, use the RetrieveLoyaltyReward endpoint.

Example

var SquareConnect = require('square-connect');
var defaultClient = SquareConnect.ApiClient.instance;

// Configure OAuth2 access token for authorization: oauth2
var oauth2 = defaultClient.authentications['oauth2'];
oauth2.accessToken = 'YOUR ACCESS TOKEN';

var apiInstance = new SquareConnect.LoyaltyApi();

var body = SquareConnect.LoyaltyApi.constructFromObject({}); // SearchLoyaltyRewardsRequest | An object containing the fields to POST for the request.  See the corresponding object definition for field details.

apiInstance.searchLoyaltyRewards(body).then(function(data) {
  console.log('API called successfully. Returned data: ' + data);
}, function(error) {
  console.error(error);
});

Parameters

Name Type Description Notes
body SearchLoyaltyRewardsRequest An object containing the fields to POST for the request. See the corresponding object definition for field details.

Return type

SearchLoyaltyRewardsResponse

Authorization

oauth2

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json