NAV Navbar

Overview

Point of Sale (POS) objects support connecting a 3rd party point of sale or ecommerce platform to the SessionM Platform. The APIs allow 3rd parties to programmatically send transaction data and associate transactions to known members of a loyalty program. The APIs enable those using such a system the ability to redeem rewards, lock/unlock offers, and, in certain cases, reinstate a specific offer on a customer's behalf after it has been redeemed. Additionally, these APIs provide access to metadata that synchronizes employee and catalog information.

Note that these APIs are specifically for point of sale and ecommerce use cases and should be used in place of existing SessionM Platform APIs for any integration of this type, unless special cases merit a custom solution.

The APIs featured in this grouping support the following POS functions:

General DTO Definitions

This section details the Data Transfer Object (DTO) definitions for the requests and responses associated with the POS APIs.

General Request Container

The tables below describe the properties for required headers and the request body.

Required Headers

Property Type
Required/Optional
Description
Authorization string
required
The BASIC authentication header with credentials (key/secret) that are provided for the specific client and/or location.
Content-Type string
required
Specifies the content type of the request body. For all POS/ECom APIs this should be application/json.

Request Body

Property Type
Required/Optional
Description
store_id string
required
The SessionM provided store identifier for a specific location.
client_id string
required
The SessionM provided identifier assigned to the client.
request_id string
required
The unique ID of the request to enforce idempotency. (A given request will only be processed once. If a subsequent request is made with the same request_id, it will return the response when one had already been generated or if it bears an error code of “pending processing”.)
culture string
optional
The culture to be returned for messages and display names.
request_payload object
required
The specific payload for the request.

General Response Container

The tables below describe the properties for the response body.

Response Body

Property Type
Required/Optional
Description
status string
required
The status code for the response. For successful API calls, this will be “OK”.
payload object
optional
The payload for the response.
errors object
optional
If status is not “OK”, this property contains error details and validation details for the given API.

Transaction Processing

Transaction Processing allows for SessionM to process transaction details in near real-time from both e-commerce platforms and point of sale systems. The calls in this API should be done asynchronously to not slow down user queue processing speeds. In the event of an integrating location going offline, all transactions should be stored on-premises for the duration of the offline event and batched back to SessionM when the location regains network connectivity.

Transaction Processing contains the following APIs:

Send Transaction API

Sends SessionM transaction details when a location is online. In the event a location is offline, these requests should be batched using the Batch Send Transaction API.

The following image shows the process flow for sending a transaction:

Image1

The above diagram shows the use of the Send Transaction API based on two scenarios:

It is important to note that if a user is not associated to the transaction (through User Lookup or offer application through Discounting) AND post-transaction association is enabled for the specific user, a globally unique QR Code should be generated and passed to SendTransaction. If a single payment was used, this would be passed as the Transaction receipt_code property. If multiple payments were used, this would be passed as the Payment Object receipt_code property.

The value of the QR Code that is printed should be of the format: https://[custom url configurable per client]/[QR CODE VALUE]. Only the QR CODE VALUE should be passed through the SendTransaction API. To generate a globally unique QR Code value, SessionM recommends using a UUID construct of whatever programming language that is being used. For example: .NET would use GUID; Java would use UUID; and Ruby would use SecureRandom.uuid.

For more information on this process flow, consult your Customer Success contact.

Endpoint

This API offers the following endpoint:

▿ REST Endpoint

POST /api/2.0/send_transaction

Endpoint Parameters

Not applicable.

Request Object

When this endpoint runs, it passes in a Transaction request object. When using this API, pass in the request_payload as the Transaction object, which is detailed in the following tables:

Request Properties for Transaction

