Toast POS Integration Implementation

Written By Devin O'Neill ()

Updated at April 17th, 2025

Objective

The purpose of this document is to define the necessary Annex Cloud loyalty endpoints for integration with Toast POS. This integration will enable Annex Cloud's loyalty program to work seamlessly with Toast POS.

Requirements

  • To establish a connection between Annex Cloud and Toast POS.
  • To support various loyalty use cases through Toast POS.

Configuring Toast POS Credentials and Fetching Restaurant Names

Enabling Toast POS Site Configuration

To enable the Toast POS site configuration, follow the steps below:

  • Access the Super Admin ADR Site
    Begin by logging into the new super admin ADR site.
  • On the super admin ADR site, navigate to the Manage Site section and select the site where Toast POS is being used.
  • Click on Pre-Built Integration Settings where you will see a list of all available platforms.
  • From the list of platforms, click on POS Actions and then click on Add Platform Services Permission.
  • Click on Add New, select a Service Name, and then toggle the Service Status to ON. Finally, click Save.

  • Once saved, Toast POS will be activated on your site.
  • Now, within the Pre-Built Integrations section, you will see Toast POS Setup listed. Click on it.
  • In the Toast POS configuration, you will see a list of all Toast Sandbox URLs. Click on the Edit Icon to adjust settings for Toast POS according to your requirements.
  • Toast POS credentials are added to the Toast POS Module within Annex Cloud.
  • Click on the Settings Icon to view the Restaurant list page.
  • Add a new restaurant on the Restaurant page.

Access Token - Production

Endpoint URL https://ws-api.toasttab.com/authentication/v1/authentication/login
 
Method POST
Headers ntent-Type:application/json

 Json Payload Example:

{
  "clientId": "XXXXXXXXX",
  "clientSecret": "XXXXXXXXXXXX",
  "userAccessType": "TOAST_MACHINE_CLIENT"
}

Successful Response Example:

{
    "@class": ".SuccessfulResponse",
    "token": {
        "tokenType": "Bearer",
        "scope": null,
        "expiresIn": 15635,
        "accessToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "idToken": null,
        "refreshToken": null
    },
    "status": "SUCCESS"
}

Restaurant Name and Details - Production

Endpoint URL https://ws-api.toasttab.com/partners/v1/connectedRestaurants
 
Method GET
Headers Authorization: XXXXXXXXXXXXX (Get from the above Access Token API)
Content-Type:application/json

 Json Payload Example:

{
  "clientId": "XXXXXXXXX",
  "clientSecret": "XXXXXXXXXXXX",
  "userAccessType": "TOAST_MACHINE_CLIENT"
}

Successful Response Example:

{
    "@class": ".SuccessfulResponse",
    "token": {
        "tokenType": "Bearer",
        "scope": null,
        "expiresIn": 15635,
        "accessToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "idToken": null,
        "refreshToken": null
    },
    "status": "SUCCESS"
}

After adding the above settings to fetch the Toast POS restaurant details and credentials from the Annex Cloud database, you can make use of the following operations.

List of Endpoints to be configured at Toast POS:

Loyalty Search

Retrieve loyalty member details based on the entered email ID or mobile number.

Get User Details - Production

Endpoint URL https:// s15.socialannex.net/api/3.0/users/{{userId}}
 
Method GET
Headers XXXXXXXX(Provided by Annex Cloud)
Accept application/json

Successful Response Example:

 {
 "id": "user@domain.com",
 "email": "user@domain.com",
  "firstName": "John",
  "lastName": "Doe",
  "zipCode": "90002",
  "optInStatus": "YES",
  "status": "ACTIVE",
  "phone": "123-123-4567",
  "birthDate": "2018-04-01T00:00:00-0700",
  "anniversaryDate": "2018-04-01T00:00:00-0700",
  "userProfileImageUrl": "https://www.socialannex.com/public/manageoptionsdesign16/images/product_landing/loyalty-hover.png",
  "createDate": "2018-04-01T00:00:00-0700",
  "updateDate": "2018-04-01T00:00:00-0700",
  "totalSpendCurrency": "150",
  "extendedAttribute": ["KEY1": "VALUE1", "KEY2": "VALUE2"]
}

