Introduction

Thanx provides a number of ways to integrate with the Thanx platform, including a number of authentication mechanisms and a powerful REST API.

This API reference provides information on available endpoints and how to interact with them.

Environments

Thanx provides a sandbox environment for you to develop against. The data in the sandbox environment is isolated from production data. All new development must be validated and tested against the sandbox environment prior to being released into production. Do not create test artifacts in production.

The sandbox API can be found at:

https://api.thanxsandbox.com

The production API can be found at:

https://api.thanx.com

Credentials

Thanx will provide you with a Client ID and Client Secret to use in communicating with our API. These values will be different for sandbox and production. We strongly recommend that these credentials are never used in an app build for security reasons. You should proxy your app's calls to Thanx resources through your own server whenever possible.

Headers

This section describes the headers expected by the Thanx API.

STANDARD_HEADERS = '-H "Content-Type: application/json" ' \
  '-H "Accept-Version: v4.0" '\
  '-H "Accept: application/json" '\
  '-H "X-ClientId: 293487fhs98345yswoeir245789" '\
  '-H "Date: Thu, 06 Oct 2011 02:26:12 GMT"'

AUTH_HEADERS = '-H "Content-Type: application/json" ' \
  '-H "Accept-Version: v4.0" '\
  '-H "Accept: application/json" '\
  '-H "Authorization: Bearer 945148251b603ae34561d90acfe4050e67494d6d1e65d4d3d52798407f03c0bd" '\
  '-H "X-ClientId: 293487fhs98345yswoeir245789" '\
  '-H "Date: Thu, 06 Oct 2011 02:26:12 GMT"'
Header Example Required Description
Authorization Bearer d6d6533c5ab9b528526f3e48a51e90b62 Optional All Thanx Loyalty API endpoints are protected and must be authorized via end user access tokens. These access tokens can be retrieved through an integration with Thanx SSO. The format of the header should be: Bearer access_token. Some endpoints don't require a user to be signed in; these are called out in their separate sections.
Content-Type application/json Optional The only accepted value is application/json or empty if no body
Accept-Version v4.0 Required The Accept-Version header specifies which version of the Thanx API that should be used. The current version is v4.0. This header is required for every request. Thanx will notify you when a new API version is available.
Accept application/json Required The only accepted value is application/json
X-ClientId f050d74b5c2b12ae17c85bd510addd7ba2 Required Thanx will provide you with this value.
X-Signature wGlo9uwpPHggRhFupSYjEkfHXhTf1uruek= Optional This should be computed on a per-request basis following the algorithm described below.
Date Thu, 06 Oct 2011 02:26:12 GMT Required This timestamp must be within 5 minutes of Thanx server time.

Request Signature

Thanx suggests that you provide a signature with every request. Thanx will validate this signature. This is an extra security feature that provides a guarantee that a request was not tampered with on its way from client to server.

# pseudocode
stringToSign = string.Join(
  ",",
  ClientId,
  HttpVerb,
  HttpContentType,
  Base64(SHA256(HttpBody)),
  UriPathAndQuery
)

signature = Base64(HMAC-SHA256(ClientSecret, UTF8(stringToSign)))

  1. Assemble the components of the string that will be signed:

    • Client ID
    • Request method (GET, POST, PATCH, PUT, DELETE)
    • Content Type (same as the header value or empty string if no body)
    • The request body (empty string if no body)
    • The request path

  2. Base64 encode the body after creating a digest using SHA-256.

  3. Join these strings together, with a comma separator.

  4. Create a digest using HMAC & SHA-256.

  5. Base64 encode the digest.

  6. This value is your signature header.

See examples to the right.

Errors

Thanx uses standard HTTP error codes to communicate the success / failure of a request.

Response (401 Unauthorized)

{
  "error": {
    "code":    "AUTHENTICATION_GENERIC",
    "message": "There was an error authenticating you."
  }
}

Response (404 NOT FOUND)

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The resource you requested was not found."
  }
}

Response (400 Bad Request)

{
  "error": {
    "code": "USER_EMAIL_INVALID",
    "message": "The email entered is invalid."
  }
}

An HTTP 400 Bad Request will always be accompanied by an object containing two properties: code (see below) and message. The code will remain static though the associated message may change at any time. Thanx can expand this list at any time.

Code Sample Message
BAD_REQUEST "An error occurred."
FORBIDDEN "You do not have access to this resource."
GENERIC_ERROR "Something went wrong"
RESOURCE_NOT_FOUND "The resource you requested was not found."
AUTHENTICATION_GENERIC "There was an error authenticating you."
USER_EMAIL_INVALID "The email entered is invalid."
USER_PHONE_INVALID "The phone entered is invalid."
USER_NAME_REQUIRED "First and last name are required fields."
REWARD_ALREADY_USED "This reward has already been used."
REWARD_EXPIRED "This reward is no longer valid."
REWARD_INAPPLICABLE "Required item not present."
REWARD_FRAUDULENT "You appear to have already used one of these rewards."
CARD_GENERIC "Unable to register this card due to an issue at Visa."
CARD_INVALID "This type of card is not accepted."

Patterns

This section calls out some patterns in this API.

General requirements

User must be able to navigate to the Thanx Privacy Policy and Terms of Service from the App and the Web Ordering experience after initial sign up has completed when they are using the app on an ongoing basis. Linking to the Thanx Terms of Service and Privacy Policy from another like document that is readily available in the app is sufficient.

User creation

The following notice with hyperlinks to the Thanx Privacy Policy and Terms of Service must be displayed in all experiences where a user signs up:

By signing up you agree to our privacy policy and our terms of service

By signing up you agree to our privacy policy and our terms of service

Note that you may style this sentence as you'd like. You may replace the default agreement links above with the corresponding brand-specific agreement links Thanx generates for your app:

Agreement Type URL Pattern
Privacy Policy https://app.thanx.com/privacy/BRAND
Terms of Service https://app.thanx.com/terms/BRAND

BRAND denotes your designated Thanx platform handle.

Card linkage

Any screen that leverages the Thanx card linkage SDK to register credit cards for loyalty tracking with the major card networks (Visa, Mastercard, Amex) must be explicitly approved by the Thanx team for design and content.

Certification

When you are ready for your integration to be certified, let your customer success representative know. Certification of a new integration takes 1-2 weeks to allow for adequate evaluation time. If certification fails, this timeline will begin again.

Upon certification of your integration in the Sandbox environment, you will be provided with a set of production credentials that will allow you access to our Production environment.

The goal of certification is to ensure that your integration uses the Thanx API correctly and is set up to be successful long-term. Please work with Thanx Developer Support when seeking to add new features to a certified integration.

Certification Checklist:

Notes: In the below list the term "experience" is used to refer to both app and web.

General

SSO requirements

Cards requirements

Rewards requirements

Receipts requirements

Feedback requirements

Communication settings requirements

Push Registrations requirements

Tags requirements

Production Launch Requirements

Push Notifications

Thanx sends users push notifications in a variety of situations, such as when they make a purchase or earn a reward. We can send push notifications to your app as well. When you are ready to register your app with Thanx for push notifications, you should send your CSM at Thanx your APNS certificate, FCM server key, and sender ID via a secure mechanism, such as Dropbox Transfer.

The rest of this page provides information regarding the types of push notifications that Thanx currently sends.

A push notification payload will contain an event key and a merchant key. Each notification type may have other information provided. The sample notification text provided is not set in stone and will sometimes vary depending on the kinds of campaigns a merchant is running.

Notification object example for iOS:
{
  aps: {
    "alert": "You just made your first purchase at Pizza Merchant! You're now 56% towards your next reward here!",
    "badge": 1,
    "sound": "default",
    "content-available": 1
  }
  "merchant_id": "oiu234oiurw",
  "event":       "purchase_discount_applied",
  "purchase_id": "wotu310589"
}

Notification object example for Android:
{
  "content_available": true,
  "data": {
    "message": "You just made your first purchase at Pizza Merchant! You're now 56% towards your next reward here!",
    "merchant_id": "oiu234oiurw",
    "event":       "purchase_discount_applied",
    "purchase_id": "wotu310589"
  },
  "notification": {
    "title": "You just made your first purchase at Pizza Merchant! You're now 56% towards your next reward here!"
  }
}

Purchase notifications

When a user makes a purchase, one of the following notifications is sent:

Discount Applied

A user activated a statement credit reward, and this reward was applied to the purchase.

Thanx! You just saved $10 at Pizza Merchant! It'll show up on your credit card statement in about two days.

event: :purchase_discount_applied

Additional payload keys:

purchase_id: 'to35yu2o4i6y34io2j24'

Reward Unlocked

A user unlocked a reward by making this purchase. This reward would have been received as a result of a referral.

The reward ($5 off) you got from Alice for signing up is now available for you to use.

event: :referral_reward_unlocked

Additional payload keys:

reward_id: 'ri3of2o5i46o32iu4u4k'

Granted

A user's receipt was accepted and they were granted progress toward their loyalty reward.

Heads up: Pizza Merchant granted you credit for $15.63 toward your next reward.

event: :progress_granted

Additional payload keys:

purchase_id: 'to35yu2o4i6y34io2j24'

Under Minimum

A user had activated a statement credit reward, but didn't spend enough money on their subsequent purchase.

We couldn't apply your statement credit reward at Pizza Merchant - it was less than the $25 minimum! We'll try to apply it to your next purchase.

event: :reward_under_minimum

Additional payload keys:

reward_id: 'ri3of2o5i46o32iu4u4k'

purchase_id: 'to35yu2o4i6y34io2j24'

Reward Earned

This purchase resulted in a user earning their loyalty reward.

Cha-ching! You just earned $10 off your purchase at Pizza Merchant! Open up Pizza Merchant and activate it when you're ready to use it.

event: :purchase_reward_earned

Additional payload keys:

reward_id: 'ri3of2o5i46o32iu4u4k'

purchase_id: 'to35yu2o4i6y34io2j24'

Initial Purchase

The user made their first purchase.

You just made your first purchase at Pizza Merchant! You're now 56% towards your next reward here!

event: :first_purchase

Additional payload keys:

purchase_id: 'to35yu2o4i6y34io2j24'

Reward Unused

A user made an purchase and had a reward they could have used.

Heads up: you had a reward waiting for you at Pizza Merchant that you could have used! Activate it before your next visit!

event: :purchase_reward_unused

Additional payload keys:

reward_id: 'ri3of2o5i46o32iu4u4k'

purchase_id: 'to35yu2o4i6y34io2j24'

Invalid Purchase Amount

A user made a purchase that was too small to count for loyalty progress.

Your purchase came in from Pizza Merchant but it was under the minimum purchase. Make a purchase over $5 to earn loyalty progress.

event: :purchase_under_minimum

Additional payload keys:

purchase_id: 'to35yu2o4i6y34io2j24'

Settlement Required

A merchant's settings require a settlement to come in before the user can be granted loyalty progress.

Your Pizza Merchant purchase came through but reward progress won't apply until your credit card purchase settles. Stay tuned!

event: :purchase_settlement_required

Additional payload keys:

purchase_id: 'to35yu2o4i6y34io2j24'

Tier Purchase Progress

A user made a purchase that counted toward tier progress. If a merchant has both a loyalty campaign and tiers, the loyalty progress message will be sent instead.

You're on your way! Spend $670.56 before the end of the year to earn Silver.

event: :purchase_tier_progress

Loyalty Progress

A user made a purchase that counted toward loyalty progress.

You're almost there! You're now 45% toward your next reward at Pizza Merchant.

event: :purchase_loyalty_progress

Additional payload keys:

purchase_id: 'to35yu2o4i6y34io2j24'

Tiers notifications

On track to reach the silver tier

You're on track to reach Silver for Pizza Merchant - spend $35.24 more by Dec 31st!

event: :tier_silver_on_track

Reached the silver tier

Silver rewards at Pizza Merchant are yours! Congrats on achieving Silver status!

event: :tier_silver_reached

On track to reach the gold tier

You're on track to reach Gold for Pizza Merchant - spend $23.45 more by Dec 31st!

event: :tier_gold_on_track

Reached the gold tier

Congrats on achieving Gold status at Pizza Merchant! Open up the app to see your new perks!

event: :tier_gold_reached

Tier status expiring soon

Your Gold status runs out in four weeks. Spend $450.24 to keep it for another year!

event: :tier_status_expiring

Vip notifications

As users earn toward VIP status, they receive the following messages.

VIP active

You're a Pizza Merchant VIP! Open up the app to check out your VIP Reward!

event: :vip_active

VIP at risk

You're almost out of time! You still need to spend $35 before Dec 1st to remain a Pizza Merchant VIP.

event: :vip_at_risk

VIP eligible

You're eligible for VIP this month at Pizza Merchant! Spend $50 before the end of the month to earn VIP status through Jan 1st!

event: :vip_eligible

VIP on track

Your spending makes you eligible to earn VIP at Pizza Merchant! Spend $50 next month to earn a free pizza all month!

event: :vip_on_track

VIP nearly there

You're almost a Pizza Merchant VIP! Spend $45 before Dec 1st to earn a free cactus all month!

event: :vip_visible

Reward notifications

A reward is issued

This text is customizable by the merchant when they run a campaign. If customized text isn't provided, the following text is used.

You have a new reward from Pizza Merchant!

event: :reward_issued

Additional payload keys:

reward_id: 'ri3of2o5i46o32iu4u4k'

A reward is expiring

Heads up! Your $5 off at Pizza Merchant expires on 12/15! Don’t miss out!

