NEW FEATURES & UPDATES - como-api-doc.s3.amazonaws.comcomo-api-doc.s3.amazonaws.com/Como API/Advanced API Docs 4.0/Latest... · payment To pay for purchases using credit, points,

Self-Service API Version 4.2.0

Table of Contents | submitPurchase | getBenefits | getMemberDetails | payment

Table of Contents

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

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

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

Request Format – Basic Calls .............................................................................................................. 2

Request Format – Advanced Calls ...................................................................................................... 3

Response Format & Errors ................................................................................................................. 3

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

Program Features .............................................................................................................................. 4

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

Program Workflow............................................................................................................................. 5

General Guidelines ........................................................................................................... 6

Monetary Values ............................................................................................................................... 6

Displaying Balances ............................................................................................................................ 6

Date Standard and Format ................................................................................................................. 6

Synchronous Execution ...................................................................................................................... 6

Empty Fields ...................................................................................................................................... 7

Specification – Basic API Calls ........................................................................................... 8

getMemberDetails call ....................................................................................................................... 8

getBenefits call ................................................................................................................................ 12

payment call .................................................................................................................................... 16

cancelPayment call .......................................................................................................................... 19

submitPurchase call ......................................................................................................................... 22

voidPurchase call ............................................................................................................................. 26

Specification – Advanced API Calls .................................................................................. 27

sendIdentificationCode call .............................................................................................................. 27

Field Details.................................................................................................................... 28

customer ......................................................................................................................................... 28

purchase.......................................................................................................................................... 30

items ............................................................................................................................................... 31

membership .................................................................................................................................... 33

assets .............................................................................................................................................. 35

deals................................................................................................................................................ 37

redeemAssets .................................................................................................................................. 39

benefits ........................................................................................................................................... 42

meansOfPayment ............................................................................................................................ 45


Additional Setup............................................................................................................. 47

Common Identifiers ......................................................................................................................... 47

Web View URL Parameters .............................................................................................................. 47

Registration iFrame.......................................................................................................................... 48

Configurations ................................................................................................................ 50

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

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

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

Identification ................................................................................................................................... 51

Main Flow........................................................................................................................................ 53

Member Profile ............................................................................................................................... 56

Gift List ............................................................................................................................................ 57

Members & Program Terms ............................................................................................................. 58

Non-Members ................................................................................................................................. 60

Voids ............................................................................................................................................... 61

Registration ..................................................................................................................................... 62

Advanced Payment .......................................................................................................................... 63

Discount Implementation................................................................................................................. 66

Tax-Excluded Countries .................................................................................................................... 67

Version Changes ............................................................................................................. 68

Version Updates (4.2.0) ................................................................................................................... 68

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


Introduction This document describes how Como Sense can be integrated with self-service solutions—such as

ordering websites or self-service kiosks.

The self-service API includes the following basic API calls:

getMemberDetails

getBenefits

payment

cancel payment

submitPurchase

voidPurchase

It also includes the following advanced API call for self-service flows:

sendIdentificationCode

Note: This document will refer to all self-service platforms as “ordering service”, although the content

is relevant for all customer-facing solutions.

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


Communication Format

Identification & Protocol

This 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 – Basic Calls

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

1 2 3

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

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


Request Format – Advanced Calls

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

1 2

1. API server host

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

Headers


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 N

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

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

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

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

Response Format & Errors

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. View All Error Codes

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

https://api.prod.como.com/api/v4/advanced/apiCall

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

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

P r o d u c t & A P I C a l l O v e r v i e w | 4


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

(like 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 control panel for app creation, campaigns and analytics. The loyalty program

offers members rewards and incentives like gifts, punch cards, and points.

Program Features

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

Gifts Gifts are items members can redeem from 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 program, 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 self-

service display.

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 from the business. Businesses can also allow members to buy points, or buy

items from 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 from 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/Como%20Mobile%20Payments%20in%20Store.pdf

P r o d u c t & A P I C a l l O v e r v i e w | 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 members 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 payments made using credit, point, or mobile payments

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

punch cards, etc.)

voidPurchase To void a transaction before the purchase is completed

sendIdentificationCode To secure member identification by sending them a temporary code by SMS/email

Program Workflow

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