Property Type
Required/Optional
Description
pos_employee_id string
required
Client system employee_id for the employee who should be associated to this transaction.
sm_employee_id string
optional
SessionM user_id for the employee, which is only required for clients that have an employee reward program.
table_id string
optional
Client system table_id for where the user was seated. For retail or e-commerce, this value is not used.
guest_count int
optional
Number of guests serviced by this transaction.
is_closed bool
required
Indicates whether this is the final state for the transaction. Should only be closed once the check is finalized and closed. This is when any discounts that were locked will be applied.
is_voided bool
required
Indicates whether this transaction was voided. If a transaction is voided, the value is true . Any and all loyalty earnings gained from association to this transaction will be removed.
transaction_id string
required
Unique transaction identifier that should correspond to any and all future updates for this transaction.
from_transaction_id string
optional
In the event of a split transaction, this should reference the parent transaction that this transaction was split from.
subtotal decimal
required
Subtotal without tax included of the transaction. This subtotal should reflect all of the applied discounts.
tax_total decimal
required
Total amount of tax for the transaction. If the tax for a certain item was included in the tax_included property of the Item object, it should not be included in the total tax accounted for in this property.
open_time DateTime
required
Date and time that this transaction was opened or created. This value should remain consistent for all correspondence regarding this transaction. Should be JavaScript JSON date time format. (yyyy-MM-ddTHH:mm:ss.fffZ) and be passed as the UTC date and time.
modified_time DateTime
required
Date and time that this transaction was last modified and triggered the update call to SessionM. Should be JavaScript JSON date time format. (yyyy-MM-ddTHH:mm:ss.fffZ) and be passed as the UTC date and time.
guest_receipt_code string
optional
The globally unique across all client transactions receipt code printed on the guest check. If no guest check is printed, this can be null.
channel string
required
Channel from which this transaction originated. For example, “STORE” or “ECOM” or “KIOSK”. Only used for client aggregation reporting. Values can be whatever the customer would like, but must be consistent across all instances of the same channel. Example values could be “IN-STORE”, “CARRY OUT”, and “DRIVE THROUGH”.
items Item[]
required
Current collection of item objects that make up this transaction.
payments Payment[]
required
Current collection of payment objects for this transaction. Note, if there are no payments applied this should be an empty array.
discounts Discount[]
required
Current collection of discount objects for this transaction. Note, if there are no discounts applied this should be an empty array.
custom_data JSON-formatted data Additional transaction-level data that can be carried into the SessionM Platform for custom use cases. Intentions for use must be vetted with the SessionM Team prior to implementation to ensure that data can be leveraged properly.

Request Properties for Item Objects

Property Type
Required/Optional
Description
line_id string
required
Unique, within-this-transaction, ID for this transaction line item. This is used for reference for modifiers and line item discounts. These values should remain consistent across subsequent requests.
item_id string
required
Client system unique item_id.
quantity decimal
required
Quantity purchased for this item.
unit_price decimal
required
Unit price for 1.0 quantity for this item.
subtotal decimal
required
Subtotal for this line. Should reflect unit_price * quantity = subtotal.
tax_included decimal
required
Amount of tax represented in the subtotal. Should only be used when the unit_price includes tax and should not be used for check-level taxes such as sales tax. Any tax that is represented at at item level via this property should not be included in the total transaction-level tax accounted for in the tax_total property.
modifies_line_id string
optional
If this item is a modifier for another item, this is the line_id of the item it modifies. Modifier prices should not be reflected within the unit_price or subtotal of the item being modified.
custom_data JSON-formatted data Additional item-level data that can be carried into the SessionM Platform for custom use cases. Intentions for use must be vetted with the SessionM Team prior to implementation to ensure that data can be leveraged properly.

Request Properties for Payment Objects

Property Type
Required/Optional
Description
payment_id string
required
The unique, to this transaction, payment ID, assigned by the client system.
amount decimal
required
Total amount of this payment applied to the transaction.
type string
required
Type of this payment. Example values: “Cash”, “Credit Card”, “Gift Card”, “Certificate”.
payment_time DateTime
required
Date and time when this payment was applied. Should be JavaScript JSON date time format. (yyyy-MM-ddTHH:mm:ss.fffZ) and be passed as the UTC date and time.
user_id string
optional
User ID that is applied to this payment.
user_id_type string
optional
Required when user_id is passed. This is used to determine the lookup type for a loyalty account. The lookup type provided must be configured as a required field and guaranteed unique within the program configuration. Legal values: “SessionM_ID”, “Email”, “Phone”, "External_ID".
additional_user_id string
optional
Additional user ID applied to this payment. Depending on program structure, this could be used for reporting purposes or where multiple user accounts within a hierarchy should be rewarded.
additional_user_id_type string
optional
Required when additional_user_id is passed. Used to determine the lookup type for a loyalty account. Lookup type provided must be configured as a required field and guaranteed unique within the program configuration. Legal values include: “SessionM_ID”, “Email”, “Phone”, "External_ID".
receipt_code string
optional
The globally unique, across all client transactions, receipt code printed on the payment check. If a user was looked up and a user_id provided, this can be null.
custom_data JSON-formatted data Additional payment-level data that can be carried into the SessionM Platform for custom use cases. Intentions for use must be vetted with the SessionM Team prior to implementation to ensure that data can be leveraged properly.

Request Properties for Discount Objects