event: :reward_expiring

Additional payload keys:

reward_id: 'ri3of2o5i46o32iu4u4k'

A reward was granted

The merchant issued a user a reward as a result of NPS feedback.

Pizza Merchant granted you a new reward: a free pizza!

event: :reward_granted

Additional payload keys:

reward_id: 'ri3of2o5i46o32iu4u4k'

Reminder about an unused reward

Don't forget! You have a reward ($15 off) waiting for you at Pizza Merchant!

event: :reward_reminder

Additional payload keys:

reward_id: 'ri3of2o5i46o32iu4u4k'

Other notifications

Invite progress earned

A user's referral made their first purchase.

Your friend Bob just made their first purchase! Here's $5 off as our way of saying thanx.

event: :invitation_progress_earned

NPS prompt

How was your visit to Pizza Merchant?

event: :purchase_nps_prompt

Additional payload keys:

purchase_id: 'to35yu2o4i6y34io2j24'

feedback_id: 'ghjh2k34j5l23kj44566'

Mobile App Support

Scheme registration for Deep Linking

Thanx provides ways to deep link into your app from different parts of the platform. In order for that deep link to work and open your app, you'll have to register a specific scheme. Contact Merchant Success or Dev Support in order to know what would be the unique scheme you'll need to use.

There are two main URLs that the Thanx platform will try to use in order to open your app:

1 - SCHEME://open

2 - SCHEME://magic

The first one is a generic URL used to open your app, and the second one is used during the authentication flow; alternatively, you can configure a different redirect URI and the second (authentication) URL will never be invoked. For example, if your SCHEME is pizzaco, then the default URLs your app needs to handle are pizzaco://open and pizzaco://magic.

Configuring the scheme for iOS

Add the following into your main Info.plist file:

<!-- Info.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
...
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLName</key>
        <string>Thanx</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>{SCHEME}</string>
        </array>
    </dict>
</array>
...
</plist>

Where {SCHEME} is your own merchant scheme provided by Thanx.

You can find more information in the Apple documentation

Configuring the scheme for Android

Add an intent-filter with the following properties for the main activity in the Manifest.xml file:

<!-- Manifest.xml -->
<activity>
  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="{SCHEME}" android:host="magic"/>
    <data android:scheme="{SCHEME}" android:host="open"/>
  </intent-filter>
</activity>

Where {SCHEME} is your own merchant scheme provided by Thanx.

You can find more information in the Android Developer documentation

Users

API Endpoint

Sandbox: https://api.thanxsandbox.com/users

This section describes endpoints that enable a third party to fetch a user's profile and update aspects of that profile.

Get user

curl https://api.thanxsandbox.com/users/fkwerr \
  $AUTH_HEADERS

Response (200 OK)

{
  "user": {
    "id": "fkwerr",
    "email": "john.smith@example.com",
    "phone": "+14158672345",
    "first_name": "Jane",
    "last_name": "Smith",
    "birth_date": {
      "year": 1987,
      "month": 8,
      "day": 14
    },
    "gender": "female",
    "zip_code": "12345"
  }
}

This endpoint will return the specified user's information. Note The user's phone number is not gathered by Thanx with the permission to use it for marketing.

HTTP Request

GET /users/:id

Response

Field Type Description
id string The user's identifier
email string The user's email
phone string The user's phone number, formatted: +14157582345
first_name string The user's first name
last_name string The user's last name
birth_date hash The user's birthday information
birth_date.year integer The user's birth year
birth_date.month integer The user's birth month
birth_date.day integer The user's birth day
gender enum The user's gender (male, female, other, unknown)
zip_code string The user's zip code

Get currently logged in user

curl https://api.thanxsandbox.com/users/me \
  $AUTH_HEADERS

Response (200 OK)

{
  "user": {
    "id": "fkwerr",
    "email": "john.smith@example.com",
    "phone": "+14158672345",
    "first_name": "Jane",
    "last_name": "Smith",
    "birth_date": {
      "year": 1987,
      "month": 8,
      "day": 14
    },
    "gender": "female",
    "zip_code": "12345"
  }
}

This endpoint will return the specified user's information. Note The user's phone number is not gathered by Thanx with the permission to use it for marketing.

HTTP Request

GET /users/me

Response

Field Type Description
id string The user's identifier
email string The user's email
phone string The user's phone number, formatted: +14157582345
first_name string The user's first name
last_name string The user's last name
birth_date hash The user's birthday information
birth_date.year integer The user's birth year
birth_date.month integer The user's birth month
birth_date.day integer The user's birth day
gender enum The user's gender (male, female, other, unknown)
zip_code string The user's zip code

Create user

Create a new user

curl https://api.thanxsandbox.com/users/ \
  -X POST \
  $STANDARD_HEADERS
  -d '{
    "user": {
      "email": "jane.smith@example.com",
      "phone": "+14158672345",
      "first_name": "Jane",
      "last_name":  "Smith",
      "birth_date": {
        "year": 1987,
        "month": 8,
        "day": 14
      },
      "gender": "other",
      "zip_code": "12345"
    }
  }'

Response (201 CREATED)

{
  "user": {
    "id": "wroeiu2304hfwf",
    "email": "jane.smith@example.com",
    "phone": "+14158672345",
    "first_name": "Jane",
    "last_name": "Smith",
    "birth_date": {
      "year": 1987,
      "month": 8,
      "day": 14
    },
    "gender": "other",
    "zip_code": "12345"
  },
  "authorization": {
    "token_type": "Bearer",
    "scope": "passwordless",
    "created_at": 1577836800,
    "access_token": "945148251b603ae34561d90acfe4050e67494d6d1e65d4d3d52798407f03c0bd",
    "refresh_token": "c74334301a7c74d21b714c905fd3047177dab56de6a86899e6f6b7f71bab7d55"
  }
}

User does not exist, additional params required to create user

curl https://api.thanxsandbox.com/users/ \
  -X POST \
  $STANDARD_HEADERS
  -d '{
    "user": {
      "email": "jane.smith@example.com"
    }
  }'

Response (400 BAD REQUEST)

{
  "error": {
    "code": "USER_NAME_REQUIRED",
    "message": "First and last name are required fields."
  }
}

Sign up an existing user without SSO

curl https://api.thanxsandbox.com/users/ \
  -X POST \
  $STANDARD_HEADERS
  -d '{
    "user": {
      "email": "jane.smith@example.com"
    }
  }'

Response (400 BAD REQUEST)

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "User account exists"
  }
}

This endpoint creates a user, but it also facilitates signing an existing platform user up with the client brand in scenarios where the SSO flow wouldn't be appropriate (i.e., the user is not signing in to an authenticated experience). If a user with the specified email already exists, it signs the user up with the client brand before returning a 400 level error. This endpoint also returns authorization information for a successfully created user, including an access_token that can be used to access other API endpoints. Experiences utilizing this endpoint must adhere to the legal requirements for user creation.

HTTP Request

POST /users

Request

Parameter Type Required Description
email string Required The user's email
phone string Optional The user's phone number, formatted: +14157582345
first_name string Required* The user's first name
last_name string Required* The user's last name
birth_date hash Optional The user's birthday information
birth_date.year integer Optional The user's birth year
birth_date.month integer Optional The user's birth month
birth_date.day integer Optional The user's birth day
gender enum Optional The user's gender (male, female, other, unknown)
zip_code string Optional The user's zip code

*This endpoint permits minimal requests that only contain an email parameter for the purposes of signing up an existing platform user with the client brand. If the email belongs to an existing user, it signs the user up with the brand before returning a 400 level error.

Response

Field Type Description
user.id string The user's identifier
user.email string The user's email
user.phone string The user's phone number, formatted: +14157582345
user.first_name string The user's first name
user.last_name string The user's last name
user.birth_date hash The user's birthday information
user.birth_date.year integer The user's birth year
user.birth_date.month integer The user's birth month
user.birth_date.day integer The user's birth day
user.gender enum The user's gender (male, female, other, unknown)
user.zip_code string The user's zip code
authorization.token_type string The type of token, usually "Bearer"
authorization.scope string This will be 'passwordless'
authorization.created_at integer The number of seconds since the epoch
authorization.access_token string The user's access token, for use in accessing other API endpoints
authorization.refresh_token string If needed, a refresh token to get another access token

Update user

curl https://api.thanxsandbox.com/users/werljwer \
  -X PATCH \
  $AUTH_HEADERS
  -d '{
    "user": {
      "email": "jane.smith@example.com",
      "first_name": "Jane"
    }
  }'

Response (200 OK)

{
  "user": {
    "id": "fgr2349gh",
    "email": "john.smith@example.com",
    "phone": "+14158672345",
    "first_name": "Jane",
    "last_name": "Smith",
    "birth_date": {
      "year": 1987,
      "month": 8,
      "day": 14
    },
    "gender": "unknown",
    "zip_code": "12345"
  }
}

This endpoint updates the specified user's information. Note The user's phone number is not gathered by Thanx with the permission to use it for marketing.

HTTP Request

PATCH /users/:id

Request

Parameter Type Required Description
email string Optional The user's email
phone string Optional The user's phone number, formatted: +14157582345
first_name string Optional The user's first name
last_name string Optional The user's last name
birth_date hash Optional The user's birthday information
birth_date.year integer Optional The user's birth year
birth_date.month integer Optional The user's birth month
birth_date.day integer Optional The user's birth day
gender enum Optional The user's gender (male, female, other, unknown)
zip_code string Optional The user's zip code

Response

Field Type Description
id string The user's identifier
email string The user's email
phone string The user's phone number, formatted: +14157582345
first_name string The user's first name
last_name string The user's last name
birth_date hash The user's birthday information
birth_date.year integer The user's birth year
birth_date.month integer The user's birth month
birth_date.day integer The user's birth day
gender enum The user's gender (male, female, other, unknown)
zip_code string The user's zip code

SSO

API Endpoint

https://api.thanxsandbox.com/oauth

This section describes the process of authenticating with Thanx via Thanx SSO. Thanx SSO authenticates the user via a password-less flow using email authentication, rather than a password. This reduces the friction of a user having to manage yet another password as well as reduces the friction of transitioning an existing user-base to Thanx.

Thanx follows the standard OAuth 2.0 spec, using the Authorization Code grant type. Refer to the OAuth 2.0 Authorization Framework RFC: Section 4.1 for additional details.

Here is what the flow would look like:

  1. User navigates to the partner website and clicks an authentication button.
  2. The merchant website prompts the user to input an email address
  3. The merchant website makes a request to the POST /oauth/authorize endpoint described below. (Continue to #4 or #5)
  4. If no account exists for the specified email address, a 401 error is thrown. A user can be created via the POST /users endpoint.
  5. If an account exists for the specified email address, an auth email is sent to specified email. The user clicks the auth email link which redirects to the merchant website at the specified redirect_uri with an authorization code in the params.
  6. Merchant website exchanges the authorization code for an access token via the POST /oauth/token endpoint described below. User is now authenticated with the Thanx system through the returned access token.

The following notice with hyperlinks to the Thanx Privacy Policy and Terms of Service must be displayed in all experiences where a user signs up:

By signing up you agree to our privacy policy and our terms of service

By signing up you agree to our privacy policy and our terms of service

Note that you may style this sentence as you'd like. You may replace the default agreement links above with the corresponding brand-specific agreement links Thanx generates for your app:

Agreement Type URL Pattern
Privacy Policy https://app.thanx.com/privacy/BRAND
Terms of Service https://app.thanx.com/terms/BRAND

BRAND denotes your designated Thanx platform handle.

Acquire authorization code

curl https://api.thanxsandbox.com/oauth/authorize \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "f4bf04a6fc27b5fa926a7318933b76440642c25cde037d8e867b3d18d771ad86",
    "redirect_uri": "https://www.example.com/oauth/callback",
    "response_type": "code",
    "scope": "passwordless",
    "username": "john.smith@example.com"
  }'

Response (200 OK)

""

This flow is to support passwordless login. If an account exists, an authentication email will be sent including a link that will eventually redirect to the redirect_uri with an authorization code.

Response (401 Unauthorized)

{
  "error": "access_denied",
  "error_description": "The resource owner or authorization server denied the request."
}

If an account does not exist for the specified email, a 401 error will be returned. To create an account, the POST /users endpoint should be used.

HTTP Request

POST /oauth/authorize

Request

Parameter Type Required Description
client_id string Required OAuth Client ID
redirect_uri string Required Where you want the user to be redirected
response_type string Required code is the required value
scope string Required passwordless is the required value
username string Required The user's email

Acquire access token

curl https://api.thanxsandbox.com/oauth/token \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "f4bf04a6fc27b5fa926a7318933b76440642c25cde037d8e867b3d18d771ad86",
    "client_secret": "83c08861ce6302e0e73d28cea30aa3f8f3ea98446e133fde60a86231f50f5c82",
    "code": "c13a4ba07f27cfc69a03a5c9cda630205e5f2833331fb761d38eef10c091f371",
    "redirect_uri": "https://www.example.com/oauth/callback"
  }'

Response (200 OK)

{
  "token_type": "Bearer",
  "scope": "passwordless",
  "created_at": 1577836800,
  "access_token": "945148251b603ae34561d90acfe4050e67494d6d1e65d4d3d52798407f03c0bd",
  "refresh_token": "c74334301a7c74d21b714c905fd3047177dab56de6a86899e6f6b7f71bab7d55"
}

Use this endpoint to acquire a user's access token. This same endpoint supports refreshing an access token using the client_id, client_secret, and refresh_token, with grant_type set to refresh_token.