1. The member securely identifies, and member gifts and basic details are displayed.

2. The member adds items to their shopping cart.

3. The member can choose which gifts to redeem from their gift list.

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

5. The member pays using regular means, 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 | 6


General Guidelines

Monetary Values

All monetary values (like 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 ordering service in the smallest unit of measurement (like cents).

Divide all balances by 100 when displaying them, 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 ordering service 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 of open—

should be handled synchronously. The ordering service is required to implement a time-out

mechanism for when the response is not received within a reasonable amount of time (around 5-10s,

taking into account the internal environment routing times of the ordering service).

For the submitPurchase call with status of 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 ordering service

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


Empty Fields

The ordering service 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 | 8


Specification – Basic API Calls

getMemberDetails call

Description

Purpose To verify the customer is a member, present their member details (name, points,

etc.) and present their gift list (to allow them to select which gifts to redeem)

When to Use • To verify the customer is a program 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 member

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

getBenefits call and redeemed using the submitPurchase call.

Related Flows Identification

Main Flow

Registration

Gift List

Member Profile

Members & Program Terms

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 customer with status as active

• inactive—assets of customer with any status except active

• all—assets of customer with any 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 assets, indicating if the asset is currently in a redeemable state and if not,

why (requires returnAssets in query and purchase in 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: Ordering X-Source-Name: Ordering 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, 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 | 12


getBenefits call

Description

Purpose 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.

Applying Discounts

• The ordering service 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.

Related Flows Main Flow

Registration

Non-Members

Discount Implementation


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: Ordering X-Source-Name: Ordering 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 | 16


payment call

Description

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

payments

When to Use When the member selects to pay with Como payments

Notes


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: The field is not always required for mobile payments and

point/credit payments. More

String N

amount Requested amount to pay in cents.

Note: See Tax-Excluded Countries Integer Y

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

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



Request Example

POST https://api.prod.como.com/api/v4/payment?mode=pay HTTP/1.1 Content-Type: application/json X-Api-Key: 3f09101f X-Branch-Id: 67 X-Pos-Id: 89 X-Source-Type: Ordering X-Source-Name: Ordering 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 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 | 19


cancelPayment call

Description

Purpose Allows the ordering service to cancel a Como credit/point/mobile payment using

the confirmation code from the payment call

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

Notes

Related Flows 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: Ordering X-Source-Name: Ordering 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 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 | 22


submitPurchase call

Description

Purpose To send Como final purchase details (amount paid, complete cart, etc.)—used by

Como to segment members or perform actions on them, like automatically punch

their punch cards (based on specific items in the cart), give points or 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 program,

guaranteed delivery is required for submitPurchase with status=final if

Como returns an error that begins with 5xx (Como server error), or if there’s a

communication error on the side of the ordering service.


Registration

Non-Members

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: Ordering X-Source-Name: Ordering 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 after the purchase is finalized (such as after an order is

submitted or in a confirmation email), 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" } ]

}

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


voidPurchase call

Description

Purpose To void a transaction before it is complete (before the submitPurchase call is sent

with status=final).

When to Use When the transaction is voided

Notes Cancelling Payments

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

is voided using the voidPurchase call (before the final submitPurchase is sent),

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

Related Flows Voids

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: Ordering X-Source-Name: Ordering 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

s e n d I d e n t i f i c a t i o n C o d e c a l l | 27


Specification – Advanced API Calls

sendIdentificationCode call

Description

Purpose To trigger Como to send the customer their temporary identifier through SMS or

email, to secure member identification.

When to Use When the member logs into ordering service via desktop or kiosk

Notes Secured Identification

When a customer identifier is passed in this API call (such as phoneNumber), a

temporary code (appClientId) is sent to the member (such as by SMS). This code

can then be passed in the getMemberDetails call to secure their identification.

Related Flows Identification

Request Format



customer Object representing a member’s identifier (only phone number or

email in this case) Note: Only one identifier should be sent. Customer 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/advanced/sendIdentificationCode HTTP/1.1 Content-Type: application/json X-Api-Key: 12345678 { "customer":{ "phoneNumber":"2128782328" } }

{ "status":"ok" }

c u s t o m e r | 28


Field Details

customer

customer is an object representing a Como member identifier. By passing customer to API calls,

Como will process the API call using the identified customer. For the sendIdentificationCode API call,

only phoneNumber and email are supported.

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

Properties (Types of Identifiers)

Field Description

phoneNumber Customer’s phone number

email Customer’s email address

temporaryToken Temporary token used for websites integrated into the business’ app (ex: ordering)

commonExtId Internal member identifier, returned in getMemberDetails or from registration iFrame

appClientId Temporary ID that the member generates from their app (as a barcode, QR code or number) or receives by SMS/email as a number

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

Examples

customers array

customer object

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

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

p u r c h a s e | 29


purchase

purchase is an object representing the customer’s purchase details, sent in all basic API calls.


transactionId

Transaction identifier from the ordering service

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

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 | 30


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

grossAmount = (gross price per item) x (quantity or weight)

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

Note: See Tax-Excluded Countries

Integer Y

netAmount

netAmount = (net price per item) x (quantity or weight)

Total amount after any Como or other discounts were applied

(in cents)

Note: See Tax-Excluded Countries

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 | 31


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 | 32


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 program membership expires Date Sometimes

status Member’s program 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 | 33


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 ordering service in the smallest unit of measurement (such as

cents). The ordering service is responsible to divide all balances (including points) by 100 when

displaying them, and display 2 decimal places.

a s s e t s | 34


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). Unlike deals, assets

