Panel

name	blue

Table of Contents

...

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)

Code Block

title	POST Request

https://hostname/crmapi/rest/v2/customer_events/purchases/preview

Code Block

title	Body
linenumbers	true

{
	"token": "{{token}}",
	"rewards_participant_identifier":{
		"access_token_identifier":{
			"authentication_code": "test@crm.com"
		}
	},


	"reference_number": "Ref101",
	"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)

Code Block

title	Response
linenumbers	true

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

...

No

Description

Web API Example

POS Conceptual Examples

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)

Note
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)

Code Block

title	POST Request

https://hostname/crmapi/rest/v2/customer_events/purchases/create

Code Block

title	Body
linenumbers	true

{
	"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_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

Code Block

title	Response
linenumbers	true

{
	"data":{
		"number": "111",
		"total_amount": 20,
		"reference_number": "REF00001"
	},
	"status":{
		"message": null,
		"description": null,
		"code": "OK"
	}
}

After Customer Identification

...

No

Description

Web API Example

POS Conceptual Examples

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)

Code Block

title	POST Request

https://hostname/crmapi/rest/v2/customer_events/spend_requests/create

Code Block

title	Body
linenumbers	true

{
	"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)

Code Block

title	Response
linenumbers	true

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

...

No

Description

Web API Example

POS Conceptual Examples

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

Note
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 that 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

Code Block

title	POST Request

Not Applicable

Receipt

Image RemovedImage Added

Anchor
additional_doc
additional_doc
Additional Documentation

...

Version	Old Version 8	New Version 9
Changes made by	Joseph Ioannou (Unlicensed)	Joseph Ioannou (Unlicensed)
Saved on	Dec 13, 2018	Dec 13, 2018

Versions Compared

Key

Anchor
additional_doc
additional_doc
Additional Documentation

Page Comparison

Versions Compared

Key

Anchoradditional_docadditional_docAdditional Documentation

Anchor
additional_doc
additional_doc
Additional Documentation