HTTP Request

POST /oauth/token

Request

Parameter Type Required Description
grant_type string Required authorization_code is the required value
client_id string Required OAuth Client ID
client_secret string Required OAuth Client Secret
code string Required The authorization code received from Thanx via redirect or API
redirect_uri string Required The same redirect_uri should be used as in the request for the authorization code

Response

Field Type Description
token_type string The type of token, usually "Bearer"
scope string This will be 'passwordless'
created_at integer The number of seconds since the epoch
access_token string The user's access token, for use in accessing other API endpoints
refresh_token string If needed, a refresh token to get another access token

Revoke Access Token

curl https://api.thanxsandbox.com/oauth/revoke \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "f4bf04a6fc27b5fa926a7318933b76440642c25cde037d8e867b3d18d771ad86",
    "client_secret": "83c08861ce6302e0e73d28cea30aa3f8f3ea98446e133fde60a86231f50f5c82",
    "token": "945148251b603ae34561d90acfe4050e67494d6d1e65d4d3d52798407f03c0bd"
  }'

Response (200 OK)

{}

Use this endpoint to revoke a user's access token.

HTTP Request

POST /oauth/revoke

Request

Parameter Type Required Description
client_id string Required OAuth Client ID
client_secret string Required OAuth Client Secret
token string Required OAuth Access Token

Features

API Endpoint

Sandbox: https://api.thanxsandbox.com/features

This section describes endpoints that enable a third party to fetch features that are configured for a given merchant. These features include and are not limited to the requirements to earn and redeem a loyalty reward, the birthday reward, and the introductory reward.

Get Features

curl https://api.thanxsandbox.com/features \
  $STANDARD_HEADERS

Response (200 OK)

{
  "features": [
    {
      "merchant_id": "wourhfslur",
      "loyalty": {
        "earn": {
          "description": "spend $150",
          "threshold": 150,
          "type": "spend"
        },
        "redeem": {
          "type": "manual",
          "text": "$10 off",
          "venue": "all"
        }
      },
      "intro": {
        "earn": {
          "description": "sign up"
        },
        "redeem": {
          "type": "manual",
          "text": "free sandwich",
          "venue": "online"
        }
      },
      "birthday": {
        "earn": {
          "description": "provide your birthday"
        },
        "redeem": {
          "type": "automatic",
          "text": "10% off",
          "venue": "instore"
        }
      }
    }
  ]
}

This endpoint returns the configuration for a merchant's features. If a merchant does not have a particular feature defined or enabled, the value for the associated feature key will be empty.

HTTP Request

GET /features

Request

Parameter Type Required Description
merchant_id string Optional Only return features for this merchant if you have access to multiple merchants

Response

Field Type Description
merchant_id string The merchant ID
loyalty hash Describes the configuration for the loyalty campaign
loyalty.earn hash Describes how the loyalty reward is earned
loyalty.earn.description string What the user should do to earn the reward
loyalty.earn.type enum Whether the user earns progress via how much they spend or how many times they visit. Returns 'spend' or 'visit'.
loyalty.earn.threshold integer How much the user needs to spend or how many visits the user needs to make to earn the reward.
loyalty.redeem hash Describes what the reward is
loyalty.redeem.type enum How the reward can be redeemed (manual, automatic)
loyalty.redeem.text string Description of what the loyalty reward is
loyalty.redeem.venue enum Where the reward can be used: (instore, online, all)
intro hash Describes the configuration for the introductory campaign
intro.earn hash Describes how the introductory reward is earned
intro.earn.description string What the user should do to earn the reward
intro.redeem hash Describes what the reward is
intro.redeem.type enum How the reward can be redeemed (manual, automatic)
intro.redeem.text string Description of what the introductory reward is
intro.redeem.venue enum Where the reward can be used: (instore, online, all)
birthday hash Describes the configuration for the birthday campaign
birthday.earn hash Describes how the birthday reward is earned
birthday.earn.description string What the user should do to earn the reward
birthday.redeem hash Describes what the reward is
birthday.redeem.type enum How the reward can be redeemed (manual, automatic)
birthday.redeem.text string Description of what the birthday reward is
birthday.redeem.venue enum Where the reward can be used: (instore, online, all)

Cards

API Endpoint

https://api.thanxsandbox.com/cards

This section describes endpoints that enable a third party to fetch and register a user's cards.

Describe Cards

curl https://api.thanxsandbox.com/cards \
  $AUTH_HEADERS

Response (200 OK)

{
  "cards": [
    {
      "id": "92b7b0dac4",
      "user_id": "weorusfs",
      "last4": "1234",
      "type": "visa",
      "zip_code": "12345"
    },
    {
      "id": "wer340fweiu",
      "user_id": "weorufjsdf",
      "last4": "4567",
      "type": "amex",
      "zip_code": "54321"
    }
  ]
}

This endpoint describes all registered cards for the given user.

HTTP Request

GET /cards

Response

Field Type Description
id string Card ID
user_id string The user the card belongs to
last4 string Last 4 digits of the card PAN
type enum Card type (visa, mastercard, amex)
zip_code string The card's billing zip code

Get Signature

curl https://api.thanxsandbox.com/card_signature?card_type=amex \
  $AUTH_HEADERS

Response (200 OK)

{
  "card_signature": {
    "amex": {
      "public_key": "sfjwoiruweoirw20394jf09wr80294"
    }
  }
}

This endpoint provides a way to retrieve a signature for card encryption. The public key and certificate returned can be used with the card encryption SDK.

HTTP Request

GET /card_signature

Request

Parameter Type Required Description
card_type string Required Card type (visa, mastercard, amex)

Response

Field Type Description
visa hash Signature information for Visa
visa.public_key The public key to use for encryption.
mastercard hash Signature information for Mastercard
mastercard.public_key The public key to use for encryption.
amex hash Signature information for American Express
amex.public_key The public key to use for encryption.

Create Card

curl https://api.thanxsandbox.com/cards \
  -X POST \
  $AUTH_HEADERS
  -d '{
    "card": {
      "last4": "1234",
      "type": "visa",
      "encrypted_pan": "\{...\}",
      "zip_code": "12345"
    }
  }'

Response (201 CREATED)

{
  "card": {
    "id": "92b7b0dac4",
    "user_id": "weorufsdf",
    "last4": "1234",
    "type": "visa",
    "zip_code": "12345"
  }
}

This endpoint registers a new card with Thanx.

HTTP Request

POST /cards

Request

Parameter Type Required Description
last4 string Required Last 4 digits of the card PAN
type string Required Card type (visa, mastercard, amex)
encrypted_pan string Required Encrypted Card PAN (Must use Thanx Tokenization SDK for this. No raw PANs should ever be sent to Thanx APIs)
zip_code string Optional The card's billing zip code

Response

Field Type Description
id string Card ID
user_id string The user the card belongs to
last4 string Last 4 digits of the card PAN
type enum Card type (visa, mastercard, amex)
zip_code string The card's billing zip code

Delete Card

curl https://api.thanxsandbox.com/cards/92b7b0dac4 \
  -X DELETE \
  $AUTH_HEADERS

Response (204 NO_CONTENT)

{}

This endpoint archives a registered card. The card is unenrolled from Visa/Mastercard/Amex.

HTTP Request

DELETE /cards/:id

Rewards

API Endpoint

Sandbox: https://api.thanxsandbox.com/rewards

This section describes endpoints that enable a third party to fetch a user's rewards and activate (use) them on behalf of the user.

Describe Rewards

curl https://api.thanxsandbox.com/rewards \
  $AUTH_HEADERS

Response (200 OK)

{
  "rewards": [
    {
      "id": "222441e34626",
      "user_id": "werofsdf",
      "merchant_id": "weroif",
      "campaign_id": "85133c3c1258",
      "state": "available",
      "earn": {
        "type": "intro",
        "text": "Signing up"
      },
      "redeem": {
        "type": "manual",
        "text": "$10 off",
        "window": 60,
        "venue": "all"
      },
      "coupon_code": {
        "code": null,
        "type": null,
        "display": null
      },
      "fine_print": "Can't be used for alcohol purchases",
      "instructions": "Example staff instructions",
      "available_at": "2019-12-25T19:00:00Z",
      "activated_at": "2020-01-01T20:00:00Z",
      "retire_at": null,
      "used_at": null
    }
  ]
}

This endpoint returns a user's rewards. Rewards are available in several different states: - available => This reward is available to use - active => The user has activated this reward for use - used => The reward has been used

HTTP Request

GET /rewards

Request

Parameter Type Required Description
states array[string] Optional Only rewards in these states will be returned. Valid options are: (available, active, used). The default is to return all rewards in these 3 states.
merchant_id string Optional Only return rewards for this merchant
user_id string Optional Only return rewards for this user. Note: the bearer token will be used to determine which user's rewards are being requested when the request is made by a logged in user.

Response

Field Type Description
id string Reward ID
user_id string User ID
merchant_id string Merchant ID
campaign_id string Campaign ID
state enum Reward State (available, active, used)
fine_print string Fine print for the reward
instructions string Staff instructions for the reward
available_at string Time the reward was given to the user in ISO8601-format
activated_at string Time the reward was activated in ISO8601-format
used_at string Time the reward was marked as used in ISO8601-format
retire_at string Time the reward will be automatically retired in ISO8601-format
coupon_code hash This hash will be populated if the reward is 'active' or 'used' and the merchant uses coupon codes.
coupon_code.code string The raw coupon code value that should be rendered based on the coupon_code_type enum
coupon_code.type enum The type of coupon code that should be used to render the coupon_code value (raw, qrcode, barcode39, barcode39extended, barcode93, barcode128, barcode_upc_a, barcode_ean_8, barcode_ean_13, barcode25interleaved)
coupon_code.display string If set, should be displayed instead of the raw coupon code value
earn hash Details of how the reward was earned
earn.type enum Type of program the reward was earned with
earn.text string Description of how the reward was earned
redeem hash Details of how the reward can be redeemed
redeem.type enum How the reward can be redeemed (manual, automatic)
redeem.text string Description of what the reward is
redeem.venue enum Where the reward can be used: (instore, online, all)
redeem.window integer Number of minutes the reward is available for use after activation

Get Single Reward

curl https://api.thanxsandbox.com/rewards/222441e34626 \
  $AUTH_HEADERS

Response (200 OK)

{
  "reward": {
    "id": "222441e34626",
    "user_id": "werofsdf",
    "merchant_id": "weroif",
    "campaign_id": "85133c3c1258",
    "state": "available",
    "earn": {
      "type": "intro",
      "text": "Signing up"
    },
    "redeem": {
      "type": "manual",
      "text": "$10 off",
      "window": 60,
      "venue": "all"
    },
    "coupon_code": {
      "code": null,
      "type": null,
      "display": null
    },
    "fine_print": "Can't be used for alcohol purchases",
    "instructions": "Example staff instructions",
    "available_at": "2019-12-25T19:00:00Z",
    "activated_at": "2020-01-01T20:00:00Z",
    "retire_at": null,
    "used_at": null
  }
}

This endpoint returns the reward corresponding to the ID in the path.

HTTP Request

GET /rewards/:reward_id

Response

Field Type Description
id string Reward ID
user_id string User ID
merchant_id string Merchant ID
campaign_id string Campaign ID
state enum Reward State (available, active, used)
fine_print string Fine print for the reward
instructions string Staff instructions for the reward
available_at string Time the reward was given to the user in ISO8601-format
activated_at string Time the reward was activated in ISO8601-format
used_at string Time the reward was marked as used in ISO8601-format
retire_at string Time the reward will be automatically retired in ISO8601-format
coupon_code hash This hash will be populated if the reward is 'active' or 'used' and the merchant uses coupon codes.
coupon_code.code string The raw coupon code value that should be rendered based on the coupon_code_type enum
coupon_code.type enum The type of coupon code that should be used to render the coupon_code value (raw, qrcode, barcode39, barcode39extended, barcode93, barcode128, barcode_upc_a, barcode_ean_8, barcode_ean_13, barcode25interleaved)
coupon_code.display string If set, should be displayed instead of the raw coupon code value
earn hash Details of how the reward was earned
earn.type enum Type of program the reward was earned with
earn.text string Description of how the reward was earned
redeem hash Details of how the reward can be redeemed
redeem.type enum How the reward can be redeemed (manual, automatic)
redeem.text string Description of what the reward is
redeem.venue enum Where the reward can be used: (instore, online, all)
redeem.window integer Number of minutes the reward is available for use after activation

Activate Reward

curl https://api.thanxsandbox.com/users/roiwe/rewards/222441e34626/activate \
  -X PATCH \
  $AUTH_HEADERS

Response (200 OK)

{
  "reward": {
    "id": "222441e34626",
    "user_id": "werofsdf",
    "merchant_id": "weroif",
    "campaign_id": "85133c3c1258",
    "state": "active",
    "earn": {
      "type": "intro",
      "text": "Signing up"
    },
    "redeem": {
      "type": "manual",
      "text": "$10 off",
      "window": 60,
      "venue": "all"
    },
    "coupon_code": {
      "code": null,
      "type": null,
      "display": null
    },
    "fine_print": "Can't be used for alcohol purchases",
    "instructions": "Example staff instructions",
    "available_at": "2019-12-25T19:00:00Z",
    "activated_at": "2020-01-01T20:00:00Z",
    "retire_at": null,
    "used_at": null
  }
}

This endpoint activates the reward, transitioning reward state from available to active.

HTTP Request

PATCH /rewards/:reward_id/activate

