NEW FEATURES & UPDATEScomo-api-doc.s3.amazonaws.com/Como_Latest_API/API Version...C o m m u n i c a...

COMO API Version 4.3.0

Table of Contents

Introduction ..................................................................................................................... 1

Communication Format .................................................................................................... 2

Identification & Protocol ......................................................................................................................... 2

Request Format ....................................................................................................................................... 2

Response Format (error handling) .......................................................................................................... 3

Product & API Call Overview ............................................................................................. 4

Club Features .......................................................................................................................................... 4

Purpose of API Calls ................................................................................................................................. 5

Club Workflow ......................................................................................................................................... 6

General Guidelines ........................................................................................................... 7

Monetary Values ..................................................................................................................................... 7

Displaying Balances ................................................................................................................................. 7

Date Standard and Format ...................................................................................................................... 7

Synchronous Execution ........................................................................................................................... 7

Empty Fields ............................................................................................................................................ 8

API Call Specification ........................................................................................................ 9

getMemberDetails call ............................................................................................................................ 9

getBenefits call ...................................................................................................................................... 13

payment call .......................................................................................................................................... 17

cancelPayment call ................................................................................................................................ 20

submitPurchase call ............................................................................................................................... 23

cancelPurchase call ............................................................................................................................... 27

voidPurchase call ................................................................................................................................... 30

Field Details ................................................................................................................... 31

customer ............................................................................................................................................... 31

purchase ................................................................................................................................................ 33

items ...................................................................................................................................................... 34

membership .......................................................................................................................................... 36

assets ..................................................................................................................................................... 38

deals ...................................................................................................................................................... 40

redeemAssets ........................................................................................................................................ 42

benefits ................................................................................................................................................. 45

meansOfPayment .................................................................................................................................. 48

POS Configurations ......................................................................................................... 50

API Settings............................................................................................................................................ 50

Translations ........................................................................................................................................... 50

Flows ............................................................................................................................. 51

Main Flow .............................................................................................................................................. 51

Non-Members ....................................................................................................................................... 55

Refunds/Voids ....................................................................................................................................... 56

Multiple Members ................................................................................................................................. 57

Registration ........................................................................................................................................... 58

Advanced Payment ................................................................................................................................ 59

Redeemable Gift List ............................................................................................................................. 60

Gift List Inquiries.................................................................................................................................... 61

Discount Implementation ...................................................................................................................... 62

Tax-Excluded Countries ......................................................................................................................... 63

Version Changes ............................................................................................................. 64

Version Updates (4.3.0) ......................................................................................................................... 64

Version Updates (4.2.4) ......................................................................................................................... 64

I n t r o d u c t i o n | 1

Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment

Introduction This document describes the Como API for external services that wish to integrate with the Como

customer engagement solution. While most of the document uses a POS semantic, all API calls can be

made from any kind of service with web access—including POS’s, e-commerce sites, vending

machines, gas station pumps, etc.

The Como API consist of the following API calls:

getMemberDetails

getBenefits

payment

cancelPayment

submitPurchase

cancelPurchase

voidPurchase

C o m m u n i c a t i o n F o r m a t | 2


Communication Format

Identification & Protocol

The Como API is based on simple HTTP POST requests over HTTPS. Identification is performed using a

secret API key. Upon registering to the Como platform, each business is provided with their own

unique API key—so all request should be sent with the API key of the relevant business.

Como API Servers

Host: https://api.prod.como.com

Note: When a static IP is required, use the following host: https://static-api.como.com

Request Format

The POST body is a UTF-8 encoded object. The URL for the request should be built as follows:

1. API server host

2. Prefix path followed by the name of the API call

3. Query parameters – specific to each API call

Headers

Name Description Type Mandatory

Content-Type The request payload content type; should be 'application/json'. String Y

X-Api-Key The api key used for authentication String Y

X-Branch-Id The business branch identifier String Y

X-Pos-Id The identifier of the POS “terminal” that triggered the request String Y

X-Source-Type Origin of the transaction, such as POS, Website, or App String Y

X-Source-Name Integrator name (ex: POS name) that triggered the request String Y

X-Source-Version Software version of the integrator String Y

https://api.prod.como.com /api/v4/apiCall?apiCallParameters

1 2 3

https://api.prod.como.com/

https://static-api.como.com/

C o m m u n i c a t i o n F o r m a t | 3


Response Format (error handling)

The response is a JSON object. The "status" attribute returned in this object indicates success ("ok") or

failure ("error"). In case of failure, the response body will contain additional information which you

can inspect for debugging and error handling. For descriptions of specific errors that are returned and

guidance for when to display them to the cashier, click here.

errors properties

Field Description Type Returned

code Error code String Always

message Description of the error String Always

cause Optional object that holds the reason the error occurred Sometimes

{ "status": "error", "errors": [ { "code": "4001012", "message": "Customer(s) not found" } ] }

http://como-api-doc.s3.amazonaws.com/Como_Latest_API/API%20Version%204.0/Server%20error%20codes%20-%20POS%20API%204.0%20Errors.pdf

C l u b F e a t u r e s | 4


Product & API Call Overview Como Sense is an end-to-end customer engagement solution that integrates with POS software to

provide a seamless customer experience. It provides businesses with a set of tools that work

together, including loyalty programs, a customized and branded mobile app, actionable data, and a

management console for creating the app, operating the loyalty program, and viewing analytics. The

loyalty club offers members rewards and incentives—like point accumulation, gifts, and punch cards.

The integration with POS systems and other third-party services enables Como to gather the data

required to deliver personalized and seamless customer experiences.

Club Features

Here’s an overview of the main features of a loyalty club.

Gifts Gifts are items members can redeem in the business—from products to discount

vouchers. Members can buy gifts in their app’s Point Shop using points or receive them

as a reward for joining the club, for their purchase, etc. Each gift can be redeemed only

once—using a code generated from the app or directly from the gift list on the POS.

Punch Cards Punch cards provide rewards to members after a certain number of purchases (such as

buy 9 coffees and get the 10th for free). Each time they make a purchase that’s eligible for

a punch, they automatically get a punch in their card after we receive the purchase

details. Once the card is full, they can redeem the card for a reward.

Deals Deals are reusable benefits or promotions that customers receive (such as 10% off their

entire purchase). Unlike gifts, deals do not need to be redeemed (they are automatically

applied) and they are not for one-time use.

Points Members can earn points for their purchase—which are automatically added once we

receive the purchase details. They can use points to buy gifts in the app’s Point Shop, to

redeem in the business. Businesses can also allow members to buy points, or buy items in

the business directly using their points.

Credit Credit can be accumulated, purchased or added—and then used as a form of payment to

purchase items from the business. Businesses can also allow members to use credit to

buy gifts from the Point Shop.

Mobile Payments Members can add credit cards to their app to use to pay for items in the business. When

they want to make a payment, they select a credit card from the list of cards they added

and tap Pay. The app then generates a payment (verification) code that they provide to

the POS. Learn more.

http://como-api-doc.s3.amazonaws.com/Product%20Docs/Mobile%20Payments.pdf

P u r p o s e o f A P I C a l l s | 5


Purpose of API Calls

Below is a short summary of the main purpose of each API call.

getMemberDetails To display member details and gifts (also required to allow employees to select

gifts to redeem from the gift list)

getBenefits To redeem gifts (assets) and/or apply deals to the purchase

payment To pay for purchases using credit, points, or mobile payments

cancelPayment To cancel credit/point/mobile payments

submitPurchase To send purchase data (used to automatically give members points, punch their

punch cards, etc.)

cancelPurchase To cancel a purchase after the purchase is completed

voidPurchase To void a transaction before the purchase is completed

C l u b W o r k f l o w | 6


Club Workflow

The diagram below shows when API calls are generated in a typical club flow.

1. The member identifies (ex: by phone number) and member details are displayed on the POS.

2. Items are added to the customer’s shopping cart.

3. Customers can choose which gifts to redeem. The cashier either enters redeem codes that

the member generates from their app or selects gifts from a list on the POS.