Failed Response Example:

{
    "errorCode": "AC1002",
    "errorMessage": "Request Not Authorized"
}

If no data is found:

{
    "errorCode": "AC1005",
    "errorMessage": "No data found"
}

Get User Points - Production

This endpoint returns the member's points balance and other relevant loyalty data.

Endpoint URL https:// s15.socialannex.net/api/3.0/points/{{userId}}
 
Method GET
Headers XXXXXXXX(Provided by Annex Cloud)
Accept application/json

Successful Response Example:

{
    "siteId": "105860280",
    "id": "vgaikwad@annexcloud.com",
    "availablePoints": 50,
    "usedPoints": 0,
    "expiredPoints": 0,
    "lifetimePoints": 50,
    "holdPoints": 0,
    "usedPointsOnReward": 0,
    "pointsToExpire": 0,
    "pointsToNextTier": 0,
    "spendToNextTier": 0,
    "pointsToExpireDate": "",
    "totalSpent": 0,
    "creditsToCurrencyRatio": 1,
    "creditsToCurrencyValue": 50,
    "ytdCreditPoints": 50,
    "ytdDebitPoints": 0,
    "availableRedemptionPoints": 0,
    "usedRedemptionPoints": 0
}

Failed Response Example:

{
    "errorCode": "AC1002",
    "errorMessage": "Request Not Authorized"
}

If no data is found:

{
    "errorCode": "AC1005",
    "errorMessage": "No data found"
}

Loyalty Inquiry

Retrieve the available loyalty offers and verify whether they have been applied to a transaction. This process is about reviewing the offer status without redeeming them.

Get User Details - Production

Endpoint URL https:// s15.socialannex.net/api/3.0/users/{{userId}}
 
Method GET
Headers XXXXXXXX(Provided by Annex Cloud)
Accept application/json

Successful Response Example:

 {
 "id": "user@domain.com",
 "email": "user@domain.com",
  "firstName": "John",
  "lastName": "Doe",
  "zipCode": "90002",
  "optInStatus": "YES",
  "status": "ACTIVE",
  "phone": "123-123-4567",
  "birthDate": "2018-04-01T00:00:00-0700",
  "anniversaryDate": "2018-04-01T00:00:00-0700",
  "userProfileImageUrl": "https://www.socialannex.com/public/manageoptionsdesign16/images/product_landing/loyalty-hover.png",
  "createDate": "2018-04-01T00:00:00-0700",
  "updateDate": "2018-04-01T00:00:00-0700",
  "totalSpendCurrency": "150",
  "extendedAttribute": ["KEY1": "VALUE1", "KEY2": "VALUE2"]
}

Failed Response Example:

{
    "errorCode": "AC1002",
    "errorMessage": "Request Not Authorized"
}

If no data is found:

{
    "errorCode": "AC1005",
    "errorMessage": "No data found"
}

Get User Points - Production

Endpoint URL https:// s15.socialannex.net/api/3.0/points/{{userId}}
 
Method GET
Headers XXXXXXXX(Provided by Annex Cloud)
Accept application/json

Successful Response Example:

{
    "siteId": "105860280",
    "id": "vgaikwad@annexcloud.com",
    "availablePoints": 50,
    "usedPoints": 0,
    "expiredPoints": 0,
    "lifetimePoints": 50,
    "holdPoints": 0,
    "usedPointsOnReward": 0,
    "pointsToExpire": 0,
    "pointsToNextTier": 0,
    "spendToNextTier": 0,
    "pointsToExpireDate": "",
    "totalSpent": 0,
    "creditsToCurrencyRatio": 1,
    "creditsToCurrencyValue": 50,
    "ytdCreditPoints": 50,
    "ytdDebitPoints": 0,
    "availableRedemptionPoints": 0,
    "usedRedemptionPoints": 0
}

Failed Response Example:

{
    "errorCode": "AC1002",
    "errorMessage": "Request Not Authorized"
}

If no data is found:

{
    "errorCode": "AC1005",
    "errorMessage": "No data found"
}

Available Rewards - Production

This endpoint retrieves available rewards based on the member's loyalty program status.

Endpoint URL https:// s15.socialannex.net/api/3.0/users/{{userId}}/reward
 