are personal benefits that the member receives, and are only for one-time use.

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

in order to display 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

status is Redeemed) DateTime Sometimes

redeemable

Shows if the asset can be redeemed in this purchase according

to the redeem conditions specified by the business—such as

based on shopping cart items, location, times of day, etc.

Note: This flag is 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 | 35


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 | 36


deals

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

receive (like 10% off for all program members). Unlike assets, members do not need to request to

use deals since all relevant deals are automatically applied to their purchase. 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

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


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

Note: If a specific benefit (returned in getBenefits) was not applied to the purchase at all, it should

not be passed in submitPurchase. If a specific benefit was applied and the benefit type was

itemCode or dealCode, it should be passed with appliedAmount of 0.


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

Note: Field should be 0 only if the benefit type is itemCode or

dealCode.

Integer Y

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

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


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 ordering service 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 entered by the customer—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 entered by the customer—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).

Note: If a specific benefit (returned in getBenefits) was not applied to the purchase at all, it should

not be passed in submitPurchase. If a specific benefit was applied and the benefit type was

itemCode or dealCode, it should be passed with appliedAmount of 0.


code

Code entered by the customer—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

Note: Field should be 0 only if the benefit type is itemCode or

dealCode.

Integer Y

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

b e n e f i t s | 41


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 ordering

service (like an item with a lower price, zero price or negative

price)

• dealCode: activates the ordering service's promotion system

(like fixed/percentage discounts, or triggers for non-Como

promotions)

String Always

sum Amount by which to discount the purchase when type is

discount (negative sum) Integer Sometimes

code Code to add or activate on the purchase when 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 ordering service.

Note: This can be different than quantity due to

discount configurations in the Como control panel

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 ordering

service String Always

quantity Quantity corresponding to the lineId quantity sent by the ordering

service (even if not all the items are discounted) Integer Always

netAmount Sum corresponding to the lineId sent by the self-service 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 | 44


meansOfPayment

An array of payments 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). These payment types should be passed with the

same values that are returned in the payment call (memberCredit, creditCard, memberPoints, etc.)

Properties


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

memberCredit, etc. String Y

details Additional information like the last 4 digits of the credit

card, the payment confirmation number, etc. 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 | 45


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 } ] }

C o m m o n I d e n t i f i e r s | 46


Additional Setup The following is also required for implementing the Como solution in an ordering service.

Common Identifiers

Como saves data which is relevant to the program and some additional data that may be relevant to

the ordering service. If the ordering service stores member data in their own database (such as past

orders, address, etc.), the external database should uniquely identify the member according to the

commonExtId field. This internal field is returned by Como in the getMemberDetails API call and

from the registration iFrame after new members register. This field is always returned and cannot be

updated (unlike phoneNumber, for example).

Web View URL Parameters

Certain parameters can be passed in the website URL to identify members that open the website

inside the app, and improve the overall customer experience. The following parameters should be