4. Upon subtotal, benefits (corresponding to gifts or deals) are applied to the purchase.

5. The customer pays using regular means of payment, and/or credit, points, or mobile

payments.

6. Purchase details are sent to the Como server.

G e n e r a l G u i d e l i n e s | 7


General Guidelines

Monetary Values

All monetary values (such as sum, totalAmount, discount, etc.) are presented in the API as follows:

• in the smallest unit of currency (for example, as cents and not dollars)

• positive when referring to a price or an amount paid by the customer

• negative when referring to a discount for the customer

Displaying Balances

All balances—such as point or credit balances—are returned with two values:

• monetary—How much the non-monetary balance is worth in currency according to the

conversion rate specified by the business (ex: what the points are worth in currency)

• nonMonetary—the balance (ex: number of points)

All balances are returned to the POS in the smallest unit of measurement (like cents). The POS should

divide all balances by 100 when displaying them on the POS, and display 2 values after the decimal.

Date Standard and Format

For all dates and times in the API, the ISO 8601 standard should be used—both for the request and

the response. Since UTC+00 is always used, the POS should convert the dates to local time for display.

There are two formats used in the API:

• format for Date: yyyy-MM-dd

• format for DateTime: yyyy-MM-ddThh:mm:ssZ (Z indicates UTC+00)

Synchronous Execution

All API calls—except for the voidPurchase call and the submitPurchase call with status=open—should

be handled synchronously. The POS is required to implement a time-out mechanism for when the

response is not received within a reasonable amount of time (around 5-10secs, taking into account

the internal POS environment routing times).

For the submitPurchase call with status=final, an asynchronous guaranteed delivery mechanism is

required for the following cases:

• if Como returns an error that begins with 5xx (representing a Como server error), or

• if there is a communication error on the side of the POS

We recommend trying to send it again twice close of the time of the purchase (since members are

waiting to see their rewards) and then trying again at the end of the day.

G e n e r a l G u i d e l i n e s | 8


Empty Fields

The POS should not send fields that don’t have values.

g e t M e m b e r D e t a i l s c a l l | 9


API Call Specification

getMemberDetails call

Description

Purpose This API call is used to verify the customer is a club member, present their member

details (name, point balance, etc.) and present their gift list (to allow the cashier to

select which gifts to redeem directly from this list).

When to Use • To verify the customer is a club member

• When requested to display details or to select gifts to redeem

Notes Redeeming Assets

The getMemberDetails call is used to display a gift list, from which the cashier can

select gifts to redeem. However, benefits are only actually calculated using the

getBenefits call and redeemed using the submitPurchase call.

Related Flows Main Flow

Multiple Members

Registration

Redeemable Gift List

Gift List Inquiries

Discount Implementation

Tax-Excluded Countries

Request Format

See Communication Format for the structure of the URL and Headers.

Query Parameters


returnAssets

Which assets (i.e. gifts) to return. Options are:

• active—assets of the customer with asset status as active

• inactive—assets of the customer with any asset status except active

• all—assets of the customer with any asset status Note: If this parameter is not passed, no assets are returned.

String N

expand

List of response items to expand, i.e. provide more information about. Option is:

• assets.redeemable –Adds the redeemable flag to the assets, indicating if the asset is currently in a redeemable state and if not, why (requires returnAssets in the query and purchase in the body)

List of Strings N



Body

Field Description Type Mandatory

customer Object representing a member’s identifier (ex: phone number) Customer Y

purchase Customer’s purchase details Purchase N

Request Example

POST https://api.prod.como.com/api/v4/getMemberDetails?returnAssets=active HTTP/1.1 Content-Type: application/json X-Api-Key: 3f09101f X-Branch-Id: 67 X-Pos-Id: 89 X-Source-Type: POS X-Source-Name: POS Name X-Source-Version: 3 { "customer": { "phoneNumber": "2128782328" }, "purchase": { "openTime": "2017-09-20T07:09:24Z", "transactionId": "3f09101f66", "totalAmount": 1200, "orderType":"dineIn", "employee":"987", "items": [ { "lineId": "1", "code": "1111", "name": "Large Coffee", "departmentCode": "56", "departmentName": "Beverages", "quantity": 5, "grossAmount": 1000, "netAmount": 1000 }, { "lineId": "2", "code": "5555", "name": "Muffin", "departmentCode": "89", "departmentName": "Bakery", "quantity": 1, "grossAmount": 200, "netAmount": 200 } ] } }

https://api.prod.como.com/api/v4/getMemberDetails?returnAssets=active



Response Format


membership An object with member details Membership Always

memberNotes

An object representing a custom message that should be

displayed to the customer on the POS, with the following

(string) attributes:

• content—the message content

• type—whether the message is text (default) or URL

Sometimes



Response Example

{ "status": "ok", "membership": { "firstName": "Jane", "lastName": "Smith", "birthday": "1995-03-03", "email": "[email protected]", "gender": "female", "phoneNumber": "2128782328", "status": "Active", "createdOn": "2016-05-19T10:19:08Z", "allowSMS": true, "commonExtId": "1d722661-0a94-4a36-8dea-ae23e5e3f440", "mobileAppUsed": true, "mobileAppUsedLastDate": "2017-06-15T10:12:29Z", "pointsBalance": { "monetary" : 2000, "nonMonetary" : 2000, "usedByPayment": false }, "creditBalance": { "monetary" : 1000, "nonMonetary" : 1000, "usedByPayment": true }, "assets": [ { "key": "60y4KJDxK2zfUrcrir9D3K2OWyvorXpPJADNroNY8", "name": "Free Muffin", "description": "Free muffin with the purchase of a large coffee", "status": "Active", "image": "https://storage-download.googleapis.com/server-prod/images/giftimg.jpg", "validFrom": "2017-01-05T20:59:59Z", "validUntil": "2017-08-05T20:59:59Z" }, { "key": "1zikFHzdF1jLPqMXdqrfEkJ2rOAXTX9Cw4BFIfq48", "name": "Sandwich Coupon", "description": "$5 Off Sandwich", "status": "Active", "image": "https://storage-download.googleapis.com/server-prod/images/giftimg.jpg", "validFrom": "2017-01-05T20:59:59Z", "validUntil": "2017-08-05T20:59:59Z" } ] }, "memberNotes":[ { "content": "Deal of the month: 20% off milkshakes", "type": "text" } ] }

g e t B e n e f i t s c a l l | 13


getBenefits call

Description

Purpose This API call is used to apply benefits or promotions to the customer’s purchase—

by redeeming a customer’s gifts (assets) or by automatically applying deals. For

example, it can be 10% off their purchase or $5 off specific items.

When to Use Upon “subtotal” after all non-Como discounts are applied

Notes Sending the Request

• If this API call is called multiple times for the same purchase, make sure to clear

the previously returned benefits and add the new benefits each time.

• If the POS doesn’t support subtotal, the POS should present a dedicated button

(or an equivalent trigger before payment).

Applying Discounts

• The POS should allocate discounts as it is essential for the proper calculation of

Como rewards, reporting, displaying discounts to customers, and tax calculation

(see Discount Implementation).

• The total discount applied for each item (including Como or other discounts)

should not be greater than the item price.


Multiple Members

Registration

Non-Members



Request Format


Query Parameters


expand

List of response items to expand, i.e. provide more information about. Options are:

• discountByDiscount - Shows how discounts should be allocated to specific items in the purchase

List of Strings N



Body


customers Array of member identifiers (ex: phone number) Customer N

purchase Customer’s purchase details Purchase Y

redeemAssets Array of the assets (gifts) that the member requested to redeem RedeemAssets N

Request Example

