API Version: 
Version 1.1 - October 2, 2015

Introduction:

The Balance Rewards API enables pre-qualified partners to connect into Walgreens to share individual member health and wellness information to be eligible to receive Balance Rewards points for healthy activity like walking, running, and weight management.

The API is designed to enable partners to seamlessly share individual health and lifestyle activity (Data Sharing), and create or validate user memberships (Authentication).

Data Sharing:

In order for Balance Rewards members to receive points for data recorded using pre-qualified partners applications, devices, or platform, partners must share full activity information with Walgreens. In no way is Walgreens able to reward activity without supporting aggregate or transaction level information. Currently, Balance Rewards members are eligible to receive the following rewards:

  • 20 points per mile (2000 steps = 1 mile); no daily maximum
  • 20 points for completing a general exercise activity, maximum of one award per day
  • NOTE: 1,000 monthly point limit for steps & general exercise activities
  • 20 points per weight measurement, maximum of one award per day
  • 20 points per blood pressure measurement, maximum of one award per day
  • 20 points per blood glucose measurements, maximum of two awards per day
  • BONUS: 250 points for connecting a compatible health & fitness device/app; up to 2 per month

Authentication:

In order for individuals to receive points for health and wellness activity, they must be a Balance Rewards member and have successfully completed a Walgreens OAuth login or registration. Further instructions on prerequisites and how to obtain required authentication credentials are contained with the API Documentation below.


Request Authorization Code:

Description: Your application will navigate to the authorization code URL, while passing parameters outlined below in order to complete the required Walgreens.com login or registration process.

 

Open a Webview/Browser:
AuthURL
?client_id=YOUR_AFFILIATE_ID
&response_type=code
&scope=steps
&redirect_uri=YOUR_REDIRECT_URI
&channel=1,5, or 6
&transaction_id=1234567890123456
&state=abcd1234xyz

 

Note:

You can send a different Channel Parameter based on your integration. 1 if the app is Web app. 5 if the app is a Mobile app. 6 if the app is a Tablet app.


Response Authorization Code:

Description: Upon successfully logging into Walgreens.com or registering with Walgreens.com, the authorization server validates the incoming parameters, verifies the client registration, and then the authorization server issues an authorization code. The authorization code will be embedded within the redirect URI as a URL parameter.

Note: The Authorization Code will only be valid for 2 minutes. You will need to generate an Access Token with the Authorization Code before it expires or else the user will have to start the oAuth Flow over again.
Sample URL redirect response:
YOUR_REDIRECT_URI
?code=AUTHORIZATION_CODE
&scope=steps
&transaction_id=ONE_PASSED_IN_REQUEST_AUTH
&state=ONE_PASSED_IN_REQUEST_AUTH

Sample Error Response:
YOUR_REDIRECT_URI
?error_code=ERROR_CODES_BELOW
&error=ERROR_NAMES_BELOW
&error_description=ERROR_DESCRIPTIONS_BELOW
&transaction_id=ONE_PASSED_IN_REQUEST_AUTH
&state=ONE_PASSED_IN_REQUEST_AUTH


Request OAuth Access Token:

Description: Your application requests the authorization server for access to the token by sending the authorization code, along with other parameters detailed below, which is shared by authorization server using the application/x-www-form-urlencoded format. The Access Token request should be a POST method.

 

POST TOKEN_URL
Content-Type: application/x-www-form-urlencoded
?grant_type=authorization_code
&act=getOAuthToken
&client_id=YOUR_AFFILIATE_ID
&client_secret=YOUR_API_KEY
&code=AUTHORIZATION_CODE
&redirect_uri=YOUR_REDIRECT_URI
&channel=1,5, or 6
&transaction_id=ONE_PASSED_IN_REQUEST_AUTH
&state=ONE_PASSED_IN_REQUEST_AUTH

Response OAuth Access Token:

Description: If the authorization token request is valid and authorized, the authorization server issues an access token and refresh token. Response Content-type is application/json.

Note: Access token expires in 30 days and refresh token expires in 45 days
Sample Success response:
Content-Type: application/json
{
"scope":"steps",
"token_type":"BEARER",
"access_token_expires_in":"2015-09-25 16:06:00",
"refresh_token_expires_in":"2015-10-10 16:06:00",
"access_token":"USER_ACCESS_TOKEN",
"refresh_token":"USER_REFRESH_TOKEN",
"transaction_id":"ONE_PASSED_IN_REQUEST_AUTH"
}

