Getting Started

The Point of Sale (POS) integration guide includes extensive and reference materials to aid POS system's developers for integrating any POS system with CRM.COM Rewards platform, using a set of recommended Web API methods provided by CRM.COM

CRM.COM Rewards & POS Ecosystem

What is CRM.COM Rewards?

CRM.COM Rewards application is designed to cover any business operations that aim to identify and award their loyal customers, via numerous reward offers. Such offers award loyal customers with conditional (or not) cashback that can be consumed on specific products, units (different merchant' stores), and specific days/hours or at the customer's discretion (with no conditions) without having any dedicated operations on the POS side (awards are agnostic to the POS software)

CRM.COM supports two reduction methods that define how the amount that is requested to be consumed (spend) by the customer will be reduced from the total amount that should be paid

Front-End Reduction - The reduction is done by a front-end system (i.e. POS) by reducing the amount of money that the consumer should actually pay
Back-End Reduction - The reduction is done is by a back-end system (i.e. PayPal) by letting the customer to pay for the full purchased amount and credit him through a payment gateway system or by generating a refund voucher

What is Point of Sale software?

Point of Sale (POS) software is the system that is used by an agent (cashier) to sell goods to a customer and collect the due amount in usually a face to face (over the counter) manner

Key Definitions

The following section lists a number of definitions that describe the key points in a POS & CRM.COM Rewards integration flow

Identify Customer	The customer is identified on the POS system by providing an identification mean, such as email address, phone number or card number
Create Customer Basket	A customer's basket is created when a set of products that is intended to be bought by the customer are presented to the POS (i.e. cashier counter) for submission
Close Customer Basket	A customer's basket is closed when the last intended product to be purchased is submitted in the POS (i.e. cashier counter) and no other adjustments will be made
Complete Payment	Completing a payment is the process where the customer is prompted to pay for the purchased products via any form of payment, such as cash, credit cards, and awarded cashback
Award	Award is the amount that will be provided to the customer in the form of cashback (credit the customer's wallet) when closing a customer's basket (given that the purchased products are eligible for an award based on a valid reward offer)
Spend	Spend is the awarded amount (debited from the customer's wallet) that will be deducted from the basket's total amount that the customer should pay for
Default Product	During the process of awarding a customer's purchased products, some products may do not exist in CRM.COM yet (due to a time-frame gap with the product synchorisation runs) Such products can be handled entirely by CRM.COM using a default product without interrupting the POS flow, and once the related record is created in CRM.COM the merchant can retrieve the intended purchased products for further analysis

How to integrate your POS system to CRM.COM

The customer is firstly identified at the POS agent by providing his identification details, such as phone number, card number. Once the customer is identifier, the agent is creating the customer's basket into the POS software by submitting all products to it. When the last intended product to be purchased is submitted in the POS and no other adjustments will be made, the customer's basket is closed, and the itemized POS sales transaction is submitted to CRM.COM in order to award the customer based on the purchased products. The payment is completed by collecting the due amount for the purchased products. The due amount can be settled via any form of payment, such as cash, credit cards, spending awarded amount, or even a combination of these

The following diagram illustrates the integration architecture and key points

CRM.COM & POS Product Synchronization

CRM.COM Product Synchronization allows a POS system to add or update a group of products that exist in the POS with the ones in CRM.COM usually through a background batch process, resulting into creating new products or update existing ones (e.g. name, description, category) in the CRM.COM

What is a CRM.COM Product?

Products are physical goods that can be used by any type of business transaction within CRM.COM software. Products are classified into services and physical goods. They can be sold rented or simply used by customers through multiple business events such as subscriptions, jobs, activities, direct sales and can also be awarded to reward participants through rewards

In addition, Products in CRM.COM have a set of attributes (type, brand, family, categories) that are used to determine their operational characteristics, define trademarks and group products based on common physical characteristics

Product Type

Product Type is used to determine the operational characteristics of products, and classify a product as a physical good or a service and what kind of a good or service is (i.e. termed, usage, traceable, non-traceable). For POS integration purposes, all products should have a product type that classifies products as non-traceable physical goods

Product Brand

Product Brand is used to define trademarks or distinctive names that serve to identify a specific Product

Product Family

Product Family is used to group products that derive from a common product platform and have similar physical characteristics

Product Categories

Product Categories are used to classify products into generic groups based on specified shared attributes

Putting it all together

Now that we have laid out all product attributes, let's put them together and present a couple examples of Products in CRM.COM

No.	Product	Product Type	Product Brand	Product Family	Product Categories
1	Galaxy Note 9	Technology	Samsung	Smartphones	Smartphone, Android phone, Octa-core processor
2	Samsung MU6070	Technology	Samsung	QLED TV	TV, QLED, 4K resolution
3	Brownie	Comestibles	Yummy Chocolates	Chocolates	Brownie, Chocolate, Diary
4	Croissant Double	Comestibles	7 Days	Croissant	Croissant, Chocolate, Vanilla
5	Iced Caramel Latte	Coffee	Coffee Brewers	Coffee	Coffee, Milk, Latte, Syrup

How Product Synchronization between POS and CRM.COM works

Product Synchronization can be achieved using CRM.COM Web API methods that a POS system can call periodically in order to synchronize product information between POS and CRM.COM

Before you begin

Prior proceeding to the integration implementation, let's walk through a few basic API concepts that will be required on each subsequently method

Authentication

Before performing any logical unit of work, an authentication token must be acquired and subsequently will be used by all other Web API methods in order to access and performed any operations in the system. All API requests must be made using a valid authentication token, otherwise such requests will fail

Acquiring an authentication token can be accomplished by using one of the following methods

Web API Key
Username & Password

Recommended Authentication Method

The recommended method of authentication is using Web API Keys of a "System Key" classification. Web API Keys are assigned to specific users in order to access a specific organization and can be used to authenticate users through Web API, resulting to an authentication token that can subsequently be used by other Web API calls, without any data restrictions

The authentication Web API call that should be performed is POST authentication/web_api_key/token (based on HTTP Basic Auth)

Web API Key Method Example

Reference

Visit API Authentication for more information

Using Fields Set

CRM.COM Web APIs offer the ability to select the fields that will be retrieved from each API method by specifying the "fields_set" input parameter

Using this parameter developers have the ability to filter the response object and retrieve only the fields that will be used for the desired implementation. If "fields_set" is not specified, then all fields of the response will be retrieved

The "fields_set" attribute is used for each call throughout the entire integration guide

Reference

Visit Introduction - Using Fields Sets for more information

Using Pagination

There are some API methods that retrieve a large number of entities, such as list API methods. Some of these CRM.COM API methods provide the option to apply pagination on the results retrieved

In such cases the API call should be constructed using the following input parameters

number_of_results: The number of results that can be retrieved through each call. The maximum number of results can be 50, and objects are returned in chronological order (oldest requests are retrieved fist)
offset: Defines the number of entities that should be skipped from the results. During the first call it should be set to 0 and then it should be increased based on the number of results that were retrieved

Reference

Visit Introduction - Using Pagination for more information

Integration Scenarios

Purchase and Spend Award Flow

The flow described below is an example of a POS integration with CRM.COM Rewards, including both purchase and spend transactions

No	Description	Web API Example	POS Conceptual Examples
Step 1 - Customer Identification
1	The customer is identified on the POS system by providing an identification mean. Such identification can be an email address, a phone number, a card number, etc Identifying a customer in CRM.COM (also referred as rewards participant) should be performed using the POST rewards_participants/show method The following identification means can be used to identify a customer in CRM.COM number: A unique number that is related to each rewards participant access_token_identifier: An access token that is related to a rewards participant. An access token is the most common parameter to use for customer identification purpose, because it can be easily assigned to a rewards participant and usually is mapped to the customer's email address, phone number or card number	POST Request https://hostname/crmapi/rest/v2/rewards_participants/show Body Expand source { "token": "{{token}}", "rewards_participant_identifier":{ "access_token_identifier":{ "authentication_code": "22265577" } }, "fields_set": "accounts_receivable,wallet" }	Prior Customer Identification
2	Once a customer is identified in CRM.COM, then the full information of the customer is returned The following information can be displayed on the POS screen The name of the customer (accounts_receivable.account_owner.name) The available balance of the customer's wallet (wallet.balance)	Response Expand source { "data":{ "wallet": { "number": "W0000000001, "balance": "10.00", ... }, "accounts_receivable":{ "life_cycle_state": "ACTIVE", "number": "400", "name": "John Doe", "id": "123456789" "account_owner":{ "name": "John Doe", "first_name": "John" "last_name": "Doe", "life_cycle_state": "FINANCIAL", "title": "Mr", "type": "PERSON", ... }, ... } }, "status":{ "message": null, "description": null, "code": "OK" } }	After Customer Identification
Step 2 - Preview Award and Spend Information (Optional)
No	Description	Web API Example	POS Conceptual Examples
1	Prior completing the sales transaction on POS, customer may request to know their available balance and the amount that are eligible to spend on the related transaction. In addition, the preview method will determine whether the purchase customer event that will be submitted can be redeemed by the Front-End System (i.e. POS) or by a Back-End System Previewing such information should be performed using the POST customer_events/purchases/preview method, and the following information should be passed to CRM.COM The related customer (accounts_receivable_identifier) The sales transaction's reference number (reference_number) The sales transaction's date (performed_on) The sales transaction's merchant (performed_by_unit_identifier) The sales transaction's items and the amount per each item (products_set)	POST Request https://hostname/crmapi/rest/v2/customer_events/purchases/preview Body Expand source { "token": "{{token}}", "rewards_participant_identifier":{ "access_token_identifier":{ "authentication_code": "22265577" } }, "reference_number": "REF0001", "performed_by_unit_identifier":{ "name" : "Unit" }, "performed_on": "2017-06-22T15:00:00", "products_set":[ { "product_identifier":{ "code": "Soft Drinks" }, "quantity": 1, "total_amount": 10, "net_amount": 8, "vat_amount": 2 }, { "product_identifier":{ "code":"Sandwiches" }, "quantity": 10, "total_amount": 20, "net_amount": 26, "vat_amount": 4 } ], "fields_set": "total_additional_spend_amount, total_automatic_spend_amount,reduction_method, total_instant_spend_amount, total_award_amount" }	Not Applicable
2	Once a customer is identified in CRM.COM, then the full information of the customer is returned The following information can be displayed on the POS screen The name of the customer (accounts_receivable.account_owner.name) The available balance of the customer's wallet (wallet.balance)	Response Expand source { "data":{ "total_additional_spend_amount": 7.9, "total_automatic_spend_amount": 0, "total_instant_spend_amount": 0, "total_award_amount": 0.08, "reduction_method": "FRONT_END_REDUCTION" }, "status":{ "message": null, "description": null, "code": "OK" } }	After Preview
Step 3 - Submitting Sales Transaction for Awarding Customer
No	Description	Web API Example	POS Conceptual Example
1	Once all products are registered in the POS, the sales transaction should be submitted in CRM.COM in the form of a purchase customer event. Creating such customer event, CRM.COM will validate whether the purchased items are eligible to be awarded by a reward offer and credit the customer's wallet balance Submitting a purchase event in CRM.COM should be performed using the POST customer_events/purchases/create method, and capture the following information The related customer (accounts_receivable_identifier) The sales transaction's reference number (reference_number) The sales transaction's date (performed_on) The sales transaction's merchant (performed_by_unit_identifier) The sales transaction's items and the amount per each item (products_set) Whether the customer event should be processed immediately, depending various business processes or not (process_immediately) - in most cases processing is immediately Optionally, the identifier of the POS can be specified (external_system) Products should already exist in CRM.COM in order for the POS to make transactions for them. In the event that a POS integration requires to perform transactions for such items, CRM.COM provides the ability to allow such transaction submission using a default product (everything is handled by CRM.COM without additional changes from the POS system)	POST Request https://hostname/crmapi/rest/v2/customer_events/purchases/create Body Expand source { "token": "{{token}}", "accounts_receivable_identifier":{ "number": "001" }, "performed_by_unit_identifier":{ "name":"Unit" }, "performed_on":"2017-05-22T16:05:00", "process_immediately": true, "external_system": "POSID01", "reference_number":"REF00001", "products_set":[ { "product_identifier":{ "code": "Soft Drinks" }, "quantity": 1, "total_amount": 10, "net_amount": 8, "vat_amount": 2 }, { "product_identifier":{ "code": "Sandwiches" }, "quantity": 4, "total_amount": 10, "net_amount": 8, "vat_amount": 2 } ], "fields_set":"number,total_awarded_amount,reference_number" }	Not Applicable
2	Once the sales transaction submission is performed (purchase customer event creation), the POS system can proceed to the redemption step The following information can be displayed on the POS screen The amount that was awarded from the purchase (total_award_amount) The amount that was automatically spend from the purchase (total_spend_amount) The available balance of the customer's wallet after the purchase (initial wallet balance + total_award_amount - total_spend_amount)	Response Expand source { "data":{ "number": "111", "total_awarded_amount": 20, "reference_number": "REF00001" }, "status":{ "message": null, "description": null, "code": "OK" } }	After Customer is Awarded
Step 4 - Redeeming Awarded Amount
No	Description	Web API Example	POS Conceptual Example
1	Customer may want to spend some of the available wallet amount on the previously created transaction, submitting a spend customer event in CRM.COM The following information can be displayed on the POS spend request form The amount that can be requested to be spent on that transaction (total_additional_spend_amount) The minimum spend amount allowed to be spend per transaction (minimum_spend_amount_per_transaction) The maximum spend amount allowed to be spend per transaction (maximum_spend_amount_per_transaction) Submitting a spend request in CRM.COM should be performed using the POST customer_events/spend_requests/create method, and capture the following information The related customer (accounts_receivable_identifier) The related purchase customer event that was created above (purchase_customer_request_identifier) The amount that is requested to be spend (spend_amount) The sales transaction's date (performed_on) The sales transaction's merchant (performed_by_unit_identifier) Whether the customer event should be processed immediately, depending various business processes or not (process_immediately) - in most cases processing is immediately Optionally, the identifier of the POS can be specified (external_system)	POST Request https://hostname/crmapi/rest/v2/customer_events/spend_requests/create Body Expand source { "token": "{{token}}", "accounts_receivable_identifier":{ "number": "001" }, "performed_by_unit_identifier":{ "name": "Unit" }, "performed_on": "2017-05-12T11:41:00", "external_system": "POSID01", "process_immediately": true, "spend_amount": 10, "purchase_customer_request_identifier":{ "number": "936" }, "fields_set":"number, spend_amount, reduction_method, spend_reward_transaction" }	Spend Request Form
2	Once the spend request is performed, it will return back the actual amount that was spent, which might be different than the amount that was requested to be spend The following information will be used in the next step of reducing and closing the sales transactions The actual amount that was spent (spend_reward_transaction.total_amount)	Response Expand source { "data":{ "number": "294", "spend_amount": 10, "reduction_method": "FRONT_END_REDUCTION", "spend_reward_transaction":{ "number": "205", "total_number": 7.9, "net_amount": 7.9, "vat_amount": 0, "life_cycle_state": "POSTED", ... } }, "status":{ "message": null, "description": null, "code": "OK" } }	After Spend Request
Step 5 - Closing the sales transaction
No	Description	Web API Example	POS Conceptual Example
1	Once the sales transaction (purchase customer event) and spend transaction (spend request customer event) are submitted successfully , then the POS system can calculate the redemption amount, reduce it from the total amount of the sales transactions, and close the sales transaction with the customer's payment The redemption amount is calculated as the sum of the following attributes The actual amount that was spent (spend_reward_transaction.total_amount), as retrieved from the "spend_request/create" method, and The amount that was spent automatically, which is the total_spend_amount as retrieved by the "purchases/create" method or from the sum of total_instant_spend_amount, total_additional_spend_amount and total_automatic_spend_amount as retrieved from the "purchases/preview" method The total_spend_amount is also the sum of total_instant_spend_amount, total_additional_spend_amount and total_automatic_spend_amount as retrieved by the "purchases/create" (all these three values are retrieved from the same method as well) The calculated redemption amount is deducted from the POS sales transaction by applying a discount on the sales transaction Upon completion, the following information is displayed and printed on the customer's receipt The amount that was awarded from the purchase (total_award_amount retrieved by the "purchases/preview" or "purchases/create") The wallet balance after the purchase. The new balance is calculated as the wallet's initial balance + awarded amount - redemption amount	Not Applicable	Receipt

Product Synchronization Flow

The flow described below is an example of synchronizing products from a POS system into CRM.COM

Product Synchronization can be achieved using existing CRM.COM Web API methods, where product information (as described previously) can be passed through a product parameter set

The maximum number of products that can be synchronized per call is 1,000

Step 1 - Synchronize Products

No

Description

Web API Example

POS Conceptual Examples

1

Product synchronization on a POS system can implemented as a batch process that is performed on a repeated basis (i.e. every day at 2 am), where product information is sent to CRM.COM

Submitting a product synchronization request in CRM.COM should be performed using the POST products/synchronise method, and capture the following information

The product synchronization definition that describes how the products information from the POS system will be handled by CRM.COM (synchronisation_definition_identifier)
The POS products and their related attributes (code, description, family, brand, categories, etc) per each product (products_set)

The maximum number of products that can be synchronized per call is 1,000

POST Request

https://hostname/crmapi/rest/v2/products/synchronise

Body

{
	"token": "{{token}}",
	"synchronisation_definition_identifier":{
		"alternative_code": "Product_Sync"
	},

	"products_set":[
		{
			"code" : "Orange Cookie",
			"alternative_code" : "10021",
			"description":"Cookie with orange cream",
		},
		{
			"code" : "Iced Caramel Latte",
			"alternative_code" : "20071",
			"description":"Latte with caramel syrup",
			"family_identifier" :{
				"code" : "Iced Coffee"
			}
		}
	],

	"fields_set":"unprocessed_products_set,processed_products_set"
}

Not Applicable

2

Once the product synchronization request is submitted and upon completion processing from the CRM.COM, the following information is returned (and handled accordingly by the POS system)

The products that were not processed by CRM.COM due to an error was thrown (unprocessed_products_set)
The products that were processed successfully by CRM.COM (unprocessed_products_set)

Response

{
	"data": {
		"unprocessed_products_set": [
			{
				"error_description": "Error:Product Family (Iced Coffee) Not Found. - Description:The specified API value was not found.",
				"error_code": "NotFoundAPIValueException",
				"request_code": "Iced Caramel Latte"
			}
		],
		"processed_products_set": [
			{
				"code": "Orange Cookie",
				"request_code": "Orange Cookie",
				"id": "E15E0F60F5D147B28C8FD50ADE4E0116"
			}
		]
	},
	"status":{
		"message": null,
		"description": null,
		"code": "OK"
	}
}

Not Applicable

Additional Documentation

Visit CRM.COM Manual in order to find more information related to the areas / concepts mentioned in above scenarios

Module	Description	Manuals' Link
Rewards Participant	Manage the customers who have signed up for Rewards or have been automatically selected to participate	Managing Rewards Participants
Rewards Offers	Reward Offers are used to Define a financial amount to be awarded to Rewards Participants, based on their actions Define the conditions for an Award to be given Define the conditions that should be met for the awarded amount to be spent	Managing Rewards Offers
Purchase Customer Events	Events linked with the purchase of goods	Purchase Customer Event
Spend Request Customer Events	Events linked with the spending of awarded amount	Spend Request Customer Event
Access Tokens	Access Tokens are used to identify and authenticate customers	Managing Access Tokens
Products	Products are goods that used by business transactions in the System	Managing Products

Integrating POS Systems v2

Getting Started

CRM.COM Rewards & POS Ecosystem

What is CRM.COM Rewards?

What is Point of Sale software?

Key Definitions

How to integrate your POS system to CRM.COM

CRM.COM & POS Product Synchronization

What is a CRM.COM Product?

Product Type

Product Brand

Product Family

Product Categories

How Product Synchronization between POS and CRM.COM works

Before you begin

Authentication

Using Fields Set

Using Pagination

Integration Scenarios

Purchase and Spend Award Flow

Step 1 - Customer Identification

Step 2 - Preview Award and Spend Information (Optional)

Step 3 - Submitting Sales Transaction for Awarding Customer

Step 4 - Redeeming Awarded Amount

Step 5 - Closing the sales transaction

Product Synchronization Flow

Step 1 - Synchronize Products

Additional Documentation