Response

Field Type Description
id string Reward ID
user_id string User ID
merchant_id string Merchant ID
campaign_id string Campaign ID
state enum Reward State (available, active, used)
fine_print string Fine print for the reward
instructions string Staff instructions for the reward
available_at string Time the reward was given to the user in ISO8601-format
activated_at string Time the reward was activated in ISO8601-format
used_at string Time the reward was marked as used in ISO8601-format
retire_at string Time the reward will be automatically retired in ISO8601-format
coupon_code hash This hash will be populated if the reward is 'active' or 'used' and the merchant uses coupon codes.
coupon_code.code string The raw coupon code value that should be rendered based on the coupon_code_type enum
coupon_code.type enum The type of coupon code that should be used to render the coupon_code value (raw, qrcode, barcode39, barcode39extended, barcode93, barcode128, barcode_upc_a, barcode_ean_8, barcode_ean_13, barcode25interleaved)
coupon_code.display string If set, should be displayed instead of the raw coupon code value
earn hash Details of how the reward was earned
earn.type enum Type of program the reward was earned with
earn.text string Description of how the reward was earned
redeem hash Details of how the reward can be redeemed
redeem.type enum How the reward can be redeemed (manual, automatic)
redeem.text string Description of what the reward is
redeem.venue enum Where the reward can be used: (instore, online, all)
redeem.window integer Number of minutes the reward is available for use after activation

Finalize Reward

curl https://api.thanxsandbox.com/rewards/222441e34626/finalize \
  -X PATCH \
  $AUTH_HEADERS

Response (200 OK)

{
  "reward": {
    "id": "222441e34626",
    "user_id": "werofsdf",
    "merchant_id": "weroif",
    "campaign_id": "85133c3c1258",
    "state": "used",
    "earn": {
      "type": "intro",
      "text": "Signing up"
    },
    "redeem": {
      "type": "manual",
      "text": "$10 off",
      "window": 60,
      "venue": "all"
    },
    "coupon_code": {
      "code": null,
      "type": null,
      "display": null
    },
    "fine_print": "Can't be used for alcohol purchases",
    "instructions": "Example staff instructions",
    "available_at": "2019-12-25T19:00:00Z",
    "activated_at": "2020-01-01T20:00:00Z",
    "retire_at": null,
    "used_at": null
  }
}

This endpoint marks the reward as used, transitioning reward state to used.

HTTP Request

PATCH /rewards/:reward_id/finalize

Response

Field Type Description
id string Reward ID
user_id string User ID
merchant_id string Merchant ID
campaign_id string Campaign ID
state enum Reward State (available, active, used)
fine_print string Fine print for the reward
instructions string Staff instructions for the reward
available_at string Time the reward was given to the user in ISO8601-format
activated_at string Time the reward was activated in ISO8601-format
used_at string Time the reward was marked as used in ISO8601-format
retire_at string Time the reward will be automatically retired in ISO8601-format
coupon_code hash This hash will be populated if the reward is 'active' or 'used' and the merchant uses coupon codes.
coupon_code.code string The raw coupon code value that should be rendered based on the coupon_code_type enum
coupon_code.type enum The type of coupon code that should be used to render the coupon_code value (raw, qrcode, barcode39, barcode39extended, barcode93, barcode128, barcode_upc_a, barcode_ean_8, barcode_ean_13, barcode25interleaved)
coupon_code.display string If set, should be displayed instead of the raw coupon code value
earn hash Details of how the reward was earned
earn.type enum Type of program the reward was earned with
earn.text string Description of how the reward was earned
redeem hash Details of how the reward can be redeemed
redeem.type enum How the reward can be redeemed (manual, automatic)
redeem.text string Description of what the reward is
redeem.venue enum Where the reward can be used: (instore, online, all)
redeem.window integer Number of minutes the reward is available for use after activation

Grant Reward

curl https://api.thanxsandbox.com/rewards/grant \
  -X POST \
  $STANDARD_HEADERS
  -d '{
    "user_id": "weoru",
    "campaign_id": "weroui234890f"
  }'

Response (200 OK)

{
  "reward": {
    "id": "222441e34626",
    "user_id": "werofsdf",
    "merchant_id": "weroif",
    "campaign_id": "85133c3c1258",
    "state": "active",
    "earn": {
      "type": "intro",
      "text": "Signing up"
    },
    "redeem": {
      "type": "manual",
      "text": "$10 off",
      "window": 60,
      "venue": "all"
    },
    "coupon_code": {
      "code": null,
      "type": null,
      "display": null
    },
    "fine_print": "Can't be used for alcohol purchases",
    "instructions": "Example staff instructions",
    "available_at": "2019-12-25T19:00:00Z",
    "activated_at": "2020-01-01T20:00:00Z",
    "retire_at": null,
    "used_at": null
  }
}

This endpoint grants the user a reward associated with the campaign provided. This endpoint is only available in SANDBOX

HTTP Request

POST /rewards/grant

Request

Parameter Type Required Description
campaign_id string Required The campaign id to grant the reward for
user_id string Required The user to grant the reward for

Response

Field Type Description
id string Reward ID
campaign_id string Campaign ID
state enum Reward State (available, active, used)
fine_print string Fine print for the reward
instructions string Staff instructions for the reward
available_at string Time the reward was given to the user in ISO8601-format
activated_at string Time the reward was activated in ISO8601-format
used_at string Time the reward was marked as used in ISO8601-format
retire_at string Time the reward will be automatically retired in ISO8601-format
coupon_code hash This hash will be populated if the reward is 'active' or 'used' and the merchant uses coupon codes.
coupon_code.code string The raw coupon code value that should be rendered based on the coupon_code_type enum
coupon_code.type enum The type of coupon code that should be used to render the coupon_code value (raw, qrcode, barcode39, barcode39extended, barcode93, barcode128, barcode_upc_a, barcode_ean_8, barcode_ean_13, barcode25interleaved)
coupon_code.display string If set, should be displayed instead of the raw coupon code value
earn hash Details of how the reward was earned
earn.type enum Type of program the reward was earned with
earn.text string Description of how the reward was earned
redeem hash Details of how the reward can be redeemed
redeem.type enum How the reward can be redeemed (manual, automatic)
redeem.text string Description of what the reward is
redeem.venue enum Where the reward can be used: (instore, online, all)
redeem.window integer Number of minutes the reward is available for use after activation

Tags

API Endpoint Sandbox: https://api.thanxsandbox.com/tags

This section describes endpoints that enable a third party to fetch and update a user's tags.

Describe Tags

curl https://api.thanxsandbox.com/tags \
  $AUTH_HEADERS

Response (200 OK)

{
  "tags": [
    {
      "id": "92b7b0dac4",
      "user_id": "werofsdf",
      "merchant_id": "weroif",
      "key": "allergens",
      "values": [
        "gluten",
        "soy",
        "dairy"
      ]
    }
  ]
}

This endpoint describes all attribute tags for the given user.

HTTP Request

GET /tags

Request

Parameter Type Required Description
merchant_id string Optional Only return tags for this merchant

Response

Field Type Description
id string Tag ID
user_id string User ID
merchant_id string Merchant ID
key string Tag key
values array(string) Array of attribute tags

Update Tags

curl https://api.thanxsandbox.com/tags \
  -X PUT \
  $AUTH_HEADERS
  -d '{
    "tag": {
      "key": "allergens",
      "merchant_id": "weroifs",
      "values": [
        "gluten",
        "soy",
        "dairy",
        "honey"
      ]
    }
  }'

Response (200 OK)

{
  "tag": {
    "id": "werwerr",
    "user_id": "werofsdf",
    "merchant_id": "weroif",
    "key": "allergens",
    "values": [
      "gluten",
      "soy",
      "dairy",
      "honey"
    ]
  }
}

This endpoint updates an attribute tag for the given user. The tag associated with the key in the request will be created or updated with the values passed in.

HTTP Request

PUT /tags

Request

Parameter Type Required Description
merchant_id string Required Merchant ID
key string Required Tag key
values array(string) Required Array of attributes tags

Response

Field Type Description
id string Tag ID
user_id string User ID
merchant_id string Merchant ID
key string Tag key
values array(string) Array of attribute tags

Delete Tag

curl https://api.thanxsandbox.com/tags/92b7b0dac4 \
  -X DELETE \
  $AUTH_HEADERS

Response (200 OK)

{}

This endpoint deletes an attribute tag with the given ID.

HTTP Request

DELETE /tags/:id

Communication Settings

API Endpoint

Sandbox: https://api.thanxsandbox.com/communication_settings

This section describes endpoints that enable a third party to fetch and update a user's communication settings.

Get Communication Settings

curl https://api.thanxsandbox.com/communication_settings \
  $AUTH_HEADERS

Response (200 OK)

{
  "communication_settings": [
    {
      "id": "weori234098",
      "merchant_id": "owierywtwt",
      "user_id": "woeruijsfwer",
      "reward_earned": {
        "notification": true,
        "email": true
      },
      "reward_unused": {
        "notification": true,
        "email": true
      },
      "reward_progress": {
        "notification": true,
        "email": true
      },
      "reward_offer": {
        "notification": true,
        "email": true
      },
      "feedback_available": {
        "notification": true
      },
      "marketing_general": {
        "email": true
      }
    }
  ]
}

This endpoint returns a user's communication settings. The notification key reflects a user's settings for receiving push notifications in their app or via text if they don't have an app installed. The email key reflects a user's settings for receiving emails.

HTTP Request

GET /communication_settings

Request

Parameter Type Required Description
merchant_id string Optional Merchant ID

Response

Field Type Description
id String The ID of the settings record
merchant_id String The ID of the merchant
user_id String The ID of the user
reward_earned hash Settings for when a user earns a loyalty reward
reward_earned.notification boolean app notification setting
reward_earned.email boolean email setting
reward_unused hash Settings for when a user has an unused reward
reward_unused.notification boolean app notification setting
reward_unused.email boolean email setting
reward_progress hash Settings for when a user earns loyalty progress
reward_progress.notification boolean app notification setting
reward_progress.email boolean email setting
reward_offer hash Settings for when a merchant sends an offer
reward_offer.notification boolean app notification setting
reward_offer.email boolean email setting
feedback_available hash Settings for when a user has the opportunity to leave feedback for a purchase
feedback_available.notification boolean app notification setting
marketing_general hash Settings for when a merchant sends general marketing
marketing_general.email boolean email setting

Update Communication Settings

curl https://api.thanxsandbox.com/communication_settings/woerihfslkwer \
  -X PATCH \
  $AUTH_HEADERS
  -d '{
    "communication_settings": {
      "reward_earned": {
        "notification": false,
        "email": false
      },
      "feedback_available": {
        "notification": true
      }
    }
  }'

Response (200 OK)

{
  "settings": [
    {
      "id": "weoruoisdhf",
      "merchant_id": "owierywtwt",
      "user_id": "woerushfwe",
      "reward_earned": {
        "notification": true,
        "email": true
      },
      "reward_unused": {
        "notification": true,
        "email": true
      },
      "reward_progress": {
        "notification": true,
        "email": true
      },
      "reward_offer": {
        "notification": true,
        "email": true
      },
      "feedback_available": {
        "notification": true
      },
      "marketing_general": {
        "email": true
      }
    }
  ]
}

This endpoint allows the update of a user's notification / email settings.

HTTP Request

PATCH /communication_settings/:id

Request

Parameter Type Required Description
id String required The ID of the settings record
reward_earned hash optional Settings for when a user earns a loyalty reward
reward_earned.notification boolean optional app notification setting
reward_earned.email boolean optional email setting
reward_unused hash optional Settings for when a user has an unused reward
reward_unused.notification boolean optional app notification setting
reward_unused.email boolean optional email setting
reward_progress hash optional Settings for when a user earns loyalty progress
reward_progress.notification boolean optional app notification setting
reward_progress.email boolean optional email setting
reward_offer hash optional Settings for when a merchant sends an offer
reward_offer.notification boolean optional app notification setting
reward_offer.email boolean optional email setting
feedback_available hash optional Settings for when a user has the opportunity to leave feedback for a purchase
feedback_available.notification boolean optional app notification setting
marketing_general hash optional Settings for when a merchant sends general marketing
marketing_general.email boolean optional email setting

Response

Field Type Description
id String The ID of the settings record
merchant_id String The ID of the merchant
user_id String The ID of the user
reward_earned hash Settings for when a user earns a loyalty reward
reward_earned.notification boolean app notification setting
reward_earned.email boolean email setting
reward_unused hash Settings for when a user has an unused reward
reward_unused.notification boolean app notification setting
reward_unused.email boolean email setting
reward_progress hash Settings for when a user earns loyalty progress
reward_progress.notification boolean app notification setting
reward_progress.email boolean email setting
reward_offer hash Settings for when a merchant sends an offer
reward_offer.notification boolean app notification setting
reward_offer.email boolean email setting
feedback_available hash Settings for when a user has the opportunity to leave feedback for a purchase
feedback_available.notification boolean app notification setting
marketing_general hash Settings for when a merchant sends general marketing
marketing_general.email boolean email setting

Push Registrations

API Endpoint

Sandbox: https://api.thanxsandbox.com/push_registrations

This section describes endpoints that enable a third party to register a device for push notifications.

Create Push Registration

curl https://api.thanxsandbox.com/push_registrations \
  -X PUT \
  $AUTH_HEADERS
  -d '{
    "push_registration": {
      "device_type": "ios",
      "token": "wourdweroi238432423425fsgd"
    }
  }'

