Beta Release
This is pre-release documentation for an API in public beta and is subject to change.
Loyalty API: Walkthrough 1

Step 2: Enroll a Buyer in the Loyalty Program

To enroll a buyer in a loyalty program, you create a loyalty account and provide the program ID and buyer's phone number. You can obtain the buyer's phone number from your application flow. For this walkthrough, you use a test phone number that works in the Square Sandbox: +14255551111.

Step 2.1: Get the program ID Permalink Get a link to this section

  1. Call ListLoyaltyPrograms to retrieve the ID of the loyalty program.

    Replace {ACCESS_TOKEN} with your Sandbox access token.

    List Loyalty Programs
    • 1
    • 2
    • 3
    • 4
    curl https://connect.squareupsandbox.com/v2/loyalty/programs \
      -H 'Square-Version: 2021-03-17' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json'
  2. Copy the program ID from the response.

Step 2.2: Create the loyalty account Permalink Get a link to this section

  1. Call CreateLoyaltyAccount to create a loyalty account.

    • Replace {ACCESS_TOKEN} with your Sandbox access token and {UNIQUE_KEY} with a unique string. A unique idempotency key guarantees that Square processes a request only once.

    • Replace the example value for program_id with the actual program ID.

    Note that the mappings field references the buyer by phone number.

    Create Loyalty Account
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    curl https://connect.squareupsandbox.com/v2/loyalty/accounts \
      -X POST \
      -H 'Square-Version: 2021-03-17' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "loyalty_account": {
          "mappings": [
            {
              "type": "PHONE",
              "value": "+14255551111"
            }
          ],
          "program_id": "ba293138-8fbd-425d-860b-18ab3example"
        },
        "idempotency_key": "{UNIQUE_KEY}"
      }'

    After receiving the request, Square does the following:

    • Checks the seller's Customer Directory to determine whether it contains a customer profile with the same phone number. If not, Square creates a customer profile using the buyer's phone number.

    • Creates an account in the specified loyalty program.

    The following is an example response:

    {
      "loyalty_account":{
        "id":"716cefbc-3d71-4d7c-bdc8-9c78fexample",
        "mappings":[
          {
            "id":"6377d589-3f09-4f00-a0e8-56d70example",
            "type":"PHONE",
            "value":"+14255551111",
            "created_at":"2020-01-30T00:11:58Z"
          }
        ],
        "program_id":"ba293138-8fbd-425d-860b-18ab3example",
        "balance":0,
        "lifetime_points":0,
        "customer_id":"REK96J96AS5AN2Y8Z4Hexample",
        "created_at":"2020-01-30T00:11:58Z",
        "updated_at":"2020-01-30T00:11:58Z"
      }
    }
    
  2. Copy the ID of the new loyalty account from the response. Make sure to copy the id for the loyalty_account, not the mappings object.

    The response also includes other account information, such as the customer_id of the associated customer profile. Note that both balance and lifetime_points are 0 because the buyer has not yet accrued any loyalty points.

    Now that you have the account ID, you can use it to access the loyalty account. For example, you can call RetrieveLoyaltyAccount.

    Retrieve Loyalty Account
    • 1
    • 2
    • 3
    • 4
    curl https://connect.squareupsandbox.com/v2/loyalty/accounts/716cefbc-3d71-4d7c-bdc8-9c7f8example \
      -H 'Square-Version: 2021-03-17' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json'

Previous

< Set up a Loyalty Program

Next

Accrue Points >