Points API
Points objects track the chronological history of a customer's points-related transactions and support the addition or removal of points for a customer account balance.
Since transaction points are associated with customers, you must create customers to engage in the transactions. Use the Standard Profile API to create customers and specify the attributes for their standard profiles.
Transaction points debits can be generated from orders created via the Orders API. Points spent on orders are displayed in objects returned by the Points API.
Transaction points credits can be generated from campaigns based on actions and corresponding incentives retrieved via the Campaigns API. Points earned from campaign incentives are displayed in objects returned by the Points API. Note that points can also be earned through the Referrals API and the Image Validation API.
The API provides the following methods:
Add or Remove Points for a Customer Account
Adds, or "comps," points to a customer account as well as removes them. This method also updates the existing points balance.
Note that adding points requires that the points attribute within the request object is set to a positive integer; conversely, if points is set to a negative integer, the method removes points from the account balance.
Endpoints
This method offers the following endpoints:
For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters
The following parameters are available when specifying the endpoint for this method:
| Endpoint Parameter | Description |
|---|---|
| api_version | Internal parameter that supports API versioning. |
| api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
| user_id | Internal identifier for the customer within the SessionM Platform. |
Request Object
When this method runs, it passes in a request object that contains a transaction object, as shown below:
{
"transaction": {
"points": 10,
"type": "survey",
"model_id": 10,
"id": "8a8ff754-9994-11e7-9ab2-8efa4370fd7e",
"user_id": "8a8ff754-9994-11e7-9ab2-8efa4370fd7e",
"campaign_id": 23,
"origin": "home_page",
"source": "mpoints",
"free_form": "first_survey"
}
}
This object is detailed in the following table:
Request Attributes for Transaction
| Attribute | Type Required/Optional |
Description |
|---|---|---|
| points | integer required |
Number of points being added to or removed from the user account; a positive integer adds points while a negative number removes them. |
| type | string required |
Type of transaction, defined by the endpoint consumer. |
| model_id | integer required |
Type identifier for transaction. |
| id | string required |
Identifier for the transaction. |
| user_id | string required |
Identifier of user. |
| campaign_id | integer required |
Identifier of campaign associated with transaction. |
| origin | string required |
Free form tracking identifier for origin of transaction. |
| source | string required |
Free form tracking identifier for source of transaction. |
| free_form | string required |
Free form tracking information. |
Response Object
In addition to a status value-pair for the transaction, the response object returned by the method contains a user object, as shown below:
{
"status": "ok",
"user": {
"id": "6a30816c-9995-11e7-86c4-d4f84370fd7e",
"available_points": 10
}
}
Statuses and Errors
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:
| Code | Reason |
|---|---|
| missing_data | No transaction data. |
| missing_data | No points to add or remove. |
For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.
Retrieve Points Transactions for a Customer
Retrieves points transactions for a customer. Maintained in reverse order - most recent first - this API records the points as credits (upon earning points) and as debits (upon redeeming points). Each line item in the record is expressed as a running balance. Note that when a customer incurs a deficit of points, the system awards "negative" points to the customer, ensuring that the appropriate balance is expressed.
Endpoints
This method offers the following endpoints:
GET /priv/v1/apps/:api_key/users/:user_id/points/transactions
GET /priv/v1/apps/:api_key/external/users/:external_id/points/transactions
For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters
The following parameters are available when specifying the endpoint for this method:
| Endpoint Parameter | Description |
|---|---|
| api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
| user_id | Internal identifier for the customer within the SessionM Platform. |
| external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
| start_date | Start date for period of time that batch of transactions occurred. Optional attribute. Defaults to now. For example, in compliance with ISO 8601/UTC standards: 2016-02-02T17:08:29Z. |
| end_date | End date for period of time that batch of transactions occurred. Optional attribute. Defaults to start_date - 1 month. For example, in compliance with ISO 8601/UTC standards: 2016-02-02T17:08:29Z. |
| limit | Optional attribute that specifies the maximum number of transactions allowed. Defaults to 1000; maximum of 1000. |
| cursor | Handles transactions that exceed limit specified in request. Optional attribute. Normally set to null in a request. Non-null value for cursor in response indicates more transactions to retrieve. This value can be included in a subsequent request to retrieve remaining transactions. null returned for cursor when no more transactions remain. |
Request Object
Not applicable.
Response Object
In addition to a status value-pair for the transaction, the response object returned by the method contains a cursor attribute along with a transactions object, as shown below:
{
"status": "ok",
"cursor": "123a04a0-c035-11e5-91d3-a6f8eb8b17f8",
"transactions": [
{
"date": "2018-01-19T20:14:17.290Z",
"description": "20000ptscapCampaignTestA EN-US",
"record_id": "2-1518",
"record_model_type_id": 2,
"record_model_id": 1518,
"transaction": "credit",
"source": "achievement",
"type": "achievement",
"transaction_id": "79",
"transaction_type": "receipt",
"transaction_payload": null,
"points": 4000,
"balance": 48000
},
{
"date": "2018-01-19T20:43:10.975Z",
"description": "achievement_name_here",
"record_id": "2-1558",
"record_model_type_id": 2,
"record_model_id": 1558,
"transaction": "credit",
"source": "achievement",
"type": "achievement",
"transaction_id": "991230000011",
"transaction_type": "purchase",
"transaction_payload":
{
"this_is_an_example": "hello"
},
"points": 50,
"balance": 50
}]
}
{
"status": "error",
"errors": {
"base": "failed",
"message": "bad start date"
},
"transactions": null
}
For more information on cursor, see its row in the Endpoint Parameters table above.
The following table details the transactions object:
Response Attributes for Points Transactions
| Attribute | Type | Description |
|---|---|---|
| date | string | Timestamp for the transaction. |
| description | string | Reflects the name of the behavior or campaign associated with the points. |
| record_id | string | Unique record identifier for the transaction. |
| record_model_type_id | integer | Identifier for the model type of the transaction record. |
| record_model_id | integer | Identifier for the model of the transaction record. |
| transaction | string | Type of transaction: credit or debit. |
| source | string | Source of points awarded in transaction. Possible values include: achievement, contest, sponsor, merchant_rewards, enterprise, comp, used and expired. |
| type | string | Type of points awarded in transaction. Possible values include: donation, sweepstakes, merchandise, digital, digital, physical and receipt. |
| transaction_id | string | Identifier for transaction. For example, receipt capture ID or purchase event ID. |
| transaction_type | string (or null) | Type of transaction. For example, receipt or purchase. |
| transaction_payload | object (or null) | Payload of data associated with transaction. |
| points | integer | Points credited or debited. |
| balance | integer | Points balance after transaction. |
Statuses and Errors
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:
| Code | Reason |
|---|---|
| failed | Bad start date. |
For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.