supported. Additional parameters may be available upon request.

Parameter Description

firstName Member’s first name (if provided)

lastName Member’s last name (if provided)

tempToken Token used to identify the member which expires after a period of time specified by the

business in their Como settings

getLat Latitude coordinate of the mobile device

getLong Longitude coordinate of the mobile device

R e g i s t r a t i o n i F r a m e | 47


Registration iFrame

Using the registration iFrame, customers can register to the loyalty program through an external

website—such as the business website or an ordering solution.

Benefits

The iFrame is always synced with the colors and fields chosen by the business in their Como settings.

All the required validations are performed within the iFrame—including mandatory fields, pattern

restrictions, if member is already registered, and validating the phone number or email by code.

The iFrame allows members to view and consent to program terms automatically when they register

(without requiring any additional steps that could negatively effect their experience and conversion).

R e g i s t r a t i o n i F r a m e | 48


iFrame URL

https://appmodules-prod.como.com/register?locationid={locationID}&transparentBackground=true&device=mobile

where the {locationID} should be replaced with the location ID of the specific business

Prefill Fields

Websites can send certain data to prefill in the registration form. Here’s an example:

<html lang="en"> <head> <meta charset="utf-8"> <title>Parent Window</title> </head> <body> <h1>Parent Window</h1> <br/> <iframe id="como-iframe" src="<path-to-como>/register?locationid=<locationId>&token=<token>" height="800" width="800"></iframe> <script> window.onload = function () { var iframeWin = document.getElementById("como-iframe").contentWindow, myMessage = {'Email': '<insert-member-email-here>', 'PhoneNumber': '<insert-phone-number-here>'}; iframeWin.postMessage(myMessage, '*'); }; </script> </body> </html>

Listener

Once registration is completed successfully (after all validations), a member identifier (commonExtId)

is returned which can be used to automatically identify the member after registration using the

getMemberDetails API call. Websites can add a listener to their hosting page and get the success

result message ({result:“success”,commonExtId:”someId”}). For example:

<html> <body> <script> window.addEventListener('message',function(event) { //result structure --> event.data = {result: "success", commonExtId: "someId"} console.log('message received: ' + event.data,event); },false); </script> <h2>HTML Iframe</h2> <iframe id="testIframe" src="<path-to-como>/register?locationid=<locationId>&token=<token>" height="800" width="800"></iframe> </body> </html>

A response is only returned if the registration is successful. If there’s an error in the registration (such

as missing values, existing member, invalid code, etc.), the error is displayed in the iFrame itself.

However, the ordering service should display an “X” or “close” button that closes the iFrame in case

the customer decides not to proceed.

https://appmodules-prod.como.com/register?locationid=3508&transparentBackground=true&device=mobile

https://appmodules-prod.como.com/register?locationid=3508&transparentBackground=true&device=mobile

A P I S e t t i n g s | 49


Configurations

API Settings

The business should be able to configure settings on the ordering service to support their needs.

Topic Setting Default

General If to actively present the login page at the start of each transaction No

Identification If members can receive their temporary ID code (appClientId) by:

a) SMS only, b) email only, or c) either SMS or email

Either SMS or Email

Member Details Which membership details to display in the member profile in addition

to the default

First name, last

name, customer

identifier, status,

points/credit

Wallets If the business uses only one wallet or multiple wallets One wallet

Points/Credit If to show the payment option 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 option for mobile payments No

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

Registration If to present an option for registration 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

If required, the ordering service can provide a translation option for errors and other text presented

on the self-service interface to support the Como API. Translations for error message should

correspond to error codes and not messages (which may change).

I d e n t i f i c a t i o n | 50


Flows

Identification

Identification via Browser or Kiosk

Secure member identification when they identify from a self-service platform (like ordering website

or self-service kiosk).

1. The member generates a temporary code from their app (appClientId), or selects to receive

the code by SMS or email.

Note: There should be a configuration per business whether the member can a) use only

phone number, b) use only email, or c) choose either phone number or email.

2. After the member enters their phone number or email, the ordering service sends a

sendIdentificationCode request.

3. If the request succeeds: the member receives their temporary identification code

(appClientId) either by SMS or email, depending on which identifier they entered.