Sample Error Response:
Content-Type: application/json
{
"error_code":"ERROR_CODES_BELOW",
"error":"ERROR_NAMES_BELOW",
"error_description":"ERROR_DESCRIPTIONS_BELOW",
"transaction_id":"ONE_PASSED_IN_REQUEST_AUTH"
}


Request Refresh Access Token:

Description: If the authorization token request is valid and authorized, the authorization server issues a new access token and refresh token. Request Content-type is application/x-www-form-urlencoded. The Refresh Access Token request should be a POST method.

 

POST TOKEN_URL
Content-Type: application/x-www-form-urlencoded
?grant_type=refresh_token
&act=getOAuthToken
&client_id=YOUR_AFFILIATE_ID
&client_secret=YOUR_API_KEY
&refresh_token=USER_REFRESH_TOKEN
&redirect_uri=YOUR_REDIRECT_URI
&channel=1,5, or 6
&transaction_id=ONE_PASSED_IN_REQUEST_AUTH
&state=ONE_PASSED_IN_REQUEST_AUTH

Response Refresh Access Token:

Description: If the authorization token request is valid and authorized, the authorization server issues a new access token and refresh token. Response Content-type is application/json.

Sample Success response:
Content-Type: application/json
{
"scope":"steps",
"token_type":"BEARER",
"access_token_expires_in":"2015-09-25 16:06:00",
"refresh_token_expires_in":"2015-10-10 16:06:00",
"access_token":"USER_ACCESS_TOKEN",
"refresh_token":"USER_REFRESH_TOKEN",
"transaction_id":"ONE_PASSED_IN_REQUEST_AUTH"
}

Sample Error Response:
Content-Type: application/json
{
"error_code":"ERROR_CODES_BELOW",
"error":"ERROR_NAMES_BELOW",
"error_description":"ERROR_DESCRIPTIONS_BELOW",
"transaction_id":"ONE_PASSED_IN_REQUEST_AUTH"
}


Request Deactivate OAuth Token:

Description: If the deactivate token request is valid and authorized, the authorization server deactivates the access token and refresh token. Request Content-type is application/x-www-form-urlencoded. The Deactivate Access Token request should be a POST method.

 

POST DEACTIVATE_TOKEN_URL
Content-Type: application/x-www-form-urlencoded
?act=deactivateToken
&client_id=YOUR_AFFILIATE_ID
&client_secret=YOUR_API_KEY
&token=USER_ACCESS_TOKEN
&channel=1,5, or 6
&transaction_id=ONE_PASSED_IN_REQUEST_AUTH

Response Deactivate Access Token:

Description: If the deactivate token request is valid and authorized, the authorization server deactivates the access token and refresh token. Response Content-type is application/json.

Sample Success response:
Content-Type: application/json
{
"status":"success",
"transaction_id":"ONE_PASSED_IN_REQUEST_AUTH"
}

Sample Error Response:
Content-Type: application/json
{
"error_code":"ERROR_CODES_BELOW",
"error":"ERROR_NAMES_BELOW",
"error_description":"ERROR_DESCRIPTIONS_BELOW",
"transaction_id":"ONE_PASSED_IN_REQUEST_AUTH"
}


Request Post Activity Data:

Description: Once the oAuth process has been completed, your app is ready to send activity data whenever new data has been received by the user from a device or when the user has entered a manual entry of data. You have the option to post the activity immediately upon receiving the data from the user, or in can be posted in batches on a scheduled basis. Request Content-type is application/json and should use a POST method.

 

Note: We will only award points for data sent that was recorded up to seven days previous and should not be more than one day in the future.
POST POST_ACTIVITY_URL
Content-Type: application/json
{
"creates": [ {
"access_token":"USER_ACCESS_TOKEN",
"affiliate_id":"YOUR_AFFILIATE_ID",
"transaction_id":"RANDOM_NUMBER_16_LENGTH",
"date":"YYYY_MM_DD",
"user_device_id":"Either user_id from their account in your app, or the UUID",
"manufacturer_name":"YOUR_COMPANY_NAME" (20 MAX LENGTH),
"device_name":"YOUR_DEVICE_NAME"  (20 MAX LENGTH,This is displayed on the Walgreens Health Dashboard),
"data": [
{
"id":"UNIQUE_ID (This must be 100% unique for every user/activity/entry)",
"device_tracked":"true or false",
"timestamp":"YYYY-MM-DD HH:MM:SS",
"type":"ACTIVITY_TYPE" (Listed below),
"value": {"EXPLAINED BELOW" }
} ]
} ]
}