POST https://api.prod.como.com/api/v4/getBenefits?expand=discountByDiscount HTTP/1.1 Content-Type: application/json X-Api-Key: 3f09101f X-Branch-Id: 67 X-Pos-Id: 89 X-Source-Type: POS X-Source-Name: POS Name X-Source-Version: 3 { "customers":[ { "phoneNumber": "2128782328" } ], "purchase": { "openTime": "2017-09-20T07:09:24Z", "transactionId": "3f09101f66", "totalAmount": 1200, "orderType":"dineIn", "employee":"987", "items": [ { "lineId": "1", "code": "1111", "name": "Large Coffee", "departmentCode": "56", "departmentName": "Beverages", "quantity": 5, "grossAmount": 1000, "netAmount": 1000 }, { "lineId": "2", "code": "5555", "name": "Muffin", "departmentCode": "89", "departmentName": "Bakery", "quantity": 1, "grossAmount": 200, "netAmount": 200 } ] }, "redeemAssets":[ { "key":"60y4KJDxK2zfUrcrir9D3K2OWyvorXpPJADNroNY8" }, { "key":"1zikFHzdF1jLPqMXdqrfEkJ2rOAXTX9Cw4BFIfq48" } ] }

https://api.prod.como.com/api/v4/getBenefits?expand=discountByDiscount



Response Format


deals An array of objects representing deals that should be

applied to a customer’s purchase Deals Sometimes

redeemAssets An array of assets (gifts) that the member requested to

redeem (including benefits that should be applied) RedeemAssets Sometimes

totalDiscountsSum Total sum of all discounts that should be applied (when the

benefit type is discount) Integer Sometimes



Response Example

{ "status": "ok", "deals": [ { "key": "30yj439fK2zfUrcrir9D37n3kf8orXpPJADN8fnj56", "name": "10% off purchase", "benefits": [ { "type": "discount", "sum": -120, "extendedData": [ { "item": { "code": "1111", "quantity": 5, "netAmount": 1000, "lineId": "1" }, "discount": -100, "discountedQuantity": 5, "discountAllocation": [ { "quantity": 5, "unitDiscount": -20 } ] }, { "item": { "code": "5555", "quantity": 1, "netAmount": 200, "lineId": "2" }, "discount": -20, "discountedQuantity": 1, "discountAllocation": [ { "quantity": 1, "unitDiscount": -20 } ] } ] } ] } ], "redeemAssets": [ { "key": "60y4KJDxK2zfUrcrir9D3K2OWyvorXpPJADNroNY8", "name": "Free Muffin", "redeemable": true, "benefits": [ { "type": "dealCode", "code": "6543" } ] }, { "key": "1zikFHzdF1jLPqMXdqrfEkJ2rOAXTX9Cw4BFIfq48", "name": "Sandwich Coupon", "redeemable": false, "nonRedeemableCause": { "code": "5501", "message": "Conditions not satisfied" } } ], "totalDiscountsSum": -120 }

p a y m e n t c a l l | 17


payment call

Description

Purpose Allows customers to pay for their purchase using their credit, points, or mobile

payments

When to Use When the cashier taps a dedicated button to pay with Como payments

Notes Verification Codes

The business can secure these payments by requiring members to provide a

verification code at the POS. Members can generate it from their app or receive it

by SMS.


Multiple Members

Advanced Payment



Request Format


Query Parameters


mode Function performed by the API call. Options:

• pay—used to perform a payment (default)

• query—used to query a balance Enum:pay|query N





Body


customer Object representing a member’s identifier (ex: phone number) Customer N

purchase Customer’s purchase details Purchase Y

verificationCode

Verification code provided by the customer—generated in the app,

or sent by SMS

Note: In many cases, this field is required for mobile payments and

point/credit payments.

String N

amount

Requested amount to pay in cents. It should be negative when

reimbursing the customer.

Note: See Tax-Excluded Countries

Integer Y

Request Example

POST https://api.prod.como.com/api/v4/payment HTTP/1.1 Content-Type: application/json X-Api-Key: 3f09101f X-Branch-Id: 67 X-Pos-Id: 89 X-Source-Type: POS X-Source-Name: POS Name X-Source-Version: 3 { "customer": { "phoneNumber": "2128782328" }, "purchase": { "openTime": "2017-09-20T07:09:24Z", "transactionId": "3f09101f66", "totalAmount": 900, "orderType":"dineIn", "employee":"987", "items": [ { "lineId": "1", "code": "1111", "name": "Large Coffee", "departmentCode": "56", "departmentName": "Beverages", "quantity": 5, "grossAmount": 1000, "netAmount": 900 }, { "lineId": "2", "code": "5555", "name": "Muffin", "departmentCode": "89", "departmentName": "Bakery", "quantity": 1, "grossAmount": 200, "netAmount": 0 } ] }, "verificationCode": "9876", "amount": 600 }

https://api.prod.como.com/api/v4/payment?mode=pay



Response Format


confirmation Payment identifier provided by the payment API call (also used for

cancelling the payment) String Always

payments

Object indicating how to apply a payment and the payment amount,

with these properties:

• paymentMethod— if the payment should be applied as a

discount, meanOfPayment or either

discountOrMeanOfPayment (Enum)

• amount—amount that should be applied as a

discount/payment towards the purchase (Integer)

Always

type

Indicates the payment type (string). Options are:

• memberCredit

• memberPoints

• creditCard (mobile payments)

Enum Always

details Additional details String Sometimes

updatedBalance

Object representing the customer’s new balance after the payment

with these properties:

• monetary

• nonMonetary

Note: This object isn’t returned if the type is creditCard.

Sometimes

Response Example

{ "status": "ok", "payments": [ { "paymentMethod": "meanOfPayment", "amount": -600 } ], "confirmation": "2b027fbd-d478-42d2-b7d9-9c7235ad6e5b", "type": "memberCredit", "updatedBalance": { "monetary": 400, "nonMonetary": 400 } }

c a n c e l P a y m e n t c a l l | 20


cancelPayment call

Description

Purpose This API call allows the POS to cancel a credit/point/mobile payment using the

confirmation code from the payment call.

When to use When the cashier taps a dedicated button to cancel the Como payment

Notes When the cancelPayment call is sent after the purchase is completed, the purchase

is not cancelled unless the cancelPurchase call is also sent.

Related Flows Refunds/Voids


Request Format


confirmation Confirmation code provided by the payment call String Y

purchase Customer’s purchase details Purchase N



Request Example

POST https://api.prod.como.com/api/v4/cancelPayment HTTP/1.1 Content-Type: application/json X-Api-Key: 3f09101f X-Branch-Id: 67 X-Pos-Id: 89 X-Source-Type: POS X-Source-Name: POS Name X-Source-Version: 3 { "confirmation":"2b027fbd-d478-42d2-b7d9-9c7235ad6e5b", "purchase": { "openTime": "2017-09-20T07:09:24Z", "transactionId": "3f09101f66", "totalAmount": 900, "orderType":"dineIn", "employee":"987", "items": [ { "lineId": "1", "code": "1111", "name": "Large Coffee", "departmentCode": "56", "departmentName": "Beverages", "quantity": 5, "grossAmount": 1000, "netAmount": 900 }, { "lineId": "2", "code": "5555", "name": "Muffin", "departmentCode": "89", "departmentName": "Bakery", "quantity": 1, "grossAmount": 200, "netAmount": 0 } ], "meansOfPayment":[ { "type":"memberCredit", "amount": 600 } ] } }

https://api.prod.como.com/api/v4/cancelPayment



Response Format


type

Indicates which payment type was used (string). Options are:

• memberCredit

• memberPoints

• creditCard (mobile payments)

Enum Always

updatedBalance

Object representing the customer’s new balance after a

credit/point payment with these properties:

• monetary

• nonMonetary

Note: This object isn’t returned if the type is creditCard.

Sometimes

Response Example

{ "status": "ok", "type": "memberCredit", "updatedBalance": { "monetary": 1000, "nonMonetary": 1000 } }

s u b m i t P u r c h a s e c a l l | 23


submitPurchase call

Description

Purpose Once the transaction is completed, this API call is used to send Como a customer’s

purchase details—such as the total amount paid and the complete shopping cart.

These purchase details are used by Como to segment members or perform actions

on them—such as automatically punch their punch cards (based on specific items

in the cart), give them points or send them other rewards.

When to Use • After the final payment (sent with status=final)