4. If the request fails: an error should be displayed.

POST https://api.prod.como.com/api/v4/advanced/sendIdentificationCode HTTP/1.1 Content-Type: application/json X-Api-Key: 3f09101f { "customer": { "phoneNumber": "2128782328" } } }

https://api.prod.como.com/api/v4/advanced/sendIdentificationCode

I d e n t i f i c a t i o n | 51


5. After the member enters the code, getMemberDetails is sent with this code (appClientId)

and with returnAssets in the query. If successful, member details and gifts are returned.

Identification via App (Redirect)

When members open the ordering website within their app, they can be securely identified using a

temporary token.

1. When the member opens the app (and is logged into the app), a temporary token is passed in

the URL. For example:

https://www.ordering.com?tempToken=08c34069-63ef-464c-9c67-8304538b382f

2. The ordering service sends a getMemberDetails request with the temporary token. If

successful, the member details are returned.

Member Identifiers & Cookies

Websites can use cookies so members will not need to re-identify during an active session. However,

the temporary identifier (appClientId /temporaryToken) cannot be used for more than one

transaction. If a member starts a second transaction while the cookie is still valid, send

getMemberDetails and all subsequent API calls with commonExtId (which was returned in the

previous getMemberDetails call for this member).

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: Ordering X-Source-Name: Ordering Name X-Source-Version: 3 { "customer": { "appClientId": "1234" } } }

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: Ordering X-Source-Name: Ordering Name X-Source-Version: 3 { "customer": { "temporaryToken": "08c34069-63ef-464c-9c67-8304538b382f" } } }

https://www.ordering.com/?tempToken=08c34069-63ef-464c-9c67-8304538b382f



M a i n F l o w | 52


Main Flow

The member should have the option to perform the following steps at any stage of the ordering

flow—which includes choosing pick up/delivery, entering an address, adding items to the cart, etc.

Step 1: Identify the member

1. The member selects to log in using their phone number or email, which is verified by sending

them a code by SMS or email. If the member opens the ordering website from their app, they

are automatically identified using a temporary token. More on secure identification

2. The ordering service sends a getMemberDetails request (with returnAssets):


3. If the request succeeds: the ordering service displays basic customer info, gifts and

memberNotes (if sent).

4. If the request fails: the ordering service displays an error.

Note: If the customer proceeds with the transaction, the invalid customer identifier should

not be passed in the remaining API calls.

Step 2: Select gifts to redeem

1. The ordering service displays a gift list (getMemberDetails with returnAssets=active) and

the member selects which gifts to redeem.

Note: When the gift list is displayed before items are added to the cart, we recommend

adding a general note on top to indicate that redeeming gifts may depend on conditions

based on shopping cart, location, time, etc. See Gift List for more.

UI Recommendations

Display:

• first name

• last name

• status

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

• memberNotes (if sent)

• member gifts




2. The ordering service saves the asset keys (corresponding to selected gifts) 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 ordering service 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 ordering service displays an error.

3. If the request fails (indicating an error processing the request), an error is displayed.

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

include the same asset keys unless the member explicitly changed the selections.

UI Recommendations

For each asset, display:

• name • description

• status • validFrom

• validUntil

• image

UI Recommendations:

For each asset, display:

• gift name

• message and code from the

nonRedeemableCause object



Step 4: Pay with points or credit

1. The member selects to pay with points/credit, and the ordering service displays a payment

screen.

Note: We’ll assume here that the member identified with appClientId or temporaryToken

and that the business allows payment with only one Como wallet.

2. The member confirms (or edits) the payment amount.

3. The ordering service 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).

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

5. If the request fails: the ordering service displays an error.

Step 5: Send a final submitPurchase

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

Note: All relevant API calls for the ordering transaction should be sent by the ordering service. If

there’s a technical limitation that requires the POS to also send API calls (such as submitPurchase),

contact the Como integration team to discuss available options.

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)

• No input for verification code

M e m b e r P r o f i l e | 55


Member Profile

At any point in the ordering flow, the ordering service should allow members to access their personal

details. These member details are retrieved using a getMemberDetails request.

The member profile should include the following details:

• first name

• last name

• customer identifier (ex: phone number)

• status

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

• memberNotes (if sent)

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