Response (200 ok)

{
  "push_registration": {
    "token": "wourdweroi238432423425fsgd",
    "device_type": "ios"
  }
}

This endpoint creates or updates a push registration record for a user's device.

HTTP Request

PUT /push_registrations

Request

Parameter Type Required Description
device_type enum Required The type of device: (ios, android)
token string Required The token returned by the local push notification library

Response

Field Type Description
device_type enum The type of device: (ios, android)
token string The registration token

Loyalty

API Endpoint

Sandbox: https://api.thanxsandbox.com/loyalty_statuses

This section describes endpoints that enable a third party to fetch a user's progress in the loyalty program.

Describe Loyalty Status

curl https://api.thanxsandbox.com/loyalty_statuses \
  $AUTH_HEADERS

Response (200 OK)

{
  "loyalty_statuses": [
    {
      "id": "wruflst",
      "user_id": "weorui",
      "merchant_id": "weoru",
      "status": {
        "progress": 45,
        "type": "spend",
        "threshold": 150
      },
      "redeem": {
        "type": "manual",
        "text": "$10 off",
        "venue": "all"
      }
    }
  ]
}

This endpoint describes the user's current loyalty statuses.

HTTP Request

GET /loyalty_statuses

Request

Parameter Type Required Description
merchant_id string Optional Only return loyalty status for this merchant

Response

Field Type Description
id string The ID of the loyalty status record
user_id string The user ID
merchant_id string The merchant ID
status hash The user's loyalty information
status.progress integer The user's progress toward their reward, out of 100
status.type enum Whether the user earns progress via how much they spend or how many times they visit. Returns 'spend' or 'visit'.
status.threshold integer How much the user needs to spend or how many visits the user needs to make to earn the reward.
redeem hash Describes the reward the user would earn
redeem.type enum How the reward can be redeemed (manual, automatic)
redeem.text string Description of what the reward is
redeem.venue enum Where the reward can be used: (instore, online, all)

Tiers

API Endpoint https://api.thanxsandbox.com/tiers

This section describes endpoints that enable a third party to fetch the configuration of a merchant's tiers.

Describe Tiers Configuration

curl https://api.thanxsandbox.com/tier_configurations \
  $STANDARD_HEADERS

Response (200 OK)

{
  "tier_configurations": [
    {
      "merchant_id": "weoru",
      "bronze_tier": {
        "id": "wyreo23",
        "name": "Bronze",
        "description": "- $10 off purchase of $25+ - complimentary birthday dessert - special event invitations",
        "color": "#ba7556",
        "spend_threshold": 0,
        "progress_paddle_image": {
          "small": "https://d1uv7brpxddy46.cloudfront.net/images/401/two_x/two_x-792ff91da8f50f9b5bfed570cef94295.png?1607038403",
          "default": "https://d1uv7brpxddy46.cloudfront.net/images/401/three_x/three_x-792ff91da8f50f9b5bfed570cef94295.png?1607038403",
          "large": "https://d1uv7brpxddy46.cloudfront.net/images/401/three_x/three_x-792ff91da8f50f9b5bfed570cef94295.png?1607038403"
        },
        "background_image": {
          "small": "https://d1uv7brpxddy46.cloudfront.net/images/400/two_x/two_x-463afd8be775b5ac6909bbaabf692353.jpg?1607038403",
          "default": "https://d1uv7brpxddy46.cloudfront.net/images/400/three_x/three_x-463afd8be775b5ac6909bbaabf692353.jpg?1607038403",
          "large": "https://d1uv7brpxddy46.cloudfront.net/images/400/three_x/three_x-463afd8be775b5ac6909bbaabf692353.jpg?1607038403"
        },
        "icon_image": {
          "small": "https://d1uv7brpxddy46.cloudfront.net/images/397/two_x/two_x-73db1207a1143a6f68374b119f826aa9.png?1607038181",
          "default": "https://d1uv7brpxddy46.cloudfront.net/images/397/three_x/three_x-73db1207a1143a6f68374b119f826aa9.png?1607038181",
          "large": "https://d1uv7brpxddy46.cloudfront.net/images/397/three_x/three_x-73db1207a1143a6f68374b119f826aa9.png?1607038181"
        }
      },
      "silver_tier": {
        "id": "fh457",
        "name": "Silver",
        "description": "Everything in Bronze, plus: - early reservations to community dinners when you reach Silver Tier",
        "color": "#bdbec0",
        "spend_threshold": 1500,
        "progress_paddle_image": {
          "small": "https://d1uv7brpxddy46.cloudfront.net/images/403/two_x/two_x-432dd66aa8b2f7aededebc434fa36232.png?1607038424",
          "default": "https://d1uv7brpxddy46.cloudfront.net/images/403/three_x/three_x-432dd66aa8b2f7aededebc434fa36232.png?1607038424",
          "large": "https://d1uv7brpxddy46.cloudfront.net/images/403/three_x/three_x-432dd66aa8b2f7aededebc434fa36232.png?1607038424"
        },
        "background_image": {
          "small": "https://d1uv7brpxddy46.cloudfront.net/images/402/two_x/two_x-1fbd60df2de3891d3f41d915bd2afef4.jpg?1607038423",
          "default": "https://d1uv7brpxddy46.cloudfront.net/images/402/three_x/three_x-1fbd60df2de3891d3f41d915bd2afef4.jpg?1607038423",
          "large": "https://d1uv7brpxddy46.cloudfront.net/images/402/three_x/three_x-1fbd60df2de3891d3f41d915bd2afef4.jpg?1607038423"
        },
        "icon_image": {
          "small": "https://d1uv7brpxddy46.cloudfront.net/images/398/two_x/two_x-f7a86c1434d71199a717d2b0caa256ac.png?1607038197",
          "default": "https://d1uv7brpxddy46.cloudfront.net/images/398/three_x/three_x-f7a86c1434d71199a717d2b0caa256ac.png?1607038197",
          "large": "https://d1uv7brpxddy46.cloudfront.net/images/398/three_x/three_x-f7a86c1434d71199a717d2b0caa256ac.png?1607038197"
        }
      },
      "gold_tier": {
        "id": "ert235",
        "name": "Gold",
        "description": "Everything in Silver, plus: - complimentary seasonal pizza per year when you reach Gold Tier",
        "color": "#c8b55e",
        "spend_threshold": 3000,
        "progress_paddle_image": {
          "small": "https://d1uv7brpxddy46.cloudfront.net/images/405/two_x/two_x-33c3dc14517c5d08b2c0869ef52c652b.png?1607038443",
          "default": "https://d1uv7brpxddy46.cloudfront.net/images/405/three_x/three_x-33c3dc14517c5d08b2c0869ef52c652b.png?1607038443",
          "large": "https://d1uv7brpxddy46.cloudfront.net/images/405/three_x/three_x-33c3dc14517c5d08b2c0869ef52c652b.png?1607038443"
        },
        "background_image": {
          "small": "https://d1uv7brpxddy46.cloudfront.net/images/404/two_x/two_x-3fbfb464595f7e136cfccebf36f2b1d8.jpg?1607038443",
          "default": "https://d1uv7brpxddy46.cloudfront.net/images/404/three_x/three_x-3fbfb464595f7e136cfccebf36f2b1d8.jpg?1607038443",
          "large": "https://d1uv7brpxddy46.cloudfront.net/images/404/three_x/three_x-3fbfb464595f7e136cfccebf36f2b1d8.jpg?1607038443"
        },
        "icon_image": {
          "small": "https://d1uv7brpxddy46.cloudfront.net/images/399/two_x/two_x-a44437b769db59fb777c922088ec840d.png?1607038208",
          "default": "https://d1uv7brpxddy46.cloudfront.net/images/399/three_x/three_x-a44437b769db59fb777c922088ec840d.png?1607038208",
          "large": "https://d1uv7brpxddy46.cloudfront.net/images/399/three_x/three_x-a44437b769db59fb777c922088ec840d.png?1607038208"
        }
      },
      "progress_bar_image": {
        "small": "https://d1uv7brpxddy46.cloudfront.net/images/423/two_x/two_x-ecbb385cc1850f090c6305fcc427293b.png?1608147464",
        "default": "https://d1uv7brpxddy46.cloudfront.net/images/423/three_x/three_x-ecbb385cc1850f090c6305fcc427293b.png?1608147464",
        "large": "https://d1uv7brpxddy46.cloudfront.net/images/423/three_x/three_x-ecbb385cc1850f090c6305fcc427293b.png?1608147464"
      }
    }
  ]
}

This endpoint describes tier configurations for the merchants accessible via the provided credentials. The gold tier may not be present if the merchant opts to have only 2 tiers.

HTTP Request

GET /tier_configurations

Request

Parameter Type Required Description
merchant_id string Optional Only return tier configuration for this merchant

Response

Field Type Description
merchant_id string The merchant ID
bronze_tier hash Describes the configuration for the bronze tier
bronze_tier.id string The identifer of the tier record
bronze_tier.name string The display name for the tier
bronze_tier.description string Describes the perks of the tier. Can return markdown.
bronze_tier.color string The hex color to use for this tier.
bronze_tier.spend_threshold integer How much the user needs to spend to be part of the tier.
bronze_tier.progress_paddle_image hash The image configured to render on the progress bar for tiers
bronze_tier.progress_paddle_image.small string The url for the small version of this image
bronze_tier.progress_paddle_image.large string The url for the large version of this image
bronze_tier.progress_paddle_image.default string The url for the version of the image usually used by Thanx
bronze_tier.background_image hash The image configured to render as the background for the tier
bronze_tier.background_image.small string The url for the small version of this image
bronze_tier.background_image.large string The url for the large version of this image
bronze_tier.background_image.default string The url for the version of the image usually used by Thanx
bronze_tier.icon_image hash The image configured to render as the icon for the tier
bronze_tier.icon_image.small string The url for the small version of this image
bronze_tier.icon_image.large string The url for the large version of this image
bronze_tier.icon_image.default string The url for the version of the image usually used by Thanx
silver_tier hash Describes the configuration for the silver tier
silver_tier.id string The identifer of the tier record
silver_tier.name string The display name for the tier
silver_tier.description string Describes the perks of the tier. Can return markdown.
silver_tier.color string The hex color to use for this tier.
silver_tier.spend_threshold integer How much the user needs to spend to be part of the tier.
silver_tier.progress_paddle_image hash The image configured to render on the progress bar for tiers
silver_tier.progress_paddle_image.small string The url for the small version of this image
silver_tier.progress_paddle_image.large string The url for the large version of this image
silver_tier.progress_paddle_image.default string The url for the version of the image usually used by Thanx
silver_tier.background_image hash The image configured to render as the background for the tier
silver_tier.background_image.small string The url for the small version of this image
silver_tier.background_image.large string The url for the large version of this image
silver_tier.background_image.default string The url for the version of the image usually used by Thanx
silver_tier.icon_image hash The image configured to render as the icon for the tier
silver_tier.icon_image.small string The url for the small version of this image
silver_tier.icon_image.large string The url for the large version of this image
silver_tier.icon_image.default string The url for the version of the image usually used by Thanx
gold_tier hash Describes the configuration for the gold tier
gold_tier.id string The identifer of the tier record
gold_tier.name string The display name for the tier
gold_tier.description string Describes the perks of the tier. Can return markdown.
gold_tier.color string The hex color to use for this tier.
gold_tier.spend_threshold integer How much the user needs to spend to be part of the tier.
gold_tier.progress_paddle_image hash The image configured to render on the progress bar for tiers
gold_tier.progress_paddle_image.small string The url for the small version of this image
gold_tier.progress_paddle_image.large string The url for the large version of this image
gold_tier.progress_paddle_image.default string The url for the version of the image usually used by Thanx
gold_tier.background_image hash The image configured to render as the background for the tier
gold_tier.background_image.small string The url for the small version of this image
gold_tier.background_image.large string The url for the large version of this image
gold_tier.background_image.default string The url for the version of the image usually used by Thanx
gold_tier.icon_image hash The image configured to render as the icon for the tier
gold_tier.icon_image.small string The url for the small version of this image
gold_tier.icon_image.large string The url for the large version of this image
gold_tier.icon_image.default string The url for the version of the image usually used by Thanx
progress_bar_image hash The image configured to render as the progress bar for tiers
progress_bar_image.small string The url for the small version of this image
progress_bar_image.large string The url for the large version of this image
progress_bar_image.default string The url for the version of the image usually used by Thanx

Describe Tier Status

curl https://api.thanxsandbox.com/tier_statuses \
  $AUTH_HEADERS

Response (200 OK)

{
  "tier_statuses": [
    {
      "id": "weourif",
      "user_id": "woeru",
      "merchant_id": "werouwer",
      "level": "bronze",
      "action_text": "Spend $100 before the end of the year to earn Silver.",
      "progress": 50,
      "expires_at": "2021-01-01T20:00:00Z",
      "current_tier_name": "Bronze",
      "next_tier_name": "Silver"
    }
  ]
}

This endpoint describes the user's current tier statuses.

HTTP Request

GET /tier_statuses

Request

Parameter Type Required Description
merchant_id string Optional Only return tier status for this merchant

Response

Field Type Description
id string The ID of the tier status record
user_id string The user ID
merchant_id string The merchant ID
level enum Current tier state (bronze, silver, gold)
action_text string Description of what the user needs to do in order to earn the next tier
progress decimal Amount spent so far
expires_at string Current tier status expiration in ISO8601-format
current_tier_name string Name of current tier
next_tier_name string Name of next tier. This will be blank if the user has gold status