Sample Success response:
Content-Type: application/json
{
"success_code":"2000",
"transaction_id":"ONE_PASSED_IN_REQUEST"
}

Sample Error Response:
Content-Type: application/json
{
"error_code":"ERROR_CODES_BELOW",
"error":"ERROR_NAMES_BELOW",
"error_description":"ERROR_DESCRIPTIONS_BELOW",
"transaction_id":"ONE_PASSED_IN_REQUEST"
}

 

Error Response when processing activities failed:

When a request of activity data is returned with a response of "error_code":"1081" and "error":"process_activity_error", there will be an addition response parameter of "activities" which is an array of the activities that failed to post successfully.

Activity Posting Types: "creates" / "updates" / "deletes"

 

  • "creates":

    This would be used for new activity data that is being posted for the first time.

  • "updates":

    This would be used for updating an activity data previously posted, ensure the same "id" is used to update the value for the correct activity.

  • "deletes":

    This would be used for deleting an activity data previously posted, ensure the same "id" is used to delete the value for the correct activity.

 

DATE/TIMESTAMP PARAMETERS:

The "date" field is meant to determine the date in which the activity data request is being sent to Walgreens and not the date of the fitness activity that the end customer completed.
The "timestamp" field is the time in which the actual fitness activity was completed by the end customer and will correspond to end customer’s time zone.


Activity Value Definitions:

Description: The below table defines what "value" parameters are currently available to pass. We are always updating with new activity types!

NOTES:

  • An individual pedestrian activity should be captured using either the total_steps activity field or the walking field or the running field, not a combination of those fields for the same activity.
  • For walking & running activities, the conversation rate is 2,000 steps per 1 mile.
  • For biking activity, data is required to include the distance in the form of miles.
  • For sleep activity, data is displayed in the activity dashboard, but there are no points awarded.
Type Example Description Units Range
total_steps
{
"id":"MjAxNS0wOS0wOCAxODoyOTaksdf",
"device_tracked":"true",
"timestamp":"2015-09-08 18:29:28"
"type":"total_steps",
"value":1000,
}
								
Number of Steps taken the entire day. Steps 0-100000
walking
{
"id":"MjAxNS0wOS0wOCAxODoyOTaksdf",
"device_tracked":"false",
"timestamp":"2015-09-08 18:33:06",
"type":"walking",
"value": {
	"duration":600,
	"distance":1,
	"steps":2000
}
}
								
Duration of Exercise

Distance Traveled

Number of Steps

Seconds

Miles

Steps

0-86400

0-1400

0-100000

running
{
"id":"MjAxNS0wOS0wOCAxODoyOTaksdf",
"device_tracked":"false",
"timestamp":"2015-09-08 18:33:06",
"type":"running",
"value": {
	"duration":600,
	"distance":1,
	"steps":2000
}
}
								
Duration of Exercise

Distance Traveled

Number of Steps

Seconds

Miles

Steps

0-86400

0-1400

0-100000

biking
{
"id":"MjAxNS0wOS0wOCAxODoyOTaksdf",
"device_tracked":"false",
"timestamp":"2015-09-08 18:33:06",
"type":"biking",
"value": {
	"duration":3600,
	"distance":5
}
}
								
Duration of Exercise

Distance Traveled

Seconds

Miles

0-86400

0-1400

NEW! general_exercise
{
"id":"MjAxNS0wOS0wOCAxODoyOTaksdf",
"device_tracked":"false",
"timestamp":"2015-09-08 18:33:06",
"type":"general_exercise",
"value": {
	"duration":3600,
	"type":"NAME_OF_ACTIVITY"
}
}
								
Duration of Exercise

Name of Activity

Seconds

String

0-86400

Examples:
"Cross-Fit",
"Weight Lifting",
"Swimming",
"Yoga"