Property Type
Required/Optional
Description
reference_id string
required
Reference ID of the discount. If this is a SessionM provided discount, this should be the provided user offer id. If this a discount provided from another system, it should be the identifier that uniquely identifies this discount within the transaction.
reference_id_type string
required
Will be used to be echoed back in Discounting APIs.
pos_discount_id string
optional
If passed, can be used to apply the discount from the point of sale side linking the discount details below to the discount on the point of sale for reporting purposes.
status string
optional
When this is provided in the response from any of the Discounting APIs it should be echoed back in subsequent transaction updates. Valid values are “LOCKED” or “REDEEMED” or “INFO” or “OFFLINE”.

Note: The OFFLINE status should ONLY be used for offline transactions. This will skip any validation or restriction checks and force the offer to be removed from the user’s wallet. In the event the offer is no longer available due to expiration or being used by another online transaction, this will fail without notification back to the point of sale. OFFLINE should only ever be used to ensure that an offer is no longer available in a user’s wallet.
display_name string
required
Name of the discount.
image_url string
optional
Image URL associated with this discount.
discounted_line_ids string[]
optional
If this discount is applied to one or more items within the transaction this should contain the line_id of what items were discounted. If this is a check level discount not applied to any specific items, this can be null.
discounted_line_id_quantities string[]
optional
This array is aligned with the indexes from the discounted_line_ids property and specifies the quantity for each line to which the discount was applied. If this property is not passed, the discount is evenly distributed across the entire quantity specified for that line (which could adversely impact discount calculation in stacking scenarios).

For example, if line_id “1234" was purchased with quantity "4", and a $10 discount was applied to the line_id, a discounted_line_id_quantities of “2” indicates that the $10 discount should be spread across only the first two items within that line_id ($5 per item).
discount_source string
required
Source system for the discount. Example: If this discount was provided by SessionM the source should be “SessionM”. If this is a discount such as an employee discount the source could be “POS”.
amount decimal
required
Amount of the discount applied to the check.
stack_order int
required
Order in which this discount was applied. If it is the only discount on the check, this value should be 0. (For multiple discounts use order example: 0 => 1 => 2 => 3 => etc.)
applied_time DateTime
required
Date and time that this discount was applied to the transaction. This should be JavaScript JSON date time format: (yyyy-MM-ddTHH:mm:ss.fffZ); and, it should be passed as the UTC date and time.
user_id string
optional
Returned from the Lock and Redeem calls, this is the SessionM user’s identification.

Response Object

The Transaction Response object will just be the generic response object with no payload, by which a 200 HTTP status code means it was received successfully. A 403 HTTP status code means the request was unauthorized or contained invalid credentials. A 500 HTTP status code means the call was unsuccessful and should be resubmitted.

Batch Send Transaction API

Sends batches of transactions in bulk. This API is designed to be used for sending transactions that occurred while offline. A maximum of 10 transactions may be sent at a time, but this limitation may vary due to average transaction request size depending on the integration.

The following image shows the process flow for batch sending a transaction:

Image2

The above scenario shows how the Batch Send Transaction API would be used in recovering from an offline period in a store. Transactions should be batched with a batch size that is configurable per client and they should be iterated over the offline files until they are all sent.

For more information on this process flow, consult your Customer Success contact.

Endpoint

This API offers the following endpoint:

▿ REST Endpoint

POST /api/2.0/send_batch_transaction

Endpoint Parameters

Not applicable.

Request Object

When this endpoint runs, it passes in a Batched Transaction object. When using this API, pass in the request_payload as the Batch Transaction object, which is detailed in the following tables:

Request Properties for Batch Transaction

Property Type
Required/Optional
Description
transactions Transaction[]
required
The collection of transactions being sent.

User Lookup

User Lookup allows for user attribution to transactions through the checkout process. There are various flows supported by the APIs below; their usage is dependent on the desired workflow.

User Lookup API

Supports user lookups by exact match. The following image shows the process flow for an exact match lookup:

Image3

The above scenario shows an exact match lookup of a user. If a transaction payload was provided, offers returned will also have a discount amount. When searching exact match, the search criteria used must be unique per user account. If multiple rows are returned, an error will be returned from the API and the cashier must to provide an alternative lookup value for that user account.

For more information on this process flow, consult your Customer Success contact.

Endpoint

This API offers the following endpoint:

▿ REST Endpoint

POST /api/2.0/lookup

Endpoint Parameters

Not applicable.

Request Object

When this endpoint runs, it passes in a User Lookup request object. When using this API, pass in the request_payload as the User Lookup object, which is detailed in the following table:

Request Properties for User Lookup