Grant Tier Status

curl https://api.thanxsandbox.com/tier_statuses/:id \
  -X PATCH \
  $STANDARD_HEADERS
  -d '{
    "tier_status": {
      "level": "silver"
    }
  }'

Response (200 OK)

{
  "tier_status": {
    "id": "weourif",
    "user_id": "woeru",
    "merchant_id": "werouwer",
    "level": "bronze",
    "action_text": "Spend $100 before the end of the year to earn Silver.",
    "progress": 50,
    "expires_at": "2021-01-01T20:00:00Z",
    "current_tier_name": "Bronze",
    "next_tier_name": "Silver"
  }
}

This endpoint allows you to modify a user's tier status. This endpoint is only available in SANDBOX

HTTP Request

PATCH /tier_statuses/:id

Request

Parameter Type Required Description
level enum Required The desired tier (bronze, silver, gold)

Response

Field Type Description
id string The ID of the tier status record
user_id string The user ID
merchant_id string The merchant ID
level enum Current tier state (bronze, silver, gold)
action_text string Description of what the user needs to do in order to earn the next tier
progress integer Progress percent toward the next tier (0-99)
expires_at string Current tier status expiration in ISO8601-format
current_tier_name string Name of current tier
next_tier_name string Name of next tier. This will be blank if the user has gold status

Feedbacks

API Endpoint

https://api.thanxsandbox.com/feedbacks

This section describes endpoints that enable a third party to view and update a user's feedback (NPS) records.

Describe Feedback

curl https://api.thanxsandbox.com/feedbacks \
  $AUTH_HEADERS

Response (200 OK)

{
  "feedbacks": [
    {
      "id": "590485d6f0",
      "user_id": "fsjlk",
      "merchant_id": "woeri34",
      "location_id": "fgr2349gh",
      "expires_at": "2020-01-07T20:00:00Z",
      "rating": null,
      "review": null,
      "purchase": {
        "id": "916895d48a",
        "purchased_at": "2020-01-01T20:00:00Z",
        "amount": 16.0,
        "order": {
          "id": "aepo3cme2p",
          "provider": "OpenTender"
        }
      }
    }
  ]
}

This endpoint describes the user's current feedback records.

HTTP Request

GET /feedbacks

Response

Field Type Description
id string Feedback ID
user_id string User ID
merchant_id string Merchant ID
location_id string Location ID
expires_at string Time the feedback expires in ISO8601-format
rating integer NPS score (null or 1-10)
review string Customer feedback
purchase.id string Purchase ID
purchase.purchased_at string Time the purchase was made in ISO8601-format
purchase.amount decimal Purchase amount
purchase.order hash Provides information about the associated order, if any
purchase.order.provider enum The online ordering provider (OLO, Toast, OpenTender, Other)
purchase.order.id string The ID of the order in the provider's system

Get Single Feedback

curl https://api.thanxsandbox.com/feedbacks/590485d6f0 \
  $AUTH_HEADERS

Response (200 OK)

{
  "feedback": {
    "id": "590485d6f0",
    "user_id": "fsjlk",
    "merchant_id": "woeri34",
    "location_id": "fgr2349gh",
    "expires_at": "2020-01-07T20:00:00Z",
    "rating": null,
    "review": null,
    "purchase": {
      "id": "916895d48a",
      "purchased_at": "2020-01-01T20:00:00Z",
      "amount": 16.0,
      "order": {
        "id": "aepo3cme2p",
        "provider": "OpenTender"
      }
    }
  }
}

This endpoint returns the feedback record corresponding with the ID in the path. If the user is no longer able to leave feedback for this purchase, a 404 will be returned instead.

HTTP Request

GET /feedbacks/:id

Response

Field Type Description
id string Feedback ID
user_id string User ID
merchant_id string Merchant ID
location_id string Location ID
expires_at string Time the feedback expires in ISO8601-format
rating integer NPS score (null or 1-10)
review string Customer feedback
purchase.id string Purchase ID
purchase.purchased_at string Time the purchase was made in ISO8601-format
purchase.amount decimal Purchase amount
purchase.order hash Provides information about the associated order, if any
purchase.order.provider enum The online ordering provider (OLO, Toast, OpenTender, Other)
purchase.order.id string The ID of the order in the provider's system

Update Feedback

curl https://api.thanxsandbox.com/feedbacks/590485d6f0 \
  -X PATCH \
  $AUTH_HEADERS
  -d '{
    "feedback": {
      "rating": 10,
      "review": "Lorem ipsum dolor sit amet"
    }
  }'

Response (200 OK)

{
  "feedback": {
    "id": "590485d6f0",
    "user_id": "weorifsdf",
    "merchant_id": "9a1f0772c",
    "location_id": "fgr2349gh",
    "expires_at": "2020-01-07T20:00:00Z",
    "rating": 10,
    "review": "Lorem ipsum dolor sit amet",
    "purchase": {
      "id": "wourhfiwer",
      "purchased_at": "2020-01-01T20:00:00Z",
      "amount": 9.99,
      "order": {
        "id": "aepo3cme2p",
        "provider": "OpenTender"
      },
    }
  }
}

This endpoint will update a user's feedback record. If your API permissions allow it (this is rare), you may use the STANDARD_HEADERS rather than the AUTH_HEADERS.

HTTP Request

PATCH /feedbacks/:id

Request

Parameter Type Required Description
rating integer Required NPS Score, 1-10
review string Optional Customer feedback

Response

Field Type Description
id string Feedback ID
user_id string User ID
merchant_id string Merchant ID
location_id string Location ID
expires_at string Time the feedback expires in ISO8601-format
rating integer NPS score (null or 1-10)
review string Customer feedback
purchase.id string Purchase ID
purchase.purchased_at string Time the purchase was made in ISO8601-format
purchase.amount decimal Purchase amount
purchase.order hash Provides information about the associated order, if any
purchase.order.provider enum The online ordering provider (OLO, Toast, OpenTender, Other)
purchase.order.id string The ID of the order in the provider's system

Purchases

API Endpoint Sandbox: https://api.thanxsandbox.com/purchases

This section describes endpoints that enable a third party to fetch a user's purchases.

Describe Purchases

curl https://api.thanxsandbox.com/purchases \
  $AUTH_HEADERS

Response (200 OK)

{
  "purchases": [
    {
      "id": "92b7b0dac4",
      "user_id": "weori235",
      "merchant_id": "9a1f0772c9ac",
      "location_id": "e7183da044",
      "purchased_at": "2020-01-01T20:00:00Z",
      "amount": 9.99,
      "order": {
        "provider": "OLO",
        "id": "YWEI2342F"
      }
    }
  ]
}

This endpoint describes all available purchases.

HTTP Request

GET /purchases

Request

Parameter Type Required Description
merchant_id string Optional Only return purchases for this merchant
location_id string Optional Only return purchases for this location
user_id string Optional Only return purchases for this user. Note: the bearer token will be used to determine which user's purchases are being requested when the request is made by a logged in user.

Response

Field Type Description
id string Reward ID
user_id string User ID
merchant_id string Merchant ID
location_id string Location ID
purchased_at string Time the purchase was made in ISO8601-format
amount decimal The purchase amount
order hash Provides information about the associated order, if any
order.provider enum The online ordering provider (OLO, Toast, OpenTender, Other)
order.id string The ID of the order in the provider's system

Get Single Purchase

curl https://api.thanxsandbox.com/purchases/92b7b0dac4 \
  $AUTH_HEADERS

Response (200 OK)

{
  "purchase": {
    "id": "92b7b0dac4",
    "user_id": "weori235",
    "merchant_id": "9a1f0772c9ac",
    "location_id": "e7183da044",
    "purchased_at": "2020-01-01T20:00:00Z",
    "amount": 9.99,
    "order": {
      "provider": "OLO",
      "id": "YWEI2342F"
    }
  }
}

This endpoint returns the purchase associated with the id in the path.

HTTP Request

GET /purchases/:purchase_id

Response

Field Type Description
id string Reward ID
user_id string User ID
merchant_id string Merchant ID
location_id string Location ID
purchased_at string Time the purchase was made in ISO8601-format
amount decimal The purchase amount
order hash Provides information about the associated order, if any
order.provider enum The online ordering provider (OLO, Toast, OpenTender, Other)
order.id string The ID of the order in the provider's system

Create Purchase

curl https://api.thanxsandbox.com/purchases \
  -X POST \
  $STANDARD_HEADERS
  -d '{
    "purchase": {
      "merchant_id":  "weoru",
      "location_id":  "hljkfd2345",
      "user_id":      "wgljsdwer23",
      "amount":       13.45,
      "purchased_at": "2020-09-15T00:52:10.655+00:00",
      "card_id":      null
    }
  }'

Response (201 CREATED)

{}

This endpoint submits a purchase to our system for processing. Because this purchase is processed asynchronously, there is no response JSON. Please allow up to a couple minutes to receive this purchase back from the GET /purchases endpoint. This endpoint is only available in SANDBOX

HTTP Request

POST /purchases

Request

Parameter Type Required Description
merchant_id string Required Merchant ID
location_id string Required Location ID
user_id string Required User ID
amount decimal Required The amount of the receipt
purchased_at string Required The timestamp of the purchase, in ISO8601
card_id string Optional The card the user used, if it is registered in Thanx

Update Purchase Tags

curl https://api.thanxsandbox.com/purchases/wourhfiwer/tags \
  -X PUT \
  $STANDARD_HEADERS
  -d '{
    "tag": {
      "key": "server_satisfaction",
      "values": [
        "10"
      ]
    }
  }'

Response (200 OK)

{
  "tag": {
    "id": "werwerr",
    "purchase_id": "wourhfiwer",
    "key": "server_satisfaction",
    "values": [
      "10"
    ]
  }
}

This endpoint updates an attribute tag for the given purchase. The tag associated with the key in the request will be created or updated with the values passed in.

HTTP Request

PUT /purchases/:purchase_id/tags

Request

Parameter Type Required Description
key string Required Tag key
values array(string) Required Array of attributes tags

Response

Field Type Description
id string Tag ID
purchase_id string Purchase ID
key string Tag key
values array(string) Array of attribute tags

Receipts

API Endpoint

Sandbox: https://api.thanxsandbox.com/receipts

This section describes endpoints that enable a third party to submit and view receipts for a user. In order to submit a receipt to Thanx, you must first make a request to the API to get a presigned upload URL. Once you have uploaded the image to this URL, make a POST /receipts request to create the receipt in Thanx.

Describe Presigned URL

curl https://api.thanxsandbox.com/upload_url?upload_type=receipt \
  $AUTH_HEADERS

Response (200 OK)

{
  "upload_url": {
    "url": "https://thanx.s3.amazonaws.com/uploads/receipts/image_5051555_1534872299.jpeg?AWS-PARAMS",
    "file_path": "uploads/receipts/image_5051555_1534872299.jpeg"
  }
}

This endpoint provides a presigned url where an image or file can be uploaded. The file_path can be used as the input to the POST /receipts endpoint.

HTTP Request

GET /upload_url

Request

Field Type Required Description
upload_type enum Required The type of upload; currently only option is (receipt)

Response

Field Type Description
url string Url to upload the image to
file_path string Path where the image will be saved

Describe Receipts

curl https://api.thanxsandbox.com/receipts \
  $AUTH_HEADERS

Response (200 OK)

{
  "receipts": [
    {
      "id": "92b7b0dac4",
      "user_id": "weorufsdf",
      "merchant_id": "werouf",
      "state": "pending",
      "rejection_text": null,
      "amount": 13.45,
      "payment_type": "cash",
      "purchased_at": "2020-09-15T00:52:10.655+00:00",
      "submitted_at": "2020-09-15T00:55:11.876+00:00",
      "user_comments": "credit card reader was not working",
      "card_id": null,
      "image": {
        "small": "https://d1uv7brpxddy46.cloudfront.net/images/363/thumbnail/thumbnail-612c5e1821440637c0137be46d141e07.jpg?1604507010",
        "large": "https://d1uv7brpxddy46.cloudfront.net/images/363/medium/medium-612c5e1821440637c0137be46d141e07.jpg?1604507010",
        "default": "https://d1uv7brpxddy46.cloudfront.net/images/363/mobile/mobile-612c5e1821440637c0137be46d141e07.jpg?1604507010"
      }
    }
  ]
}

This endpoint describes the receipts in Thanx.

HTTP Request

GET /receipts

Request

Parameter Type Required Description
user_id string Optional User ID. Note: the bearer token will be used to determine which user's receipts are being requested when the request is made by a logged in user.
merchant_id string Optional Merchant ID

Response

Field Type Description
id string The receipt ID
merchant_id string Merchant ID
user_id string User ID
state enum The processing state of the receipt (pending, processing, applied, denied)
rejection_text string If the receipt is denied, the reason provided
amount decimal The amount of the receipt
payment_type enum (card, cash, other)
purchased_at string The timestamp of the purchase, in ISO8601
submitted_at string When the user submitted the receipt, in ISO8601
user_comments string Any user-entered notes
card_id string The card the user used, if it is registered in Thanx
image hash The uploaded receipt image information
image.small string The url for the small version of this image
image.large string The url for the large version of this image
image.default string The url for the version of the image usually used by Thanx

Create Receipt

curl https://api.thanxsandbox.com/receipts \
  -X POST \
  $AUTH_HEADERS
  -d '{
    "receipt": {
      "merchant_id": "weoru",
      "amount": 13.45,
      "payment_type": "cash",
      "purchased_at": "2020-09-15T00:52:10.655+00:00",
      "image_path": "uploads/receipts/image_5051555_1534872299.jpeg",
      "user_comments": "credit card reader was not working",
      "card_id": null
    }
  }'