In the member’s personal area, the ordering service can also present additional info saved in their

database such as their address and past orders.

G i f t L i s t | 56


Gift List

At any point, members should be able to view and select which gifts to redeem from their gift list.

Gifts are retrieved using the getMemberDetails call with returnAssets=active in the query.

Note: Each time the member selects to display the gift list, send a new getMemberDetails request.

Redeemable Gifts

All gifts that have the potential to be redeemed are active. Since gifts may depend on conditions (based on specific items, locations, times, etc.), not all active gifts are redeemable in any transaction. Conditions are validated upon subtotal when the cart is complete (via getBenefits call).

• If the gift list is displayed before items are added to the cart, it should include a general note

on top to indicate that redeeming gifts may depend on the shopping cart, location, time, etc.

• If the gift list is displayed after items are added to the cart:

o Send getMemberDetails with the following URL (and purchase details in the body): https://api.prod.como.com/api/v4/getMemberDetails?returnAssets=active&expand=assets.redeemable

o Add a note under each gift returned with redeemable as false, such as “Redeem conditions not yet met”.

Inactive Gifts

The ordering service should also provide members with the option to view inactive gifts—to

undertand why certain gifts don’t appear in their gift list (such as expired or redeemed gifts). Inactive

gifts are retrieved using the getMemberDetails call with returnAssets=inactive in the query, and

the following details should be displayed: name, description, status, validFrom, validUntil, and image.

Display the following details:

• name

• description

• status

• validFrom

• validUntil

• image

https://api.prod.como.com/api/v4/getMemberDetails?returnAssets=active&expand=assets.redeemable

https://api.prod.como.com/api/v4/getMemberDetails?returnAssets=active&expand=assets.redeemable

M e m b e r s & P r o g r a m T e r m s | 57


Members & Program Terms

As a data-driven solution, Como allows businesses to comply with all the relevant privacy regulations.

As such, members must agree to the program terms in order to participate in their loyalty program.

How It Works

When members register through the app or registration iFrame (presented in the ordering site), they

automatically agree to program terms. However, when they register in other ways (such as by quick

registration at the POS), they will receive a link by SMS/email to agree to program terms. New

members who didn’t consent (within a grace period) cannot earn and use program benefits.

Ordering Flows

Here’s the flow for member who didn’t consent to program terms:

1. The member selects to log in using their phone number or email, which is verified by sending

them a code by SMS or email. If the member opens the ordering website from their app, they

are automatically identified using a temporary token. Learn more

2. The ordering service sends a getMemberDetails request.

The response includes values for all the fields that are normally returned, however it won’t

return the details or gifts of this specific member. For example:

{ "status": "ok", "memberNotes": [ { "content": "To use your benefits, accept the program terms (using the SMS/email sent after registration) and login again.", "type": "text" } ], "membership": { "firstName": "No consent", "lastName": "No consent", "commonExtId": "8407cd10-8e3d-4e8a-9061-66f10cfdd403", "createdOn": "2018-08-16T12:16:04Z", "status": "Inactive", "pointsBalance": { "usedByPayment": false, "balance": { "monetary": 0, "nonMonetary": 0 } }, "creditBalance": { "usedByPayment": false, "balance": { "monetary": 0, "nonMonetary": 0 } } } }

M e m b e r s & P r o g r a m T e r m s | 58


3. When getMemberDetails returns (membership) status as inactive: the ordering service

only displays memberNotes from the response (instead of the basic customer info and gift

screen displayed after identification in the Main Flow).

Note: If configured by the business in their Como settings, a link is automatically sent to the

member by SMS/email to allow them to consent to terms.

4. The ordering service proceeds with the transaction as if they are an identified member,

including sending the submitPurchase call with their customer identifier.

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


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

Step 1: Enter coupon codes

1. The customer selects to enter a coupon code.

Note: This option should be available to all customers (whether or not they identified), such

as part of the checkout screen.

2. The customer enters the coupon codes.

3. The ordering service saves the coupon codes.

Step 2: Apply benefits

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

Step 3: Send a final submitPurchase

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

UI Recommendations:

If a customer wants to redeem multiple

gifts, all codes should be entered into the

same screen.

V o i d s | 60


Voids

