Applies to: Loyalty API | Catalog API
Learn how to set up a loyalty program to help increase repeat visits to a seller's business.
Square sellers can subscribe to Square Loyalty and set up a loyalty program to help increase repeat visits to their business. A loyalty program defines how buyers can earn points and redeem points for discounts. For more information, see Loyalty Program.
In this walkthrough, you create and manage resources (such as a loyalty account, catalog items, and orders) by calling Square APIs in the Square Sandbox environment. Before you begin, you need to get your Sandbox account credentials, create catalog items used for rewards, and set up a loyalty program that you can use for testing. Note that the Loyalty API cannot be used to create or update a loyalty program.
It's helpful to understand some of the Sandbox features used in this walkthrough:
-
Sandbox test account - A fake seller account used for testing. This walkthrough assumes you're using the default test account created by Square, which has full access to Sandbox resources.
You can optionally create and authorize another test account if you want to test OAuth permissions or test an account in a different country. If so, grant the permissions required for the API requests used in this walkthrough and use the new account's access token in your API requests.
-
Sandbox Square Dashboard - The Sandbox version of the Square Dashboard that sellers use to manage their business.
You'll subscribe to Square Loyalty and set up a test loyalty program in the Sandbox Square Dashboard. You can also optionally use the dashboard throughout the walkthrough to view the changes you make with Square APIs.
-
Sandbox payment methods - Test credit card numbers and other values used to make fake payments.
First, you'll use a test credit card number to subscribe to Square Loyalty on behalf of your test seller account. Then, you'll use a test payment token to pay for an order on behalf of a buyer. Note that Sandbox payment methods are never charged.
Follow these steps to get the access token and location ID used in this walkthrough.
- Sign in to the Developer Console and open your application. If you don't have a Square account, see Get Started to learn how to create an account and an application.
Get your Sandbox access token:
- At the top of the page, in the Sandbox and Production toggle, choose Sandbox.
- On the Credentials page, under Sandbox Access Token, choose Show and then copy the token. All Square API requests require an access token for authorization. This personal access token grants full access to the Sandbox resources in your account.
Important
The Sandbox access token is a secure secret. Don't share it with anyone.
Get your location ID:
-
In the left pane, choose Locations.
-
On the Locations page, keep Default Test Account selected and copy a location ID.
Note
To retrieve location IDs programmatically, call ListLocations.
The loyalty program in this walkthrough offers a free coffee reward tier and a free sandwich reward tier. These items must be added to the product catalog before you can set up the reward tiers. For more information about Square catalogs, see Catalog API.
-
Call BatchUpsertCatalogObjects in the Catalog API to add two items to the catalog.
Replace
{ACCESS_TOKEN}with your Sandbox access token and{UNIQUE_KEY}with a unique idempotency key.
The following is an excerpt of the example response:
{ "objects":[ { "type":"ITEM", "id":"WVKYFIQQVJMTHQFKKexample", "updated_at":"2020-03-09T03:02:50.862Z", "version":1583722970862, "is_deleted":false, "present_at_all_locations":true, "item_data":{