Method GET
Headers XXXXXXXX(Provided by Annex Cloud)
Accept application/json

Successful Response Example:

{
    "siteId": "102942361",
    "creditsToCurrencyRatio": "1",
    "creditsToCurrencyValue": 3064,
    "rewardDetail": [
        {
            "rewardId": "29660",
            "rewardCategory": "",
            "displayText": "10off",
            "rewardType": "1",
            "rewardTerms": "",
            "rewardDescription": "",
            "creditRequired": "250",
            "deductAmount": "0.00",
            "rewardCurrency": "",
            "rewardUrl": "",
            "rewardImageUrl": "",
            "defaultThumbnailImageURL": "",
            "videoImageURL": "",
            "productId": "",
            "tierId": "",
            "tierName": "",
            "tierEligible": "",
            "userTierId": "",
            "userTierName": "",
            "tierAchievedDate": "",
            "rewardExpirationType": "Rolling",
            "rewardExpirationPeriod": "180 Days",
            "eligible": "YES",
            "yearSelected": "",
            "period": "",
            "periodDetails": "",
            "rewardLimit": "1",
            "limitPeriod": "Anniversary Year",
            "redeemCount": 0,
            "remainingCount": 1,
            "autoRewardStatus": "NO",
            "timeBasedIssuanceFlag": "NO",
            "timeBasedIssuanceDate": "",
            "tierData": []
        },
        {
            "rewardId": "29661",
            "rewardCategory": "",
            "displayText": "25off",
            "rewardType": "1",
            "rewardTerms": "",
            "rewardDescription": "",
            "creditRequired": "500",
            "deductAmount": "0.00",
            "rewardCurrency": "",
            "rewardUrl": "",
            "rewardImageUrl": "",
            "defaultThumbnailImageURL": "",
            "videoImageURL": "",
            "productId": "",
            "tierId": "",
            "tierName": "",
            "tierEligible": "",
            "userTierId": "",
            "userTierName": "",
            "tierAchievedDate": "",
            "rewardExpirationType": "Rolling",
            "rewardExpirationPeriod": "180 Days",
            "eligible": "YES",
            "yearSelected": "",
            "period": "",
            "periodDetails": "",
            "rewardLimit": "1",
            "limitPeriod": "Anniversary Year",
            "redeemCount": 0,
            "remainingCount": 1,
            "autoRewardStatus": "NO",
            "timeBasedIssuanceFlag": "NO",
            "timeBasedIssuanceDate": "",
            "tierData": []
        },
        {
            "rewardId": "29662",
            "rewardCategory": "",
            "displayText": "50off",
            "rewardType": "1",
            "rewardTerms": "",
            "rewardDescription": "",
            "creditRequired": "1000",
            "deductAmount": "0.00",
            "rewardCurrency": "",
            "rewardUrl": "",
            "rewardImageUrl": "",
            "defaultThumbnailImageURL": "",
            "videoImageURL": "",
            "productId": "",
            "tierId": "",
            "tierName": "",
            "tierEligible": "",
            "userTierId": "",
            "userTierName": "",
            "tierAchievedDate": "",
            "rewardExpirationType": "Rolling",
            "rewardExpirationPeriod": "180 Days",
            "eligible": "YES",
            "yearSelected": "",
            "period": "",
            "periodDetails": "",
            "rewardLimit": "1",
            "limitPeriod": "Anniversary Year",
            "redeemCount": 0,
            "remainingCount": 1,
            "autoRewardStatus": "NO",
            "timeBasedIssuanceFlag": "NO",
            "timeBasedIssuanceDate": "",
            "tierData": []
        }
    ]
}

Failed Response Example:

{
    "errorCode": "AC1002",
    "errorMessage": "Request Not Authorized"
}

If no data is found:

{
    "errorCode": "AC1005",
    "errorMessage": "No data found"
}

Loyalty Redeem

You can retrieve the loyalty offers that have been applied to a transaction and confirm their redemption by using the following API. This process focuses on using or redeeming available offers during a purchase.

Get User Details - Production

Endpoint URL https:// s15.socialannex.net/api/3.0/users/{{userId}}
 
Method GET
Headers XXXXXXXX(Provided by Annex Cloud)
Accept application/json