Before a purchase is complete (i.e., before submitPurchase is sent with status=final), specific items

can be removed from the cart, or the entire purchase can be voided (abandoned). Once the purchase

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

through the business.

Remove Items

Before a purchase is completed, the member can remove specific items from their cart—for example,

if they made a mistake or changed their mind. In this case, the ordering service should clean the

shopping cart before sending submitPurchase—sending only the items that were actually purchased.

Void Purchases

Before a purchase is completed, the entire transaction may be voided—for example, due to a time-

out mechanism, expired cookie or an abandoned cart. In this case, the ordering service should send

the voidPurchase call. This provides Como with an indication that this purchase will not be finalized,

and to release any logic that was applied for this purchase. For example, if the customer requested to

redeem a gift (and getBenefits was sent) and does not proceed with this transaction, sending

voidPurchase “unlocks” the gift so they can now redeem it immediately in a different transaction.

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


Registration

If the business allows registration in their API settings, customers can register to the loyalty program

from a self-service flow using the registration iFrame.

1. The customer selects to register.

2. The customer fills out the registration form (including any validations required) and submits.

3. If the registration is successful, a member identifier is returned (commonExtId).

Note: Websites can add a listener to their hosting page and get the success result message:

({result:“success”,commonExtId:“8407cd10-8e3d-4e8a-9061-66f10cfdd403”}). Read more

4. The ordering solution sends getMemberDetails with the member identifier.

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: Ordering X-Source-Name: Ordering Name X-Source-Version: 3 { "customer": { "commonExtId": "8407cd10-8e3d-4e8a-9061-66f10cfdd403" } } }


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


Advanced Payment

There are various Como payment types: points, credit, and mobile payments (in-app credit cards). To

support the different payment flows, the ordering solution should allow the business to configure

whether they use one wallet for their program (only points/credit or only mobile payments) or

multiple wallets (both points/credit and mobile payments). See API Settings

One Wallet – QuickPay

If the business configures to use only one wallet, the member can pay without a payment code when

they identify by appClientId or temporaryToken. Learn more

1. The member selects to pay with points/mobile payments and the payment screen is

displayed.

2. The member confirms or edits the payment amount, and taps Pay.

Note: For tax-excluded countries, the payment amount should be prefilled with or without

tax according to the business settings for whether each payment type is a discount or mean

of payment.

3. The ordering service sends a payment request.

4. If the request succeeds, the payment amount from the response is applied to the purchase.

5. If the request fails, an error is displayed.

One Wallet – Payment Code

If the member does not identify with appClientId or temporaryToken, then they need to provide a

verification code to pay. For example, if the temporary identifier is no longer valid or after registration

via iFrame, the member will be identified using commonExtId.


displayed.

UI Recommendations

Display:

• payment amount should be autofilled but editable (no max amount)

• No input for payment/verification code should appear




a. For mobile payments:

b. For points/credit:

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

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



UI Recommendations

Display:

• payment amount should be autofilled but editable

• input for verification code

UI Recommendations



• “Generate Code” button— triggers a payment request without a verification code. Although Como returns an error “Pending verification code”, Como will send an SMS

to the member with a code. Once the member gives the code to the cashier, another payment request can be sent.

• Monetary points/credit balance (whichever has usedByPayment=true)



Multiple Wallets – MultiPay

If the business uses both point/credit and in-app credit card payments, the member should provide a

verification code when they pay (no matter how they identify). Learn more


displayed.

a. For mobile payments:

b. For points/credit:

2. The member enters the verification code generated from their app and confirms (or edits)

the payment amount.



UI Recommendations

Display:



UI Recommendations



• Monetary points/credit balance (whichever has usedByPayment=true)


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



Customers can receive discounts in different ways—from the external 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 customer 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 ordering service 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 ordering service 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 | 66



For countries in which item prices are presented without tax, the ordering service 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 ordering service:

• 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 ordering service settings that points should be

applied as a discount. In the dedicated point payment screen, the external platform 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 | 67


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

Version Updates (4.2.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

www.como.com

Documents

NEW FEATURES & UPDATES - como-api-doc.s3.amazonaws.comcomo-api-doc.s3.amazonaws.com/Como API/Advanced API Docs 4.0/Latest... · payment To pay for purchases using credit, points,