Response (201 CREATED)

{
  "receipt": {
    "id": "92b7b0dac4",
    "user_id": "weorufsdf",
    "merchant_id": "werouf",
    "state": "pending",
    "rejection_text": null,
    "amount": 13.45,
    "payment_type": "cash",
    "purchased_at": "2020-09-15T00:52:10.655+00:00",
    "submitted_at": "2020-09-15T00:55:11.876+00:00",
    "user_comments": "credit card reader was not working",
    "card_id": null,
    "image": {
      "small": "https://d1uv7brpxddy46.cloudfront.net/images/363/thumbnail/thumbnail-612c5e1821440637c0137be46d141e07.jpg?1604507010",
      "large": "https://d1uv7brpxddy46.cloudfront.net/images/363/medium/medium-612c5e1821440637c0137be46d141e07.jpg?1604507010",
      "default": "https://d1uv7brpxddy46.cloudfront.net/images/363/mobile/mobile-612c5e1821440637c0137be46d141e07.jpg?1604507010"
    }
  }
}

This endpoint submits a receipt for processing.

HTTP Request

POST /receipts

Request

Parameter Type Required Description
merchant_id string Required Merchant ID
amount decimal Required The amount of the receipt
payment_type enum Required (card, cash, other)
purchased_at string Required The timestamp of the purchase, in ISO8601
image_path string Required The path of the uploaded image
user_comments string Optional Any user-entered notes
card_id string Optional The card the user used, if it is registered in Thanx

Response

Field Type Description
id string The receipt ID
merchant_id string Merchant ID
user_id string User ID
state enum The processing state of the receipt (pending, processing, applied, denied)
rejection_text string If the receipt is denied, the reason provided
amount decimal The amount of the receipt
payment_type enum (card, cash, other)
purchased_at string The timestamp of the purchase, in ISO8601
submitted_at string When the user submitted the receipt, in ISO8601
user_comments string Any user-entered notes
card_id string The card the user used, if it is registered in Thanx
image hash The uploaded receipt image information
image.small string The url for the small version of this image
image.large string The url for the large version of this image
image.default string The url for the version of the image usually used by Thanx

Referrals

API Endpoint Sandbox: https://api.thanxsandbox.com/referrals https://api.thanxsandbox.com/referral_links

This section describes endpoints that enable a third party to fetch a user's referrals and referral links.

curl https://api.thanxsandbox.com/referral_links \
  $AUTH_HEADERS

Response (200 OK)

{
  "referral_links": [
    {
      "merchant_id": "9a1f0772c9ac",
      "link": "https://signup.thanx.com/pizza_bob/Jane-23uow234243"
    }
  ]
}

This endpoint returns a user's referral links, one for each merchant the credentials have access to.

HTTP Request

GET /referral_links

Request

Parameter Type Required Description
merchant_id string Optional Only return referral links for this merchant

Response

Field Type Description
merchant_id string Merchant ID
link string The URL a user can share with others

Locations

API Endpoint Sandbox: https://api.thanxsandbox.com/locations

This section describes endpoints that enable a third party to fetch a merchant's locations.

Describe Locations

curl https://api.thanxsandbox.com/locations \
  $STANDARD_HEADERS

Response (200 OK)

{
  "locations": [
    {
      "id": "92b7b0dac4",
      "merchant_id": "9a1f0772c9ac",
      "street": "123 Pizza Lane",
      "city": "Smalltown",
      "state": "CA",
      "zip": "12345",
      "name": "Pizza Town Co",
      "phone": "(415) 555-3728"
    }
  ]
}

This endpoint describes locations accessible for the provided client ID. If a merchant_id is provided the locations will be further filtered.

HTTP Request

GET /locations

Request

Parameter Type Required Description
merchant_id string Optional Only return locations for this merchant

Response

Field Type Description
id string Location ID
merchant_id string Merchant ID
street string Location's street address
city string Location's city
state string Location's state
zip string Location's zip code
name string The name of the location if it has one
phone string The phone number of the location

SDK iOS

This section describes the installation and usage of the Thanx iOS SDK. For more details including class and properties documentation, please visit https://thanx.github.io/thanx-sdk-ios-distribution/

SDK Android

This section describes the installation and usage of the Thanx Android SDK. For more details including class and properties documentation, please visit https://thanx.github.io/thanx-sdk-android-distribution/

Webhooks

This section describes webhooks that are available. To request access to our webhook functionality, please contact your CSM.

In order for Thanx to send webhooks to you, we require an endpoint where you want to receive your payloads. The payloads are in JSON format and use the same record identifiers as our API endpoints.

Purchase Data

A generic purchase webhook payload looks like the first payload listed to the right.

{
  "purchase": {
    "id": "92b7b0dac4",
    "user": {
      "id": "weori235",
      "email": "bob@bob.com"
    },
    "merchant": {
      "id": "9a1f0772c9ac",
      "name": "Pizza Shack"
    },
    "location": {
      "id": "e7183da044",
      "name": "Pizza Shack 12",
      "street": "123 Pizza Lane",
      "city": "Smalltown",
      "state": "CA",
      "zip": "12345",
      "time_zone": "America/New_York",
      "latitude": "37.76271750294678",
      "longitude": "-122.42438230349147"
    },
    "purchased_at": "2020-01-01T20:00:00Z",
    "amount": 9.99,
    "order": {
      "provider": "OLO",
      "id": "RTF234S"
    },
    "products": [
      "Snickers",
      "Twix"
    ]
  }
}

If you're a mall and the location hasn't opted in to data sharing, it will look more like the second payload listed to the right.

{
  "purchase": {
    "id": "92b7b0dac4",
    "user": {
      "id": "weori235",
      "email": "bob@bob.com"
    },
    "merchant": {
      "id": "9a1f0772c9ac",
      "name": "The Best Mall Ever"
    },
    "location": {
      "name": "Food"
    },
    "purchased_at": "2020-01-01T20:00:00Z",
    "amount": 9.99,
    "order": {},
    "products": []
  }
}

Payload description:

Field Type Description
id string The ID of the purchase record in Thanx
user hash User information
user.id string The ID of the user record in Thanx
user.email string The user's email. This value may not be present.
merchant hash Merchant information
merchant.id string The ID of the merchant record in Thanx
merchant.name string The name of the merchant
location hash Location information
location.name string The location name or category
location.id string The ID of the location record in Thanx, if permitted
location.street string The street address of the location, if permitted
location.city string The location's city, if permitted
location.state string The location's state, if permitted
location.zip string The location's zip code, if permitted
location.time_zone string The location's time zone, if permitted
location.latitude string The location's latitude, if permitted
location.longitude string The location's longitude, if permitted
purchased_at string Time the purchase was made in ISO8601-format
amount decimal The purchase amount
order hash The order information, if this purchase reflects an online order
order.provider enum (OLO, Toast, OpenTender, Other)
order.id string The order ID in the provider's system
products array The list of products the user bought

[LEGACY] SSO

API Endpoint

https://auth.thanxsandbox.com

This section describes the process of authenticating with Thanx via Thanx SSO. Thanx SSO authenticates the user via a password-less flow using email authentication, rather than a password. This reduces the friction of a user having to manage yet another password as well as reduces the friction of transitioning an existing user-base to Thanx.

Thanx follows the standard OAuth 2.0 spec, using the Authorization Code grant type. Refer to the OAuth 2.0 Authorization Framework RFC: Section 4.1 for additional details.

There are two primary options for implementing SSO with Thanx:

Thanx-hosted SSO Form

SSO with Thanx-hosted Form

  1. User navigates to the merchant website and clicks an authentication button.
  2. The merchant website redirects to Thanx Auth, as described in the GET /oauth/authorize endpoint described below.
  3. User enters their email address in the Thanx-hosted form.
  4. If the email address is new to Thanx, the user is prompted to input their first and last name to create an account, after which an authorization code is returned to the redirect_uri (skip to step 6). If the email address already exists in Thanx, Thanx Auth sends an auth email to the specified email.
  5. The user clicks the auth email link which redirects to the merchant website at the specified redirect_uri with an authorization code in the params.
  6. Merchant website exchanges the authorization code for an access token via the POST /oauth/token endpoint described below. User is now authenticated with the Thanx system through the returned access token.

Self-hosted SSO Form

SSO with Self-hosted Form - New User SSO with Self-hosted Form - Existing User

  1. User navigates to the merchant website and clicks an authentication button.
  2. The merchant website prompts the user to input an email address
  3. The merchant website makes a request to the POST /oauth/authorize endpoint described below. (Continue to #4 or #5)
  4. If no account exists for the specified email address, a 401 error is thrown. The merchant website should then reprompt the user to input a first and last name and resend the request to POST /oauth/authorize with the first_name and last_name parameters. Upon successful creation of the user, a 201 HTTP response is returned with an authorization code in the response body. (Continue to #6)
  5. If an account exists for the specified email address, an auth email is sent to specified email. The user clicks the auth email link which redirects to the merchant website at the specified redirect_uri with an authorization code in the params.
  6. Merchant website exchanges the authorization code for an access token via the POST /oauth/token endpoint described below. User is now authenticated with the Thanx system through the returned access token.

The following notice with hyperlinks to the Thanx Privacy Policy and Terms of Service must be displayed in all experiences where a user signs up:

By signing up you agree to our privacy policy and our terms of service

By signing up you agree to our privacy policy and our terms of service

Note that you may style this sentence as you'd like. You may replace the default agreement links above with the corresponding brand-specific agreement links Thanx generates for your app:

Agreement Type URL Pattern
Privacy Policy https://app.thanx.com/privacy/BRAND
Terms of Service https://app.thanx.com/terms/BRAND

BRAND denotes your designated Thanx platform handle.

Send user to authentication flow

Example Entrypoint

https://auth.thanxsandbox.com/oauth/authorize?\
  response_type=code&\
  client_id=abcdefghijklmnop0123456789&\
  redirect_uri=https%3A%2F%2Fwww.yourdomain.com%2Foauth%2Fcallback

This is the initial entrance into the authentication flow, rather than an API endpoint. This is where your 'Login with Thanx' button should link to. Be sure to escape your redirect uri! You will receive a callback at the redirect_url specified with the session code in the parameters after authentication is completed.

HTTP Request

GET /oauth/authorize

Request

Parameter Type Required Description
response_type string Required This should be code
client_id string Required This is your client ID
redirect_uri string Required A redirect_uri (escaped!) where Thanx will redirect to once the user has authenticated. This must be part of a whitelist in Thanx.

Acquire authorization code

curl https://auth.thanxsandbox.com/oauth/authorize \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "f4bf04a6fc27b5fa926a7318933b76440642c25cde037d8e867b3d18d771ad86",
    "redirect_uri": "https://www.example.com/oauth/callback",
    "response_type": "code",
    "scope": "passwordless",
    "username": "john.smith@example.com",
    "first_name": "John",
    "last_name": "Smith",
    "birth_date": "1980-12-15"
  }'

Response (200 OK)

""

Response (201 Created)

{
  "code": "c13a4ba07f27cfc69a03a5c9cda630205e5f2833331fb761d38eef10c091f371"
}

Response (401 Unauthorized)

{
  "error": "access_denied",
  "error_description": "The resource owner or authorization server denied the request."
}

This flow is to support passwordless login.

If an account exists, an authentication email will be sent including a link that will eventually redirect to the redirect_uri with an authorization code.

If an account does not exist for the specified email, a 401 error will be returned.

If the optionally specified first_name and last_name parameters are included, an attempt to create an account will be made if the email does not already have an associated account. Upon success, a 201 success and an authorization code will be returned.

HTTP Request

POST /oauth/authorize

Request

Parameter Type Required Description
client_id string Required OAuth Client ID
redirect_uri string Required Where you want the user to be redirected
response_type string Required code is the required value
scope string Required passwordless is the required value
username string Required The user's email
first_name string Optional The user's first name. Must be specified to trigger user creation
last_name string Optional The user's last name. Must be specified to trigger user creation
birth_date string Optional The user's birth date. Should be in the format YYYY-MM-DD. Optionally specified during user creation

Acquire access token

curl https://auth.thanxsandbox.com/oauth/token \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "f4bf04a6fc27b5fa926a7318933b76440642c25cde037d8e867b3d18d771ad86",
    "client_secret": "83c08861ce6302e0e73d28cea30aa3f8f3ea98446e133fde60a86231f50f5c82",
    "code": "c13a4ba07f27cfc69a03a5c9cda630205e5f2833331fb761d38eef10c091f371",
    "redirect_uri": "https://www.example.com/oauth/callback"
  }'

Response (200 OK)

{
  "token_type": "Bearer",
  "scope": "passwordless",
  "created_at": 1577836800,
  "access_token": "945148251b603ae34561d90acfe4050e67494d6d1e65d4d3d52798407f03c0bd",
  "refresh_token": "c74334301a7c74d21b714c905fd3047177dab56de6a86899e6f6b7f71bab7d55"
}

Use this endpoint to acquire a user's access token. This same endpoint supports refreshing an access token using the client_id, client_secret, and refresh_token, with grant_type set to refresh_token.

HTTP Request

POST /oauth/token

Request

Parameter Type Required Description
grant_type string Required authorization_code is the required value
client_id string Required OAuth Client ID
client_secret string Required OAuth Client Secret
code string Required The authorization code received from Thanx via redirect or API
redirect_uri string Required The same redirect_uri should be used as in the request for the authorization code

