Points API

Track a customer's points transaction history and add or remove points from their account balance.

The Points API has been deprecated. While its methods are still implemented, they may be removed in future implementations. Therefore, new integrations should use the Incentives 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.

API Contingencies and Combinations:

Before you can begin using the Points API, ask SessionM to enable your point transaction history.
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
Retrieve points transactions for a customer

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 for Add or Remove Points for a Customer Account

This method offers the following endpoints:

REST Endpoints

POST /priv/:api_version/apps/:api_key/users/:user_id/points

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 for Add or Remove Points for a Customer Account

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 for Add or Remove Points for a Customer Account

When this method runs, it passes in a request object that contains a transaction object, as shown below:

JSON Request

{
  "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 for Add or Remove Points for a Customer Account

In addition to a status value-pair for the transaction, the response object returned by the method contains a user object, as shown below:

JSON Response

{
  "status": "ok",
  "user": {
    "id": "6a30816c-9995-11e7-86c4-d4f84370fd7e",
    "available_points": 10
  }
}

Statuses and Errors for Add or Remove Points for a Customer Account

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 for Retrieve Points Transactions for a Customer

This method offers the following endpoints:

REST 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 for Retrieve Points Transactions for a Customer

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 for Retrieve Points Transactions for a Customer

Not applicable.

Response Object for Retrieve Points Transactions for a Customer

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:

JSON Response (Success)

{
    "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
    }]
}

JSON Response (Error)

{
  "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 for Retrieve Points Transactions for a Customer

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.

Was this page helpful?