Property Type
Required/Optional
Description
email string
optional
Email associated with the desired user account.
phone string
optional
Phone number that is associated with the desired user account. Format required is numbers only.
user_id string
optional
ID of the user account.
external_customer_id string
optional
External ID associated with the desired user account. This ID can include a customer's assigned loyalty card number.
transaction Transaction
optional
If the transaction object is passed, the response of this API will only contain eligible offers and will also contain the discount details. If this value is not provided, all offers in the user’s wallet will be returned and no discount application details will be provided. If an order is changed, you would call lookup again and provide the modified transaction using the user_id for a lookup argument.

Response Object

Response Properties for User Lookup

Property Type
Required/Optional
Description
users user[]
required
Result from the lookup.

Response Properties for User

Property Type
Required/Optional
Description
user_reference_id string
required
Contains the user_id for the account.
user_account_id string
optional
Only returned in full responses.
first_name string
optional
First name of the user.
last_name string
optional
Last name of the user.
phone string
optional
Phone number of the user.
email string
optional
Email for the user.
points decimal (Nullable)
optional
Summary of spendable points for the user account. This will only be returned for programs that have configured it to be returned in a user lookup.
profile_fields KVP(string,string)
optional
Key value pair collection housing profile fields with values that are configured for the integration. Key will be the profile field and the value will be the value for the profile field.
offers Discount[]
optional
Offers for the user account. Only returned if the full user account is returned and will contain discount information if a transaction was provided.
point_accounts PointAccount[] Detailed description of all point accounts associated with this user account. If multiple point accounts are associated with this user account, this will return details for each account.

Response Properties for Point Account Objects

Property Type Required Description
account_name string Yes Name of the point account.
user_point_account_id string No ID of the user point account.
point_account_id string Yes ID of the point account
grouping_label string Yes Grouping to which the point account belongs.
available_balance decimal Yes Available points.
life_time_value decimal Yes Lifetime points for the account.

Discounting

Discounting allows for a full range of discount workflows. The SessionM recommended path is to lock an offer, process the transaction and allow the transaction’s finalization through Send Transaction to process the offer. Alternatively, you can call immediate redeem to immediately process the offer for use.

Discounting contains the following APIs:

Immediate Redeem API

Allows an offer to be immediately consumed. To reverse the offer usage, you will have to call the Reinstate Offer API to re-issue the offer to the user. The response to this API is the Discount object as the payload for the General Response contract above.

The following image shows the process flow for an immediate redemption:

Image5

The above scenario illustrates the immediate redemption process. Immediately following the Immediate Redeem API call, payment should be collected and the transaction closed. If further modifications to the line items are made, the redeemed offer should be reinstated and reapplied to ensure that the discounted amount is accurate.

For more information on this process flow, consult your Customer Success contact.

Endpoint

This API offers the following endpoint:

▿ REST Endpoint

POST /api/2.0/redeem

Endpoint Parameters

Not applicable.

Request Object

When this endpoint runs, it passes in an Immediate Redeem request object. When using this API, pass in the request_payload as the Immediate Redeem object, described in the following tables:

Request Properties for Immediate Redeem

Property Type
Required/Optional
Description
offer_lookup_code string
required
Lookup code for the offer.
offer_lookup_type string
required
Specifies what the offer_lookup_code represents. Valid values are “TTLCode” and “UserOfferId”.
transaction Transaction
required
Transaction to which this discount is being applied.

Lock Offer API

Allows an offer to be “locked” by a transaction and redeemed upon the finalization of that transaction. The response to this API is the Discount object as the payload for the General Response contract above.

The following image shows the process flow for locking an offer:

Image6

The above scenario illustrates how Lock Offer API should be used. Note that similar to the Immediate Redeem API, the Lock Offer should be used immediately prior to taking payment and closing the transaction. If the transaction is modified after the Lock Offer API has been called and the discount applied, the Lock Offer API should be called again, passing the exact same transaction ID, and applying the returned modified discount if it is still valid. Additionally, it is crucial that the same discount object that was the response from the Lock Offer API is also passed back in the post-finalize, "send transaction" flow. If an offer is invalid and can no longer be applied to the check, the Unlock Offer API should be called to release the offer back to the user’s wallet.

For more information on this process flow, consult your Customer Success contact.

Endpoint

This API offers the following endpoint:

▿ REST Endpoint

POST /api/2.0/lock

Endpoint Parameters

Not applicable.

Request Object

When this endpoint runs, it passes in a Lock Offer request object. When using this API, pass in the request_payload as the Lock Offer object, described in the following tables:

Request Properties for Lock Offer