weight
{
"id":"MjAxNS0wOS0wOCAxODoyOTaksdf",
"device_tracked":"true",
"timestamp":"2015-09-08 18:29:28"
"type":"weight",
"value":168,
}
								
Total Weight Measured Pounds 0-1500
blood_pressure
{
"id":"MjAxNS0wOS0wOCAxODoyOTaksdf",
"device_tracked":"true",
"timestamp":"2015-09-08 18:33:06",
"type":"blood_pressure",
"value": {
	"systolic":120,
	"diastolic":80
}
}
								
Systolic Blood Pressure

Diastolic Blood Pressure

MmHg

MmHg

0-300

0-300

blood_oxygen_ratio
{
"id":"MjAxNS0wOS0wOCAxODoyOTaksdf",
"device_tracked":"true",
"timestamp":"2015-09-08 18:33:06",
"type":"blood_glucose",
"value": 10
}
								
Blood Oxygen Saturation Precent Oxigenated 0-100
blood_glucose
{
"id":"MjAxNS0wOS0wOCAxODoyOTaksdf",
"device_tracked":"true",
"timestamp":"2015-09-08 18:33:06",
"type":"blood_glucose",
"value": {  
	"value":56.2,
	"medicine_relation":"Pre-Medicine",
	"meal_relation":"Pre", 
	"meal":"Breakfast"
}
}
								

Blood Glucose Value

Medicine Relation

Relation To Meal

Meal Type

Mg/dL

 

String

 

String

 

String

0-1000

 

"Pre-Medicine",
"Post-Medicine"

 

"Pre" or "Post"

Examples:
"Breakfast",
"Lunch",
"Dinner"

sleep
{
"id":"MjAxNS0wOS0wOCAxODoyOTaksdf",
"device_tracked":"true",
"timestamp":"2015-09-08 18:33:06",
"type":"sleep",
"value": {
	"duration":34552,
	"quality":"Normal"
}
}
								
Duration of Sleep

Quality of Sleep

Seconds

String

0-86400

Examples:
"Good",
"Normal",
"Bad"


NEW! Request Balance Rewards Points Totals:

Description: With this endpoint we have introduced the ability for your integration to retrieve the points total for a connected Walgreens Balance Rewards user by leveraging the access token that is gained in the oAuth process. Request Content-type is application/json and should use a POST method.

 

POST GET_POINTS_URL
Content-Type: application/json
{
"access_token":"USER_ACCESS_TOKEN",
"affiliate_id":"YOUR_AFFILIATE_ID",
"act":"getBRPoints",
"transaction_id":"RANDOM_NUMBER_16_LENGTH"
}
 

NEW! Response Balance Rewards Points Totals:

Description: If the authorization token is valid, the server issues the points total for that user. The points comes back with the Total Balance Rewards points, and the points earned from doing healthy choices. Response Content-type is application/json.

Sample Success response:
Content-Type: application/json
{
"total_rewards_points":"Total Balance Rewards points",
"healthy_choice_points":"Balance Rewards points earned by healthy choices.",
"transaction_id":"ONE_PASSED_IN_REQUEST"
}

Sample Error Response:
Content-Type: application/json
{
"error_code":"ERROR_CODES_BELOW",
"error":"ERROR_NAMES_BELOW",
"error_description":"ERROR_DESCRIPTIONS_BELOW",
"transaction_id":"ONE_PASSED_IN_REQUEST"
}


API Error Codes:

Error Code Error Type Description
1001 invalid_request Any missing parameters in the request.
Invalid response_type.
Invalid grant_type.
Invalid value in the request params.
1011 unauthorized_client The client_id is invalid or not registered.
The redirect_uri is invalid.
1021 access_denied When the Authorization Code already exists for the user.
1031 invalid_scope The requested scope is invalid or not authorized to that client.
1041 invalid_authcode The authorization code which is in the request is invalid or expired.
1051 invalid_token The access token or refresh token which is in the request is invalid or expired.
1061 temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server.
1071 application_error Unable register user in Walgreens.com (Balance Rewards registration) due to some internal issues.
1081 process_activity_error Token validation success but unable process one or more activities. Only failed activity ids will be sent in the response object.

Disclaimer:

Consistent with the Terms of Use, your ability to launch a production integration of an Application is subject to approval by Walgreens.