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

Step 3: Accrue Points

Create an order for a $12 item using the Orders API. After the buyer pays for the order, you call the Loyalty API to compute and add the points to the buyer's account for the purchase. The order earns the buyer 12 points based on the accrual rule in the loyalty program.

Step 3.1: Create an order Permalink Get a link to this section

  1. Call CreateOrder to create an order for one $12 item.

    Create Order
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    curl https://connect.squareupsandbox.com/v2/orders \
  -X POST \
  -H 'Square-Version: 2021-03-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "order": {
      "line_items": [
        {
          "name": "a non-catalog-item",
          "quantity": "1",
          "base_price_money": {
            "amount": 1200,
            "currency": "USD"
          }
        }
      ],
      "location_id": "{LOCATION_ID}"
    },
    "idempotency_key": "{UNIQUE_KEY}"
  }'
    Try in API Explorer

  2. Note the order ID in the response.

Step 3.2: Take a payment Permalink Get a link to this section

Take the payment for the preceding order. Use the Payment API, CreatePayment endpoint, to take the payment of $12. In the Sandbox, you use a fake nonce "cnon:card-nonce-ok" to take a payment. For more information, see Square API endpoint testing.

Create Payment
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2021-03-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "source_id": "cnon:card-nonce-ok",
    "amount_money": {
      "amount": 1200,
      "currency": "USD"
    },
    "order_id": "{ORDER_ID}",
    "idempotency_key": "{UNIQUE_KEY}"
  }'
Try in API Explorer

Step 3.3: Add points to the loyalty account Permalink Get a link to this section

  1. Check the current point balance in the loyalty account before adding points by calling RetrieveLoyaltyAccount:

    Retrieve Loyalty Account
    • 1
    • 2
    • 3
    • 4
    curl https://connect.squareupsandbox.com/v2/loyalty/accounts/{account_id} \
  -H 'Square-Version: 2021-03-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'
    Try in API Explorer

  2. Call AccumulateLoyaltyPoints to add points to the buyer's account for the order. The endpoint uses the order to determine the points to add to the buyer's loyalty account. In the request:

    • loyalty_account_id identifies the loyalty account of the buyer.

    • order_id is the order for which the buyer is getting points.

    Accumulate Loyalty Points
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    curl https://connect.squareupsandbox.com/v2/loyalty/accounts/{account_id}/accumulate \
  -X POST \
  -H 'Square-Version: 2021-03-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "accumulate_points": {
      "order_id": "{ORDER_ID}"
    },
    "location_id": "{LOCATION_ID}",
    "idempotency_key": "{UNIQUE_KEY}"
  }'
    Try in API Explorer

    Using the order information, the endpoint computes the loyalty points for the purchase and adds the points to the buyer's loyalty account. The following is an example response:

    {
   "event":{
      "id":"bbd1ef00-92ac-3e5f-8887-cd3c6example",
      "type":"ACCUMULATE_POINTS",
      "created_at":"2020-05-07T22:31:48Z",
      "accumulate_points":{
         "loyalty_program_id":"ba293138-8fbd-425d-860b-18ab3example",
         "points":12,
         "order_id":"KauTZmbuDVviwvL9L00QsYexample"
      },
      "loyalty_account_id":"716cefbc-3d71-4d7c-bdc8-9c78fexample",
      "location_id":"S8GWD5example",
      "source":"LOYALTY_API"
   }
}

Step 3.4: Verify the loyalty account balance Permalink Get a link to this section

Call RetrieveLoyaltyAccount to verify the loyalty points balance:

Retrieve Loyalty Account
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/loyalty/accounts/{account_id} \
  -H 'Square-Version: 2021-03-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'
Try in API Explorer

In the following example, the loyalty account has a balance of 12 points:

{
   "loyalty_account":{
      "id":"716cefbc-3d71-4d7c-bdc8-9c78fexample",
      "mappings":[
         {
            "id":"6d4271ae-cf8e-4013-8ffc-9de12example",
            "type":"PHONE",
            "value":"+14255551111",
            "created_at":"2020-05-07T21:55:22Z"
         }
      ],
      "program_id":"ba293138-8fbd-425d-860b-18ab3example",
      "balance":12,
      "lifetime_points":12,
      "customer_id":"Q8002FSMQ88489JDBT028C93example",
      "created_at":"2020-05-07T21:55:22Z",
      "updated_at":"2020-05-07T21:55:22Z"
   }
}

Previous

< Enroll a Buyer

Next

Redeem Points >