Property Type
Required/Optional
Description
offer_lookup_code string
required
Lookup code for the offer.
offer_lookup_type string
required
Specifies what the offer_lookup_code represents. Valid values are: “TTLCode” and “UserOfferId”.
transaction Transaction
required
Transaction to which this discount is being applied.

Unlock Offer API

Allows an offer to be “unlocked” once it had been locked. The response to this API is the General Response contract above, with no payload.

For more information on this API's process flow, consult your Customer Success contact.

Endpoint

This API offers the following endpoint:

▿ REST Endpoint

POST /api/2.0/unlock

Endpoint Parameters

Not applicable.

Request Object

When this endpoint runs, it passes in an Unlock Offer request object. When using this API, pass in the request_payload as the Unlock Offer object, which is detailed in the following tables:

Request Properties for Unlock Offer

Property Type
Required/Optional
Description
user_offer_id string
required
User offer ID being unlocked. This will be what is passed back as the reference ID to any prior offer lookup request for SessionM serviced offers.
employee_id string
required
Employee ID who triggered the action to unlock the user offer.

Reinstate Offer API

Allows an offer to be reinstated after it has been redeemed. This needs to be used if the Immediate Redeem API was used or if the Lock Offer API was used and the transaction was closed. The response to this API is the General Response contract above, with no payload.

For more information on this API's process flow, consult your Customer Success contact.

Endpoint

This API offers the following endpoint:

▿ REST Endpoint

POST /api/2.0/reinstate

Endpoint Parameters

Not applicable.

Request Object

When this endpoint runs, it passes in an Reinstate Offer request object. When using this API, pass in the request_payload as the Reinstate Offer object, described in the following tables:

Request Properties for Reinstate Offer

Property Type
Required/Optional
Description
user_offer_id string
required
User offer ID being reinstated. Passed back as the reference ID to any prior offer lookup request for SessionM serviced offers.
employee_id string
required
Employee ID who triggered the action to reinstate the user offer.

Metadata

Metadata allows for synchronizing employee and catalog information to the SessionM system. Catalog changes should be updated as soon as possible after the catalog has changed. Employee information should be synchronized routinely to ensure that reporting accurately represents employee patterns and trends.

Metadata contains the following APIs:

Upload Catalog API

Synchronizes the stores catalog information with the SessionM Platform. Unknown items will not be eligible for discounts and will not be reflected properly in reports. When the catalog changes, the Upload Catalog API should be called as soon as possible.

For more information on this API's process flow, consult your Customer Success contact.

Endpoint

This API offers the following endpoint:

▿ REST Endpoint

POST /api/2.0/upload_catalog

Endpoint Parameters

Not applicable.

Request Object

When this endpoint runs, it passes in a Catalog request object. When using this API, pass in the request_payload as the Catalog object, described in the following tables:

Request Properties for Catalog

Property Type
Required/Optional
Description
items Category[] or Item[]
required
Mixed array of Category or Item objects, representing the catalog or menu for this store.

Request Properties for Category

Property Type
Required/Optional
Description
category_id string
required
Unique Category ID assigned by the point of sale system. Used in all future transactions to lookup the category.
name string
required
Display name for this category.
description string
optional
Description for this category.
category_ids string[]
optional
Children category IDs for this category.
item_ids string[]
optional
Children item IDs for this category.

Request Properties for Item

Property Type
Required/Optional
Description
item_id string
required
Unique Item ID assigned by the point of sale system. Used in all future transactions to lookup the item.
sku string
optional
SKU assigned for the item. This should be sent if the point of sale system uses configured SKUs to represent an item in addition to the internal Item ID.
name string
required
Display name for the item.
description string
optional
Description for the item.
is_modifier bool
required
Indicates whether this item represents a modifier.
modifies_item_ids string[]
optional
Only used when item passed is a modifier. Describes what items this modifier can be associated with in a transaction.

Upload Employees API

Synchronizes the store's employee information with the SessionM Platform.

For more information on this API's process flow, consult your Customer Success contact.

Endpoint

This API offers the following endpoint:

▿ REST Endpoint

POST /api/2.0/upload_employees

Endpoint Parameters

Not applicable.

Request Object

When this endpoint runs, it passes in an Employees request object. When using this API, pass in the request_payload as the Employees object, described in the following tables:

Request Properties for Employees

Property Type
Required/Optional
Description
employees Employee[]
required
An array of employees for this store.

Request Properties for Employee

Property Type
Required/Optional
Description
employee_id string
required
Unique employee ID assigned by the point of sale system.
first_name string
required
First name of this employee.
last_name string
required
Last name of this employee.
start_date DateTime
optional
Start date of this employee.
end_date DateTime
optional
End date of this employee.