Successful Response Example:

{
 "id": "user@domain.com",
 "email": "user@domain.com",
  "firstName": "John",
  "lastName": "Doe",
  "zipCode": "90002",
  "optInStatus": "YES",
  "status": "ACTIVE",
  "phone": "123-123-4567",
  "birthDate": "2018-04-01T00:00:00-0700",
  "anniversaryDate": "2018-04-01T00:00:00-0700",
  "userProfileImageUrl": "https://www.socialannex.com/public/manageoptionsdesign16/images/product_landing/loyalty-hover.png",
  "createDate": "2018-04-01T00:00:00-0700",
  "updateDate": "2018-04-01T00:00:00-0700",
  "totalSpendCurrency": "150",
  "extendedAttribute": ["KEY1": "VALUE1", "KEY2": "VALUE2"]
}

Failed Response Example:

{
    "errorCode": "AC1002",
    "errorMessage": "Request Not Authorized"
}

If no data is found:

{
    "errorCode": "AC1002",
    "errorMessage": "Request Not Authorized"
}

Get User Points - Production

To check member points, use the following endpoint:

Endpoint URL https:// s15.socialannex.net/api/3.0/points/{{userId}}
 
Method GET
Headers XXXXXXXX(Provided by Annex Cloud)
Accept application/json

Successful Response Example:

{
    "siteId": "105860280",
    "id": "vgaikwad@annexcloud.com",
    "availablePoints": 50,
    "usedPoints": 0,
    "expiredPoints": 0,
    "lifetimePoints": 50,
    "holdPoints": 0,
    "usedPointsOnReward": 0,
    "pointsToExpire": 0,
    "pointsToNextTier": 0,
    "spendToNextTier": 0,
    "pointsToExpireDate": "",
    "totalSpent": 0,
    "creditsToCurrencyRatio": 1,
    "creditsToCurrencyValue": 50,
    "ytdCreditPoints": 50,
    "ytdDebitPoints": 0,
    "availableRedemptionPoints": 0,
    "usedRedemptionPoints": 0
}

Failed Response Example:

{
    "errorCode": "AC1002",
    "errorMessage": "Request Not Authorized"
}

If no data is found:

{
    "errorCode": "AC1005",
    "errorMessage": "No data found"
}

Available Rewards - Production

To view available rewards, use this endpoint:

Endpoint URL https:// s15.socialannex.net/api/3.0/users/{{userId}}/reward
 
Method GET
Headers XXXXXXXX(Provided by Annex Cloud)
Accept application/json

Successful Response Example:

