POS and eCommerce Systems
A new updated version will be released when either new flows are introduced to cover market needs or (rarely) backwards-incompatible changes are made to the API. Currently, you are viewing docs for CRM.COM & POS Integrators v1, released on June 20, 2020.
What is Point of Sale?
Point of Sale (POS) 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.
What is CRM.COM?
CRM.COM is a rewards platform that awards loyal customers via a broad range of reward offers. Each offer defines a goal that customers should reach in order to earn an award in the form of cashback, conditional or not, that can be spent on specific products, locations or days/hours. Customers can spend their awards either on request, or by setting auto-spend preferences or as part of an instant discount.
The reduction method defines how the amount requested to be spent by the customer will be reduced from the total amount that should be paid in a single purchase transaction. CRM.COM supports the following reduction methods
- Front-End Reduction: The front-end system (POS) is responsible to reduce the amount of money that the consumer should actually pay by the amount to be spent.
- Back-End Reduction: A back-end system (e.g. PayPal) is responsible to reduce such amount of money, by letting the customer to pay the full transaction amount and credit him through a payment gateway system the reduced amount.
In the context of Rewards, the reduction method may vary per merchant and the decision falls under each POS integration to decide whether front-end or back-end reduction should take place.
Transaction Acquiring
On checkout, the POS simply submits the purchase transaction to CRM.COM and optionally indicates a spend amount.
Void Transaction
On voiding an existing transaction, the POS simply submits the purchase transaction that should be voided to CRM.COM.
Ad Hoc Return of Goods
On refunding a number of returned products (without knowing the iniital purchase transaction number), the POS simply submits the amount of money for such products to CRM.COM.
Product Synchronization
Product Synchronization provides the ability for the POS system to create or update a group of products into CRM.COM. Synchronization can be achieved either real-time during the transaction acquiring (creating product skus or product families that do not exist in CRM.COM) or offline, where the POS system will be able to create new or update existing product skus, families and brands in the CRM.COM.
The following sections cover in detail the main CRM.COM & POS integration flows.
- On checkout, the customer is asked if he desires to spend any of his available CRM.COM wallet balance
- The itemized POS sales transaction (or optionally the transaction total) is submitted to CRM.COM, along with a customer’s identification mean (e.g. card number) and requested spend amount (ref. Submit Purchase - Example 7)
- The payment is completed by collecting the full amount for the purchased products
- Customer is awarded and gets notified via the APP. The spend amount is credited to the customer’s designated card or bank account by an external payment gateway system (integrated with CRM.COM)
Please follow the following link for a quick demonstration of the Front-End Reduction POS Flow Examples
Customer Identification
- On checkout, the customer is asked if he desires to spend any his available CRM.COM wallet balance
- The itemized POS sales transaction (or optionally the transaction total) is submitted to CRM.COM, along with a customer’s identification mean (e.g. card number) and requested spend amount (ref. Submit Purchase - Example 2)
- Customer is awarded and spend amount is calculated real-time based on purchased products
- The spend amount is deducted from the amount to pay by the POS system, either as a discount (before VAT) or as a payment method (after VAT)
Customer Self-Service Identification
- On checkout, the itemized POS sales transaction (or optionally the transaction total) is submitted to CRM.COM, without any customer identification action taking place (ref. Submit Purchase - Example 5)
- The POS generates a QR code based on the purchase and organisation identifier (semicolon separated). Such QR code is printed on the POS receipt
- Customers via their mobile app scan the QR code from the receipt and they get awarded (no spend is triggered)
QR codes are valid for 72 hours
Customer Self-Service Spend
- Prior to checkout, customers request an OTP via their mobile app to spend (including optionally a spend amount - if not specified, all available wallet amount can be spent)
- On checkout, customers are prompted if they want to spend by providing an OTP
- The itemised POS sales transaction is submitted to CRM (including the OTP) (ref. Submit Purchase - Example 6)
- Customer is awarded and spend amount is calculated real-time based on purchased products
- The spend amount is deducted from the amount to pay by the POS system, either as a discount (before VAT) or as a payment method (after VAT)
- The POS agent selects the purchase that needs to be voided
- On confirming such action, the void purchase is submitted to CRM.COM (ref. Void Purchase)
- CRM.COM responds back, confirming the completion of such action
- The purchase and all corresponding awards will be reversed by CRM.COM
- The POS agent submits an ad hoc return of goods to CRM.COM (ref. Ad Hoc Return of Goods)
- CRM.COM responds back, confirming the completion of such action
- An amount proportional to the return amount, purchase transaction total amount and awarded amount on that purchase will be debited from the customer’s wallet in CRM.COM
Order Provisioning using CRM.COM Webhooks
- Customer submits an order to CRM.COM
- CRM.COM fires a single webhook request with the customer’s order details over to the POS system
- POS system responds back, confirming the receival of such request
- A sales transaction (based on the received order information) is created in the POS
Order Provisioning using POS Adaptors
- Customer submits an order to CRM.COM
- CRM.COM creates a sales transaction over to the POS system (CRM.COM is integrated with the POS system, consuming its APIs)
- POS system responds back, confirming the creation of such sales transaction
Order Provisioning using POS Adaptors is supported only for MICROS Simphony and Twinsoft
- The POS system requests to perform product synchronization over to CRM.COM (ref. Synchronise Products)
- CRM.COM responds back, confirming the receival of such request
- Imported products, families, brands and categories are created or updated into CRM.COM
Product synchronization on a POS system can be implemented as a batch process that is performed on a repeated basis (e.g. every day at 02:00), where product information is sent to CRM.COM
If your business model supports ordering, then via our product synchronization API you can update for each imported product its pricing, variants and components
The following sections include reference materials to aid POS system’s developers for integrating any POS system with CRM.COM platform.
Application Programming Interface
CRM.COM API is designed around REST, allowing you to access and extend the software’s current functionality in a simple, programmatic way using intuitive URL endpoints, conventional HTTP requests and response codes, like most external system integrations. CRM.COM BackOffice API is recommended.
Authentication
CRM.COM BackOffice API uses either API keys to authenticate requests (recommended) or an authentication JWT token obtained from a user successful logging in.
API keys can be accessed and managed in the CRM.COM Dashboard. Such API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas.
All API requests must be made over HTTPS. API requests made over plain HTTP or without authentication will fail.
{id}{id}/loyalty_identifiers{id}/financials{id}/rewardsRetrieves the list of contacts (can be filtered based on contact attributes)
Request parameters
The value of the search across Full Name, Company Name and Contact Code (case insensitive)
The full name of contact. Applicable only when searching for physical persons
The name of the company. Applicable only when searching for companies
The contact’s unique code
The contact’s email address
The contact’s phone number
The contact’s loyalty identifier
The customer identification medium
Filters contacts based on the country code that the contact agreed to registered to
If set to true then information about the primary account and wallet will be also retrieved
Defines on which attribute the results should be sorted
Defines how the results will be ordered
The page number that should be retrieved
The size (total records) of each page
Request headers
The secret api key required for API calls to ensure that the client is trusted
Responses
The request has succeeded
Body
The contact identifier
The contact code
The contact type
The contact full name
The contact’s email address
Details about contact phones
The phone identifier
The phone type
Defines whether the phone is the primary one
The phone country code
The phone number
The contact’s loyalty identifiers (e.g. cards)
The unique identifier of the loyalty identifier (CIM)
The loyalty identifier
Details about the contact’s financials
Details about the account
The account identifier
The account number
The account currency (code)
Defines whether the account is the primary one
The account life cycle state
Details about the wallet
The wallet identifier
The wallet code
The wallet life cycle state
The wallet currency (code)
The page number
The number of records per page
The overal number of records
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
GET /customers?include_financials=true&code=C0123456 HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
HTTP/1.1 200 OK
Content-Type: application/json
{
"content": [
{
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"code": "ABC-123",
"contact_type": "COMPANY",
"contact_name": "John CRM Doe",
"email_address": "johndoe@crm.com",
"phones": [
{
"id": "60bcca96-4965-4d56-8341-cb6f5ae61803",
"phone_type": "MOBILE",
"is_primary": "true",
"country_code": "357",
"number": "99999999"
}
],
"loyalty_identifiers": [
{
"id": "e172cdd1-41f4-47ec-717e-2c3733afb19f",
"identifier": "1478521478521"
}
],
"financials": [
{
"accoun": {
"id": "6d595a01-3c39-2a00-ffd5-9a10a55c3bf9",
"number": "A1234",
"currency_code": "EUR",
"is_primary": "true",
"life_cycle_state": "ACTIVE"
},
"wallet": {
"id": "6d595a01-3c39-2a00-ffd5-9a10a55c3bf9",
"name": "W1234",
"life_cycle_state": "",
"currency_code": "EFFECTIVE"
}
}
]
}
],
"paging": {
"page": 2,
"size": 20,
"total": 5124
}
}{id}Get details for a specific contact
Path variables
The contact identifier that should be returned
Request headers
The secret api key required for API calls to ensure that the client is trusted
Responses
The request has succeeded
Body
The contact identifier
The contact’s unique code
Type of contact support types include Person and Company.
The name of the company if the contact type is COMPANY
The title of the contact. Applicable only if the type is PERSON
The first name of the contact. Applicable and mandatory only if the type is PERSON
The middle name of the contact. Applicable and mandatory only if the type is PERSON
The last name of the contact. Applicable and mandatory only if the type is PERSON
The full name of the contact (takes into consideration the name display settings)
The contact’s email
The contact’s preferred language for communication
Notes for the contact
The contact’s unique statutory code
Defines whether the contact is Tax Exempt or not
Details about the contact category
The category identifier
The category name
Details about the contact’s dmographic information (applicable for PERSON contects)
The contact gender
The contact’s country of residence
Details about the contact’s passport
The passport number
The issue country for the passport
The expiration date for the passport
Details about the ID (applicable for PERSON contects)
The ID number
The country that issued such ID
The expiration date for the ID
Details about the contact nameday (applicable for PERSON contects)
The nameday month
The nameday day
Details about the contact birthday (applicable for PERSON contects)
The year of birth
The month of birth
The day of birth
Details about the addresses
The address identifier
The address type
Defines whether the address is primary or not
The address of care of
The address line 1
The address line 2
The address state/province/county
The address town/city
The address postal code
The address country
The latitude of the address
The longitude of the address
The Google textual identifier that uniquely identifies an address
Details about the phones
The phone identifier
The phone type
Defines whether the phone is the primary one
The phone country code
The phone number
The contact’s consent state
Defines whether the contact is anonymized
The contact’s interaction status, retrieved from REDIS
The contact’s total spend amount in the last 12 months, retrieved from REDIS
Defines whether the SMS communication will be opt out
Defines whether the EMAIL communication will be opt out
Details about the KYC profile
The KYC profile identifier
The name of the KYC profile
The status of the KYC profile assigned to Contact
The contact referral code
The contact’s loyalty identifiers (e.g. cards)
The unique identifier of the loyalty identifier (CIM)
The loyalty identifier
The custom field’s unique key
The custom field’s value
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
GET /contacts/CAD1E31269B76D7A65ACCE45B2E68DFD HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"code": "ABC-123",
"contact_type": "PERSON",
"company_name": "Louis Kozior",
"title": "Sir",
"first_name": "Louis",
"middle_name": "Aloz",
"last_name": "Kozior",
"contact_name": "Louis Aloz Kozior",
"preferred_language_code": "ENG",
"category": {
"id": "8a317250-8076-24ea-6fa3-63812679e552",
"name": "Category A"
},
"demographics": {
"gender": "FEMALE",
"country_of_residence": "CY",
"passport": {
"passport_number": "PASS1234",
"issue_country_code": "GRC",
"expiration_date": 129876567
},
"id_details": {
"id_number": "ID1234",
"issue_country_code": "CYP",
"expiration_date": 129876567
},
"name_day": {
"month": 10,
"day": 4
},
"date_of_birth": {
"year": 2018,
"month": 10,
"day": "16"
}
}
}{id}/loyalty_identifiersRetrieve the loyalty identifiers (e.g. loyalty card) for a specific contact
Path variables
The contact identifier that should be returned
Request headers
The secret api key required for API calls to ensure that the client is trusted
Responses
The request has succeeded
Body
The unique identifier of the loyalty identifier (CIM)
The loyalty identifier of the customer
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
GET /contacts/CAD1E31269B76D7A65ACCE45B2E68DFD/loyalty_identifiers HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
HTTP/1.1 200 OK
Content-Type: application/json
{
"content": [
{
"id": "1adaae9e-6dbb-f389-e5d0-8288f0c87a62",
"identifier": "2143454566754"
}
]
}{id}/financialsGet a single account, along with its financial details
Path variables
The account identifier whose financial details will be retrieved
Responses
OK
Body
The account’s name
The account’s number
Defines whether the account is the primary one of the contact
The account’s life cycle state
The account’s currency (3 code currency)
The account’s calculated balance
The unpaid amount that is passed its due date
The account’s credit limit
The ID of the latest closed accounting period
The name of the account’s latest accounting period
The opening balance brought forwards after the latest closed accounting period
The unique identifier of the Account classification
The name of the Account classification
The account’s wallet information (if available)
The wallet’s unique identifier
A unique 16-digit code that if not provided, it is auto-generated
The total balance of the wallet
The commerce balance of the wallet
The open balance of the wallet
The wallet’s life cycle state
The minimum wallet balance threshold. If not provided, the global rules apply
Defines the limit rules applied on specific wallet. If not provided, the global rules apply
The minimum amount allowed
The maximum amount allowed
The period for which the limit is applied
The wallet transaction type for which the limit is applied
Details about auto-topup details
Sets the threshold for the auto topup to be performed
The amount to get topped up
Indicates the method of collecting money
The contact’s actual preferred payment method. Required and mandatory only for online payments (Card, Wallet, PayPal and Account). Defaults to the primary payment method, if any.
Details about the billing address
The address identifier
The address line 1
The address line 2
The address state/province/county
The address town/city
The address postal code
The address country code
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
GET /accounts/4AD9C84FA60F9FE407140E20F707726A/financials HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
HTTP/1.1 200 OK
Content-Type: application/json
{
"name": "John Smith AC00123456",
"number": "AC00123456",
"wallet": [
{
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"code": "W00123456",
"balance": 150.5,
"commerce_balance": 98,
"open_balance": 1,
"life_cycle_state": "EFFECTIVE"
}
]
}{id}/rewardsGet a single account, along with its reward details
Path variables
The account identifier whose details will be retrieved
Request headers
The secret api key required for API calls to ensure that the client is trusted
Responses
OK
Body
The account identifier
The account’s name
The account’s number
The account’s currency (3 code currency)
The date when the account was signed up for the first time
Information about the organisation that sign up the account for the first time
The organisation identifier
The organisation name
Defines whether the account can spend or not
The date that the spending status of the account was updated
Information about the user that updated the spending status of the account
The user identifier
The user’s email address
The user’s first name
The user’s last name
Information about the automatic spend settings for the account
Defines whether automatic spend is enabled for the account
Defines whether automatic spends will occur on the next purchase of a specific merchant or based on wallet balance and purchase amount to a group of merchants
The minimum wallet balance amount that should be available for the spend to be performed. Applicable when automatic spend preference is for all merchant purchases
The min amount (inclusive) that the purchase customer event total amount should be in order for the automatic spend to be applied. Applicable when automatic spend preference is for all merchant purchases
Information about the merchants that automatic spending is allowed
The merchant record identifier
Defines whether the merchant is setup for automatic spend on the next visit
Information about organisation
The organisation identifier
The organisation name
Information about the account’s reward tier
The reward tier identifier
The reward tier name
The designated hexadecimal code of the tier’s color
The account’s value units that accumulated during the last rolling period
The account’s value units that accumulated overall
The progression percentage until the next reward tier is reached
Information about the reward schemes that the account has signed up to
The reward scheme identifier
The reward scheme name
The date when the account was signed up on the specific reward scheme
The email address that was used during sign up (applicable if the reward scheme is a close loop scheme based on email domains)
Defines how customers can sign up to the reward scheme
The customer’s preferred payment method identifier that will be used for spending purposes for back-end reduction rewards (applicable payment methods are direct debit and credit cards related)
The preferred payment method identifier
The customer’s preferred payment method identifier that will be used for spending purposes
The first six digits of the card (applicable only if the payment method type is card based)
The last four digits of the card (applicable only if the payment method type is card based)
The bank’s iban (applicable only if the payment method type is direct debit based)
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
GET /accounts/4AD9C84FA60F9FE407140E20F707726A/rewards HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"name": "John Smith AC00123456",
"number": "AC00123456",
"currency_code": "EUR",
"reward_tier": {
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"name": "Gold",
"color": "#d4af37",
"period_value_units": 222,
"lifetime_value_units": 333,
"next_tier_progression": 45.98
}
}{id}/cancelA supplementary API that enables the POS agents to search through existing purchases, either based on contact or specific purchase attributes
Request parameters
The contact identifier who performed the purchase
The purchase’s reference number
The date from which the purchase was performed.If not specified, then the last 10 purchases will be returned
The date until which the purchase was performed
The life cycle state of the customer event
The organisation that the purchase customer event was performed
The transaction acquiring point that captured the customer event
Filters customer events that have greater or equal total amount as specified
Filters customer events that have less or equal total amount as specified
Defines on which attribute the results should be sorted
Defines how the results will be ordered
The page number that should be retrieved
The size (total records) of each page
Request headers
Responses
The request has succeeded
Body
The purchase identifier (POS based)
The purchase unique referene number (can be the same as the POS based identifier or a unique transaction number if it’s supported)
Contact details
The contact identifier
The contact full name
The contact code
Account details
The account identifier
The account name
The account number
The purchase’s life cycle state
The reduction method that was applied on the related spend
The purchase event’s classification details
The classification identifier
The classification name
The purchase’s total net amount of all products’ net amount
The purchase’s total tax amount of all products’ tax amount
The purchase’s discount amount
The purchase’s total amount after discount
The organisation details at which the purchase was performed
The organisation identifier at which the purchase was performed
The organisation name at which the purchase was performed
The date on which the purchase was performed
The page number
The number of records per page
The overal number of records
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
GET /purchases HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
HTTP/1.1 200 OK
Content-Type: application/json
{
"content": [
{
"id": "CEEE83D6E0804A30966F684B0269AD91",
"reference_number": "REF1234",
"contact": {
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"name": "John Doe",
"code": "CO1234"
},
"account": {
"id": "CEEE83D6E0804A30966F684B0269AD91",
"name": "ACR1234 John Doe",
"number": "ACR1234"
},
"life_cycle_state": "POSTED",
"reduction_method": "BACK_END",
"classification": {
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD",
"name": "Delivery"
},
"total_net_amount": 1.51,
"total_tax_amount": 0.49,
"discount_amount": 1,
"total_amount": 1,
"organisation": {
"id": "CEEE83D6E0804A30966F684B0269AD91",
"name": "Bravo Coffee"
},
"performed_on": 1576486645
}
],
"paging": {
"page": 2,
"size": 20,
"total": 5124
}
}Create a purchase customer event into CRM.COM (in posted state) based on the submitted POS purchase transaction
Request headers
The secret api key required for API calls to ensure that the client is trusted
Request body
The purchase Identifier (POS based)
The contact identifier that the purchase is created for
The value for a single contact identification medium representing the customer that the purchase is created for
The OTP token that will identify the contact who requested to spend (applicable on Customer Self Service Identification/Spend)
The purchase unique referene number (can be the same as the POS based identifier or a unique transaction number if it’s supported)
The unique identifier of the payment medium used in the purchase (e.g. the first 8 digits of a credit card)
The date that the customer event was performed (if not specified, default to date of posting such purchase)
Defines the reduction method that will be applied on spend
The purchased products (either products object or explicit net/tax/total amounts should be provided)
The purchased product sku family (either product sku or product famly should be speciifed)
The purchased product name (will be used on online product sync)
The purchase product family (either product sku or product famly should be speciifed)
The purchased product net amount
The purchased product vat amount
The purchased product total amount (net and vat amount)
The purchased product quantity
Information related with the ad-hoc spend request that should be created as part of the purchase
The amount to be spent by the specified spend request in system currency
Details about the merchant’s point on which the purchase is made
The merchant transaction acquiring point identifier (either tap id or code should be provided)
The merchant transaction acquiring point code (either tap id or code should be provided)
Details about the merchant’s outlet point on which the purchase is made
The outlet transaction acquiring point identifier (either tap id or code should be provided)
The outlet transaction acquiring point code (either tap id or code should be provided)
The discount of the purchase
The purchase net amount. Applicable when no products (sku/family) are provided
The purchase tax amount. Applicable when no products (sku/family) are provided
The purchase total amount (net + tax - discount). Applicable when no products (sku/family) are provided
Details about the customer event classification
The customer event classification identifier
The customer event classification name
Details about the pass
The pass code
The pass one time password (if applicable)
Responses
The request has succeeded
Body
The purchase identifier
The purchase reference number (applicable only for Front-End Reduction)
The total award amount (applicable only for Front-End Reduction)
The sum of all spends (instant discount, auto spends, spends on request). Applicable only for Front End Reduction
The spend related to instant discount. Applicable only for Front End Reduction
The spend related to auto spend requests. Applicable only for Front End Reduction
The actual spend related to requested spend requests. Applicable only for Front End Reduction
The wallet’s open balance amount that was spent. Applicable only for Front End Reduction
The wallet’s commerce balance amount that was spent. Applicable only for Front End Reduction
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
Create a purchase event of classification Delivery with spend request and pass code redemption
POST https://sandbox.crm.com/backoffice/v1/purchases HTTP/1.1
api_key: adea79a6-fe7f-2e92-56c7-9a0685ffa290
Content-Type: application/json
{
"id": "b2fbaa45-af26-4dba-b866-546a26dee1f9",
"reference_number": "O00123",
"contact_id": "acd11adc-51cc-5d41-f1dd-f625a18b3ff3",
"reduction_method": "FRONT_END",
"products": [
{
"product_sku": "10023401",
"product_name": "Soda",
"net_amount": 1.00,
"tax_amount": 0.02,
"total_amount": 1.02,
"quantity": 1
},
{
"product_sku": "20057809",
"product_name": "Caramel Donut",
"net_amount": 10.00,
"tax_amount": 0.19,
"total_amount": 10.19,
"quantity": 10
}
],
"classification": {
"name": "Delivery"
},
"spend_request": {
"amount": 1.21
},
"pass": {
"code": 1234
},
"outlet_tap": {
"code": "8239"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "b2fbaa45-af26-4dba-b866-546a26dee1f9",
"reference_number": "RF123",
"total_award": 1.4,
"total_spend": 1.21,
"instant_discount": 0.21,
"auto_spend": null,
"spend_on_request": 1.00,
"total_open_spend": 1.12,
"total_commerce_spend": 0.09
}Submit Front-End Reduction Purchase (product sku only, spend request)
POST /purchases HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json
{
"id": "RF000001",
"contact_id": "f7aa324c-9670-43dd-6e1e-d5ee7e044168",
"reduction_method": "FRONT_END",
"products": [
{
"product_sku": "FREDESPR001",
"product_name": "Freddo Espresso",
"net_amount": 4.15,
"tax_amount": 1.04,
"total_amount": 5.19,
"quantity": 2
},
{
"product_sku": "ICL0001",
"product_name": "Iced Caramel Latte",
"net_amount": 5.15,
"tax_amount": 1.04,
"total_amount": 6.19,
"quantity": 1
}
],
"merchant_tap": {
"code": "EK123456"
},
"outlet_tap": {
"code": "CD123456"
},
"spend_request": {
"amount": 2.12
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "RF000001",
"reference_number": "RF000001"
"total_award": 0.54,
"total_spend": 1.72,
"instant_discount": 0.21,
"auto_spend": 1.51,
"spend_on_request": 0.00
}Submit Front-End Reduction (product sku only, spend request & discount on total transaction)
POST /purchases HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json
{
"id": "RF000001",
"contact_id": "f7aa324c-9670-43dd-6e1e-d5ee7e044168",
"reference_number": "RF000001",
"reduction_method": "FRONT_END",
"products": [
{
"product_sku": "FREDESPR001",
"product_name": "Freddo Espresso",
"net_amount": 4.15,
"tax_amount": 1.04,
"total_amount": 5.19,
"quantity": 2
},
{
"product_sku": "ICL0001",
"product_name": "Iced Caramel Latte",
"net_amount": 5.15,
"tax_amount": 1.04,
"total_amount": 6.19,
"quantity": 1
}
],
"discount_amount": 1.56,
"merchant_tap": {
"code": "EK123456"
},
"outlet_tap": {
"code": "CD123456"
},
"spend_request": {
"amount": 2.12
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "RF000001",
"reference_number": "RF000001"
"total_award": 0.54,
"total_spend": 1.72,
"instant_discount": 0.21,
"auto_spend": 1.51,
"spend_on_request": 0.00
}Submit Front-End Reduction (product sku only, spend request, pass & discount on total transaction)
POST /purchases HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json
{
"id": "RF000001",
"contact_id": "f7aa324c-9670-43dd-6e1e-d5ee7e044168",
"reduction_method": "FRONT_END",
"products": [
{
"product_sku": "FREDESPR001",
"product_name": "Freddo Espresso",
"net_amount": 4.15,
"tax_amount": 1.04,
"total_amount": 5.19,
"quantity": 2
},
{
"product_sku": "ICL0001",
"product_name": "Iced Caramel Latte",
"net_amount": 5.15,
"tax_amount": 1.04,
"total_amount": 6.19,
"quantity": 1
}
],
"discount_amount": 1.56,
"merchant_tap": {
"code": "EK123456"
},
"outlet_tap": {
"code": "CD123456"
},
"pass": {
"code": "1231231231231231"
},
"spend_request": {
"amount": 2.12
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "RF000001",
"reference_number": "RF000001"
"total_award": 0.54,
"total_spend": 1.72,
"instant_discount": 0.21,
"auto_spend": 1.51,
"spend_on_request": 0.00
}Submit Front-End Reduction (no contact identification. product sku & discount on total transaction value)
POST /purchases HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json
{
"id": "191e36d5-2afc-3715-1b7c-5e38528c48b3",
"reduction_method": "FRONT_END",
"products": [
{
"product_sku": "FREDESPR001",
"product_name": "Freddo Espresso",
"net_amount": 4.15,
"tax_amount": 1.04,
"total_amount": 5.19,
"quantity": 2
},
{
"product_sku": "ICL0001",
"product_name": "Iced Caramel Latte",
"net_amount": 5.15,
"tax_amount": 1.04,
"total_amount": 6.19,
"quantity": 1
}
],
"discount_amount": 1.56,
"merchant_tap": {
"code": "EK123456"
},
"outlet_tap": {
"code": "CD123456"
},
"spend_request": {
"amount": 2.12
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "191e36d5-2afc-3715-1b7c-5e38528c48b3",
"reference_number": "RF000001"
}Submit Front-End Reduction (contact token, product sku & discount on total transaction value)
POST /purchases HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json
{
"id": "191e36d5-2afc-3715-1b7c-5e38528c48b3",
"contact_token": "123456",
"reduction_method": "FRONT_END",
"products": [
{
"product_sku": "FREDESPR001",
"product_name": "Freddo Espresso",
"net_amount": 4.15,
"tax_amount": 1.04,
"total_amount": 5.19,
"quantity": 2
},
{
"product_sku": "ICL0001",
"product_name": "Iced Caramel Latter",
"net_amount": 5.15,
"tax_amount": 1.04,
"total_amount": 6.19,
"quantity": 1
}
],
"discount_amount": 1.56,
"merchant_tap": {
"code": "EK123456"
},
"outlet_tap": {
"code": "CD123456"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "191e36d5-2afc-3715-1b7c-5e38528c48b3",
"reference_number": "RF000001",
"total_award": 0.54,
"total_spend": 1.72,
"instant_discount": 0.21,
"auto_spend": 1.51,
"spend_on_request": 0.00
}Submit Back-End Reduction Purchase (product sku and family)
POST /purchases HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json
{
"cim": "4A30966F684B0269AD91",
"reference_number": "RF000001",
"payment_medium_identifier": "42424242",
"performed_on": 1572423477,
"reduction_method": "FRONT_END",
"products": [
{
"product_sku": "FREDESPR001",
"product_name": "Freddo Espresso",
"net_amount": 4.15,
"tax_amount": 1.04,
"total_amount": 5.19,
"quantity": 2
},
{
"product_family": "Beverages",
"net_amount": 5.15,
"tax_amount": 1.04,
"total_amount": 6.19,
"quantity": 1
}
],
"merchant_tap": {
"code": "EK123456"
},
"outlet_tap": {
"code": "CD123456"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "CAD1E31269B76D7A65ACCE45B2E68DFD"
}Submit Back-End Reduction Purchase (total transaction)
POST /purchases HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json
{
"id": "CEEE83D6E0804A30966F684B0269AD91",
"cim": "4A30966F684B0269AD91",
"reference_number": "RF000001",
"payment_medium_identifier": "42424242",
"reduction_method": "BACK_END",
"merchant_tap": {
"code": "0000012"
},
"outlet_tap": {
"code": "0000012345"
},
"net_amount": 99.99,
"tax_amount": 1.00,
"total_amount": 100.99
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "ccca2889-301b-40ad-aed9-9c3a78e6e50b",
"reference_number": "RF123"
}{id}/cancelCancel an existing customer’s purchase and as a result any related awards/spends will be reversed
Path variables
The purchase identifier (POS based) that will be cancelled
Request headers
The secret api key required for API calls to ensure that the client is trusted
Responses
The request has succeeded
Body
The purchase identifier
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
POST https://sandbox.crm.com/backoffice/v1/purchases/ccca2889-301b-40ad-aed9-9c3a78e6e50b/cancel HTTP/1.1
api_key: adea79a6-fe7f-2e92-56c7-9a0685ffa290
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "ccca2889-301b-40ad-aed9-9c3a78e6e50b"
}Performs an ad hoc return of goods for a speciifc customer
Request headers
The secret api key required for API calls to ensure that the client is trusted
Request body
The contact identifier that the customer event is created for (either contact_id or cim must be specified)
The value for a single contact identification medium representing the customer event is created for (either contact_id or cim must be specified)
The currency code
The amount (real currency) of purchased goods that are returned
Details about the merchant that submits such transaction (either id or code should be specified)
The organisation (business/merchant) tap identifier
The organisation (business/merchant) tap code
Details about the venue that submits such transaction (either id or code should be specified)
The organisation (venue) tap identifier
The organisation (venue) tap code
Responses
The request has succeeded
Body
The purchase identifier that ad hoc return of goods is applied
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
POST /purchases/ad_hoc_return HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json
{
"cim": "4A30966F684B0269AD91",
"currency_code": "EUR",
"amount": 14.56,
"merchant_tap": {
"code": "EK123456"
},
"outlet_tap": {
"code": "CD123456"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "ccca2889-301b-40ad-aed9-9c3a78e6e50b"
}Create a new Topup for an Account or a Wallet
Request headers
The secret api key required for API calls to ensure that the client is trusted
Request body
The account (identifier) for which the top-up will be performed. Either account or wallet is applicable and mandatory
The wallet (identifier) for which the top-up will be performed. Either account or wallet is applicable and mandatory
The date of the top-up request
The top-up amount
Indicates the method of collecting money
The identifier of the actual payment method if any
A unique 16-digit code, will be auto-generated if not provided
Responses
OK
Body
The top-up identifier
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
POST https://sandbox.crm.com/backoffice/v1/topups HTTP/1.1
Content-Type: application/json
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
{
"wallet_id": "72c47daa-4b86-2d81-56e1-f61eb2264043",
"topup_date": 1618298816,
"amount": 19.99,
"payment_method": "CASH"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "2b98beb3-df11-f14d-561b-a93fcd4a246a"
}{id}{id}/actionsRetrieve a list of orders based on search criteria
Request parameters
Filters based on order number
Fitlers based on the order state
[
"NEW"
]Filter orders based on the organisation’s tap code that will fulfill such orders (tap should be active)
Filter orders based on created date
Returns results where the created date is greater than this value
Returns results where the created date is greater than or equal to this value
Returns results where the created date is less than this value
Returns results where the created date is less then or equal to this value
Defines on which attribute the results should be sorted
Defines how the results will be ordered
The page number that should be retrieved
The size (total records) of each page
Request headers
The secret api key required for API calls to ensure that the client is trusted
Responses
OK
Body
The order identifier
The order number
The order state
The order general notes
The order total number of milestones
The order supply method
The total number of items that were ordered
The total cost of all order items
The amount that was used from wallet funds
The amount due to be paid (total cost MINUS wallet funds)
Details about the (total) amount that was provided as discount
Total discount amount excluding taxes. This amount equals to the sum of all discount amounts among all invoiced items. Note that this amount does not include the taxed amount.
The total discount amount including taxes
The currency (code)
Details about the contact that placed the order
The contact identifier
The contact code
The contact name
The address line 1
The address line 2
The address state/province/county
The address town/city
The address postal code
The address country
The address of care of
The latitude of the address
The longitude of the address
The Google textual identifier that uniquely identifies an address
Details about the order category
The order category identifier
The order category name
Details why the order was cancelled
The cancellation reason identifier
The cancellation reason name
Details about the organisation that will carry through the order
The organisation identifier
The organisation name
Details about the order items
The order item identifier
The order item notes
The order item state
The order item quantity
Details about the order item product
The product identifier
The product SKU
The product name
The product quantity
The product price (of a single unit)
The product cost (price * quantity - promotion)
The product classification
Details about the product components (modifies/add ons)
The product component identifier
The product component SKU
The product component name
The product component quantity
The product component price (of a single unit)
Details about the product variants
The variant key
the variant name
The variant value
Details about the product price terms
Details about the billing period
The duration of the billing period
The unit of time of the billing period
Defines whether price terms will be automatically renewed or not
Details about the order key dates
The date/time that the order was submitted
The date/time that the order was completed
The date/time that the order was cancelled
The expected period that order will be fulfilled
The unit of time for the expected fulfilled time
The expected date/time that order will be fulfilled
The date/time that order will be expired (if not completed)
The date/time that order was requested to be completed
The date/time that order was started (in progress)
Defines whether the orders are configured to be printed
Defines whether the order has been printed successfully
Defines whether the order is configured to be provisioned
Defines whether the order is configured to be provisioned
Defines whether the order has been provisioned successfully (applicable only if the order is available for provision)
Defines the integration on which the order has been provisioned (applicable only if the order is available for provision)
The custom field’s unique key
The custom field’s value
The page number
The number of records per page
The overal number of records
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
Retrieve today’s orders for a specific venue that are currently new
GET /backoffice/v1/orders?life_cycle_state=NEW&fulfilled_by_tap_code=8269&created_on[gte]=1628456400 HTTP/1.1
api_key: adea79a6-fe7f-2e92-56c7-9a0685ffa290
HTTP/1.1 200 OK
Content-Type: application/json
{
"paging": {
"page": 1,
"size": 2,
"total": 2
},
"content": [
{
"number": "A11636",
"address": null,
"currency": "EUR",
"notes": "please add a couple napkins",
"contact": {
"id": "ed86f87f-3df2-4c83-8897-736c08536eb9",
"name": "Sozos K",
"code": "6562126827272730"
},
"category": null,
"assignee": null,
"discount": {
"amount": 0.68,
"amount_incl_tax": 0.72
},
"id": "970cc6bc-ca78-4f35-9fb7-09c81a42dfc7",
"life_cycle_state": "NEW",
"supply_method": "DELIVERY",
"total_cost": 6.38,
"wallet_funds_amount": 0.20,
"amount_due": 6.18,
"key_dates": {
"id": null,
"submitted_on": 1628500082,
"completed_on": null,
"cancelled_on": null,
"expires_on": null,
"requested_date": null,
"started_on": null,
"estimated_fulfillement": 1628507280,
"estimated_fulfillement_in": 119,
"estimated_fulfillment_UOT": "MINUTE"
},
"number_of_milestones": 1,
"cancellation_reason": null,
"fulfilled_by": {
"id": "8967BAB2A75A456DA055D00111F97DFE",
"name": "Store 1"
},
"is_favorite": false,
"number_of_items": 3,
"is_printed": true,
"available_for_printing": null,
"order_provision": {
"provisioner": null,
"available_for_provision": false,
"is_provisioned": true
},
"amount_to_collect": 6.18,
"total_before_discount": 7.10,
"order_items": []
},
{
"number": "A11635",
"address": null,
"currency": "EUR",
"notes": null,
"contact": {
"id": "ed86f87f-3df2-4c83-8897-736c08536eb9",
"name": "Sozos K",
"code": "6562126827272730"
},
"category": null,
"assignee": null,
"discount": {
"amount": 0.00,
"amount_incl_tax": 0.00
},
"id": "16105370-9be8-412e-976c-f987c40254a6",
"life_cycle_state": "NEW",
"supply_method": "PICK_UP",
"total_cost": 7.70,
"wallet_funds_amount": null,
"amount_due": 7.70,
"key_dates": {
"id": null,
"submitted_on": 1628499814,
"completed_on": null,
"cancelled_on": null,
"expires_on": null,
"requested_date": null,
"started_on": null,
"estimated_fulfillement": 1628507014,
"estimated_fulfillement_in": 120,
"estimated_fulfillment_UOT": "MINUTE"
},
"number_of_milestones": 1,
"cancellation_reason": null,
"fulfilled_by": {
"id": "8967BAB2A75A456DA055D00111F97DFE",
"name": "Store 1"
},
"is_favorite": false,
"number_of_items": 3,
"is_printed": true,
"available_for_printing": null,
"order_provision": {
"provisioner": null,
"available_for_provision": false,
"is_provisioned": true
},
"amount_to_collect": 7.70,
"total_before_discount": 7.70,
"order_items": []
}
]
}{id}Retrieve details for a specific order
Path variables
The order (identifier) that will be retrieved
Request headers
The secret api key required for API calls to ensure that the client is trusted
Responses
OK
Body
The order identifier
The order (reference) number
The order state
The order notess
The order supply method
The total cost of all order items (total order items cost + taxes - discounts)
The amount that was used from wallet funds
Details about the (total) amount that was provided as discount
Total discount amount excluding taxes. This amount equals to the sum of all discount amounts among all invoiced items. Note that this amount does not include the taxed amount.
Tbe amount due to be paid (total cost - wallet funds)
The order currency
An informative description related to the order’s payment
Defines whether the order was marked as a favorite one from the contact
The total number of items for the order
Details about the contact who placed the order
The contact identifier
The contact code
The contact name
The contact phone number
The address line 1
The address line 2
The address state/province/county
The address town/city
The address postal code
The address country
The address of care of
The latitude of the address
The longitude of the address
The Google textual identifier that uniquely identifies an address
Details about the order category
The category identifier
The category name
Details about the cancellation reason (applicable only if the order was cancelled)
The cancellation reason identifier
The cancellaton reason
Details about the organisation that will fulfill the order
The organisation identifier
The organisation name
The organisation phone number
The address identifier
The address type
Defines whether the address is primary or not
The address of care of
The address line 1
The address line 2
The address state/province/county
The address town/city
The address postal code
The address country
The latitude of the address
The longitude of the address
The Google textual identifier that uniquely identifies an address
Details about the ordered items
The item identifier
The item notes
The item state
The order item (product) quantity (same as product.quantity)
Details about the ordered product item
The product identifier
The product SKU
The product name
The product quantity
The product price (of a single unit)
The product cost (price * quantity - promotion)
The product classification
Details about the components
The product component identifier
The product component SKU
The product component name
The product component quantity
The product component price (of a single unit)
Details about the variants
The variant key
The variant name
The variant value
The creative identifier
Information about the creative type
The creative width
The creative height
The creative format
The creative content URL
The creative public identifier
Information about the creative transformations
The transformed creative width
The transformed creative height
The transformed creative URL
Details about the order key dates
The date that the order was submitted
The date that the order was completed
The date that the order was cancelled
Defines the estimated time until order fulfillment
Defines the estimated unit of time (UOT) until order fulfillment
The date that the order was estimated to be fufilled
The date that the order will expire
The date that the order was started
The date that the order was requested
The custom field’s unique key
The custom field’s value
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
GET https://sandbox.crm.com/backoffice/v1/orders/997f1287-3d83-827a-7199-e5df2c0e4e67 HTTP/1.1
api_key: adea79a6-fe7f-2e92-56c7-9a0685ffa290
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "997f1287-3d83-827a-7199-e5df2c0e4e67",
"number": "ORDER1234",
"life_cycle_state": "CANCELLED",
"notes": "Lorem Ipsum",
"supply_method": "DELIVERY",
"total_cost": 5.99,
"wallet_funds_amount": 1.98,
"discount": {
"amount": 1.91,
"amount_incl_tax": 2.12
},
"amount_due": 3.01,
"currency": "EUR",
"payment_info": "NOT PAID - TO BE PAID IN CASH",
"is_favorite": true,
"number_of_items": 6,
"contact": {
"id": "1866a75f-953e-4109-86b4-1cab53fbaaa8",
"code": "1234",
"name": "John Doe",
"phone_number": "357 22265566",
"country_code": "CYP"
},
"address": {
"address_line_1": "Elia Papakyriakou 7",
"address_line_2": "Thomas V",
"state_province_county": "Active",
"town_city": "Nicosia",
"postal_code": "2415",
"country": "CYP",
"care_of": "",
"lat": 35.157115,
"lon": 33.313719,
"googlePlaceId": "ChIJrTLr-GyuEmsRBfy61i59si0"
},
"category": {
"id": "1866a75f-953e-4109-86b4-1cab53fbaaa8",
"name": "Seasonal"
},
"cancellation_reason": {
"id": "1866a75f-953e-4109-86b4-1cab53fbaaa8",
"name": "Placed by mistake"
},
"fulfilled_by": {
"id": "1866a75f-953e-4109-86b4-1cab53fbaaa8",
"name": "CRM Nicosia",
"phone": "357 22265577",
"address": {
"id": "52e2dc4c-3dc1-8ceb-6a15-f1f1b82aed87",
"address_type": "HOME",
"is_primary": true,
"care_of": "",
"address_line_1": "Elia Papakyriakou 7",
"address_line_2": "Thomas V",
"state_province_county": "Active",
"town_city": "Nicosia",
"postal_code": "2415",
"country": "CYP",
"lat": 35.157115,
"lon": 33.313719,
"googlePlaceId": "ChIJrTLr-GyuEmsRBfy61i59si0"
}
},
"order_items": [
{
"id": "1866a75f-953e-4109-86b4-1cab53fbaaa8",
"notes": "Lorem Ipsum",
"life_cycle_state": "PENDING_DELIVERY",
"quantity": 1,
"product": {
"id": "1866a75f-953e-4109-86b4-1cab53fbaaa8",
"sku": "SKU1234",
"name": "Iced Latte",
"quantity": 2,
"price": 1.7,
"cost": 3.4,
"classification": "EXPENSES_SERVICE",
"components": [
{
"id": "1866a75f-953e-4109-86b4-1cab53fbaaa8",
"sku": "B1234",
"name": "Brown Sugar",
"quantity": 1,
"price": 0.5
}
],
"variant_attributes": [
{
"key": "size",
"name": "Size",
"value": "Grande"
}
],
"price_terms": {
"billing_period": {
"duration": 1,
"uot": ""
},
"auto_renew": true,
"termed_period_cycles": 1,
"contract_period": {
"duration": 1,
"uot": ""
},
"trial_period": {
"duration": "",
"uot": ""
},
"price_model": "FIXED",
"bill_model": "POST_BILL"
},
"creatives": [
{
"id": "CA123456789AQWSXZAQWS1236547896541",
"type": "ATTACHMENT",
"width": 2159,
"height": 3075,
"format": "jpg",
"url": "https://assets.crm.com/image/logo.jpg",
"public_id": "crm-com/image",
"media": [
{
"width": 200,
"height": 300,
"url": "https://asset.crm.com/image/offer/c_scale,w_200/logo.jpg"
}
]
}
]
}
}
],
"key_dates": {
"submitted_on": 1592809457,
"completed_on": 1592809457,
"cancelled_on": 1592809457,
"estimated_fulfillment_in": 30,
"estimated_fulfillment_UOT": "MINUTES",
"estimated_fulfillment": 1592809457,
"expires_on": 1592809457,
"started_on": 1,
"requested_date": 1
},
"milestones": [
{
"payment_method": "CARD",
"paid_on": "ON_COMPLETE",
"posted_on": 1234567,
"payment_method_details": {
"brand": "VISA",
"last4": 1234,
"funding_type": "Credit"
},
"invoice": {
"id": "1866a75f-953e-4109-86b4-1cab53fbaaa8",
"number": "INV1234"
},
"payment": {
"id": "1866a75f-953e-4109-86b4-1cab53fbaaa8",
"number": "PAY1234"
}
}
],
"custom_fields": [
{
"key": "back_office",
"value": "0001-12345"
}
],
"available_for_printing": true,
"is_printed": true,
"order_provison": {
"available_for_provision": "true",
"is_provisoned": true,
"provisoner": "TWINSOFT"
}
}{id}/actionsUpdates a single order based on the preferred action
Path variables
The order (identifier) that will be updated
Request headers
The secret api key required for API calls to ensure that the client is trusted
Request body
The action that will be applied on the order
The reason why an order is cancelled (applicable if action = CANCEL)
Responses
OK
Body
The order (identifier) that was updated
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
PUT https://sandbox.crm.com/backoffice/v1/orders/997f1287-3d83-827a-7199-e5df2c0e4e67/actions HTTP/1.1
api_key: adea79a6-fe7f-2e92-56c7-9a0685ffa290
Content-Type: application/json
{
"action": "START_PROGRESS"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "997f1287-3d83-827a-7199-e5df2c0e4e67"
}
PUT https://sandbox.crm.com/backoffice/v1/orders/997f1287-3d83-827a-7199-e5df2c0e4e67/actions HTTP/1.1
api_key: adea79a6-fe7f-2e92-56c7-9a0685ffa290
Content-Type: application/json
{
"action": "COMPLETE"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "997f1287-3d83-827a-7199-e5df2c0e4e67"
}PUT https://sandbox.crm.com/backoffice/v1/orders/997f1287-3d83-827a-7199-e5df2c0e4e67/actions HTTP/1.1
api_key: adea79a6-fe7f-2e92-56c7-9a0685ffa290
Content-Type: application/json
{
"action": "CANCEL",
"cancellation_reason_id": "86d3a62b-5ee5-3a9e-b6dd-517a5dc908dd"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "997f1287-3d83-827a-7199-e5df2c0e4e67"
}Retrieve all reasons that will justify an order cancellation
Request parameters
Defines on which attribute the results should be sorted
Defines how the results will be ordered
The page number that should be retrieved
The size (total records) of each page
Request headers
The secret api key required for API calls to ensure that the client is trusted
Responses
OK
Body
The cancellation reason identifier
The cancellation reason name
The cancellation reason description
The page number
The number of records per page
The overal number of records
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
GET https://sandbox.crm.com/backoffice/v1/order_cancellation_reasons HTTP/1.1
api_key: adea79a6-fe7f-2e92-56c7-9a0685ffa290
HTTP/1.1 200 OK
Content-Type: application/json
{
"content": [
{
"id": "caf332bc-4e90-47b5-a05d-142b264897b9",
"name": "Cancelled by Customer",
"description": "Customer requested to cancel an order due to mistake"
}
],
"pages": {
"page": 2,
"size": 20,
"total": 5124
}
}Order Provisioning to POS systems is achieved using CRM.COM Webhooks Adaptor (via CRM.COM Automations).
A webhook is an event notification method where an application (or a system) is provided with real time information for an order created in CRM.COM without requiring an additional integration (the POS integrator is responsible to parse such order information in order to be able to perform POS operations).
Attached is the order details, send to a POS using a webhook
The order event
The date that the event was submitted
Details about the contact that placed the order
The contact identifier
The contact code
The contact name
Details about the account that placed the order
Details about the customer’s account
The account identifier
The account name
The account number
Details about the business organisation
Details about subsidiary organisation
The subsidiary organisation identifier
The subsidiary organisation name
Details about merchant organisation
The merchant organisation identifier
The merchant organisation name
Details about venue organisation
The venue organisation identifier
The venue organisation name
Details about the contact’s delivery address
Address line 1 details
Address line 2 details
Address town/city
Address postal code
Address country (code)
Details about the order transaction
The order identifier
The order number
The order state
The currency in which the order was made (3 code currency)
The order’s net amount
The order’s tax amount
The order’s discount amount
The order’s total amount
Details about the order
The order identifier
The order number
The state of the order
Defines how the order will be supplied
Details about the order’s category
The category identifier
The category name
Details about the order’s cancellation reason
The cancellation reason identifier
The cancellation reason name
The order notes
The date that the order was submitted
The estimated date that the order will be fulfilled
The date that the order was completed
The date that the order was cancelled
The date that the order was expired
The date that the order was requested
Defines whether the order is the favourited one (for the customer)
The total cost of the order
The order’s currency
Details about the payment method
The payment method
The payment method brand
The type of funding on which the payment is made against
The currency in which the order was made (3 code currency)
The payment amount
Details about the ordered products
The product identifier
The product sku
The product name
The product notes
Details about the product type
The product type identifier
The product type name
Details about the product brand
The product brand identifier
The product brand name
Details about the product family
The product family identifier
The product family name
Details about the product category
The product category identifier
The product category name
The ordered product quantity
The ordered product net amount
The ordered product tax amount
The ordered product discount amount
The ordered product total amount
Details about the bundle products
The bundle product identifier
The bundle product sku
The bundle product name
Performs product synchornization between the products that exist in the POS system over to CRM.COM
Request headers
The secret api key required for API calls to ensure that the client is trusted
Request body
Details about the products to synchornise
The product sku
The product name
The product description
The product type (if type is provided, id or name should be specified)
The product type identifier
The product type name
Details about the product brand (if brand is provided, id or name should be specified)
The product brand identifier
The product brand name
Details about the product family (if family is provided, id or name should be specified)
The product family identifier
The product family name
Details about the product categories (for each provided category, id or name or code should be specified)
The product category identifier
The product category name
The product category code
Defines the period that the product will be valid (if not specified, will be always valid)
The date from which the product will be valid
The date up to which the product will be valid
Details about the product tax rate
The tax rate identifier
The tax rate name
The pricing rate model
The pricing tax model
The price (amount)
The price currency (3 code)
Details about the pricing tiering (required for Tiered and Volume based rate models)
The lowest tier
The top tier
The tier price (amount)
Details about the product variant attributess
The variant key
The variant value
Details about the product components
The component product sku that will be used as component (sku or family, category or product type should be specified)
The component product family that will be used as component (sku or family, category or product type should be specified)
The product family identifer (id or name should be specified)
The product family name (id or name should be specified)
The component product type that will be used as component (sku or family, category or product type should be specified)
The product type identifer (id or name should be specified)
The product type name (id or name should be specified)
The component product category that will be used as component (sku or family, category or product type should be specified)
The product category identifer (id, name or codeshould be specified)
The product category name (id, name or codeshould be specified)
The product category code (id, name or codeshould be specified)
Defines if pricing is inclusive
The minimum number of components that should be added (applicable only for product family and type)
The maximum number of components that should be added (applicable only for product family and type)
Defines whether the component must be added to the product or not
Defines the classification of the component
The creative identifier
Information about the creative type
The creative width
The creative height
The creative format
The creative content URL
The creative public identifier
Information about the creative transformations
The transformed creative width
The transformed creative height
The transformed creative URL
The unique product sku of variant_attribute (required if the synced product is a variant attribute of another product)
Responses
The request has succeeded
Body
A unique identifier of the Web API call which can be used for triggering the webhook and relate the api request to the webhook request (enables integrator to match the api request with the webhook request).
The input request was invalid or incorrect, often due to missing a required parameter
The provided API Key or Token is invalid
The API key or Token does not have permissions to perform the request
The requested resource does not exist
The server encountered an unexpected condition which prevented it from fulfilling the request
The server received an invalid response from the upstream server it accessed in attempting to fulfill the request
The server is currently unable to handle the request due to a temporary overloading or maintenance
The server did not receive a timely response from the upstream server
POST /synchronise_products HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json
{
"products": [
{
"sku": "IL001",
"name": "Iced Latte",
"description": "Cold Brew Latte",
"brand": {
"name": "Brew Ltd"
},
"family": {
"name": "Coffee"
},
"category": {
"name": "Cold Drinks"
}
},
{
"sku": "HL002",
"name": "Hot Latte",
"description": "Hot Latte",
"brand": {
"name": "Coffee Ltd"
},
"family": {
"name": "Coffee"
},
"category": {
"name": "Warm Drinks"
}
}
]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "a781bbc1-9067-c384-52fe-43586f89110a"
}POST /synchronise_products HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json
{
"products": [
{
"sku": "IL001",
"name": "Iced Latte",
"description": "Cold Brew Latte",
"brand": {
"name": "Brew Ltd"
},
"family": {
"name": "Coffee"
},
"category": {
"name": "Cold Drinks"
},
"pricing": {
"rate_model": "FLAT",
"tax_model": "TAX_INCLUSIVE",
"price": 4.99,
"currency": "EUR"
}
}
]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "a781bbc1-9067-c384-52fe-43586f89110a"
}POST https://sandbox.crm.com/backoffice/v1/synchronise_products HTTP/1.1
Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
{
"products": [
{
"sku": "SUGAR001",
"name": "Brown Sugar",
"description": "Brown Sugar",
"type": {
"name": "Condiments"
},
"brand": {
"name": "Fresh Sug"
},
"pricing": {
"rate_model": "FLAT",
"tax_model": "TAX_INCLUSIVE",
"price": 1.99,
"currency": "EUR"
}
},
{
"sku": "FREESP01",
"name": "Freddo Espress0",
"description": "Freddo Espresso",
"type": {
"name": "Wet"
},
"brand": {
"name": "Fresh Brew Inc"
},
"family": {
"name": "Homebrew"
},
"category": {
"name": "Drinks"
},
"pricing": {
"rate_model": "FLAT",
"tax_model": "TAX_INCLUSIVE",
"price": 4.99,
"currency": "EUR"
}
},
{
"sku": "MFREESP01",
"name": "Freddo Espresso Medio",
"description": "Freddo Espresso Medio",
"type": {
"name": "Wet"
},
"brand": {
"name": "Fresh Brew Inc"
},
"family": {
"name": "Homebrew"
},
"category": {
"name": "Drinks"
},
"pricing": {
"rate_model": "FLAT",
"tax_model": "TAX_INCLUSIVE",
"price": 5.99,
"currency": "EUR"
},
"main_product_sku": "FREESP01",
"variant_attributes": [
{
"key": "size",
"value": "Primo"
},
{
"key": "size",
"value": "Maximo"
}
],
"components": [
{
"sku": "SUGAR001",
"inclusive": true,
"mandatory": true,
"classification": "MODIFIER"
}
]
}
]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "a781bbc1-9067-c384-52fe-43586f89110a"
}POST https://sandbox.crm.com/backoffice/v1/synchronise_products HTTP/1.1
Content-Type: application/json
authorization: eyJraWQiOiIvcHJpdmF0ZUtleS5wZW0iLCJ0eXAiOiJKV
{
"products": [
{
"sku": "SUGAR001",
"name": "Brown Sugar",
"description": "Brown Sugar",
"type": {
"name": "Condiments"
},
"family": {
"name": "Coffee & Tea Condiments"
},
"categories": [{
"code": "100"
}],
"pricing": {
"rate_model": "FLAT",
"tax_model": "TAX_INCLUSIVE",
"price": 1.99,
"currency": "EUR"
}
},
{
"sku": "FFM001",
"name": "Full Fat",
"description": "Full Fat Milk",
"type": {
"name": "Condiments"
},
"family": {
"name": "Coffee & Tea Condiments"
},
"categories": [{
"code": "100"
},{
"name": "Latte Medio Milk El"
}]
"pricing": {
"rate_model": "FLAT",
"tax_model": "TAX_INCLUSIVE",
"price": 1.99,
"currency": "EUR"
}
},
{
"sku": "MFREESP01",
"name": "Freddo Espresso Medio",
"description": "Freddo Espresso Medio",
"type": {
"name": "Wet"
},
"family": {
"name": "FREDDO"
},
"categories": [{
"code": "210"
}],
"pricing": {
"rate_model": "FLAT",
"tax_model": "TAX_INCLUSIVE",
"price": 5.99,
"currency": "EUR"
},
"components": [
{
"product_category": {
"code": "500"
},
"mandatory": false,
"classification": "MODIFIER",
"min_amount": 0,
"max_amount": 1,
"inclusive": true
},
{
"product_category": {
"code": "100"
},
"mandatory": true,
"classification": "MODIFIER",
"min_amount": 1,
"max_amount": 2
}
]
}
]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "a781bbc1-9067-c384-52fe-43586f89110a"
}POST /synchronise_products HTTP/1.1
api_key: 4dc0809f-ed91-4b68-b912-5bd6064d901e
Content-Type: application/json
{
"products": [
{
"sku": "225092",
"name": "Iced Mocha Grande",
"type": {
"name": "Coffees"
},
"brand": {
"name": "Brew Ltd"
},
"family": {
"name": "Cold Coffee"
},
"categories": [
{
"name": "Coffee"
}
],
"pricing": {
"rate_model": "FLAT",
"tax_model": "TAX_INCLUSIVE",
"price": 4.00,
"currency": "EUR"
},
"components": [
{
"sku": "282227",
"inclusive": "true",
"min_amount": 1,
"max_amount": 4,
"mandatory": "false",
"classification": "MODIFIER"
}
]
},
{
"sku": "282227",
"name": "Classic Chocolate",
"type": {
"name": "Syrups"
},
"pricing": {
"rate_model": "FLAT",
"tax_model": "TAX_INCLUSIVE",
"price": 0.00,
"currency": "EUR"
}
}
]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "a781bbc1-9067-c384-52fe-43586f89110a"
}