• After applying the getBenefits response (sent with status=open)

Notes Sending the Request

• On final payment, the submitPurchase call should be sent for all purchases

(including purchases of non-members) to allow the business to receive

actionable data and BI on all their purchases.

• Since the submitPurchase call is the basis of the entire loyalty club, guaranteed

delivery is required for submitPurchase with status=final in the following cases:

if Como returns an error that begins with 5xx (representing a Como server

error), or if there’s a communication error on the side of the POS.


Multiple Members

Registration

Non-Members

Refunds/Voids



Request Format


Query Parameters


status Indicates whether the transaction was finalized

(final) or not (open) Note: Default is final String N



Body


customers Array of member identifiers (ex: phone number) Customer N

purchase The customer’s purchase details Purchase Y

redeemAssets

An array of the assets (gifts) that were applied or partially

applied to the purchase (using the getBenefits call)

Note: This allows us to mark the asset as used (since assets can

only be redeemed once).

RedeemAssets N

deals An array of deals that were applied or partially applied to the

purchase (using the getBenefits call) Deals N



Request Example

POST https://api.prod.como.com/api/v4/submitPurchase HTTP/1.1 Content-Type: application/json X-Api-Key: 3f09101f X-Branch-Id: 67 X-Pos-Id: 89 X-Source-Type: POS X-Source-Name: POS Name X-Source-Version: 3 { "customers":[ { "phoneNumber":"2128782328" } ], "purchase": { "openTime": "2017-09-20T07:09:24Z", "transactionId": "3f09101f66", "totalAmount": 900, "orderType":"dineIn", "employee":"987", "items": [ { "lineId": "1", "code": "1111", "name": "Large Coffee", "departmentCode": "56", "departmentName": "Beverages", "quantity": 5, "grossAmount": 1000, "netAmount": 900 }, { "lineId": "2", "code": "5555", "name": "Muffin", "departmentCode": "89", "departmentName": "Bakery", "quantity": 1, "grossAmount": 200, "netAmount": 0 } ], "meansOfPayment":[ { "type":"memberCredit", "amount": 600 }, { "type":"cash", "amount": 300 } ] }, "deals":[ { "key":"30yj439fK2zfUrcrir9D37n3kf8orXpPJADN8fnj56", "appliedAmount": -120 } ], "redeemAssets":[ { "key": "60y4KJDxK2zfUrcrir9D3K2OWyvorXpPJADNroNY8", "appliedAmount": 0 } ] }

Note: The appliedAmount

should be 0 only if the benefits

type is itemCode or dealCode.

https://api.prod.como.com/api/v4/submitPurchase



Response Format


confirmation Confirmation code provided by the submitPurchase API call String Always

memberNotes

An object representing a custom message that should displayed to the

customer (ex: printed on the receipt), with these (string) attributes:

• content—the message content

• type—whether the message is text (default) or URL

Sometimes

Response Example

{ "status": "ok", "confirmation": "KYr2Zs4vabkuoANrzD9CkAzlsn9BQJO26i1Q09Cd69DmHlI8", "memberNotes":[ { "content": "Check your app to see your new point balance", "type": "text" } ] }

c a n c e l P u r c h a s e c a l l | 27


cancelPurchase call

Description

Purpose This API call allows the POS to cancel a transaction using the confirmation code

from the submitPurchase call.

When to Use When the cashier initiates a purchase cancellation

Notes Cancelling Payments

If a member pays for their purchases using the payment call and then cancels their

purchase using the cancelPurchase call, the payment is not cancelled unless the

cancelPayment call is also sent.


Request Format


Body


confirmation Confirmation code provided by the submitPurchase call String Y

purchase The customer’s purchase details Purchase N

c a n c e l P u r c h a s e c a l l | 28


Request Example

Response Format

Only the status field (“ok”) is returned for a successful response.

Response Example

POST https://api.prod.como.com/api/v4/cancelPurchase HTTP/1.1 Content-Type: application/json X-Api-Key: 3f09101f X-Branch-Id: 67 X-Pos-Id: 89 X-Source-Type: POS X-Source-Name: POS Name X-Source-Version: 3 { "confirmation": "KYr2Zs4vabkuoANrzD9CkAzlsn9BQJO26i1Q09Cd69DmHlI8", "purchase": { "openTime": "2017-09-20T07:09:24Z", "transactionId": "3f09101f66", "totalAmount": 900, "orderType":"dineIn", "employee":"987", "items": [ { "lineId": "1", "code": "1111", "name": "Large Coffee", "departmentCode": "56", "departmentName": "Beverages", "quantity": 5, "grossAmount": 1000, "netAmount": 900 }, { "lineId": "2", "code": "5555", "name": "Muffin", "departmentCode": "89", "departmentName": "Bakery", "quantity": 1, "grossAmount": 200, "netAmount": 0 } ], "meansOfPayment":[ { "type":"memberCredit", "amount": 600 }, { "type":"cash", "amount": 300 } ] }

{ "status":"ok" }

https://api.prod.como.com/api/v4/cancelPurchase

v o i d P u r c h a s e c a l l | 29


voidPurchase call

Description

Purpose This API call allows the POS to void a transaction before it is complete (before the

submitPurchase call is sent with status=final).

When to Use When the cashier voids the transaction

Notes Cancelling Payments

If a member pays for their purchases using the payment call and then the purchase

is voided using the voidPurchase call, the payment is not cancelled unless the

cancelPayment call is also sent.


Request Format


Body


purchase The customer’s purchase details Purchase Y

Request Example

Response Format

Only the status field (“ok”) is returned for a successful response.

Response Example

POST https://api.prod.como.com/api/v4/voidPurchase HTTP/1.1 Content-Type: application/json X-Api-Key: 3f09101f X-Branch-Id: 67 X-Pos-Id: 89 X-Source-Type: POS X-Source-Name: POS Name X-Source-Version: 3 { "purchase": { "openTime": "2017-09-20T07:09:24Z", "transactionId": "3f09101f66", "totalAmount": 0 } }

{ "status":"ok" }

https://api.prod.como.com/api/v4/voidPurchase

c u s t o m e r | 30


Field Details

customer

customer is an object representing a Como club member identifier. By passing the customer object to

API calls, Como will process the API call using the identified customer.

Note: When the API call allows more than one customer in the request, the customers array is used

instead (with the same properties as customer).

Each customer has the type of the identifier as the key and the identifier as the value.

Properties (Types of Identifiers)

Field Description

phoneNumber Customer’s phone number

govId Locally relevant government issued ID number, driver’s license, etc.

memberId An external number representing the member like their membership card number

appClientId A temporary ID that the member generates from their app—presented as a number,

barcode or QR code

customIdentifier Custom identifier chosen by the business such as government ID or license plate number

Example

customers array

customer object

"customer": { "Customer1_Identifier_type":"Customer1_Identifier_value" }

{ "customers":[ { "phoneNumber":"534645645" }, { "phoneNumber":"3f09101f9" } ] }

{ "customer": { "phoneNumber": "534645645" } }

p u r c h a s e | 31


purchase

purchase is an object representing the customer’s purchase details. It should be sent in all API calls.


transactionId

Transaction identifier from the POS

Note: The same identifier should be passed in all API

calls for the same transaction.

String Y

openTime Transaction start time – should be the same value each

time this field is sent for the same transaction DateTime Y

relatedTransactionId

Transaction identifier from an external system (ex:

ordering system) – should only be sent if the transaction

was initiated in an external system

String N

totalAmount Total amount of the purchase in cents

Note: See Tax-Excluded Countries Integer Y

totalTaxAmount Total amount of tax applied to the purchase in cents

Note: Only reported for Tax-Excluded Countries Integer N

totalGeneralDiscount

Total amount in cents of all discounts that weren’t

apportioned to particular items (including Como

discounts and other discounts)

Integer N

orderType Type of transaction—such as takeaway, dineIn or

delivery String N

items An array of items in the current transaction Items N

meansOfPayment Array of payments made in the transaction (incl. the

payments made using the payment call that were

applied as means of payment)