{
    "siteId": "102942361",
    "creditsToCurrencyRatio": "1",
    "creditsToCurrencyValue": 3064,
    "rewardDetail": [
        {
            "rewardId": "29660",
            "rewardCategory": "",
            "displayText": "10off",
            "rewardType": "1",
            "rewardTerms": "",
            "rewardDescription": "",
            "creditRequired": "250",
            "deductAmount": "0.00",
            "rewardCurrency": "",
            "rewardUrl": "",
            "rewardImageUrl": "",
            "defaultThumbnailImageURL": "",
            "videoImageURL": "",
            "productId": "",
            "tierId": "",
            "tierName": "",
            "tierEligible": "",
            "userTierId": "",
            "userTierName": "",
            "tierAchievedDate": "",
            "rewardExpirationType": "Rolling",
            "rewardExpirationPeriod": "180 Days",
            "eligible": "YES",
            "yearSelected": "",
            "period": "",
            "periodDetails": "",
            "rewardLimit": "1",
            "limitPeriod": "Anniversary Year",
            "redeemCount": 0,
            "remainingCount": 1,
            "autoRewardStatus": "NO",
            "timeBasedIssuanceFlag": "NO",
            "timeBasedIssuanceDate": "",
            "tierData": []
        },
        {
            "rewardId": "29661",
            "rewardCategory": "",
            "displayText": "25off",
            "rewardType": "1",
            "rewardTerms": "",
            "rewardDescription": "",
            "creditRequired": "500",
            "deductAmount": "0.00",
            "rewardCurrency": "",
            "rewardUrl": "",
            "rewardImageUrl": "",
            "defaultThumbnailImageURL": "",
            "videoImageURL": "",
            "productId": "",
            "tierId": "",
            "tierName": "",
            "tierEligible": "",
            "userTierId": "",
            "userTierName": "",
            "tierAchievedDate": "",
            "rewardExpirationType": "Rolling",
            "rewardExpirationPeriod": "180 Days",
            "eligible": "YES",
            "yearSelected": "",
            "period": "",
            "periodDetails": "",
            "rewardLimit": "1",
            "limitPeriod": "Anniversary Year",
            "redeemCount": 0,
            "remainingCount": 1,
            "autoRewardStatus": "NO",
            "timeBasedIssuanceFlag": "NO",
            "timeBasedIssuanceDate": "",
            "tierData": []
        },
        {
            "rewardId": "29662",
            "rewardCategory": "",
            "displayText": "50off",

            "rewardType": "1",
            "rewardTerms": "",
            "rewardDescription": "",
            "creditRequired": "1000",
            "deductAmount": "0.00",
            "rewardCurrency": "",
            "rewardUrl": "",
            "rewardImageUrl": "",
            "defaultThumbnailImageURL": "",
            "videoImageURL": "",
            "productId": "",
            "tierId": "",
            "tierName": "",
            "tierEligible": "",
            "userTierId": "",
            "userTierName": "",
            "tierAchievedDate": "",
            "rewardExpirationType": "Rolling",
            "rewardExpirationPeriod": "180 Days",
            "eligible": "YES",
            "yearSelected": "",
            "period": "",
            "periodDetails": "",
            "rewardLimit": "1",
            "limitPeriod": "Anniversary Year",
            "redeemCount": 0,
            "remainingCount": 1,
            "autoRewardStatus": "NO",
            "timeBasedIssuanceFlag": "NO",
            "timeBasedIssuanceDate": "",
            "tierData": []
        }
    ]
}

Failed Response Example:

{
    "errorCode": "AC1002",
    "errorMessage": "Request Not Authorized"
}

If no data is found:

{
    "errorCode": "AC1005",
    "errorMessage": "No data found"
}

Loyalty Accrue

Members earn points with every purchase. As you shop more, you collect more points, which can be redeemed for future rewards such as discounts or free items.

Points Debit - Production

To debit points, use the following endpoint:

Endpoint URL https:// s15.socialannex.net/api/3.0/points
 
Method POST
Headers XXXXXXXX(Provided by Annex Cloud)
Accept application/json

JSON Payload Example:

{
"id": "{{email_id}}",
"orderId": "1234356778"
"actionId": "100",
"debit": "30",
"activity": "DEBIT",
"reason":"testing"
}

Successful Response Example:

{
    "siteId": "102942361",
    "id": "testACuser@mail.com",
    "actionId": "100",
    "activity": "DEBIT",
    "debit": 30,
    "pointsDeducted": 30,
    "reason": "testing",
    "updatedAvailablePoints": 3034,
    "updatedLifetimePoints": 8064,
    "previousTier": "FRIENDS",
    "updatedUserTier": ""
}

Failed Response Example:

{
    "errorCode": "AC1002",
    "errorMessage": "Request Not Authorized"
}

If no data is found:

{
    "errorCode": "AC1005",
    "errorMessage": "No data found"
}

Get User Details - Production

Endpoint URL https:// s15.socialannex.net/api/3.0/users/{{userId}}
 
Method GET
Headers XXXXXXXX(Provided by Annex Cloud)
Accept application/json

Successful Response Example:

 {
 "id": "user@domain.com",
 "email": "user@domain.com",
  "firstName": "John",
  "lastName": "Doe",
  "zipCode": "90002",
  "optInStatus": "YES",
  "status": "ACTIVE",
  "phone": "123-123-4567",
  "birthDate": "2018-04-01T00:00:00-0700",
  "anniversaryDate": "2018-04-01T00:00:00-0700",
  "userProfileImageUrl": "https://www.socialannex.com/public/manageoptionsdesign16/images/product_landing/loyalty-hover.png",
  "createDate": "2018-04-01T00:00:00-0700",
  "updateDate": "2018-04-01T00:00:00-0700",
  "totalSpendCurrency": "150",
  "extendedAttribute": ["KEY1": "VALUE1", "KEY2": "VALUE2"]
}

