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:
The above diagram shows the use of the Send Transaction API based on two scenarios:
- Online state (Communication Processed to SessionM)
- Offline State (Logging Transactions to Disk)
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:
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:
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 |
|---|---|---|
| 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. |
| 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. |
| 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:
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:
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. |
| 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. |