The loyalty accounts API allows a site owner to create and manage its customers' loyalty accounts. The loyalty accounts maintain a customer's balance of loyalty points.
With the loyalty accounts API, you can:
- Create a new loyalty account.
- Adjust the balance of a loyalty account.
- Earn points to a loyalty account.
- Retrieve loyalty accounts and transactions related to those accounts.
- Handle webhooks when an account is updated or adjusted.
Note: Before loyalty accounts can be created, the site's loyalty program must be active. See the activate loyalty program endpoint to learn how to activate the loyalty program using the API.
A loyalty account stores a customer's loyalty points balance. A site's customers can earn points to their account and redeem those points for rewards.
Retrieves a list of accounts, given the provided filters.
You can retrieve selected loyalty accounts with an array of contactIds or retrieve a list of all of a site's loyalty accounts
with an empty request parameter. Use the cursorPaging parameters to limit how many items load at a time.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
Creates a loyalty account for one of a site's contacts.
To create a new loyalty account, the customer must first be a site contact with a contact ID. See the Contacts API to learn more about a site's contacts. The site must also have an active loyalty program before loyalty accounts can be created. See the activate loyalty program endpoint to activate a site's loyalty program.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
Adds points to a loyalty account.
Only a positive amount can be added using the earn points endpoint. To adjust an account's balance for a negative amount, use Adjust Points.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
Adjusts the point balance of a loyalty account.
You can adjust the balance in two ways:
balanceallows you to set the total points balance to this new amount.amountallows you to adjust the points balance by this amount. This amount can be a positive number to increase the points balance or a negative number to decrease the balance.
An account may not be adjusted to result in a negative balance. If you pass an integer in both the balance and the amount parameters then the balance adjustment takes effect and the
amount adjustment is ignored.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
Retrieves an account using the loyalty account ID.
You can also retrieve an account using a secondary ID, such as a contact ID or a member ID by using the Get Account by Secondary ID endpoint.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
Retrieves the total amount of points earned, redeemed, and adjusted for the entire loyalty program.
The balance is the current total of points outstanding, while the earned, adjusted, and redeemed amounts
are the historically accumulated amounts. The totals include the amounts for all loyalty accounts.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
Retrieves the account belonging to the specified contact or member.
This endpoint retrieves loyalty accounts using either a customer's contact ID or member ID. Your app can also retrieve an account using the loyalty account ID by using the Get Account endpoint.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
Retrieves a list of accounts, given the provided filters and search capabilities. Search is executed on the account's name and email values.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
Retrieves a transaction using the transaction ID.
A loyalty transaction includes any activity that changes a loyalty account point balance, such as adjusting, earning, or redeeming loyalty points. To retrieve all of the transactions for a specific loyalty account, use List Transactions.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
Retrieves a list of transactions, given the provided filters.
Loyalty transactions include any activities that change a loyalty account point balance, such as adjusting, earning, or redeeming loyalty points. To retrieve a specific transaction, use that transaction's ID and Get Transaction.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
Triggered when a loyalty account is created.
Event Body
Triggered when the points of a loyalty account are adjusted, earned, or redeemed.
Event Body
Triggered when a loyalty account is updated, including when points are adjusted, earned, or redeemed.