Failed Response Example:

{
    "errorCode": "AC1002",
    "errorMessage": "Request Not Authorized"
}

If no data is found:

{
    "errorCode": "AC1005",
    "errorMessage": "No data found"
}

Place an Order – Production

Endpoint URL https:// s15.socialannex.net/api/3.0/orders
 
Method POST
Headers XXXXXXXX(Provided by Annex Cloud)
Accept application/json

Json Payload Example

{
    "orderTotal": 20,
    "userId": "ac.test12@annex.com",
    "storeId": null,
    "orderDate": "2022-10-07 17:55:00",
    "id": "fsdafsafsad243234",
    "orderDetail": [
        {
            "id": "a0T0T000002UL5iUAG",
            "unitPrice": 20,
            "quantity": 1,
            "productName": "B-17291484",
            "autoDelivery": "YES",
            "secondaryKey": "test"
        }
    ],
    "email": "ac.test12@annex.com",
    "discountAmount": 0,
    "coupon": [
        29276
    ],
    "source": "web"
}

Successful Response Example:

{
    "siteId": "102942360",
    "id": "fsdafsafsad2432323423",
    "userId": "ac.test45@annex.com",
    "email": "ac.test12@annex.com",
    "orderTotal": 20,
    "source": "web",
    "pointsAwarded": 20,
    "pointsExpirationDate": "2025-01-28T04:43:18+0000",
    "coupon": [
        29276
    ],
    "previousTier": "",
    "updatedUserTier": "",
    "currentTier": "FRIENDS",
    "nextTier": "BESTIES",
    "pointsToNextTier": 0,
    "currentTierPurchaseRatio": "1",
    "spendAmountToNextTier": 91,
    "tierAchievedDate": "2023-11-29T23:47:32+0000",
    "tierExpirationDate": "2025-11-29T23:47:31+0000",
    "orderDetail": [
        {
            "id": "a0T0T000002UL5iUAG",
            "unitPrice": 20,
            "quantity": 1,
            "productName": "B-17291484",
            "autoDelivery": "YES",
            "secondaryKey": "test",
            "points": 20
        }
    ],
    "updatedAvailablePoints": 360,
    "updatedLifetimePoints": 360
}

Failed Response Example:

{
    "errorCode": "AC1002",
    "errorMessage": "Request Not Authorized"
}

If no data is found:

{
    "errorCode": "AC1005",
    "errorMessage": "No data found"
}

Loyalty Reverse

Describes member returns of purchased items and how the returns impact the member’s points and rewards.

Order Return - Production

To return an order, use the following endpoint:

Endpoint URL https:// s15.socialannex.net/api/3.0/orders/{{orderId}}
 
Method PATCH
Headers XXXXXXXX(Provided by Annex Cloud)
Accept application/json

JSON Payload Example:

{
"orderId": "fsdafsafsad2432323423",
"status": "return"
}

Successful Response Example:

{
    "siteId": "102942360",
    "orderId": "fsdafsafsad2432323423",
    "pointsRemoved": 20,
    "updatedAvailablePoints": 340,
    "updatedLifetimePoints": 360,
    "previousTier": "",
    "updatedUserTier": "",
    "currentTier": "FRIENDS",
    "nextTier": "BESTIES",
    "pointsToNextTier": 0,
    "currentTierPurchaseRatio": "1",
    "spendAmountToNextTier": 111,
    "tierAchievedDate": "2023-11-29T23:47:32+0000",
    "tierExpirationDate": "2025-11-29T23:47:31+0000"
}

Failed Response Example:

{
    "errorCode": "AC1002",
    "errorMessage": "Request Not Authorized"
}

If no data is found:

{
    "errorCode": "AC1005",
    "errorMessage": "No data found"
}

Related Articles

OneView Commerce POS Integration Document

Introduction Annex Cloud is a loyalty program solution provider. Annex Cloud offe...

Shopify Features Document

Objective The purpose of this document is to describe the features supported on S...

SAP Customer Data Cloud Integration Document

SAP Customer Data Cloud Integration Document This document outlines the steps to ...

Toast POS Integration Features

Objective The purpose of this document is to describe the features supported on T...