Orders API
Order objects are closely tied to rewards. More specifically, they are rewards that have been redeemed by a customer. This API allows a third-party system to access orders for a specific customer. In addition, it supports placing an order and retrieving details of previous orders.
When an order is placed, it is initially in a "pending" state. From that point, conditions can be configured for the review of the order or it can be automatically approved without any review.
Once placed, an order reduces the customer's balance. The platform performs validations to determine whether or not the customer is qualified to make the order. It also ensures that there is enough inventory to satisfy the order, and that the IP address is not fraudulent.
Orders can fire emails automatically to whoever is engaged in the order redemption for purposes such as sending out gift card codes. All of the details associated with an order can be reviewed by a managed service, which can generate reports and also handle the requisite fraud tracking and prevention responsibilities. Note that order histories for customers are preserved indefinitely by SessionM.
When customers redeem physical merchandise, the request object passed in with the create method can specify a shipping address. Since shipping addresses associated with orders are free form, the platform performs the requisite validation logic to ensure the address is legitimate.
When an order is placed, the associated points are deducted from the customer's balance. Response objects returned by the Standard Profile API reflect this balance. Note that this API can also be used to create customers, a necessary part of any order being placed.
Order redemptions are represented in the response object returned by the Points API, including point debit balances and record identifiers for the orders placed.
Request objects for this API can include an attribute associated with the details in a Challenge object, which are managed by the Skills Test Challenge API. The use of challenge questions is a required component of orders placed for Canadian customers entering sweepstakes.
The state of an order can be queried on demand and returned in the order response object as a status attribute.
This API provides the following methods:
- Create an order for a reward
- Retrieve all orders for a customer
- Retrieve an order for a customer
- Update an order status
Create an Order for a Reward
Builds a new order for a reward.
Endpoints
This method offers the following endpoints:
POST /priv/v1/apps/:api_key/users/:user_id/offers/:offer_id/orders
POST /priv/v1/apps/:api_key/external/users/:external_id/offers/:offer_id/orders
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. |
| offer_id | Identifier for reward tied to order. |
| external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
Request Object
When this method runs, it passes in a request object that contains several attributes, including two "child" objects (shipping_address and challenge):
{
"order": {
"quantity": 1,
"email": "example@test.com",
"ip": "127.0.0.1",
"shipping_address" : {
"addressee" : "Mr. Tim O'Brian",
"street1" : "215 Hanover St.",
"street2" : "Suite 100",
"city" : "Boston",
"state_province" : "MA",
"country" : "US",
"postal_code" : "01902"
},
"challenge" : {
"id": 111111
}
}
}
These objects are detailed in the following tables:
| Attribute | Type Required/Optional |
Description |
|---|---|---|
| quantity | integer optional |
Defaults to 1. |
| string optional |
Fulfillment email. Defaults to the current customer's email address. Data is encrypted for storage on the disk. | |
| ip | string optional |
Used for tracking order origins for fraud detection. |
| shipping_address | object optional |
Free form address object. |
| challenge | object optional |
For more information, see the table below. |
| status | string optional |
Order status. |
Request Attributes for Challenge
| Attribute | Type Required/Optional |
Description |
|---|---|---|
| id | integer required |
Skills test challenge ID. Required only for Canadian contests |
Response Object
In addition to a status value-pair for the transaction, the response object returned by the method contains an order object, as shown below:
{
"status": "ok",
"order": {
"id": 111111,
"offer_id": 2,
"user" : {
"id":"xxxxx",
"available_points":"0"
},
"quantity": 1,
"points": 100,
"status": "pending_approval",
"created_at": "2015-01-20 13:04:45",
"name": "Electronic Giftcard",
"logo": "http://content.sessionm.com/1/2/2/2/giftcard.png",
"description": "Used at electronic.com",
"shipping_address" : {
"addressee" : "Mr. Tim O'Brian",
"street1" : "215 Hanover St.",
"street2" : "Suite 100",
"city" : "Boston",
"state_province" : "MA",
"country" : "US",
"postal_code" : "01902"
}
}
}
The following table documents this object:
| Attribute | Type | Description |
|---|---|---|
| id | integer | Order ID. |
| offer_id | integer | Reward ID. |
| user_id | string | Customer ID. |
| user | object | For more information, see the table below. |
| quantity | integer | Order quantity. |
| points | integer | Total cost in points. |
| status | string | Order status: pending_approval, approved, rejected. |
| created_at | string | Order creation time in UTC. |
| name | string | Reward name. |
| logo | string | Reward logo URL. |
| description | string | Reward description. |
| offer_type | string | Reward type. Sample values include: prize, reward, deal, coupon, instant reward, participation reward, balance transfer, contest entries, benefit, trigger and redemption. |
| external_id | string | Order external ID. |
| shipping address | object | Free form shipping address if passed in. |
Response Attributes for User
| Attribute | Type Required/Optional |
Description |
|---|---|---|
| id | string | SessionM customer identifier. |
| available_points | integer | Customer's current points balance, which can be utilized for the specified order. Displays when the enable_mpoints_info_in_users_api setting is enabled, which is accessed via the SessionM Admin Portal. For more information, consult your Customer Success contact. |
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 |
|---|---|
| invalid_api_key | The API key sent in cannot be found. |
| user_not_found | The customer ID sent in cannot be found. |
| requires_registered_user | The customer ID sent in is not registered. |
| offer_not_available | The reward is not available. |
| missing_data | Required parameter. |
| challenge_not_found | A challenge required by a Canadian contest is required. |
For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.
Retrieve All Orders for a Customer
Retrieves all of the orders associated with a specified customer.
Endpoints
This method offers the following endpoints:
GET /priv/v1/apps/:api_key/users/:user_id/orders
GET /priv/v1/apps/:api_key/external/users/:external_id/orders
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. |
| limit | Defaults to 50. |
| page | Defaults to 1. |
| between | Find all orders between these dates; comma-separated. |
| before | Find all orders before this date. |
| after | Find all orders before this date. |
Request Object
Not applicable.
Response Object
In addition to a status value-pair for the transaction, the response object returned by the method contains an orders array, which can comprise multiple objects, as shown below:
{
"orders": [
{
"id": 111111,
"offer_id": 2,
"user_id": "xxxxx",
"quantity": 1,
"points": 100,
"status": "pending_approval",
"created_at": "2015-01-20 13:04:45",
"name": "Electronic Giftcard",
"logo": "http://content.sessionm.com/1/2/2/2/giftcard.png",
"description": "Used at electronic.com",
"shipping_address" : {
"addressee" : "Mr. Tim O'Brian",
"street1" : "215 Hanover St.",
"street2" : "Suite 100",
"city" : "Boston",
"state_province" : "MA",
"country" : "US",
"postal_code" : "01902"
}
}
]
}
For more information, see the order object.
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. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.
Retrieve an Order for a Customer
Retrieves an order associated with a specified customer.
Endpoints
This method offers the following endpoints:
GET /priv/v1/apps/:api_key/users/:user_id/orders/:order_id
GET /priv/v1/apps/:api_key/external/users/:external_id/orders/:order_id
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. |
| order_id | Identifier for the order. |
| external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
Request Object
Not applicable.
Response Object
In addition to a status value-pair for the transaction, the response object returned by the method contains an order object, as shown below:
{
"order": {
"id": 111111,
"offer_id": 2,
"user_id": "xxxxx",
"quantity": 1,
"points": 100,
"status": "approved",
"created_at": "2015-01-20 13:04:45",
"name": "Electronic Giftcard",
"logo": "http://content.sessionm.com/1/2/2/2/giftcard.png",
"description": "Used at electronic.com",
"shipping_address" : {
"addressee" : "Mr. Tim O'Brian",
"street1" : "215 Hanover St.",
"street2" : "Suite 100",
"city" : "Boston",
"state_province" : "MA",
"country" : "US",
"postal_code" : "01902"
}
}
}
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. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.
Update an Order Status
Updates an existing order status.
Endpoints
This method offers the following endpoints:
POST /priv/v1/apps/:api_key/orders/:order_id
POST /priv/v1/apps/:api_key/external/orders/:external_order_id
PUT /priv/v1/apps/:api_key/orders/:order_id
PUT /priv/v1/apps/:api_key/external/orders/:external_order_id
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. |
| order_id | Identifier for the order. |
| external_order_id | Identifier for order's external ID. |
Request Object
When this method runs, it passes in a request object that contains an order object, as shown below:
Response Object
In addition to a status value-pair for the transaction, the response object returned by the method contains an order object, as shown below:
{
"status": "ok",
"order": {
"id": 1,
"user_id": "4f5b82c0-07c8-11e6-8d84-624132d14633",
"offer_id": 1,
"quantity": 1,
"points": 6000,
"status": "approved",
"created_at": "2015-01-20 13:04:45",
"name": "$5 Amazon Gift Card",
"logo": "http://localhost:3001/assets/01/1/13/5amazon.png",
"description": "Amazon Gift Cards never expire and can be redeemed towards millions of items at Amazon stores and amazon.com",
"offer_type": "prize",
"external_id": "external1"
}
}
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 |
|---|---|
| invalid_api_key | The API key sent in cannot be found. |
| invalid_request_order_status | The status of the invalid request order. |
| invalid_order_status | The status of the invalid order. |
For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.