MeansOfPayment N

tags

Array of strings—includes optional tags that are

available to the business

Note: The business specifies in API settings which

attributes correspond to tags.

String array N

employee ID or name of the current transaction operator (ex:

cashier) String N

i t e m s | 32


items

items is a list of items in the purchase—used by Como to calculate discounts and validate conditions

based on the customer’s shopping cart. It should be sent in the submitPurchase, getBenefits,

getMemberDetails and payment calls.

Properties


lineId Line reference number corresponding to the line item String Y

code Item identification code (i.e. PLU) String Y

name Human readable item name String Y

departmentCode Department code (or other relevant hierarchy code) String Y

departmentName Human readable hierarchy information String Y

quantity Number of times the item was purchased in this transaction Integer Y

weight

Weight of the current item for items priced by weight. It should

be in the highest unit of measurement (kg, pounds, liters, etc.)

Note: If the item is weighable, quantity must be 1.

This field is mandatory if the item is weighable. If not, this field

should not be passed.

Double N

grossAmount

𝑔𝑟𝑜𝑠𝑠𝐴𝑚𝑜𝑢𝑛𝑡 = (𝑔𝑟𝑜𝑠𝑠 𝑝𝑟𝑖𝑐𝑒 𝑝𝑒𝑟 𝑖𝑡𝑒𝑚)𝑥(𝑞𝑢𝑎𝑛𝑡𝑖𝑡𝑦 𝑜𝑟 𝑤𝑒𝑖𝑔ℎ𝑡)

where gross price is the price before it’s discounted (in cents)


Integer Y

netAmount

𝑛𝑒𝑡𝐴𝑚𝑜𝑢𝑛𝑡 = (𝑛𝑒𝑡 𝑝𝑟𝑖𝑐𝑒 𝑝𝑒𝑟 𝑖𝑡𝑒𝑚)𝑥(𝑞𝑢𝑎𝑛𝑡𝑖𝑡𝑦 𝑜𝑟 𝑤𝑒𝑖𝑔ℎ𝑡)

Total amount after any Como or other discounts were applied

(in cents)


Integer Y

action Type of action that’s performed for this line—values are: sale

(default) or refund Enum N

tags

Array of strings—including optional tags that are available to the

business and are relevant for the specific item

Note: The business specifies in API settings which attributes

correspond to tags.

String array N

i t e m s | 33


Example

{ "items":[ { "lineId":"1", "code":"601040007", "name":"Prod1", "departmentCode":"123", "departmentName":"Dep1", "quantity":1, "grossAmount":400, "netAmount":400, "action":"sale", "tags":[ "Nestle", "dairy" ] }, { "lineId":"2", "code":"601040007", "name":"Prod1", "departmentCode":"123", "departmentName":"Dep1", "quantity":2, "grossAmount":800, "netAmount":800, "action":"sale", "tags":[ "Nestle", "dairy" ] }, { "lineId":"3", "code":"601040008", "name":"Prod2", "departmentCode":"456", "departmentName":"Dep2", "quantity":1, "weight":1.2415, "grossAmount":400, "netAmount":400, "action":"sale", "tags":[ "Organic", "produce" ] } ] }

items list with three items. The second item is

identical to the first item but with the

quantity of 2 (notice that the grossAmount

has doubled). The third item is a weighable

item (so it has quantity of 1).

m e m b e r s h i p | 34


membership

membership is an object representing the member (returned in the getMemberDetails call). Although

the business can configure other fields that will be returned, here are the main attributes:


firstName First name of the member String Sometimes

lastName Last name of the member String Sometimes

pushNotificationEnabled Whether the member enabled push notifications in the app Boolean Sometimes

locationEnabled Whether or not the member enabled location for the app Boolean Sometimes

mobileAppUsed Whether or not the member used their app Boolean Sometimes

mobileAppUsedLastDate Last login from the mobile app DateTime Sometimes

phoneNumber Member’s phone number String Sometimes

allowSMS Whether or not the member enabled SMS’s from Como Boolean Always

govId Locally relevant government issued ID number String Sometimes

commonExtId Member identifier for external purposes String Always

email Member’s email address String Sometimes

memberId External number representing the member (ex: membership

card number) String Sometimes

birthday Member’s birthday Date Sometimes

anniversary Member’s anniversary Date Sometimes

gender Member’s gender (options are defined by the business) String Sometimes

genericString1 A general purpose string variable String Sometimes

genericInteger1 A general purpose integer variable Integer Sometimes

genericCheckBox1 A general purpose boolean variable Boolean Sometimes

genericDate1 A general purpose date variable DateTime Sometimes

tag Business tags that provide additional information about the

member String Sometimes

assets An array of assets (gifts or punch cards) of the member Assets Sometimes

expirationDate Date that the customer’s club membership expires Date Sometimes

status Member’s club status. Options: Active, Inactive, Expired,

Pending Enum Always

pointsBalance Member’s current point balance PointsBalance Always

creditBalance Member’s current credit balance CreditBalance Always

m e m b e r s h i p | 35


Balance Fields

A customer’s current point or credit balance is represented by the pointsBalance and creditBalance

objects, each with the properties below.


monetary

How much the non-monetary balance is worth in currency according to

the conversion rate specified by the business (ex: what the points are

worth in currency)

Integer Always

nonMonetary The balance (ex: number of points) Integer Always

usedByPayment Whether or not this balance is the one used for payment (via the

payment call) Boolean Always

Note: All balances are returned to the POS in the smallest unit of measurement (such as cents). The

POS is responsible to divide all balances (including points) by 100 when displaying them on the POS,

as well as display 2 decimal places.

a s s e t s | 36


assets

assets is an array of objects providing details on a member’s gifts or punch cards. Customers can

choose to redeem assets in the purchase for a benefit (such as a free drink).

The array can be obtained by calling getMemberDetails using the returnAssets query parameter, in

order to present a gift list to the customer.

Properties


key Unique identifier of the asset String Always

name Name of the asset String Always

description Detailed description of the asset String Always

status

The value can be:

• Active–asset has potential to be redeemed

• Redeemed—asset has already been redeemed

• Deactivated—asset was deactivated by the business

• Expired—asset’s expiration date has passed

• Future—asset is only valid from a future date

• In progress—asset cannot be redeemed in this purchase

String Always

image URL of the asset’s image String Always

validFrom Date and time from which the asset can be redeemed DateTime Always

validUntil Expiration date and time of the asset DateTime Always

redeemDate Date on which the asset was redeemed (returned only when the

status is Redeemed) DateTime Sometimes

redeemable Shows if the asset can be redeemed (returned only when the

query includes expand=assets.redeemable) Boolean Sometimes

nonRedeemableCause

When redeemable is false, object containing details of why the

asset cannot be redeemed, with these properties:

• code: Error code corresponding to the reason that the asset

cannot be redeemed (String)

• message: Reason the asset cannot be redeemed (String)

Sometimes

a s s e t s | 37


Example

{ "assets": [ { "key": "3T6qGoLjHV7RRKkdfLLmH09CGve9AkVIa46R9BWhro8", "name": "$10 off purchase", "description": "Get $10 off a purchase over $40", "status": "Active", "image": "https://storage-download.googleapis.com/server-prod/images/giftimg.jpg", "validFrom": "2017-01-09T07:56:14Z", "validUntil": "2017-12-01T07:56:14Z", "redeemable": true } ] }

d e a l s | 38


deals

deals is an object which represents reusable benefits or promotions that customers automatically

receive (like 10% off for all club members). It is used in two ways:

1. getBenefits Response

In the response of the getBenefits API call, deals is an array of objects representing benefits that

should be applied to a customer’s purchase.


key Unique identifier for the deal—that should be sent in the

submitPurchase call if the deal was applied to the purchase String Always

name Human readable deal name String Always

benefits Array representing the benefits provided to the customer Benefits Always

2. submitPurchase Request

In the request of the submitPurchase API call, deals is an array of objects representing benefits that

