Reward Customers Wherever They Shop with Loyalty API and Customers API

Earning customer loyalty is critical in this unprecedented time as businesses try to stay afloat with the support of their customers. One of the ways to maintain a strong customer relationship is through a loyalty program, whether it’s offering a free drink with a meal purchase or rewarding customers with a gift card after they spend $500 on merchandise. Square makes it easy to launch a digital loyalty program from scratch with Square Loyalty, an intuitive customer rewards program that’s integrated with Square Point of Sale and Square Online Store. Square Loyalty enables sellers to enroll, engage, and reward their customers directly within the checkout flow and increase customer engagement and sales. In fact, customers who enroll in a Square Loyalty rewards program are twice as likely to be repeat customers and spend 37% more per visit on average.

As businesses shift from in-store to online and mobile, sellers need a way to reward their customers wherever they shop. Square Loyalty API extends Square Loyalty to third-party channels, offering a seamless omnichannel loyalty solution for businesses that use the Point of Sale app or Square Online Store. Now eCommerce and order-ahead app developers can support Square Loyalty on their platforms, and businesses can extend Square Loyalty to their custom-built solutions. With the API, developers can automatically enroll customers into a loyalty program, view loyalty account details, accrue and redeem loyalty points, and more within a third-party solution. Then developers can synchronize the data with Square to maintain a single source of truth for sellers.

Running an effective customer program also requires consolidating customer data across channels. Built on top of Square Customer Directory, Square Customers API enables developers to automatically synchronize customer data across Square and non-Square applications. The new Customer Groups API and enhanced Customer Search endpoint make it easy to search, group, and take personalized actions on that data. For example, a developer may create a “season passholders” group within a third-party ticketing system and automatically synchronize that group with Square Point of Sale. Now the developer can trigger a discount directly within the point of sale for customers belonging to that group. Additionally, developers can look up customers by phone number or email address in real time to power identity resolution during online and mobile checkout flows.

Together, Loyalty API and Customers API empower developers to unlock a unified, omnichannel loyalty program for Square sellers, no matter where they run their business.

How Loyalty API and Customers API Work

Imagine you’re building an order-ahead app for food trucks, integrated with Loyalty API and Customers API. Square sellers using your platform can extend their Square Loyalty program to buyers ordering through your app. Plus, sellers can trust that buyer data is automatically synchronized with data in the Point of Sale app.

Here’s how it works. When a buyer places an order on your app and arrives at the checkout screen, you can call the SearchCustomers endpoint to look up the buyer by email address or phone number (as provided at checkout). You’ll want to find out whether the buyer has an existing customer profile. Here’s what that search looks like:

curl -X POST \
https://connect.squareup.com/v2/customers/search \
-H 'Accept: */*' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Content-Type: application/json' \
-H 'Square-Version: 2020-05-28' \
-d '{
    "query": {
        "filter": {
            "phone_number": {
                "exact": "+1 (234) 555-6789"
            }
        }
    }
}'

Let’s say there is an existing customer profile for the buyer (i.e., the above query returns customer_id: 123). Next you would use the SearchLoyaltyAccounts endpoint within Loyalty API to find out if a Loyalty account exists for that buyer. If the search indicates no Loyalty account exists, you can create a new Loyalty account. Simply call the CreateLoyaltyAccount endpoint, as shown below. You can use the customer ID retrieved in the previous step to associate with the Loyalty account.

curl -X POST \
https://connect.squareupsandbox.com/v2/loyalty/accounts \
-H 'Accept: */*' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Content-Type: application/json' \
-H 'Square-Version: 2020-05-28' \
-d '{
"loyalty_account": {
  "mappings": [
    {
      "type": "PHONE",
      "value": "+12345556789"
    }
  ],
  "program_id": "{{LOYALTY_PROGRAM_ID}}",
  "customer_id": "123"
},
"idempotency_key": "{{UNIQUE_KEY}}"
}'

Then call the AccumulateLoyaltyPoints endpoint to grant the buyer Loyalty points for their purchase.

curl -X POST \
https://connect.squareup.com/v2/loyalty/accounts/{{ACCOUNT_ID}}/accumulate \
-H 'Accept: */*' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Content-Type: application/json' \
-H 'Square-Version: 2020-05-28' \
-d '{
   "idempotency_key": "{{UNIQUE_KEY}}",
   "location_id": "{{LOCATION_ID}}",
   "accumulate_points": {
       "order_id": "{{ORDER_ID}}"
   }
}'

Let’s say the seller wants to send a welcome email to the new Loyalty enrollee. You can call the AddGroupToCustomer endpoint to add the new buyer (using the customer_id: 123) to a Customer Group, as shown below. Then the Customer Group automatically syncs across all platforms that the seller uses. Now the seller can access the Customer Group for a targeted email from Square Marketing or any third-party email platform.

curl -X PUT \
https://connect.squareup.com/v2/customers/{{CUSTOMER_ID
}}
/groups/{{GROUP_ID}} \ 
-H 'Accept: */*' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Content-Type: application/json' \
-H 'Square-Version: 2020-05-28'

Get Started

Loyalty API is available in beta to developers in the U.S., Canada, and Australia (UK coming soon.) Customer Groups API and the enhanced Customer Search endpoint are available in beta to developers in the U.S., Canada, UK, Japan, and Australia. These APIs are free for developers to use in Sandbox and in production. Sellers interested in leveraging the Loyalty API integration will need to have an active paid subscription to Square Loyalty.

Check out the Loyalty API documentation and Customers API documentation to learn how to get started and access the API reference docs. We encourage developers to share their feedback on our community Slack channel or Square Developer Forums.

If you want to keep up to date with the rest of our content, be sure to follow this blog and our Twitter account, and sign up for our developer newsletter!