Revoke Access Token

curl https://auth.thanxsandbox.com/oauth/revoke \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "f4bf04a6fc27b5fa926a7318933b76440642c25cde037d8e867b3d18d771ad86",
    "client_secret": "83c08861ce6302e0e73d28cea30aa3f8f3ea98446e133fde60a86231f50f5c82",
    "token": "945148251b603ae34561d90acfe4050e67494d6d1e65d4d3d52798407f03c0bd"
  }'

Response (200 OK)

{}

Use this endpoint to revoke a user's access token.

HTTP Request

POST /oauth/revoke

Request

Parameter Type Required Description
client_id string Required OAuth Client ID
client_secret string Required OAuth Client Secret
token string Required OAuth Access Token

Describe User

curl https://auth.thanxsandbox.com/users/me \
  -H "Authorization: Bearer 945148251b603ae34561d90acfe4050e67494d6d1e65d4d3d52798407f03c0bd" \
  -H "Content-Type: application/json"

Response (200 OK)

{
  "id": "fgr2349gh",
  "identifier": "11650a5cad69",
  "email": "john.smith@example.com",
  "first_name": "John",
  "last_name": "Smith",
  "birth_date": "1980-12-15"
}

Response (401 Unauthorized)

""

This endpoint will return info for the authorized user

HTTP Request

GET /users/me

Response

Field Type Description
id string Thanx User UID
identifier string Thanx User Identifier
email string The user's email
first_name string The user's first name
last_name string The user's last name
birth_date string Optional

[LEGACY] Identity

API Endpoint

https://merchant.thanxsandbox.io

These APIs enable merchants to fully own their users by providing the ability to create user records on the Thanx platform and transparently authenticate them. This enables merchants to embed the Thanx consumer experience into merchant-owned mobile or web experiences without requiring end-users to re-authenticate with Thanx.

Create user

curl https://merchant.thanxsandbox.io/merchants/1/users \
  -X POST \
  -H "Accept: application/vnd.thanx-v1+json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 945148251b603ae34561d90acfe4050e67494d6d1e65d4d3d52798407f03c0bd"
  -d '{
    "user": {
      "email": "john.smith@example.com",
      "first_name": "John",
      "last_name": "Smith",
      "birth_date": "1980-12-15"
    }
  }'

Response (201 Created)

{
  "user": {
    "id": "fgr2349gh",
    "email": "john.smith@example.com",
    "first_name": "John",
    "last_name": "Smith"
  }
}

Response (400 Bad Request)

{
  "errors": "Invalid user birthday"
}

Response (409 Conflict)

{
  "errors": "A user with that email already exists"
}

This endpoint allow creation of users. Users that are created by this mechanism are automatically associated with the specified merchant. If this specified merchant attempts to create a user with an email that is already in the Thanx system but not yet associated with the merchant, the request will succeed and return a user identifier that is consistent across merchants.

HTTP Request

POST /merchants/:merchant_id/users

Request

Parameter Type Required Description
email string Required User's email address
first_name string Required User's first name
last_name string Required User's last name
birth_date string Optional User's birth date in the format YYYY-MM-DD

Response

Field Type Description
user hash User info
user.id string User ID
user.email string User email address
user.first_name string User first name
user.last_name string User last name

Describe user

curl https://merchant.thanxsandbox.io/merchants/1/users/2 \
  -H "Accept: application/vnd.thanx-v1+json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 945148251b603ae34561d90acfe4050e67494d6d1e65d4d3d52798407f03c0bd"

Response (200 OK)

{
  "user": {
    "id": "fgr2349gh",
    "email": "john.smith@example.com",
    "first_name": "John",
    "last_name": "Smith"
  }
}

Response (404 Not Found)

""

This endpoint will return the specified user

HTTP Request

GET /merchants/:merchant_id/users/:user_id

Describe users

curl https://merchant.thanxsandbox.io/merchants/1/users \
  -H "Accept: application/vnd.thanx-v1+json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 945148251b603ae34561d90acfe4050e67494d6d1e65d4d3d52798407f03c0bd"

Response (200 OK)

{
  "users": [
    {
      "id": "fgr2349gh",
      "email": "john.smith@example.com",
      "first_name": "John",
      "last_name": "Smith"
    }
  ]
}

This endpoint will return a paginated list of users associated with the merchant

HTTP Request

GET /merchants/:merchant_id/users

Request

Parameter Type Required Description
email string Optional Scope list of users by email
page integer Optional Page of results to return
per_page integer Optional Number of results to return per page (1 to 100)

Response

Parameter Type Required Description
email string Optional Scope list of users by email
page integer Optional Page of results to return
per_page integer Optional Number of results to return per page (1 to 100)

Update user

curl https://merchant.thanxsandbox.io/merchants/1/users \
  -X PATCH \
  -H "Accept: application/vnd.thanx-v1+json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 945148251b603ae34561d90acfe4050e67494d6d1e65d4d3d52798407f03c0bd" \
  -d '{
    "user": {
      "id": "fgr2349gh",
      "email": "jane.smith@example.com",
      "first_name": "Jane"
    }
  }'

Response (200 OK)

{
  "users": [
    {
      "id": "fgr2349gh",
      "email": "john.smith@example.com",
      "first_name": "Jane",
      "last_name": "Smith"
    }
  ]
}

This endpoint updates the specified user's information.

HTTP Request

PATCH /merchants/:merchant_id/users/:user_id

Request

Parameter Type Required Description
email string Optional User's email address
first_name string Optional User's first name
last_name string Optional User's last name
birth_date string Optional User's birth date in the format YYYY-MM-DD

Create access token

curl https://merchant.thanxsandbox.io/merchants/1/users/2/token \
  -X PATCH \
  -H "Accept: application/vnd.thanx-v1+json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 945148251b603ae34561d90acfe4050e67494d6d1e65d4d3d52798407f03c0bd" \
  -d '{ "scope": "web" }'

Response (200 OK)

{
  "token_type": "Bearer",
  "scope": "web",
  "created_at": 1577836800,
  "access_token": "945148251b603ae34561d90acfe4050e67494d6d1e65d4d3d52798407f03c0bd",
  "expires_in": "300"
}

This endpoint will create and return an access token for the user

HTTP Request

PATCH /merchants/:merchant_id/users/:user_id

Request

Parameter Type Required Description
scope string Required sdk for SDK - multi-use and long-lived
web for web embed - single-use and short-lived

[LEGACY] Ordering / Loyalty Integration

API Endpoint

https://loyalty.thanxsandbox.com/api

This section describes API endpoints that enable an online ordering platform to integrate with Thanx. This API provides a way to retrieve a user's rewards and apply discounts to their basket. An online ordering platform with a Thanx merchant as a customer can use this API to allow Thanx users to use their discounts when making purchases online. The GET /account endpoint provides a user's available rewards. The POST /baskets endpoint computes a discount and marks rewards as used in the Thanx system. Integrators are expected to apply the discount to the basket.

Custom Ordering UI

Example Olo API requests:

# Exchange Thanx Token for Olo Token:
POST /users/getorcreate
{
  provider:       'thanx', # name of loyalty provider
  providertoken:  '...',   # thanx access token
  provideruserid: '...'    # thanx user id
}

# Fetch Thanx Rewards:
GET /baskets/{uid}/loyaltyrewards/qualifying?authtoken={olo token}&...

For merchants looking to build a custom ordering UI, there is no additional integration work required outside of the SSO integration, since ordering providers like Olo and Brandibble have already built integrations with Thanx as documented in below.

Custom Ordering UI

After the custom ordering UI authenticates the Thanx User, the Thanx token is passed to the ordering provider. The ordering provider in turn uses that access token to fetch qualifying rewards from the Thanx APIs.

Headers

All Ordering / Loyalty integration API endpoints described below must include the following headers.

Header Type Required Description
Authorization string Required All Thanx Loyalty API endpoints are protected and must be authorized via end user access tokens. These access tokens can be retrieved through an integration with Thanx SSO. The format of the header should be: Bearer access_token
Content-Type string Required The only accepted value is application/json
Accept string Required The Accept header specifies which version of the Thanx API that should be used. The current version is v1 for the vendor thanx. This header is required for every request. The value should be application/vnd.thanx-v1+json. Thanx will notify you when a new API version is available.
Merchant-Key string Required The Merchant key header identifies the merchant in Thanx. The value for this key will be provided to you by Thanx and is the same in production and sandbox.

Retrieve Account

curl https://loyalty.thanxsandbox.com/api/account?location_uid=8bda69 \
  -H "Authorization: Bearer 945148251b603ae34561d90acfe4050e67494d6d1e65d4d3d52798407f03c0bd" \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.thanx-v1+json" \
  -H "Merchant-Key: cb71e3"

Response (200 OK)

{
  "id": "wer23gtTT",
  "email": "john.smith@example.com.com",
  "rewards": [
    {
      "id": "gheTfR",
      "value": 10,
      "minimum": 20,
      "maximum": 20,
      "label": "A free hamburger",
      "state": "redeemable",
      "type": "amount",
      "products": [
        "234234-23423423",
        "3458-345345"
      ],
      "fine_print": "Cannot be applied to alcohol",
      "retire_at": "2020-05-01T20:00:00Z"
    }
  ],
  "progress": {
    "percentage": 20,
    "towards": "$5 off next purchase"
  }
}

Response (401 Unauthorized)

{
  "code": 401,
  "message": "There was an error authenticating you."
}

This endpoint allows the retrieval of a user account information, including the user's rewards. By default, only rewards available to use at the current time are returned.

HTTP Request

GET /account

Request

Parameter Type Required Description
location_uid string Optional The location identifier; this is what your system uses to identify a location. Providing this information allows Thanx to return rewards that can be used at this location.

Response

Field Type Description
id string The identifier for the user's account
email string The user's email
rewards array(hash) The user's available rewards for the merchant specified in the header. This array can be empty.
rewards.id string The Reward Identifier
rewards.value number The value of the discount, present for 'amount' and 'percent' types
rewards.minimum number The minimum spend for this reward, if applicable
rewards.maximum number The maximum discount possible for this reward, if applicable
rewards.label string The reward description
rewards.state enum The state of the reward (redeemable, unredeemable)
rewards.type enum The type of reward (amount, percent, item)
rewards.products array(string) POS Identifiers for items this discount applies to, if applicable
rewards.fine_print string Any fine print for the reward.
rewards.retire_at string Time the reward will be automatically retired in ISO8601-format if a retire date is set
progress hash A user's progress toward their next loyalty reward
progress.percentage integer Percent progress toward the next loyalty reward
progress.towards string Description of progress toward the next loyalty reward

Create & Update Basket

curl https://loyalty.thanxsandbox.com/api/baskets \
  -X POST \
  -H "Authorization: Bearer 945148251b603ae34561d90acfe4050e67494d6d1e65d4d3d52798407f03c0bd" \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.thanx-v1+json" \
  -H "Merchant-Key: cb71e3" \
  -d '{
    "id": "gwer-werwr-2134-rty",
    "state": "billed",
    "order_timestamp": "2019-05-08T18:02:05Z",
    "location_uid": "LG-567fhwer",
    "rewards": [
      "fheTRR"
    ],
    "payments": [
      {
        "issuer": "visa",
        "last4": "1234",
        "amount": 10.45,
        "authorized_at": "2019-05-07T18:02:05Z"
      }
    ],
    "items": [
      {
        "id": "ng-23492",
        "name": "Cheese Pizza",
        "price": 9.95,
        "categories": [
          "pizza",
          "vegetarian"
        ]
      }
    ],
    "subtotal": 23.45
  }'

Response (200 OK)

{
  "id": "fhwerwe-23663-ryryre",
  "state": "checkout",
  "discount": "10.25"
}

Response (400 Bad Request)

{
  "code": 400,
  "message": "The reward was not found in our system"
}

Response (401 Unauthorized)

{
  "code": 401,
  "message": "There was an error authenticating you."
}

This endpoint is used to notify Thanx of the states that a basket can be in and receive reward redemption information in return. A basket can be in one of the following states:

HTTP Request

POST /baskets

Request

Parameter Type Required Description
id string Required Basket unique ID
state enum Required Basket state (checkout, placed, billed, completed, voided, refunded)
order_timestamp string Optional When the order is wanted in (ISO 8601 format). If this timestamp is not provided, Thanx assumes the order is wanted ASAP. Providing this timestamp allows Thanx to determine if a reward will be valid in the future (for example, for a weekend only promotion where the user orders in advance)
location_uid string Optional The location identifier; this is what your system uses to identify a location. Providing this information allows Thanx to apply location restricted rewards.
rewards array(string) Required Reward IDs to apply to the basket. If you are integrating with reward codes, provide the reward code here instead.
payments array(hash) Required Array of payment methods
payments.issuer string Required Issuer of the payment method
payments.last4 string Required Last 4 digits of the payment method
payments.amount decimal Required Amount used for the payment method
payments.authorized_at string Required The timestamp of when the authorization was submitted to the issuer, in ISO8601 format
items array(hash) Required Array of items
items.id string Required Item ID in your system / POS
items.name string Required Item name
items.price decimal Required Item amount
items.categories array(string) Optional categories that describe this item
subtotal decimal Required The subtotal of the basket in USD (before taxes & tips)

Response

Field Type Description
id string Response ID
state enum Basket state (checkout, placed, billed, completed, voided, refunded)
discount string Discount to apply
curl ruby javascript