were applied to a customer’s purchase (from the deals returned in the getBenefits call).


key Unique identifier for the deal—that was returned in the getBenefits call String Y

appliedAmount Discount amount applied to the purchase from the getBenefits deals Integer Y

{ "deals": [ { "key": "kjdsfh8734yrb34feh34", "name": "Spend $20 and get a free coffee", "benefits": [ { "type": "dealCode", "code": "1234" } ] }, { "key": "kjdhf984u3rjh9ujf3", "name": "10 percent off the purchase", "benefits": [ { "type": "discount", "sum": -200 } ] } ] }

d e a l s | 39


{ "deals": [ { "key": "kjdsfh8734yrb34feh34", "appliedAmount": 0 }, { "key": "kjdhf984u3rjh9ujf3", "appliedAmount": -200 } ] }

r e d e e m A s s e t s | 40


redeemAssets

redeemAssets is an object which represents personal one-time benefits that the customer wants to

redeem (like a coupon for $5 off their purchase). It is used in three ways:

1. getBenefits Request

To redeem a customer’s assets (gifts), the POS sends the getBenefits API call with the redeemAssets

array, where each array item points to an asset either by code or by key (but not both).


code

Code given by the customer to the POS—which was generated

from their app or presented on a coupon

Note: Either code or key should be sent, but not both.

String

Y

key Asset key provided in the response of the getMemberDetails call


String

{ "redeemAssets": [ { "code": "2003" }, { "code": "7689" }, { "key": "50i0JIztJ2jbTrMnhrv0LGSbzwY6cqXVBzhrnM48" } ] }



2. getBenefits Response

redeemAssets is then returned with additional fields specifying the benefits that should be applied to

the customer’s purchase, or indicating that the asset isn’t redeemable and why.


code

Code given by the customer to the POS—which was

generated from their app or presented on a coupon

Note: Either code or key is always returned, but not both.

String

Always

key

Asset key provided in the response of the getMemberDetails

API call

Note: Either code or key is always returned, but not both.

String

name Human readable name of the asset String Always

redeemable Shows if the asset can be redeemed Boolean Always

nonRedeemableCause

When redeemable is false, object containing details of why the

asset cannot be redeemed, with these properties:

• code: Error code corresponding to the reason that the

asset cannot be redeemed (String)

• message: Reason the asset cannot be redeemed (String)

Sometimes

benefits Represents the benefits that should be provided to the

customer (corresponding to the asset they want to redeem)

Benefits Always

{ "redeemAssets": [ { "code": "2003", "name": "Free Coffee", "redeemable": true, "benefits": [ { "type": "discount", "sum": -10 } ] }, { "key": "50i0JIztJ2jbTrMnhrv0LGSbzwY6cqXVBzhrnM48", "name": "Sandwich Deal", "redeemable": false, "nonRedeemableCause": { "code": "5501", "message": "The asset was redeemed" } } ] }



3. submitPurchase Request

redeemAssets should be also sent in the submitPurchase call—with all the assets (gifts) the customer

successfully redeemed in the purchase (with the fields below). This allows Como to mark the assets as

used (since assets can only be redeemed once).


code

Code given by the customer to the POS—which was generated from

their app or presented on a coupon


String

Y

key Asset key provided in the response of the getMemberDetails API call


String

appliedAmount Discount amount corresponding to the redeemed asset Integer Y

{ "redeemAssets": [ { "code": "2003", "appliedAmount": -10 } ] }

b e n e f i t s | 43


benefits

benefits is an array of objects representing the benefits provided to the customer when redeeming

assets (gifts) or using deals— such as a free coffee and 10% off their purchase. This array is returned

in the getBenefits API call (part of deals or redeemAssets).

Properties


type

Indicates how to apply the benefit to the purchase—options are:

• discount: discounts defined and calculated by Como (such as a

percentage or fixed amount off the entire purchase or specific

items)

• itemCode: used for actual catalog items in the POS system (like

an item with a lower price, zero price or negative price)

• dealCode: activates the POS's promotion system (like fixed

discounts, percentage discounts or triggers for POS

promotions)

String Always

sum Amount by which to discount the purchase when the type is

discount (negative sum) Integer Sometimes

code Code to add or activate on the purchase when the type is either

itemCode or dealCode String Sometimes

extendedData

Array representing the breakdown of how the discount should be

allocated to specific items in the purchase—returned only when

type is discount and expand=discountByDiscount is passed in the

query (see Discount Implementation)

ExtendedData Sometimes

ExtendedData Properties


item Object representing to the item that was discounted Item Always

discount Total discount that should be applied to the lineId

(negative sum) Integer Always

discountedQuantity

Number of items that are discounted from the items

corresponding to the lineId sent by the POS. Note: This

can be different than quantity due to discount

configurations in the Como management console

Integer Always

discountAllocation Array of different discount rates for the lineId since each

item can be discounted differently DiscountAllocation Always



Item Properties


code Item code corresponding to the lineId item code sent by the POS String Always

quantity Quantity corresponding to the lineId quantity sent by the POS (even if

not all the items are discounted) Integer Always

netAmount Sum corresponding to the lineId sent by the POS Integer Always

lineId Line reference number corresponding to the line item that is discounted String Always

DiscountAllocation Properties


quantity Number of items corresponding to a specific discount rate (unitDiscount) Integer Always

unitDiscount Discount rate applied to each item from the corresponding quantity in

the discountAllocation array Integer Always

Examples

Without extendedData:

{ "benefits": [ { "type": "dealCode", "code": "1234" }, { "type": "discount", "sum": -10 } ] }



With extendedData:

{ "benefits": [ { "type": "discount", "sum": -700, "extendedData": [ { "item": { "code": "222", "quantity": 2, "netAmount": 3000, "lineId": "1" }, "discount": -300, "discountedQuantity": 2, "discountAllocation": [ { "quantity": 2, "unitDiscount": -150 } ] }, { "item": { "code": "111", "quantity": 1, "netAmount": 4000, "lineId": "2" }, "discount": -400, "discountedQuantity": 1, "discountAllocation": [ { "quantity": 1, "unitDiscount": -400 } ] } ] }

m e a n s O f P a y m e n t | 46


meansOfPayment

An array of payments that were made for the purchase (sent in the submitPurchase call under

purchase). This array should also include the payments that were made using the payment call, if they

were applied as a mean of payment (and not discount).

Properties


type Type of the payment—such as cash, credit_card,

cheque, memberCredit, etc. String Y

details Additional info like the payment confirmation number String N

amount Sum of the payment in cents Integer Y

paymentCard Object containing additional info on the payment card

used (such as credit card, debit card, etc.) PaymentCard N

PaymentCard Properties


cardType Type of card used (visa, mc, amex, etc.) String N

last4 Last 4 digits of the card number String N

cardholderName Name of card holder appearing on the card String N

first6 First 6 digits of the card number String N

expirationMonth Expiration month on the card String N

expirationYear Expiration year of the card String N

token Token String N

m e a n s O f P a y m e n t | 47


Example

{ "meansOfPayment":[ { "type":"credit_card", "details":"jdfv87rnf8f", "amount":2000, "paymentCard":

{ "cardType":"VISA",

"last4":"1234", "cardholderName":"Jane Smith", "first6":"458023", "expirationMonth":"02", "expirationYear":"2020", "token":"12kjfg843krjf90f" } }, { "type":"memberCredit", "amount":1000 } ] }

P O S C o n f i g u r a t i o n s | 48


POS Configurations

API Settings

The business should be able to configure certain settings on the POS to support their specific needs.

Topic Setting Default

General If to show a pop-up at the start of each transaction to ask if they are a

member

No

Identification Which identification methods to display and the names All methods

If to show gifts or member details first after identification Member details

Gift List If to show all active assets or only redeemable assets in the gift list All active assets

Member Details Which membership details to display in addition to the default

First name, last name,

customer identifier,

status, points, credit

Points/Credit If to show the payment screen for points/credit Yes

If to apply a point/credit payment as a discount or mean of payment* Discount

Mobile Payments If to show the payment screen for mobile payments Yes

If to apply a mobile payment as a discount or mean of payment* Mean of payment

Registration If to use the registration flow, and if so, the membership item code Yes

Purchase

Which purchase attributes to send as purchase tags None

Which item attributes to send as item tags None

If to send submitPurchase with status=open before purchase is finalized No

If to send getBenefits for non-members** No

If to send submitPurchase for non-members** Yes

* Only required in tax-excluded countries (see Tax-Excluded Countries)

** When non-members request to redeem assets, both getBenefits and submitPurchase should be

sent regardless of these configurations

Translations

The POS should allow each business to translate and present translations for any text presented on

the POS interface to support the Como API.

M a i n F l o w | 49


Flows The POS should support all the outlined flows—including the settings chosen by the business.

Main Flow

Step 1: Identify the member

1. The cashier selects to identify a member.

2. The cashier enters the member identifier.

3. The POS sends the getMemberDetails request (without returnAssets), with the following URL: https://api.prod.como.com/api/v4/getMemberDetails

Note: If the business configures to display the gift list first after identification (API settings),

then the request should be sent with returnAssets. Each time the cashier selects to display

the gift list, a new getMemberDetails request should be sent (to refresh the gift list which can

include different gifts).

UI Recommendations

There should be an option to allow

non-members to use coupon codes

without identifying (ex: Add Coupon

Code button).

UI Recommendations

The business configures which identifiers

to display and the names (API settings).



4. If the request succeeds: the POS displays the customer details and memberNotes (if sent).

5. If the request fails: the POS displays an error.

Step 2: Select gifts to redeem

The cashier can select the gifts that the member wants to redeem in two ways: by entering the

redeem codes (generated from the app), or by selecting the gifts directly from the gift list on the POS.

1. To select gifts using codes: the cashier enters the redeem codes.

UI Recommendations

Display:

• first name

• last name

• identifier (ex: phone number)

• status

• points (“pointsBalance” – monetary)

• credit (“creditBalance” – monetary)

• any other fields chosen by the business (see API settings)

Note: Both balances should be divided by 100 and display 2 decimal places. There should also be an indication for which balance is used for payment (ex: $)

UI Recommendations

Display:

• customer identifier (to discover typos)

• cancel button (so the invalid identifier will not be sent with purchase details)

• try again button

UI Recommendations:

If a customer wants to redeem multiple

gifts, all codes should be entered into the

same screen.



2. To select gifts from the gift list:

• The POS sends the getMemberDetails request, with the following URL: https://api.prod.como.com/api/v4/getMemberDetails?returnAssets=active

• The POS displays all assets (gifts) and the cashier selects which to redeem.

3. The POS saves the redeem codes and asset keys (corresponding to the gifts selected) and

displays a message to indicate that the discounts are only applied before payment.

Step 3: Apply benefits

Benefits corresponding to deals or selected gifts are applied to the purchase (see Discount

Implementation).

1. Upon “subtotal” (and after all non-Como discounts are applied), the POS sends a getBenefits

request (including any gifts that the member requested to redeem in Step 2).

2. If the request succeeds:

• All benefits in the response are applied to the purchase.

• For redeemAssets with redeemable as false, the POS displays an error.

3. If the request fails (indicating an error processing the request), the POS displays an error.

UI Recommendations

For each asset, display:

• name

• status

• validFrom

• validUntil

• image

UI Recommendations:


• gift name

• message and code from the nonRedeemableCause object



Note: If getBenefits is sent multiple times (ex: shopping cart is changed after subtotal), it should

include the same asset keys/codes unless the cashier explicitly changed the selections.

Step 4: Pay with points or credit

1. When the cashier selects to pay with points/credit, the POS displays a payment screen.

2. The cashier enters the verification code (that the member generated from the app or

received by SMS) and confirms (or edits) the payment amount.

Note: Since a verification code is not mandatory in all cases, entering this code should not be

mandatory on this screen (although this field should always be displayed).

3. The POS sends a payment request.

4. If the request succeeds: the payment amount is applied to the purchase (as either a discount

or mean of payment, according to the paymentMethod in the response) and the POS displays

a pop-up with the updated balance.

Note: The amount that should be applied should be taken from the response since it may be

less than the requested amount (if the customer didn’t have enough in their balance).


Step 5: Send a final submitPurchase

After the final payment, the POS sends a submitPurchase request with status as final.

UI Recommendations

Display:

• Either monetary points or credit balance (whichever has usedByPayment as true)

• payment amount should be autofilled but editable (with no limit for a max amount)

• “Generate Code” button—This button should trigger a payment request without a verification code. Although Como returns an error “Pending verification code”, this triggers Como to send an SMS to the member with a code. Once the member gives the code to the cashier, another payment request can be sent.

N o n - M e m b e r s | 53


Non-Members

Non-members can also perform Como related actions—such as redeem gifts (using third party codes).

Their purchase details also provide the business with actionable data and BI. The business can

configure whether or not to send the getBenefits or submitPurchase calls for non-members (API

settings). However, getBenefits and submitPurchase should always be sent for members who request

to redeem assets.

Step 1: Enter coupon codes

1. The cashier selects to enter a coupon code.

2. The cashier enters the coupon codes.

3. The POS saves the coupon codes.


Benefits are applied to the purchase as in Step 3 of the main flow.


After the final payment, the POS sends a submitPurchase request with status as final.

UI Recommendations

There should be an option to allow non-

members to use coupon codes without

identifying (ex: Add Coupon Code button).

UI Recommendations:

If a customer wants to redeem multiple

gifts, all codes should be entered into the

same screen.

R e f u n d s / V o i d s | 54


Refunds/Voids

Before a purchase is complete, specific items or the entire purchase can be voided. Once the

purchase is complete, customers may be able refund their entire purchase or only specific items

(depending on the business’ refund policy and local legal requirements).

Refund Purchases

Once a purchase is completed (after submitPurchase was sent with status=final), customers can

refund their entire purchase using the cancelPurchase call. However, if a payment was made using

the payment call, it is not cancelled unless the cancelPayment call is also sent.

Refund Items

Once a purchase is completed (after submitPurchase was sent with status=final), customers can

refund specific items in a separate transaction using the submitPurchase call. The refunded items

should be sent in a new transaction as follows:

• action should be refund

• quantity should be negative

• grossAmount should be negative

• netAmount should be negative

Void Items

Before a purchase is completed (before submitPurchase is sent with status=final), the cashier can void

specific items in the same transaction—for example, if a mistake was made or if the customer

changed their mind. In this case, the POS should clean the shopping cart before sending the

submitPurchase request—sending only the items that were actually purchased.

Void Purchases

Before a purchase is completed (before submitPurchase is sent with status=final), the cashier can void

the entire purchase using the voidPurchase call. For example, if customers change tables in a

restaurant, the waiter can void the current transaction and open a new one. If the customer

requested to redeem a gift in the first transaction and getBenefits was sent, sending voidPurchase

“unlocks” the gift so they can now redeem it in the new transaction.

M u l t i p l e M e m b e r s | 55


Multiple Members

Multiple members can participate in the same transaction. The member whose details are currently

displayed on the POS is the “main member” on the purchase. The “main member” on the purchase

should be controlled from a single place—the member details screen.

Step 1: Identify all members

Step 1 from the main flow is performed for each member separately—where each getMemberDetails

request includes only the member currently being identified.

Step 2: Select gifts to redeem

Step 2 of the main flow is performed for each member that wants to redeem a gift. The cashier can

change the “main member” on the purchase to view and select their gifts.


Step 3 of the main flow is performed for all members together—so the getBenefits request includes

all the selected gifts (from all members). However, the “main member” should be passed first in the

customers array since only the deals of the “main member” are returned.

Step 4: Pay with points or credit

Step 4 of the main flow is performed for each member that wants to pay—where each payment

request includes only the member currently paying (“main member”). The cashier can change the

“main member” on the purchase to use their payment balance.


Step 5 of the main flow is performed for all members together—where all members should be passed

in the customers array but the “main member” should be passed first.

UI Recommendations

Display:

• Option to add another member to the purchase (ex: “add member” button)

• Option to change the “main member” on the purchase (ex: drop-down menu)

R e g i s t r a t i o n | 56


Registration

New members can register to the club using the POS puchase registration flow—where the customer

is registered only after the POS sends the submitPurchase call with their phone number and a specific

membership item.

Note: If additional members are identified on a purchase that’s used to register a new member, the

registration will not succeed.

Step 1: Try to identify the customer

The customer tries to identify using their phone number—using step 1 of the main flow. Once the

POS receives an error (since the customer is not found), the POS displays a message with the option

to register the new member.

Step 2: Add membership item

The cashier selects to register the customer and the POS automatically adds a membership item to

their cart.

Note: The membership item is a dedicated item that the business adds to their catalog (either as a

paid item or free item). The membership item code is specified in the API settings.


Step 3 of the main flow is performed.


After the final payment, the POS sends a submitPurchase request with status as final—including the

customer’s phone number in the customers array.

Once Como receives the submitPurchase call with an unregistered phone number and the

membership item, the customer is either automatically registered or receives an SMS with a code to

enter into their app to register (based on the flow the business selects via Como).

UI Recommendations

Display:

• customer identifier (to discover typos)

• register button

• cancel button (so the invalid identifier will not be sent with purchase details)

• try again button—since in many cases, the error occurs because of a typo

A d v a n c e d P a y m e n t | 57


Advanced Payment

In addition to paying with points or credit, members can pay with mobile payments.

Pay with Mobile Payments

Businesses can allow members to pay for their purchases using mobile payments—where members

can pay with credit cards that they added to their app. To secure these payments, members are

usually required to provide a verification code that they generate from their app. Learn more.

1. When the cashier selects to pay with mobile payments, the POS displays the payment screen.

2. The cashier enters the payment code (that was generated from the app) and confirms (or

edits) the amount.

3. The POS send a payment request.

4. If the request succeeds: the payment amount (from the response) is applied towards the

purchase.


UI Recommendations

Display:

• payment amount should be autofilled but editable

• payment code field should be displayed but not mandatory to fill out


R e d e e m a b l e G i f t L i s t | 58


Redeemable Gift List

Instead of presenting a gift list with all active assets (as in step 2 of the main flow), the business can configure in API settings to display only redeemable assets. In this case, the gift list includes only assets that satisfy advanced redeem conditions based on shopping cart. To show only redeemable assets, the POS sends the getMemberDetails request with: • https://api.prod.como.com/api/v4/getMemberDetails?returnAssets=active&expand=assets.rede

emable

• Purchase details are required to validate redeem conditions based on shopping cart If the request succeeds, only assets with redeemable as true should be presented in the gift list. Note: Each time the cashier selects to display the gift list, a new getMemberDetails request should be sent. Refreshing the gift list is essential since changes in the shopping cart can change which gifts are “redeemable” (and which gifts are displayed).

G i f t L i s t I n q u i r i e s | 59


Gift List Inquiries

To allow the cashier to address customer inquiries regarding gifts that don’t appear in the gift list

(expired gifts, gifts that don’t meet the current conditions, etc.), the following flow should be

supported.

1. The cashier selects to display only inactive/non-redeemable gifts.

2. The POS sends the getMemberDetails request according to the API settings for whether the

gift list includes all active assets or only redeemable assets.

In other words, if the gift list displays all active assets, this list should display inactive assets. If

the gift list displays only redeemable assets, this list should displays only non-redeemable

assets.

Display URL Body

All inactive assets https://api.prod.como.com/api/v4/getMemberDetails?returnAssets=inactive

Only non-redeemable

assets

https://api.prod.como.com/api/v4/g

etMemberDetails?returnAssets=inact

ive&expand=assets.redeemable

Purchase details are required to check

which assets cannot be redeemed

based on shopping cart

3. The POS displays the inactive/non-redeemable gift list.

UI Recommendations

For all inactive assets, display all assets from

the response. For only non-redeemable

assets, display only assets with redeemable

as false.


• name

• status

• validFrom

• validUntil

• image

D i s c o u n t I m p l e m e n t a t i o n | 60



Customers can receive discounts in different ways—from the POS promotion system (non-Como),

Como benefits (deals and gifts) and Como payments applied as discounts.

Order of Discounts

Discounts should be applied to a customer’s purchase in the following order:

For Como benefits, deals should be applied before gifts. If the member requested to redeem a gift but

there is no discount left to apply (ex: relevant items are already free), the gift should not be passed in

submitPurchase at all so that the member can redeem it in a different purchase.

Note: The total discount applied for each item (Como or other) should not be greater than the item price.

Re-applying Discounts

If getBenefits needs to be sent again (ex: shopping cart is changed after subtotal):

1. Clear all discounts from the purchase (including Como benefits and discount payments)

2. Send cancelPayment if a payment was applied as a discount

3. Send a new getBenefits request—including the same asset keys/codes unless the cashier

explicitly changes the selection

Discount Allocation

Discounts should be allocated to the right items since Como rewards are based on which items are

discounted. For example, members can accumulate points at different rates for different items (ex:

10% on dairy, 5% on meat), or not receive punches for free items. Discount allocation also enables

accurate tax calculation for items that are taxed differently, and showing customers which items were

discounted.

The POS should reflect all discounts in the item price (netAmount). For Como benefits, discounts

should be: a) allocated according to extendedData, b) displayed to the customer according to the

specific deal or gift, and c) reported in submitPurchase in redeemAssets and deals.

Note: If the POS cannot allocate discounts as described due to technical limitations, contact the Como integration team to discuss which options are available.

T a x - E x c l u d e d C o u n t r i e s | 61



For countries in which item prices are presented without tax, the POS should report certain amounts

without tax—so that benefits are calculated accurately and payments are properly applied.

Purchase

Amounts related to the item prices should be reported without tax—so Como can properly calculate

benefits like gifts and deals.

• In purchase: totalAmount should exclude tax.

• In items: grossAmount and netAmount should exclude tax.

However, the total tax on the purchase should be reported in totalTaxAmount in purchase.

Payments

Each business can configure whether a specific Como payment type (ex: points) should be applied as

a discount or as a mean of payment. This affects whether the payment is applied before or after tax.

To ensure the payment is properly applied, the following is required from the POS:

• Setting per business if to apply a specific payment type as a discount or mean of payment

• Separate payment screens for each payment type

• Payment amount in each payment screen should be autofilled according to the setting:

→ for discounts, the payment amount should exclude tax

→ for means of payment, the payment amount should include tax

For example, suppose the business configures in the POS settings that points should be applied as a

discount. In the dedicated point payment screen, the POS autofills the payment amount as the

amount without taxes. However, the amount should still be editable.

V e r s i o n C h a n g e s | 62


Version Changes Below is a summary of the changes that were made in the API doc since the last version (4.2.4).

Version Updates (4.3.0)

Gift Cards • Gift card functionality was removed from the document

submitPurchase • New object was added to meansOfPayment when the payment is made

using a card: paymentCard

API Settings • Separate settings for whether or not to send getBenefits or

submitPurchase for non-members, including the clarification that both

API calls should be sent when the non-member requests to redeem an

asset in the purchase

Version Updates (4.2.4)

General Guidelines • Clarification that the time-out mechanism should be around 5-10secs

• Clarification for the guaranteed delivery mechanism of submitPurchase

regarding when to try sending it again

To view a summary of the changes that were made in the API doc since the older versions, click here.

http://como-api-doc.s3.amazonaws.com/Como_Latest_API/API%20Version%204.0/Como%20API%20v4%20-%20Version%20Changes.pdf

www.como.com

NEW FEATURES & UPDATEScomo-api-doc.s3.amazonaws.com/Como_Latest_API/API Version...C o m m u n i c a...

Documents

Transcript of NEW FEATURES & UPDATEScomo-api-doc.s3.amazonaws.com/Como_Latest_API/API Version...C o m m u n i c a...