0% found this document useful (0 votes)

141 views

Treazure API Documentation 1.18.0

Uploaded by

gognicufye

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

141 views

Treazure API Documentation 1.18.0

Uploaded by

gognicufye

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 101

p

Treazure API documentation

Document version 1.18.0
Cow Hills Retail BV
Leusderend 38 +31 85 77 34 500

3832 RC Leusden [email protected]

The Netherlands www.cowhills.nl

All rights reserved. No part of this publication may be reproduced, distributed, or

transmitted in any form or by any means, including photocopying, records or other
electronical or mechanical methods, without the prior written permission of Cow
Hills Retail B.V.

Cow Hills Retail B.V. KvK 30218521 BTW NL 8169.90.499.B01 IBAN NL03ABNA0453746330 BIC
ABNANL2A
Name Date Change Document
version

P. Vermeulen March 5th 2015 Initial version 0.1

P. Vermeulen March 18th 2015 Minor technical content changes 0.2

P. Vermeulen March 27th 2015 Minor technical content changes 0.3

P. Vermeulen April 1st 2015 Minor technical content changes 0.4

P. Vermeulen April 2nd 2015 Added paragraph for pre-publication in 0.41

PemCalculation API.

P. Vermeulen April 23rd 2015 Added wildcard article characteristics 0.42

P. Vermeulen May 4th 2015 Added shipping costs discount 0.43

P. Vermeulen May 6th 2015 EmployeeCard.DiscountType is no longer 0.44

mandatory

P. Vermeulen May 27th 2015 Added EmployeeCard.Balance 0.45

P. Vermeulen July 10th 2015 Fixed minor grammatical errors 0.46

P. Vermeulen November 16th Added paragraph for timeouts 0.47

2015

R. Groeneveld January 21st 2016 First translation 0.15

R. Groeneveld February 8th 2016 Fixed minor grammatical errors 0.48

P. Vermeulen February 18th 2016 Added giftcard API 1.0 0.5

R. Groeneveld March 10th 2016 Revised all translations 0.51

P. Vermeulen April 6th 2016 Added PRD endpoints, added new Wsdl urls 0.52

P. Vermeulen March 9th 2017 1) Added operation CouponExists. 0.53

2) Added Gid to ref.
3) Added Count to LoyaltyResult.
4) Added TransactionAttributes to
FinancialResult.

R. Groeneveld June 26th 2017 Finalized for publication 1.0

T. Waslijah Juli 10th 2017 Changed CalculationMoment from optional to 1.1

mandatory
Added GiftCard example requests and responses

P. Vermeulen Sep 18th 2017 1) Added UploadCoupons to Coupon-1-0 1.2

service
2) Added CouponActivatedCount to
CouponBatchInfo

© Cow Hills Retail BV Page 2 of 100

3) Added VoidCoupons to Coupon-1-0
service
4) Added return code SyntaxError
5) Added Reloadable to giftcard product
6) Added ActivateWithCardId to giftcard
product
7) Added UploadGiftcards to
GiftcardBackoffice-1-0
8) Added ExtraArticleResult to
PemCalculation-1-0
9) Added ValidUntill to Activate operation
of GiftcardFrontoffice-1-0
10) Added Description to
DiscountVoucherResult,
IssuesCouponResult and
TypeValueResult

P. Vermeulen Sep 21th 2017 1) Added MessageResult to 1.3

PemCalculation-1-0
2) Added BaseAmt to Ref
3) Added BatchMode Manual

P. Vermeulen Oct 2nd 2017 1) Changed commentary for 1.4

EmployeeDiscountType in paragraph
EmployeeCards
2) Added parameters to CreateProduct
operation in Giftcard Backoffice API
3) Added currency to ActivateGiftcard and
RedeemGiftcard operations of Giftcard
Frontoffice API.
4) Added password types OTP and TOTP.

P. Vermeulen Oct 3rd 2017 Minor editorial changes 1.4.1

P. Vermeulen Oct 12th 2017 1) Added MaxLoadAmount and 1.5

BarcodeType to
CreateGiftcardProductParameters
2) Added response to
CreateGiftcardProduct

P. Vermeulen Nov 1st 2017 1) Extended documentation for 1.7.0

parameters for GenerateCoupons
operation
2) Added TRZ-PROMO-TIME Http header
3) Added paragraph about time zones and
local time (3.10)
4) Added paragraphs about coupon and
giftcard uniqueness

P. Vermeulen Nov 2nd 2017 1) Added paragraph regarding backwards 1.7.1

and forwards compatibility
2) Added xs:any to Wsdl-schemas

© Cow Hills Retail BV Page 3 of 100

P. Vermeulen Nov 13th 2017 1) Corrected format of value of TRZ- 1.7.2
PROMO-TIME Http header

P. Vermeulen Nov 16th 2017 1) Added ValidFrom to 1.7.3

GiftcardBatchParameters

P. Vermeulen Nov 17th 2017 1) Added Json endpoints 1.8.0

2) Added Server Status API
3) Added paragraph about Gid (Grouping
identifier)

R. Groeneveld Dec 12th 2017 Updated mandatory request variables 1.8.1

P. Vermeulen Dec 15th 2017 1) Added field Display to FinancialResult 1.8.2

M. Schinkel Dec 28th 2017 1) Added field GiftcardType to Giftcard 1.9.0

2) Added property GiftcardType to request
dataholders
3) Included giftcard type to the services
impl

E. de Jong Feb 14th 2018 Added (optional) FinancialCalculationResults 1.9.1

PemCalculation-1-0 (for display purposes)

P. Vermeulen Mar 13th 2018 1. Adds paragraph about local time and 1.9.3
zonal information in time values
2. Minor additions in paragraph regarding
ActivateGiftcard

R. Groeneveld Nov 16th 2018 Minor editorial changes. 1.9.4

R. Groeneveld Jan 14th 2019 Expanded CouponExists paragraph 1.9.5

R. Groeneveld Jan 16th 2019 Added LoyaltyVault 1.9.6

R. Groeneveld Jan 16th 2019 Expanded Giftcard API with new properties 1.9.7

P. Vermeulen Apr 18th 2019 Add information about Http response codes of 1.9.8
Treazure responses.

P. Vermeulen Jun 20th 2019 Adds UID to sale element 1.9.9

P. Vermeulen Jul 11th 2019 Adds BookingType to FinancialResult 1.10.0

P. Vermeulen Jul 12th 2019 Adds EmployeeBalanceVault-1-0 1.11.0

P. Vermeulen Jul 12th 2019 Adds locking of coupons to specific customers. 1.12.0
Adds employee discount percentage on sale
level.

P. Vermeulen Oct 8th 2019 1. Adds ExpiresBefore and CreatedAfter to 1.13.0

GetCoupons operation.
2.

P. Vermeulen Nov 13th 2019 Adds CouponType to CouponExists operation of 1.14.0

PemCalculation API.

© Cow Hills Retail BV Page 4 of 100

P. Vermeulen May 5th 2020 Adds MutatedSince to GetCoupons operation of 1.15.0
Coupon API.

P. Vermeulen Jul 1st 2020 Added sale count limit of 999. 1.16.0

P. Vermeulen Aug 26th 2022 Added sale max discount percentage 1.17.0

E. de Jong Okt 14th 2022 1. Updated Airmiles Payment options 1.18.0

2. Added Receipt Discount type
‘AirmilesReceiptAmount’

© Cow Hills Retail BV Page 5 of 100

1 Introduction
This document describes the different API’s Treazure offers.

The following API’s are covered in this document:

API Commentary

Authentication This is a general API used for starting and ending sessions. Session are used to
access the different API’s hosted on the platform.

Coupon The coupon API offers couponing functionality, personal/unique codes can be
generated, issued, redeemed and maintained.

CustomerVoucher The CustomerVoucher API is used to redeem vouchers. A customer voucher is a

voucher issued to a customer when a specific promotional event triggers and is
linked to the used customer card.

PemCalculation The PemCalculation API is used to calculate promotional discounts and benefits.
A basket1) is offered to the API and a directly applicable formatted response is
returned.

PemConfiguration The PemConfiguration API is used to configure and maintain promotional events.
This is only used in stand-alone environtments, i.e. this is not used in situations
where the ROS (Retail Online Suite) software is installed.

Giftcard (frontoffice) For loading and redeeming preexisting giftcards.

Giftcard (backoffice) For managing giftcard products and creating individual giftcards.

LoyaltyVault For tracking loyalty balances.

Employee Balance For tracking employee discount balances.

Vault

Server status For obtaining service status.

1) A basket contains the articles, used customer/employee cards and any other relevant information regarding
discounts and benefits.

© Cow Hills Retail BV Page 6 of 100

2 Table of contents
1 Introduction ..................................................................................................................................................... 6
2 Table of contents ............................................................................................................................................. 7
3 General .......................................................................................................................................................... 11
Glossary ............................................................................................................................................... 11
Contract, retailer, account and API key .............................................................................................. 11
Licenses ............................................................................................................................................... 12
Staging and production ....................................................................................................................... 12
Sessions and API key ........................................................................................................................... 12
Endpoints (Soap) ................................................................................................................................. 13
WSDL and XML schema (Soap)............................................................................................................ 14
Endpoints (Json) .................................................................................................................................. 14
Help page (Json) and schema .............................................................................................................. 15
Error-feedback .................................................................................................................................... 15
HTTP headers ...................................................................................................................................... 18
Time and time zones ........................................................................................................................... 18
3.12.1 Local time ................................................................................................................................... 18
3.12.2 Sessions ...................................................................................................................................... 18
3.12.3 API key ........................................................................................................................................ 18
Backwards and forwards compatibility ............................................................................................... 19
Http response codes ........................................................................................................................... 19
4 Authentication API ......................................................................................................................................... 20
Function: Authenticate ....................................................................................................................... 20
4.1.1 Password types ............................................................................................................................... 21
Function: Logoff .................................................................................................................................. 22
5 Coupon API .................................................................................................................................................... 23
Coupon status ..................................................................................................................................... 23
Coupon strategy .................................................................................................................................. 23
Generating coupons; series and batches ............................................................................................ 24
Locking coupons to specific customers ............................................................................................... 24
Operations........................................................................................................................................... 24
Complex type: CouponParameters ..................................................................................................... 24
Complex type: CouponInfo ................................................................................................................. 25
Function: ActivateCoupon ................................................................................................................... 25
Function: CancelActivateCoupon ........................................................................................................ 26
Function: RedeemCoupon................................................................................................................... 27
Function: CancelRedeemCoupon ........................................................................................................ 29
Function: CreateAndActivateOnDemandCoupon ............................................................................... 29
Function: GenerateCoupons ............................................................................................................... 31
5.13.1 Coupon uniqueness .................................................................................................................... 33
Function: GetCouponBatches ............................................................................................................. 33

© Cow Hills Retail BV Page 7 of 100

Function: GetCouponCount ................................................................................................................ 34
Function: GetCouponInfo .................................................................................................................... 35
Function: GetCoupons......................................................................................................................... 37
Function: ResetRedeemCount ............................................................................................................ 38
Function: VoidCouponBatch ............................................................................................................... 39
Function: UploadCoupons ................................................................................................................... 39
Function: VoidCoupons ....................................................................................................................... 40
6 CustomerVoucher API .................................................................................................................................... 41
Function: RedeemCustomerVoucher .................................................................................................. 41
Function: GetCustomerVouchers ........................................................................................................ 42
7 PemCalculation API ........................................................................................................................................ 44
PrePublish ........................................................................................................................................... 44
Function: Calculate .............................................................................................................................. 44
7.2.1 Authentication token ...................................................................................................................... 44
7.2.2 Timeout ........................................................................................................................................... 44
7.2.3 Request and response .................................................................................................................... 45
CalculationRequest ............................................................................................................................. 45
7.3.1 General parameters ........................................................................................................................ 45
7.3.2 CustomerCards ............................................................................................................................... 46
7.3.3 AirmilesCards .................................................................................................................................. 46
7.3.4 EmployeeCards ............................................................................................................................... 47
7.3.5 Sales ................................................................................................................................................ 48
7.3.5.1 Attribs .................................................................................................................................... 49
7.3.5.2 Flags ....................................................................................................................................... 49
7.3.5.3 AirmilesPayment .................................................................................................................... 50
7.3.5.4 Discount on sale line level ...................................................................................................... 50
7.3.5.4.1 Markdown (PLU discount) .................................................................................. 50
7.3.5.4.2 NewPrice ............................................................................................................. 51
7.3.5.4.3 EmployeeDiscount .............................................................................................. 51
7.3.6 Discounts ........................................................................................................................................ 52
7.3.7 Coupons .......................................................................................................................................... 53
7.3.8 TransactionAttributes ..................................................................................................................... 54
7.3.9 PriorUses ......................................................................................................................................... 54
7.3.10 ShippingCosts ............................................................................................................................. 55
CalculationResponse ........................................................................................................................... 56
7.4.1 Complex type: Ref ........................................................................................................................... 56
7.4.2 Warnings ......................................................................................................................................... 57
7.4.3 FinancialResult / FinancialCalculationResult .................................................................................. 57
7.4.3.1 Shipping costs ........................................................................................................................ 59
7.4.4 LoyaltyResult and saved Airmiles ................................................................................................... 60

© Cow Hills Retail BV Page 8 of 100

7.4.5 IssuedCouponResult ....................................................................................................................... 60
7.4.6 DiscountVoucherResult .................................................................................................................. 61
7.4.7 TypeValueResult ............................................................................................................................. 62
7.4.8 ExtraArticleResult ........................................................................................................................... 62
7.4.9 MessageResult ................................................................................................................................ 63
7.4.10 Summary .................................................................................................................................... 63
7.4.11 Grouping identifier (gid) ............................................................................................................. 65
Function: GetInfo ................................................................................................................................ 66
Function: GetPemEntryCodesForCustomerCardLimit ......................................................................... 67
Function: CouponExists ....................................................................................................................... 68
8 PemConfiguration API .................................................................................................................................... 69
Structure ............................................................................................................................................. 69
General settings .................................................................................................................................. 69
Filters ................................................................................................................................................... 70
Article rules ......................................................................................................................................... 71
Customer card rule.............................................................................................................................. 72
Employee card rule ............................................................................................................................. 73
Site rule ............................................................................................................................................... 73
(Pre)publication ................................................................................................................................... 74
9 Giftcard API (frontoffice) ............................................................................................................................... 75
Giftcard-status..................................................................................................................................... 75
Function: GetGiftcardInfo ................................................................................................................... 75
Function: ActivateGiftcard .................................................................................................................. 75
Function: CancelActivateGiftcard........................................................................................................ 77
Function: RedeemGiftcard .................................................................................................................. 77
Function: CancelRedeemGiftcard ....................................................................................................... 77
Function: RefundGiftcard .................................................................................................................... 77
10 Giftcard API (backoffice) ................................................................................................................................ 78
Entities ................................................................................................................................................ 78
Function: CreateProduct ..................................................................................................................... 78
Function: GetGiftcardProducts ........................................................................................................... 79
Function: GenerateGiftcards ............................................................................................................... 80
10.4.1 Giftcard uniqueness ................................................................................................................... 80
Function: GetGiftcardBatches ............................................................................................................. 80
Function: GetGiftcardBarcodes ........................................................................................................... 81
Function: UpdateGiftcard.................................................................................................................... 82
Function: GetGiftcardHistory .............................................................................................................. 82
Function: UploadGiftcards .................................................................................................................. 82
11 LoyaltyVault ................................................................................................................................................... 83
Function: IssueAccount ....................................................................................................................... 83
Function: CancelIssueAccount ............................................................................................................ 84
Function: LoadAccountBalance ........................................................................................................... 84

© Cow Hills Retail BV Page 9 of 100

Function: CancelLoadAccountBalance ................................................................................................ 86
Function: GetAccountBalance ............................................................................................................. 86
Function: RedeemAccountBalance ..................................................................................................... 87
Function: CancelRedeemAccountBalance........................................................................................... 88
12 EmployeeBalanceVault API ............................................................................................................................ 90
Setup ................................................................................................................................................... 90
Meta data ............................................................................................................................................ 90
Account identifier ................................................................................................................................ 90
Function: GetAccountBalance ............................................................................................................. 90
Function: LoadAccountBalance ........................................................................................................... 90
Function: CancelLoadAccountBalance ................................................................................................ 91
Function: RedeemAccountBalance ..................................................................................................... 91
Function: CancelRedeemAccountBalance........................................................................................... 91
Function: CreateNewAccounts ............................................................................................................ 91
13 Server status API ............................................................................................................................................ 92
Ping...................................................................................................................................................... 92
14 Appendix A: General result codes .................................................................................................................. 93
15 Appendix B: Example use cases ..................................................................................................................... 94
Promotion can only be used thrice per customer. .............................................................................. 94
Employee discount .............................................................................................................................. 95
Markdown prices ................................................................................................................................ 96
Pregenerating coupons ....................................................................................................................... 97
15.4.1 Generating coupons ................................................................................................................... 98
15.4.2 Registering a coupon from the customer ................................................................................... 98
15.4.3 Using a coupon ........................................................................................................................... 98
15.4.4 Redeeming a coupon .................................................................................................................. 99

© Cow Hills Retail BV Page 10 of 100

3 General
This chapter will cover general information regarding the Treazure web platform.

Glossary
The following terms are specific to this document:

Term Commentary

Account Information used to log into the platform and identify oneself.

API Application programming interface, a programmatic interface consisting of one or

more publicly exposed endpoints to a defined request-response message system.

API key A code passed in by computer programs calling an API to identify the calling
program. It is used, for example to prevent malicious use or abuse of the API.

Service Service hosted by the API.

Consuming system The system using the service/API (i.e. the e-commerce platform).

Contract A binding agreement which allows the use of the Treazure platform.

License A specific permit, bound to any number of API’s. All contracts have at least one
license, which allows the use of a part of the Treazure platform.

Promotion A definition of a calculated result, this can either be a financial promotion

(discount/free article) or the issuing of vouchers for future sales.

Promotion filter A filter to set the conditions for a promotion, limiting it to specific situations.
These can consist of pre-defined sets of articles, but also for example the use of
customer cards or (specific) coupons.

Promotion The combination of all defined promotions. These are maintained by the retailer,
configuration either within Treazure or an external system.

Promotion The service needs promotions, these can be supplied in various ways:
configuration-type • From a POS environment (e.g. ROS)
• From the internal management module and the designated API
(PemConfiguration API)

Retailer A company selling consumers goods and/or services.

Contract, retailer, account and API key

When a contract is initiated a retailer1) will be created. A unique retailer ID will be generated which is needed
to log into the Authentication API.

A single retailer can have multiple Treazure accounts, each account is used for authentication on the web
service. For all actions performed on/in Treazure authentication is necessary, only valid accounts can
authorize. Valid accounts have a login ID and a valid password.

On top of user authentication an API key can be released. Such a key can be used for specific read-only
functions to improve performance, thus eliminating the need to log in/out for each request.

1) The retailer as an entity within the platform.

© Cow Hills Retail BV Page 11 of 100

Licenses
The licenses are assigned on a contract level in Treazure. Licenses restrict access to certain API’s, this way
access to a specific API (e.g. Coupon) can be prohibited, while at the same time access can be granted to other
API’s.

Accessibility to the different API’s is defined in the main contract, access can be granted to any number of
accounts.

Globally access needs to be granted though the license, within the contract access must be granted to any
number of accounts in order to use the functionality.

Staging and production

Treasure has two environments; staging and production. These environments are not physically connected.
Therefore you will receive two contracts, retailer ID’s, account sets, API keys etc. upon purchase, one for each
environment.

Bear in mind that configurations cannot be synchronized between the two environments. Every configuration
has to be done twice in its entirety.

Sessions and API key

Treazure can process request strings using sessions. A session can only be started from the Authentication API;
using the function Authenticate. Upon successful authentication a token will be returned, this token needs to
be sent along with any subsequent request in the session, unless otherwise specified.

A session can be closed by calling the Logoff function in the Authentication API, the token will be annulled
instantly.

Sessions created have a limited validity; a session will expire ten (10) minutes after being idle. Idle in this case
means since the last activity, a sliding window applies. Since the timer will be reset after each activity within
ten minutes of the last activity.

Keep this in mind when implementing Treazure services. You can, for example, choose to limit requests to only
one session per request. A request can consist of multiple actions, if the actions are in the same request string,
authentication only needs to take place once.

Certain read-only operations don’t need session authentication, but can be done using the API key. An
example is the calculate function in the PemCalculation API. This API is focussed on speed, this is achieved by
eliminating the need to authenticate with each request.

© Cow Hills Retail BV Page 12 of 100

Endpoints (Soap)
The staging API endpoints can be found in the table below:

API URL

Authentication https://services-staging.treazure.nl/Authentication-1-0

Coupon https://services-staging.treazure.nl/Coupon-1-0

CustomerVoucher https://services-staging.treazure.nl/CustomerVoucher-1-0

PemCalculation https://services-staging.treazure.nl/PemCalculation-1-0

PemConfiguration https://services-staging.treazure.nl/PemConfiguration-1-0

RosConnector https://services-staging.treazure.nl/RosConnector-1-0

Giftcard (frontoffice) https://services-staging.treazure.nl/Giftcard-1-0

Giftcard (backoffice) https://services-staging.treazure.nl/GiftcardBackoffice-1-0

LoyaltyVault https://services-staging.treazure.nl/LoyaltyVault-1-0

Server status https://services-staging.treazure.nl/ServerStatus-1-0

Production endpoints may vary:

API Commentary

Authentication https://services.treazure.nl/Authentication-1-0

Coupon https://services.treazure.nl/Coupon-1-0

CustomerVoucher https://services.treazure.nl/CustomerVoucher-1-0

PemCalculation https://services.treazure.nl/PemCalculation-1-0

PemConfiguration https://services.treazure.nl/PemConfiguration-1-0

RosConnector https://services.treazure.nl/RosConnector-1-0

Giftcard (frontoffice) https://services.treazure.nl/Giftcard-1-0

Giftcard (backoffice) https://services.treazure.nl/GiftcardBackoffice-1-0

LoyaltyVault https://services.treazure.nl/LoyaltyVault-1-0

Server status https://services.treazure.nl/ServerStatus-1-0

Communicating with Treazure requires encryption using SSL\TLS, therefore the URI’s in the tables above all
show the HTTPS scheme. This allows for bidirectional encryption, ensuring safe(r) communications.

© Cow Hills Retail BV Page 13 of 100

WSDL and XML schema (Soap)
WSDL schemes are available for all API’s and operations. The following URL’s can be used to call the WSDL
pages on the staging environment:

API URL

Authentication https://services-staging.treazure.nl/Authentication-1-0/wsdl

Coupon https://services-staging.treazure.nl/Coupon-1-0/wsdl

CustomerVoucher https://services-staging.treazure.nl/CustomerVoucher-1-0/wsdl

PemCalculation https://services-staging.treazure.nl/PemCalculation-1-0/wsdl

PemConfiguration https://services-staging.treazure.nl/PemConfiguration-1-0/wsdl

RosConnector https://services-staging.treazure.nl/RosConnector-1-0/wsdl

Giftcard (frontoffice) https://services-staging.treazure.nl/Giftcard-1-0/wsdl

Giftcard (backoffice) https://services-staging.treazure.nl/GiftcardBackoffice-1-0/wsdl

LoyaltyVault https://services-staging.treazure.nl/LoyaltyVault-1-0/wsdl

Employee Balance https://services-staging.treazure.nl/EmployeeBalanceVault-1-0/wsdl

Vault

Please note: these URL’s can only be used on the staging environment. The production environment does not
serve Wsdl content.

Types used in the XML schemes in the WSDL can be found in the following namespaces:

Xml-namespace Commentary

http://cowhills.nl/EAccount General Treazure-namespace.

http://cowhills.nl/EAccount/PEM/CalculationResponse Namespace for promotion calculation

responses.

http://cowhills.nl/EAccount/PEM/CalculationRequest Namespace for promotion calculation input

(basket).

http://cowhills.nl/EAccount/PEM/Config Namespace for promotion maintenance.

Endpoints (Json)
Each service is accessible as a Json endpoint. These endpoints have the same Url as their Soap equivalent but
have the suffix /json.

For instance, the Json endpoint of the authentication service is available at https://services-
staging.treazure.nl/Authentication-1-0/json

© Cow Hills Retail BV Page 14 of 100

Help page (Json) and schema
For each Json service there is a default help page available. This Html page shows the available operations and
accepted Http methods. Just like Wsdl’s these help pages are only available in the staging environment.

Access this page by appending the suffix /help to the Json endpoint, for instance https://services-
staging.treazure.nl/Authentication-1-0/json

The scheme cannot be obtained from this page. The object structure is the same as the Soap endpoints so the
schema should be obtained from the Wsdl/schema of the Soap interface.

With the Xsd a Json request can be constructed. For instance the following Soap request:

The Authenticate-element is the method name and in the Json endpoint this is indicated in the Url. The
parameters can be converted from the Soap request and written als the following Json request:

{
"RetailerId" : "***",
"LoginId" : "***",
"Password" : "***",
"UtcOffset" : "05:00"
}

Error-feedback
This paragraph describes how errors will be fed back from Treazure, in order to handle these in a fashionable
manner.

© Cow Hills Retail BV Page 15 of 100

Primarily errors will be encapsulated in the response message, the ‘code’ attribute in the response should
contain the result code.

For example (Soap):

And in Json:

{
"ConfigurationSequenceNumber": 6083,
"Code": "Success"
}

As you can see the value of the code attribute is Success, meaning the response has been handled correctly. In
the appendix you can find all response codes and what they imply. Note that these result codes are
implemented throughout the entire platform. Meaning that some codes will never occur for certain
operations.

If an unexpected error occurs, a specific error message will be sent. These messages will be sent if a request
could not be handled properly, see the below for example (Soap):

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<s:Fault>
<faultcode>s:LicenseRequired</faultcode>
<faultstring xml:lang="nl-NL">License 'Pem' required</faultstring>
</s:Fault>
</s:Body>
</s:Envelope>

And for Json:

{
"faultcode": "AuthenticationError",
"faultstring": "Need to be authenticated (unknown api key)"
}

The following components can be identified:

Parameter Commentary Type

faultcode The error code. String

This can be one of the following codes:

• LicenseRequired
• AuthenticationError1)
• InternalError

© Cow Hills Retail BV Page 16 of 100

faultstring Textual additional information regarding the error that just String
occurred.

© Cow Hills Retail BV Page 17 of 100

HTTP headers
The following HTTP headers are added to the response:

Name Commentary Type

TRZ-SRV The physical node on which the request was executed. String

TRZ-VERSION The version of Treazure which handled the request. String

TRZ-PROMO-SRV2) The name of the agent who handled the request. String

TRZ-PROMO-TIME2) The time that is used for calculating baskets. This header ISO 8601 time
is only provided when an explicit calculation moment is format,
provided. without time
zone.

These values can be used for troubleshooting and for trace purposes, because Treazure is balanced/scalable
and workload is divided.

1) Note: this could should not be used for authentication purposes. In the authentication operation of the Authentication API the result will
be returned using the generic status codes. This specific code will be return if for example a session expired while sending a new request.

2) Is only used in the calculate method of the PemCalculation API.

Time and time zones

Treazure fully supports time zones and universal/local time. This is bound to the authentication model. Since
there are 2 models both models require a different approach.

3.12.1 Local time

Both models assume local time and will ignore zonal information specified by standards.

So providing the following value will be interpreted by Treazure as 2018-03-12T18:59:59.

Because Treazure asumes all provided times in session bound calls are local it ignores the specified zonal
information (and the time will be converted to 18:59:59). It is advised to not specify zonal information in time
fields.

3.12.2 Sessions
Treazure supports usage in different time zones on a session level. When a session is started the Utc time offset
should be specified. All session based communication from and to Treazure will then take place in the local time,
Treazure will internally convert to Utc.

This means the client is responsible for determining the Utc offset based on time zone and daylight savings when
logging in. See for more information about providing the offset the Authenticate method in the Authentication
API.

3.12.3 API key

When using the API key (PemCalculation API) there is no session and Treazure does not provide automatic time
conversion. Since the service is unable to determine the time of the caller from the request or prior requests the

© Cow Hills Retail BV Page 18 of 100

local time should always be supplied in the request with the API-key. See for more information the chapters
about the specific operations.

Backwards and forwards compatibility

The Treazure API schemas and Wsdl will account for backward compatibility. Parameters, services and
operations may be added in future releases but these will all be optional. Treazure will continue to operate with
the existing requests and the request schemas will still validate. Operations which change signature in a
compatibility breaking way will be added as new operations and not break existing functionality.

Also, the Wsdl/schemas account for forward compatibilty. New added elements can appear in responses and
the schema will still validate (although the new elements will not be understoond unless a new Wsdl/Xsd is
loaded).

This is because the complex types in the schema contain the xs-any-element:

<xs:complexType name="CouponGenerationResult">
<xs:sequence>
<xs:element minOccurs="0" name="ReturnCode" type="tns:ReturnCode"/>
<xs:element minOccurs="0" name="CouponBatchId" nillable="true" type="xs:string"/>
<xs:element minOccurs="0" name="ErrorMessage" nillable="true" type="xs:string"/>
<xs:any minOccurs="0" processContents="lax"/>
</xs:sequence>
</xs:complexType>

Http response codes

The responses returned by the Treazure API follow some Http response codes. These Http codes are tied to the
general Treazure result codes. These response codes are described in Appendix A: General result codes.

© Cow Hills Retail BV Page 19 of 100

4 Authentication API
This API is used to start and end Treazure sessions, it is available for all contracts.

Function: Authenticate
The function Authenticate must be used to start a new session.

Example of a request:

The message contains the below three important parameters:

Name Commentary Type

RetailerId The provided retailer ID. String

LoginId The provided login ID. String

Password The provided password (linked to the login). String

There are multiple ways to provide the password, based

on the account setup. See the next paragraph for more
information.

UtcOffset The Utc time offset to use for this session in HH:mm String
format.

The parameter is optional. If not provided the offset of

timezone Western Europe is used.

If authentication is successful the following response will be sent:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<AuthenticateResponse xmlns="http://cowhills.nl/EAccount">
<AuthenticateResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<IsAdmin>false</IsAdmin>
<ReturnCode>Success</ReturnCode>
<Token>39f503da-174b-46d5-af53-9d9a7fa00c83</Token>
</AuthenticateResult>
</AuthenticateResponse>
</s:Body>
</s:Envelope>

The token, for the session, is embedded in the response message.

A result message contains the following values:

© Cow Hills Retail BV Page 20 of 100

Name Commentary Type

AccessibleModules The modules/licences that are avaible to the String array

authenticated user.

IsAdmin Whether the specified account is an administrator String

account.

Markets The markets this user has access to. String[]

ReturnCode The operation result. String

Note: this is the value which needs to checked whether

authentication was successful. If the supplied credentials
do not match AuthenticationFailed will be returned.

Token The unique session token. String

4.1.1 Password types

There are 3 methods to provide Treazure with the password.

Method Description Pro’s Con’s

Plain text The password is a static Little maintenance, one Vulnerable to replay
value. account can be used for attack.
multiple clients.

One time password The provided password is Password can only be Account cannot be shared
(OTP) encoded with an used once. between multiple clients.
incremented numerical
value.

Time based one time The provided password is Password can only be Clocks of Treazure and
password (TOTP) encoded with a time used for a short period of clients have to be in sync.
based component. time (30s). Account can be
shared between multiple
clients.

For the methods OTP and TOTP the password has to be encoded.

For OTP the hashing method is as follows (C#):

static string HashPwd_Otp(string retailerId, string userName, string pwd, long ticks)
{
using (var sha256 = SHA256.Create())
{
var bytes = Encoding.UTF8.GetBytes($"{retailerId.ToUpper()}.{userName.ToUpper()}.{pwd}");
var usernamePasswordHash = sha256.ComputeHash(bytes);

var uniqueNumber = BitConverter.GetBytes(ticks).AsEnumerable();

if (BitConverter.IsLittleEndian)
{
uniqueNumber = uniqueNumber.Reverse();
}

var hash2 = sha256.ComputeHash(usernamePasswordHash.Concat(uniqueNumber).ToArray());

© Cow Hills Retail BV Page 21 of 100

var paswordBytes = uniqueNumber.Concat(hash2);

var pwdBase64 = Convert.ToBase64String(paswordBytes.ToArray());

return pwdBase64;
}
}

Please note the following:

1) RetailerID and user name should be all caps.

2) Password is case sensitive

For TOTP, see https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm.

The parameters are:

Parameter Description Parameter value

K The key RETAILERID.USERNAME.Password; retailerid and

username are all caps, password/secret is case
sensitive.

T0 Time to start counting The Unix Epoch (1 jan 1970 00:00:00 UTC)
steps from

T1 Interval 30 seconds

N Token length 10

Function: Logoff
Calling the Logoff function ends the current session. The corresponding token must be supplied, which in turn,
is annulled instantly. The function is not used to log in.

Note: although a session will automatically expire after 10 minutes of inactivity, it is still strongly advised to
explicitly end sessions. Doing so prevents unwanted and unsanctioned operations on the system.

Example of a request:

A successful logoff is confirmed by the following response message:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<LogoffResponse xmlns="http://cowhills.nl/EAccount">
<LogoffResult>Success</LogoffResult>
</LogoffResponse>
</s:Body>
</s:Envelope>

© Cow Hills Retail BV Page 22 of 100

5 Coupon API
The Coupon API offers possibilities to generate, issue and redeem coupons. This chapter covers general
coupon and detailed API information.

Coupon status
The following coupon statusses exist:

Status Commentary

Created The coupon has been created, but not yet issued.

Active The coupon has been issued and can be redeemed.

PartiallyRedeemed The coupon has been redeemed partially (this allows for multiple redeems),
meaning that it can be redeemed again.

Redeemed The coupon has been redeemed, it cannot be redeemed again.

Expired The coupon has been expired, it cannot be redeemed anymore.

Void The coupon has been voided, it cannot be redeemed anymore.

Coupon strategy
A coupon can be created with status ‘created’ or ‘active’. When generating a batch of coupons the status can
be defined in the request (see paragraph GenerateCoupons). It depends on the situation which generation
strategy and status fits best.

Some examples:

Coupon type Strategy

Coupons for print work A batch of coupons needs to be generated with AutoActivate=True; this way
and/or e-mail the coupons can be redeemed instantly.

Coupons for print work, A batch of coupons needs to be generated with AutoActivate=False; coupon
explicit distribution IDs are generated but cannot be redeemed after generation.

Each coupon needs to be activated one by one. This can be integrated in the
checkout process for example.

This method is recommended when activation at checkout is desirable.

Coupons for online on- This method can be used if the coupon barcode can be generated upon
demand distribution request, i.e. doesn’t have to be known in advance. A coupon batch can be
created to limit the number of coupons generated. In which case the
CreateAndActivateOnDemandCoupon function will generate the barcode at
the time needed.

This option is especially suited for coupons issued as a result of a

promotional event (e.g. a 10% discount on your next purchase). The coupon
can be printed or sent by mail/app to the customer.

© Cow Hills Retail BV Page 23 of 100

Generating coupons; series and batches
The Coupon API relies on preconfigured series or batches. A series is a collection of coupons either
pregenerated or a framework which can be used to generate coupons on-demand. You can, for example,
pregenerate 10.000 coupons which all represent the same value (relative or absolute).

Generate operations are dependant on a CouponRangeId, this range ID is an alpha-numeric value, which is
only used for identification of the series/batch. The consuming system must store which series/batches exist in
order to keep relevant meta-information (description, barcode type, logos etc.).

Coupons can be generated per run, you can run multiple generations within a batch. This can provide useful
when you need more coupons, or when an action is extended.

A batch is generated using a prefix and some digits from the serialnumber of the series. The system will then
generate unique barcodes based on this information. Pregenerated coupons are not generated on-the-fly, but
rather in the background, always taking already generated barcodes under consideration. This method ensures
performance on the Treazure server, guaranteeing on-the-fly generation for coupons upon request (non
pregenerated coupons).

Locking coupons to specific customers

It is possible to lock a coupon to a specific customer. The can be done during the issue process and when
redeeming the exact same customer reference value has to be specified.

Please note that it is not required to use an actual customer ID. Since the value is only used for comparision
purposes you can also specify a hashed value. It may be wise to consider this because there is no need to store
customer ID’s in Treazure.

Operations
The next few paragraphs will clarify the operations performed by the Coupon API. In the process some
complex types will be explained.

Complex type: CouponParameters

This type is used for functions operating on specific coupons. The parameters defined have a relation to the
barcode of the coupon and not the series or batch. This is because the functions (e.g. status/info requests)
using this type have no awareness of any batch/series, nor do they have the need for this.

Issuing and redeeming coupons will most likely occur in POS (Point Of Sale) environments. Thence these
functions have shop and employee property fields to keep track of the coupons.

Name Commentary Type

Barcode The barcode of the generated coupon. String

The maximum length of the value is 250 characters.

OperatorID The ID of the employee, as known in the POS system. String

The maximum length of the value is 20 characters.

ShopId The ID of the shop performing the request. String

© Cow Hills Retail BV Page 24 of 100

The maximum length of the value is 10 characters.

PosId The ID of the POS system. String

The maximum length of the value is 5 characters.

ReceiptNr The unique ID of the receipt, as known in the POS String

system.

The maximum length of the value is 10 characters.

If the length restriction is not met, the status code InvalidParameterValue is returned.

Complex type: CouponInfo

The CouponInfo type is returned by multiple implemented functions, the follow properties exist:

Name Commentary Type

Status The status of the coupon. See corresponding paragraph. Enum

Barcode The unique barcode of the coupon. String

CouponRangeId A pointer to the batch/series to which the coupon String

belongs. Use this value to determine the meta data (e.g.
description).

CreatedAt The creation date of the coupon. DateTime

SerialNumber The serial number of the coupon (= the unique String

component of the barcode).

RedeemCount The amount of times the coupon has been redeemed. Int

MaxRedeemCount The limit of how many times the coupon can and Int
can/may be redeemed.

ValidFrom As of when the coupon can be redeemed, this field is DateTime

optional; default is instantaneously.

CustomerReference The customer reference that this coupon is locked to. If String
this value is not available the coupon is not locked to a
specific customer.

Function: ActivateCoupon
The ActivateCoupon function facilitates the activation of coupons.

The following parameters exist:

Name Commentary Type

CouponParameters More in-depth information is available in the Complex

corresponding paragraph.

© Cow Hills Retail BV Page 25 of 100

Example of a request:

Example of a response:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<ActivateCouponResponse xmlns="http://cowhills.nl/EAccount">
<ActivateCouponResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ActivationId>5b87c54d-5f07-462e-8307-8b910f2cee8b</ActivationId>
<Coupon>
<Barcode>9999459231533836726</Barcode>
<CouponRangeId>ca6b4b57-eb89-4528-82bb-51f43e91770d</CouponRangeId>
<CreatedAt>2015-03-26T11:36:57</CreatedAt>
<MaxRedeemCount>3</MaxRedeemCount>
<RedeemCount>1</RedeemCount>
<SerialNumber>459231533836726</SerialNumber>
<Status>Active</Status>
<ValidFrom i:nil="true"/>
<ValidUntill>2015-04-09T00:00:00</ValidUntill>
</Coupon>
<ReturnCode>Success</ReturnCode>
</ActivateCouponResult>
</ActivateCouponResponse>
</s:Body>
</s:Envelope>

The following values will be returned:

Name Commentary Type

ReturnCode The result of the operation. Enum

ActivationId The unique activation ID, this value can be used to String
reverse activation.

Coupon This field is used to store coupon specific information. Complex

For more info see the corresponding paragraph.

Function: CancelActivateCoupon
This function is used to reverse activation of one specific coupon. Activation can be either through the
ActivateCoupon or CreateAndActivateOnDemandCoupon functions.

Note: this function can only be used if the last operation was activation of the coupon. It is never possible to
reverse more than one step in the lifecycle of a coupon.

Example of a request:

© Cow Hills Retail BV Page 26 of 100

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:eac="http://cowhills.nl/EAccount">
<soapenv:Header/>
<soapenv:Body>
<eac:CancelActivateCoupon>
<eac:Auth>dcbc9f3c-c136-47ab-a6d6-23592f865f52</eac:Auth>
<eac:Parameters>
<eac:Barcode>9999459231533836726</eac:Barcode>
<eac:OperatorId>Server01</eac:OperatorId>
<eac:PosId>Web</eac:PosId>
<eac:ShopId>9999</eac:ShopId>
</eac:Parameters>
<eac:CancelActivateParameters>
<eac:ActivationId>5b87c54d-5f07-462e-8307-8b910f2cee8b</eac:ActivationId>
</eac:CancelActivateParameters>
</eac:CancelActivateCoupon>
</soapenv:Body>
</soapenv:Envelope>

The following parameters exist:

Name Commentary Type

CouponParameters More in-depth information is available in the Complex

corresponding paragraph.

CancelActivateParameters. The ID issued upon activation. String

ActivationId

Example of a result:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<CancelActivateCouponResponse xmlns="http://cowhills.nl/EAccount">
<CancelActivateCouponResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ReturnCode>Success</ReturnCode>
</CancelActivateCouponResult>
</CancelActivateCouponResponse>
</s:Body>
</s:Envelope>

The following values will be returned:

Parameter Commentary Type

ReturnCode The result of the operation. Enum

Function: RedeemCoupon
This function is used to redeem activated coupons. If configured, it is possible to redeem a coupon multiple
times, each redemption must be done separately by calling the RedeemCoupon function.

Example of a request:

© Cow Hills Retail BV Page 27 of 100

<eac:OperatorId>Server01</eac:OperatorId>
<eac:PosId>Web</eac:PosId>
<eac:ShopId>9999</eac:ShopId>
</eac:Parameters>
</eac:RedeemCoupon>
</soapenv:Body>
</soapenv:Envelope>

The following parameters exist:

Name Commentary Type

CouponParameters More in-depth information is available in the Complex

corresponding paragraph.

RedeemParameters. The customer reference for the redeem. If the coupon is Complex
CustomerReference locked to a customer this value must match. If the
coupon is not locked to a customer this value is ignored.

Example of a result:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<RedeemCouponResponse xmlns="http://cowhills.nl/EAccount">
<RedeemCouponResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Coupon>
<Barcode>9999459231533836726</Barcode>
<CouponRangeId>ca6b4b57-eb89-4528-82bb-51f43e91770d</CouponRangeId>
<CreatedAt>2015-03-26T11:36:57</CreatedAt>
<MaxRedeemCount>3</MaxRedeemCount>
<RedeemCount>1</RedeemCount>
<SerialNumber>459231533836726</SerialNumber>
<Status>PartiallyRedeemed</Status>
<ValidFrom i:nil="true"/>
<ValidUntill>2015-04-09T00:00:00</ValidUntill>
</Coupon>
<RedeemId>69feff1a-0ae2-4f7c-8189-c8c23cc81604</RedeemId>
<ReturnCode>Success</ReturnCode>
</RedeemCouponResult>
</RedeemCouponResponse>
</s:Body>
</s:Envelope>

The following values will be returned:

Name Commentary Type

ReturnCode The result of the operation. Enum

RedeemId The unique ID assigned to the redemption, this value is String

needed to cancel the redemption.

Coupon More in-depth information is available in the Complex

corresponding paragraph.

Redeeming a coupon doesn’t necessarily mean the status changes to ‘redeemed’. As mentioned earlier a
coupon can be redeemed multiple times (if configured accordingly).

© Cow Hills Retail BV Page 28 of 100

Function: CancelRedeemCoupon
This function allows for cancellation of a redemption.

Note: you can use this function only if the last action on the specified coupon was a redemption. It is never
possible to reverse more than one step in the lifecycle of a coupon.

Example of a request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:eac="http://cowhills.nl/EAccount">
<soapenv:Header/>
<soapenv:Body>
<eac:CancelRedeemCoupon>
<eac:Auth>dcbc9f3c-c136-47ab-a6d6-23592f865f52</eac:Auth>
<eac:Parameters>
<eac:Barcode>9999459231533836726</eac:Barcode>
<eac:OperatorId>Server01</eac:OperatorId>
<eac:PosId>Web</eac:PosId>
<eac:ShopId>9999</eac:ShopId>
</eac:Parameters>
<eac:CancelRedeemParameters>
<eac:RedeemId>69feff1a-0ae2-4f7c-8189-c8c23cc81604</eac:RedeemId>
</eac:CancelRedeemParameters>
</eac:CancelRedeemCoupon>
</soapenv:Body>
</soapenv:Envelope>

The following parameters exist:

Parameter Commentary Type

CouponParameters More in-depth information is available in the Complex

corresponding paragraph.

CancelRedeemParameters. The ID assigned upon redemption. String

RedeemId

Example of a response:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<CancelRedeemCouponResponse xmlns="http://cowhills.nl/EAccount">
<CancelRedeemCouponResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ReturnCode>Success</ReturnCode>
</CancelRedeemCouponResult>
</CancelRedeemCouponResponse>
</s:Body>
</s:Envelope>

The following values will be returned:

Name Commentary Type

ReturnCode The result of the operation. Enum

Function: CreateAndActivateOnDemandCoupon
This function is used for creating a coupon on-demand. For example if the result of a promotional event
requires the generation of a coupon as opposed to immediate financial benefit. This eliminates the need for

© Cow Hills Retail BV Page 29 of 100

great amounts of pregenerated coupons. Plus it provides insight in the amount of coupons issued, this can be
queried using the GetCouponBatches function.

Coupons generated this way are automatically activated, this is by design. It is not possible to generate on-
demand coupons with different statuses. Also, generation is only allowed if the series is contained in a batch of
type OnDemand. If the batch is not configured correctly the error code NotFound will be returned, this means
the consuming system (POS) needs to take this into account. This code is also returned when a batch is full, i.e.
the predefined maximum number of coupons has been reached.

It’s recommended to check coupon settings in the management system prior to using them. This way you can
verify if a batch is missing or almost at its max, enabling you to take proper action.

Example of a request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:eac="http://cowhills.nl/EAccount">
<soapenv:Header/>
<soapenv:Body>
<eac:CreateAndActivateOnDemandCoupon>
<eac:Auth>dcbc9f3c-c136-47ab-a6d6-23592f865f52</eac:Auth>
<eac:CouponRangeId>ca6b4b57-eb89-4528-82bb-51f43e91770d</eac:CouponRangeId>
<eac:CreateAndActivateCouponParameters>
<eac:ValidFrom>2015-04-01T00:00:00</eac:ValidFrom>
<eac:ValidUntill>2015-04-30T23:59:59</eac:ValidUntill>
</eac:CreateAndActivateCouponParameters>
<eac:Parameters>
<eac:OperatorId>Server01</eac:OperatorId>
<eac:PosId>Web</eac:PosId>
<eac:ShopId>9999</eac:ShopId>
</eac:Parameters>
</eac:CreateAndActivateOnDemandCoupon>
</soapenv:Body>
</soapenv:Envelope>

The following parameters exist:

Name Commentary Type

CouponRangeId The coupon series for which the coupon is generated. String

CreateAndActivateCoupon- The optional parameter to set an active/valid from date DateTime

Parameters.ValidFrom for a coupon.

CreateAndActivateCoupon- The optional parameter to set the expiration date for a DateTime
Parameters.ValidUntill coupon.

CouponParameters More in-depth information is available in the Complex

corresponding paragraph.

Note that the barcode field will be generated, because

no specific coupon is requested, but the info is used to
create a new one.

Example of a response:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<CreateAndActivateOnDemandCouponResponse xmlns="http://cowhills.nl/EAccount">
<CreateAndActivateOnDemandCouponResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

© Cow Hills Retail BV Page 30 of 100

<ActivationId>1f3c14d0-7562-431f-9d32-717f5d1f5bb7</ActivationId>
<Coupon>
<Barcode>999995772918581</Barcode>
<CouponRangeId>ca6b4b57-eb89-4528-82bb-51f43e91770d</CouponRangeId>
<CreatedAt>2015-04-01T09:21:01.8332671Z</CreatedAt>
<MaxRedeemCount>1</MaxRedeemCount>
<RedeemCount>0</RedeemCount>
<SerialNumber>5772918581</SerialNumber>
<Status>Active</Status>
<ValidFrom>2015-04-01T00:00:00</ValidFrom>
<ValidUntill>2015-04-30T23:59:59</ValidUntill>
</Coupon>
<ReturnCode>Success</ReturnCode>
</CreateAndActivateOnDemandCouponResult>
</CreateAndActivateOnDemandCouponResponse>
</s:Body>
</s:Envelope>

The following values will be returned:

Name Commentary Type

ReturnCode The result of the operation. Enum

ActivationId The unique ID assigned to the activation. This value can String
be used to cancel activation.

Coupon More in-depth information is available in the Complex

corresponding paragraph.

Function: GenerateCoupons
This function is used to trigger coupon generation. A batch ID will be returned to identify the newly created
batch. The actual generation of the coupon batch will be delegated to the background process to balance the
load on the platform. It can take up to a few minutes before the new batch can be used by/in other systems.

Status updates of the batches can be requested using the GetCouponBatches function. The GetCoupons
function can be used to request information on specific coupons.

Example of a request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:eac="http://cowhills.nl/EAccount">
<soapenv:Header/>
<soapenv:Body>
<eac:GenerateCoupons>
<eac:Auth>dcbc9f3c-c136-47ab-a6d6-23592f865f52</eac:Auth>
<eac:RangeInfo>
<eac:AutoActivate>false</eac:AutoActivate>
<eac:BatchMode>OnDemand</eac:BatchMode>
<eac:CouponRangeId>ca6b4b57-eb89-4528-82bb-51f43e91770d</eac:CouponRangeId>
<eac:MaxRedeemCount>1</eac:MaxRedeemCount>
<eac:NumberOfCoupons>500</eac:NumberOfCoupons>
<eac:OperatorId>Server01</eac:OperatorId>
<eac:Prefix>99999</eac:Prefix>
<eac:SerialNumberDigits>10</eac:SerialNumberDigits>
<eac:ValidUntill>2015-04-30T23:59:59</eac:ValidUntill>
</eac:RangeInfo>
</eac:GenerateCoupons>
</soapenv:Body>
</soapenv:Envelope>

The following parameters exist:

© Cow Hills Retail BV Page 31 of 100

Name Commentary Type

AutoActivate Defines whether the coupon is activated upon issuing. Boolean

For more information please see the paragraph regarding

strategies for generating coupons.

BatchMode The batch type. String

The types below exist:

• PreGenerated; coupon are generated in batches.
• OnDemand; coupons are generated just-in-time.
For example if a promotional events needs
coupons to be generated when the transaction
is committed.
• Manual; coupons are expected to be uploaded
into this batch. The system will not
create/assign coupons itself.

MaxRedeemCount The number of times a coupon may/can be redeemed. Int

NumberOfCoupons The number of coupons in the batch; this value must be Int
absolute and cannot exceed 1.000.000.

Prefix The prefix for the coupon, this value is mandatory. String

The maximum length of the value is 50 characters.

SerialNumberDigits The number of digits the serial number must consist of. Int
The value needs to be between 5 and 25.

ValidUntill The mandatory expiration date, after this date the DateTime
coupons cannot be redeemed anymore.

The value must be between 00:00 the next day and five
years from now (start of day).

OperatorId The operator that creates the batch of coupons. String

The maximum length of the value is 20 characters.

CouponRangeId The generic coupon identifier for the generated coupons. String

The maximum length of the value is 100 characters.

Example of a response:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GenerateCouponsResponse xmlns="http://cowhills.nl/EAccount">
<GenerateCouponsResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<CouponBatchId>a91f99f5-fd92-43ef-ac20-9d45b19c624d</CouponBatchId>
<ReturnCode>Success</ReturnCode>
</GenerateCouponsResult>
</GenerateCouponsResponse>
</s:Body>
</s:Envelope>

© Cow Hills Retail BV Page 32 of 100

The following values will be returned:

Name Commentary Type

ReturnCode The result of the operation. Enum

CouponBatchId The assigned batch ID. String

5.13.1 Coupon uniqueness

When generating new coupons Treazure will check whether the distribution factor will not get too low. If more
then 1 out of 10.000 possible coupon serial numbers exist Treazure will not accept the creation of more coupons.

Function: GetCouponBatches
The GetCouponBatches function provides functionality to query which batches exist for coupon series.

Example of a request:

The following parameters exist:

Name Commentary Type

CouponRangeId The coupon series. String

Example of a response:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetCouponBatchesResponse xmlns="http://cowhills.nl/EAccount">
<GetCouponBatchesResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<CouponBatchInfo>
<BatchId>1d141121-f220-4bc3-857f-478999912639</BatchId>
<BatchMode>PreGenerated</BatchMode>
<BatchStatus>Ready</BatchStatus>
<CouponCount>50</CouponCount>
<CouponCreatedCount>50</CouponCreatedCount>
<CreatedAt>2015-03-26T11:36:55</CreatedAt>
<OperatorId>PV2</OperatorId>
<ValidUntill>2015-04-09T00:00:00</ValidUntill>
</CouponBatchInfo>

<CouponBatchInfo>
<BatchId>b2fc83fa-e1d5-42c5-8a97-a55860852f14</BatchId>
<BatchMode>OnDemand</BatchMode>
<BatchStatus>Pending</BatchStatus>
<CouponCount>1000</CouponCount>
<CouponCreatedCount>1</CouponCreatedCount>
<CreatedAt>2015-04-01T08:35:14</CreatedAt>
<OperatorId>PV2</OperatorId>
<ValidUntill>2015-04-15T00:00:00</ValidUntill>
</CouponBatchInfo>

© Cow Hills Retail BV Page 33 of 100

</GetCouponBatchesResult>
</GetCouponBatchesResponse>
</s:Body>
</s:Envelope>

The result message contains a collection of CouponBatchInfo entities. The following properties will be returned
per batch:

Name Commentary Type

CreatedAt The creation date and time of the batch. DateTime

ValidUntill The expiration date of the batch. DateTime

BatchStatus The status of the entire batch: Enum

• Pending; generation is scheduled or in progress
(progression can be queried using the
CouponCount or CouponCreatedCount
functions).
• Ready; generation is successful.
• Error; an error occurred during generation.

BatchMode The batch type: Enum

• PreGenerated; the batch contains only

pregenerated coupons.
• OnDemand; the batch contains only coupons
generated on-demand.
• Manual; coupons are expected to be uploaded
into this batch. The system will not
create/assign coupons itself.

CouponCount The number of coupons in the batch, this represents the Int
theoretical maximum size of the batch.

In the case of a pregenerated batch, this number

represents the final number of coupons.

CouponCreatedCount The number of already generated coupons in the batch, Int

if this number matches the CouponCount, generation is
completed or, in case of on-demand generation, the
batch is full

BatchId The batch ID. String

OperatorId The operator who generated/requested the generation String

of the batch.

CouponActivatedCount The number of activated coupons in this batch. Int

Function: GetCouponCount
This function can be used to request information regarding the number of coupons within a batch.

The following parameters exist:

Name Commentary Type

© Cow Hills Retail BV Page 34 of 100

CouponRangeId The coupon series for which information is requested, String
this parameter is mandatory.

BatchId The ID of the batch for which information is requested. If String

not provided this parameter is ignored.

Status The status for which information is requested. If not Enum

provided this parameter is ignored.

Example of a request:

The result contains the number of coupons, for example:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetCouponCountResponse xmlns="http://cowhills.nl/EAccount">
<GetCouponCountResult>50</GetCouponCountResult>
</GetCouponCountResponse>
</s:Body>
</s:Envelope>

Function: GetCouponInfo
The GetCouponInfo function is used for requesting information of a single coupon.

The following parameters exist:

Name Commentary Type

CouponParameters Information regarding a specific coupon. More in-depth Complex

information is available in the corresponding paragraph.

Example of a request:

© Cow Hills Retail BV Page 35 of 100

</soapenv:Body>
</soapenv:Envelope>

Example of a result:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetCouponInfoResponse xmlns="http://cowhills.nl/EAccount">
<GetCouponInfoResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Coupon>
<Barcode>9999459231533836726</Barcode>
<CouponRangeId>ca6b4b57-eb89-4528-82bb-51f43e91770d</CouponRangeId>
<CreatedAt>2015-03-26T11:36:57</CreatedAt>
<MaxRedeemCount>3</MaxRedeemCount>
<RedeemCount>0</RedeemCount>
<SerialNumber>459231533836726</SerialNumber>
<Status>Active</Status>
<ValidFrom i:nil="true"/>
<ValidUntill>2015-04-09T00:00:00</ValidUntill>
</Coupon>
<CouponHistory>
<CouponHistoryEvent>
<Comment i:nil="true"/>
<OperatorId>PV2</OperatorId>
<PosId i:nil="true"/>
<ReceiptNr i:nil="true"/>
<ShopId i:nil="true"/>
<Stamp>2015-03-26T11:36:57</Stamp>
<StatusNew>Created</StatusNew>
<StatusOld>Created</StatusOld>
</CouponHistoryEvent>
<CouponHistoryEvent>
<Comment>Test comment</Comment>
<OperatorId>Server01</OperatorId>
<PosId>Web</PosId>
<ReceiptNr i:nil="true"/>
<ShopId>9999</ShopId>
<Stamp>2015-04-01T09:17:32</Stamp>
<StatusNew>Active</StatusNew>
<StatusOld>Active</StatusOld>
</CouponHistoryEvent>
</CouponHistory>
<ReturnCode>Success</ReturnCode>
</GetCouponInfoResult>
</GetCouponInfoResponse>
</s:Body>
</s:Envelope>

The following values will be returned:

Name Commentary Type

Coupon More in-depth information is available in the Complex

corresponding paragraph.

ReturnCode The result of the operation. Enum

CouponHistory The history of the requested coupon. This is a collection Complex

of entries, each entry has the following properties:
• Stamp; date/time on which the mutation took
place.
• OperatorId; the employee ID of the operator
who performed the mutation.
• Comment; any given explanation/commentary
on the mutation.

© Cow Hills Retail BV Page 36 of 100

• ShopId; the provided shop ID for the mutation.
• PosId; the pos ID for the mutation.
• StatusOld; the status before mutation (if
applicable).
• StatusNew; the new status (if applicable).

Function: GetCoupons
This function can be used to query multiple coupons in a series/batch.

The following parameters exist:

Name Commentary Type

CouponRangeId The series for which coupons are being requested. String

BatchId The batch for which coupons are being requested. String

Status The status of the coupons being requested, this Enum

parameter is optional.

ExpiresBefore Optional value that restricts the returned data to Datetime

coupons that will expire before the supplied date.

Note that this parameter can only be used in conjunction

with parameter Status.

CreatedSince Optional value that restricts the returned data to Datetime

coupons that are created after the supplied date.

Note that this parameter cannot be used together with

ExpiresBefore.

MutatedSince Optional value that restricts the returned data to DateTime

coupons that have been mutated after the supplied date.

Example of a request:

Depending on how many coupons match the predicate, a result message will be sent. The result can contain
zero, one or multiple CouponInfo elements. The CouponInfo complex type is explained in the corresponding
paragraph.

Example of a response:

© Cow Hills Retail BV Page 37 of 100

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetCouponsResponse xmlns="http://cowhills.nl/EAccount">
<GetCouponsResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<CouponInfo>
<Barcode>9999085479192193537</Barcode>
<CouponRangeId>ca6b4b57-eb89-4528-82bb-51f43e91770d</CouponRangeId>
<CreatedAt>2015-03-26T11:36:57</CreatedAt>
<MaxRedeemCount>3</MaxRedeemCount>
<RedeemCount>0</RedeemCount>
<SerialNumber>85479192193537</SerialNumber>
<Status>Active</Status>
<ValidFrom i:nil="true"/>
<ValidUntill>2015-04-09T00:00:00</ValidUntill>
</CouponInfo>
<CouponInfo>
<Barcode>9999997280363549575</Barcode>
<CouponRangeId>ca6b4b57-eb89-4528-82bb-51f43e91770d</CouponRangeId>
<CreatedAt>2015-03-26T11:36:57</CreatedAt>
<MaxRedeemCount>3</MaxRedeemCount>
<RedeemCount>0</RedeemCount>
<SerialNumber>997280363549575</SerialNumber>
<Status>Active</Status>
<ValidFrom i:nil="true"/>
<ValidUntill>2015-04-09T00:00:00</ValidUntill>
</CouponInfo>
</GetCouponsResult>
</GetCouponsResponse>
</s:Body>
</s:Envelope>

Function: ResetRedeemCount
This function is used to reset the registered number of redemptions for a single coupon. It can be embedded in
the coupon management.

The following statusses can be used:

▪ Active

▪ Redeemed

▪ PartiallyRedeemed

Voided coupons (status: Void) cannot be reset, in this case WrongStatus will be returned.

The following parameters exist:

Name Commentary Type

Coupon Information regarding the coupon. More in-depth Complex

information is available in the corresponding paragraph.

ResetRedeemCount- Any comments provided for the operation. This is saved String
Parameters.Comment in the coupon history and will be shown when
GetCouponInfo is called.

ResetRedeemCount- The new number of redemptions, the value must be String

Parameters.RedeemCount anywhere between zero (0) and the set maximum
number of redemptions for the batch in which the
coupon was created.

Example of a request:

© Cow Hills Retail BV Page 38 of 100

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:eac="http://cowhills.nl/EAccount">
<soapenv:Header/>
<soapenv:Body>
<eac:ResetRedeemCount>
<eac:Auth>dcbc9f3c-c136-47ab-a6d6-23592f865f52</eac:Auth>
<eac:Parameters>
<eac:Barcode>9999459231533836726</eac:Barcode>
<eac:OperatorId>Server01</eac:OperatorId>
<eac:PosId>Web</eac:PosId>
<eac:ShopId>9999</eac:ShopId>
</eac:Parameters>
<eac:ResetRedeemCountParameters>
<eac:Comment>Test comment</eac:Comment>
<eac:RedeemCount>0</eac:RedeemCount>
</eac:ResetRedeemCountParameters>
</eac:ResetRedeemCount>
</soapenv:Body>
</soapenv:Envelope>

Example of a response:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<ResetRedeemCountResponse xmlns="http://cowhills.nl/EAccount">
<ResetRedeemCountResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ReturnCode>Success</ReturnCode>
</ResetRedeemCountResult>
</ResetRedeemCountResponse>
</s:Body>
</s:Envelope>

Function: VoidCouponBatch
This function is used to void a batch of coupons.

The following parameters exist:

Name Commentary Type

CouponRangeId The ID of the coupon series. String

BatchId The ID of the coupon batch. String

OperatorId The employee ID of the operator performing the String

operation.

The following values will be returned:

Name Commentary Type

ReturnCode The result of the operation. Enum

Function: UploadCoupons
This function is used to upload coupons in the Treazure system. It requires a batch with mode = manual to be
present for a specific coupon batch ID.

For each coupon, the following parameters exist:

© Cow Hills Retail BV Page 39 of 100

Name Commentary Type

SerialNumber The serial number of the coupon. String

ValidUntill The date/time untill the coupon is valid. If not supplied DateTime
the validity of the batch is used.

ValidFrom The date/time untill the coupon is valid. If not supplied DateTime
the validity of the batch is used.

Barcode The unique barcode of the coupon. String

The coupon upload is executed in full: all coupons are either succesfully uploaded or all coupons fail the upload.
If one coupon fail the upload validations (for instance: barcode already present in system) all coupons fail the
upload.

You can only upload up to 100 coupons at one time. If more coupons should be uploaded the upload-function
should be executed multiple times.

Function: VoidCoupons
This function is used for voiding individual coupons. A coupon is identified by it’s serial number. Up to 100
coupons can be voided at once.

The void is executed in full: all coupons are either succesfully voided or all coupons fail the void. If one coupon
fail the void validations (for instance: coupon already void) all coupons fail the void.

© Cow Hills Retail BV Page 40 of 100

6 CustomerVoucher API
The CustomerVoucher API is used to create and track vouchers per customer. A voucher is nothing more than
an internal code representing (some) value, for example; a specific promotional benefit. It can be used to limit
promotional events based on the use of customer cards.

The API doesn’t store promotional events, responsibility lies with the POS (consuming) system for that matter.
It is also no apprised of any redeem limitations, this is also the responsibility of the consuming (POS) system.

If the PemCalculation API is used, information available there can be hooked up to the CustomerVoucher API
directly. Each customer voucher has a limited validity, this validity is returned upon registration as the
previously specified expiration date/time.

Please note: this API is not meant to issue unique codes to customer, this should be done using the Coupon
API.

Function: RedeemCustomerVoucher
This function is used to redeem customer vouchers, it can be integrated in a check-out process.

The following parameters exist:

Name Commentary Type

CustomerId The unique customer ID. String

ExpirationDate The mandatory expiration date of the registered number. DateTime

The value must be between 00:00 the next day and five
years from now (start of day).

Please note: this expiration date will also apply to the

previously registered number. I.e. not just the number
redeemed in the current transaction.

RedeemCount The number to redeem, this cannot be lower than -1000, Int
exactly 0 or exceed 1000.

If the check-out is rolled back (insufficient funds, change

of heart etc.) the redeem count must be negative in
order to cancel the redemption.

VoucherId The unique ID of the voucher for which the number String
needs to be registered.

If a voucher ID is provided that has already been

registered, the current number will be incremented.

Example of a request:

© Cow Hills Retail BV Page 41 of 100

<eac:CustomerId>Customer0000001</eac:CustomerId>
<eac:ExpirationDate>2016-01-01T00:00:00</eac:ExpirationDate>
<eac:RedeemCount>1</eac:RedeemCount>
<eac:VoucherId>Promotion-001</eac:VoucherId>
</eac:RedeemRequest>
</eac:RedeemCustomerVoucher>
</soapenv:Body>
</soapenv:Envelope>

Example of a response:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<RedeemCustomerVoucherResponse xmlns="http://cowhills.nl/EAccount">
<RedeemCustomerVoucherResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<RedeemCount>6</RedeemCount>
<ReturnCode>Success</ReturnCode>
</RedeemCustomerVoucherResult>
</RedeemCustomerVoucherResponse>
</s:Body>
</s:Envelope>

The following values will be returned:

Name Commentary Type

RedeemCount The number redemptions registered to the voucher. String

ReturnCode The result of the operation. Enum

Function: GetCustomerVouchers
The GetCustomerVoucher function is used to query all known and valid (i.e. not expired) customer vouchers for
a single customer.

Multiple vouchers can be queried at once, they are selected using the voucher ID’s. The ID’s can be requested
via the PemCalculation API using the operation GetPemEntryCodesForCustomerCardLimit. For more
information please check the user case concerning promotion limitations and customer cards.

The following parameters exist:

Name Commentary Type

CustomerId The unique ID of the customer String

VoucherIds One or more voucher ID’s. Array

Example of a request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:eac="http://cowhills.nl/EAccount"
xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
<soapenv:Header/>
<soapenv:Body>
<eac:GetCustomerVouchers>
<eac:Auth>dcbc9f3c-c136-47ab-a6d6-23592f865f52</eac:Auth>
<eac:CustomerId>Customer0000001</eac:CustomerId>
<eac:VoucherIds>
<arr:string>Promotion-001</arr:string>
<arr:string>Promotion-002</arr:string>
</eac:VoucherIds>

© Cow Hills Retail BV Page 42 of 100

</eac:GetCustomerVouchers>
</soapenv:Body>
</soapenv:Envelope>

Example of a response:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetCustomerVouchersResponse xmlns="http://cowhills.nl/EAccount">
<GetCustomerVouchersResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ReturnCode>Success</ReturnCode>
<Vouchers>
<CustomerVoucher>
<ExpirationDate>2016-01-01T00:00:00</ExpirationDate>
<RedeemCount>6</RedeemCount>
<VoucherId>Promotion-001</VoucherId>
</CustomerVoucher>
</Vouchers>
</GetCustomerVouchersResult>
</GetCustomerVouchersResponse>
</s:Body>
</s:Envelope>

The following values will be returned:

Name Commentary Type

Vouchers Zero, one or more vouchers. Known and valid (i.e. not Complex
expired) vouchers will be returned. If a voucher is not
found, nothing will be returned regarding that voucher.
Therefore vouchers not in the response need to be
regarded as vouchers with a redemption count of 0.

Voucher.ExpirationDate The expiration date of the voucher. DateTime

Voucher.RedeemCount The number of times the voucher has been redeemed. Int

Voucher.VoucherId The corresponding voucher ID. String

ReturnCode The result of the operation. If no vouchers are found Enum

NotFound is returned.

The result of the operation can be forwarded to (for example) the PemCalculcation API using the PriorUse
elements. This method returns any known limitation for the customer card and how many times it has been
used in calculation. This information must be used to call the redeem function.

© Cow Hills Retail BV Page 43 of 100

7 PemCalculation API
This API is used for promotion calculations.

PrePublish
Each request fort his API can be provided with a PrePublish parameter. This parameter defined whether the
Treazure pre-pubish environment is to be used or not. For more information please check the
PemConfiguration API.

Please note: if Treazure is populated from an external system (e.g. the Retail Online Suite) pre-publishing is not
available. In this case a license error will be returned, see the below example:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<s:Fault>
<faultcode>s:LicenseRequired</faultcode>
<faultstring xml:lang="en-US">License 'Pem' required</faultstring>
</s:Fault>
</s:Body>
</s:Envelope>

Function: Calculate
The calculate function, as the name implies, takes care of calculcating the benefit for the customer. A basket is
offered to the API by the consuming system and the result consists of the same basket and the applied
promotional discounts (i.e. discounts and/or vouchers).

The calculate function is stateless; i.e. every request needs the whole basket and no information is kept in
memory on any basket.

7.2.1 Authentication token

An API key is needed for each calculation request, an API key is a unique key/guid used to eliminate the need
for sessions. API keys are issued when the contracts are concluded.

Note: the calculcation function is the only one which does not require an active session, but can be performed
with an API key instead. Thus removing the need to log on and log off, deviating from the normal procedure
which all other functions use.

7.2.2 Timeout
A calculcation request has a configured maximum execution time, to prevent overloads. The internal timeout
has been set to 1s (one second), which, normally, is more than enough.

When a timeout occurs the status code InternalError will be returned. There are two possible responses:

• TRZ timeout; this is a client timeout, the Treazure environment did not receive a response in a timely
manner.

• Engine timeout; this indicates a backend timeout, for example if a calculation took too long causing
the engine to cancel the operation.

© Cow Hills Retail BV Page 44 of 100

</CalculateResult>
</CalculateResponse>
</s:Body>
</s:Envelope>

7.2.3 Request and response

A calculation can be performed using a SOAP request. The next few paragraphs describe the structure of these
requests and responses.

CalculationRequest
The Calculate function is used to calculcate a result based on the contents of the sent basket. The input is
defined in the CalculationRequest structure.

The structure consists of several different components, we will be discussing these in the next few paragraphs.

7.3.1 General parameters

The following parameters can be defined to request a calculation:

Name Commentary Type Mandatory

SiteId A value indicating the unique ID of the String Yes1)

requesting site (shop). This can be either a
physical shop, or a webshop. This ID can be used
to filter promotions, for example based on
geographical conditions.

CalculationMoment This parameter offers the possibility to DateTime Yes

calculcate a promotion on a given date and
time.
1. Because the virtual promo agents can
be located in any random timezone,
the only way to make sure that the
promotion request is handeled with
the designated date and time settings
is to use the CalculationMoment.
2. This also offers functionality to
calculate against a future or past date
for testing purposes.

This value should be local time and not contain

time zone information.

UsePrepublish Determines whether non-published Bool No, default is

configuration should be used. If set to false, or false
not set at all the last known published
configuration will be used.

LanCode The language code in which the result needs to String Yes
be given. The code needs to be configured in
Treazure, all other codes are not (yet)
supported.
1) this value is mandatory when promotions for all stores are uploaded, else the value is disregarded.

© Cow Hills Retail BV Page 45 of 100

7.3.2 CustomerCards
It is possible to provide multiple customer cards (CustomerCard) for calculation.

Name Commentary Type Mandatory

Uid A unique identifier for the concerning customer String Yes

card.

CustomerLevelId The type/level of the customer card. This offers String No

functionality to filter promotion on certain levels
of customers. You can en- or disable promotions
on a defined customer level/type.

DiscountPercentage The discount percentage in centimes. Int No

Example of a CustomerCards element:

<pem:CustomerCards>
<pem:CustomerCard>
<pem:Uid>CustomerCard001</pem:Uid>
</pem:CustomerCard>
</pem:CustomerCards>

7.3.3 AirmilesCards
It is possible to add Airmiles cards to the calculation. The interface offers to possibilities to add any (absolute)
number of cards. However at this point only the first registered card will be used.

Example of an AirmilesCards element:

<pem:AirmilesCards>
<pem:AirmilesCard>
<pem:Uid>Air_01</pem:Uid>
<pem:Balance>5900</pem:Balance>
<pem:ValuePerUnit>1</pem:ValuePerUnit>
<pem:PointsPerUnit>100</pem:PointsPerUnit>
</pem:AirmilesCard>
</pem:AirmilesCards>

The following parameters exist:

Name Commentary Type Mandatory

Uid A unique identifier for the concerning Airmiles String Yes

card.

This doesn’t have to be the actual card number.

Balance The balance of the concerning Airmiles card in Int No

centimes. If no Airmiles are redeemed (only
saved), this value must be left empty.

Note: this value is the amount in the local

currency (not the total number of points), keep
this in mind when setting the parameter. The
consuming system needs to translate the number
of Airmiles to the amount in the local currency.

© Cow Hills Retail BV Page 46 of 100

The value is used to control the Airmiles
payments; the consuming system determines the
amount used and validates it against the available
number of points.

For example:

• Article A, limited to a 20 euro payment

through Airmiles
• Article B, limited to a 10 euro payment
through Airmiles
• Airmiles balance is 25 euro’s.

In this case Treazure will apply a discount of 20

euro’s to article ‘A’ and a discount of 5 euro’s to
article ‘B’ (together 25 euro’s).

ValuePerUnit The value in centimes for the number of Airmiles Int No

defined in the PointsPerUnit element valid for
airmiles discount/payment on product level

PointsPerUnit The number of Airmiles in centimes used to Int No

define the ValuePerUnit

7.3.4 EmployeeCards
It is possible to submit multiple employee cards (i.e. EmployeeCard elements) to the calculation.

Name Commentary Type Mandatory

Uid A unique identifier for the concerning employee String Yes

card. This value can be used by the consuming
system to match the discounts with the sale
entities.
Since all data is sent to the server and back, it is
not recommended to use unnecessary large
strings.

DiscountPercentage The discount percentage in centimes. If no Int No

discount is applicable the value needs to be 0.

EmployeeDiscountType The type of employee discount applied. Enum No

Currently possible values:

• Regular; regular employee discount

(default)
• Wear; corporate clothing discount
• Meal; meal discount

Note: if an employee is entitled to multiple

discount types, a card needs to be registered for
each type. Make sure that each UID is unique,
since it is bound to each sale entity. For example
if a card is used to two articles, the first UID is 1,

© Cow Hills Retail BV Page 47 of 100

the second one is 2 and so on. You are of course
free to implement your own system of keeping
track of discounts.

Balance The maximum amount of employee discount Int No

that can be applied. If a balance is 9,45 this
prevents Treazure from applying too much
discount in the case of 10% over an amount of
100.

This parameter can only be submitted with

absolute values. It only applies when
DiscountPercentage is also defined.

Example of an EmployeeCards element:

<pem:EmployeeCards>
<pem:EmployeeCard>
<pem:Uid>EMP001</pem:Uid>
<pem:DiscountPercentage>6000</pem:DiscountPercentage>
<pem:EmployeeDiscountType>Regular</pem:EmployeeDiscountType>
</pem:EmployeeCard>
</pem:EmployeeCards>

7.3.5 Sales
The Sales element allows for submission of sale lines. Normally promotions will be assigned to these elements.

Example of a Sales element:

<pem:Sales>
<pem:Sale>
<pem:Uid>Sale_001</pem:Uid>
<pem:ArticleId>10187055003</pem:ArticleId>
<pem:Amount>12500</pem:Amount>
<pem:Count>1</pem:Count>
<pem:Flags>
<pem:Flag>AirmilesLoyalty</pem:Flag>
</pem:Flags>
<pem:AirmilesPayment>
<pem:MaxPercentage>1000</pem:MaxPercentage>
</pem:AirmilesPayment>
</pem:Sale>
<pem:Sale>
<pem:Uid>Sale_002</pem:Uid>
<pem:ArticleId>10187055003</pem:ArticleId>
<pem:Amount>5999</pem:Amount>
<pem:Count>1</pem:Count>
<pem:Flags>
<pem:Flag>AirmilesLoyalty</pem:Flag>
</pem:Flags>
<pem:AirmilesPayment>
<pem:MaxPercentage>2500</pem:MaxPercentage>
</pem:AirmilesPayment>
</pem:Sale>
</pem:Sales>

A Sale element has the following properties:

Name Commentary Type Mandatory

© Cow Hills Retail BV Page 48 of 100

Uid A unique identifier for this sale. This value is used String Yes
as a reference for assigned discounts.
Since all data is sent to the server and back, it is
not recommended to use unnecessary large
strings.

ArticleId The article ID of the concerning Sale element. String Yes

ColorId The ID of the color as known in the master data. String No

This value is ofter used on fashion articles.

SizeId The ID of the size as known in the master data. String No

This value is often used on fashion articles.

GroupId The ID of the article group (lowest level in the String Yes
hierarchy) of the article as known in the master
data. It must be the lowest level, because the API
is unaware of the assortment (hierarchy and
otherwise).

Amount The gross amount of the sale line in centimes. Int Yes

Note: in this amount the number of articles

(count) has already been taking into account. I.e.
two articles of 50,- gives an amount of 100,-.

Count The number of articles (with the same article ID). Int Yes
This value is limited to 999. Any higher number
will result in a response code
InvalidParameterValue.

MaxDiscountPercentage The maximum percentage of discount assigned. Int No

7.3.5.1 Attribs
A Sale element can have certain sale attributes; Attribs. These are predefined on retailer level.

Example of a Attribs element:

<pem:Attribs>
<pem:Attrib>
<pem:Type>ProductieMaand</pem:Type>
<pem:Value>Jan</pem:Value>
</pem:Attrib>
</pem:Attribs>

An attribute has the following properties:

Name Commentary Type Mandatory

Type The type of the attribute, this value is case sensitive. String Yes

Value The value of the attribute, this value is also case String Yes
sensitive.

7.3.5.2 Flags
A Sale element can be supplemented with certain flags, these flags allow for the submission of specific
discount rules (whether or not specific discounts are allowed):

© Cow Hills Retail BV Page 49 of 100

Example of a Flags element:

<pem:Sale>
<pem:Uid>Sale_001</pem:Uid>
<pem:ArticleId>10187055003</pem:ArticleId>
<pem:Amount>12500</pem:Amount>
<pem:Count>1</pem:Count>
<pem:Flags>
<pem:Flag>AirmilesLoyalty</pem:Flag>
</pem:Flags>
</pem:Sale>

The following flags exist:

Name Commentary Default value

EmployeeDiscount Whether or not employee discount is allowed. By default no employee

discount is allowed.

AirmilesLoyalty Whether or not Airmiles can be saved on the sale By default no Airmiles will
line. be saved.

DenyDiscount Whether or not any discount is allowed on the By default discounts are
sale line. allowed.

7.3.5.3 AirmilesPayment
This element makes it possible to add optional control values for calculating Airmiles payments/discount
calculations.

Example of an AirmilesPayment element:

<pem:AirmilesPayment>
<pem:AirMilesToRedeem>100</pem:AirMilesToRedeem>
</pem:AirmilesPayment>

The following properties exist:

Name Commentary Type

AirMilesToRedeem The number or Airmiles that will be used to calculate the actual Int
Airmiles discount/payment

7.3.5.4 Discount on sale line level

7.3.5.4.1 Markdown (PLU discount)
A markdown price is actually a discount of the difference between the current and former price, this discount
is already known in the consuming system. It needs to be communicated to Treazure using the new price type
Plu.

Example of a Plu type discount:

<pem:Sales>
<pem:Sale>
<pem:Uid>Sale001</pem:Uid>
<pem:ArticleId>10187055003</pem:ArticleId>
<pem:Amount>3000</pem:Amount>
<pem:Count>3</pem:Count>
<pem:Discounts>

© Cow Hills Retail BV Page 50 of 100

<pem:Discount>
<pem:Type>Plu</pem:Type>
<pem:Uid>PLU001</pem:Uid>
<pem:NewPrice>2250</pem:NewPrice>
</pem:Discount>
</pem:Discounts>
</pem:Sale>
</pem:Sales>

In this example three articles of 10,- are in the basket. These articles have markdown prices of 7,50 per article
and the new price of the set is 22,50. This value needs to take the amount of articles in account.

The following result will be given:

As seen in the above result the total amount for the sale line is 7,50, divided over three lines, of the type Plu.

7.3.5.4.2 NewPrice
With a NewPrice line discount it is possible to specify a new price on line level and get the difference as a
discount.

<pem:Sales>
<pem:Sale>
<pem:Uid>Sale001</pem:Uid>
<pem:ArticleId>10187055003</pem:ArticleId>
<pem:Amount>3000</pem:Amount>
<pem:Count>3</pem:Count>
<pem:Discounts>
<pem:Discount>
<pem:Type>NewPrice</pem:Type>
<pem:Uid>PLU001</pem:Uid>
<pem:NewPrice>2250</pem:NewPrice>
<pem:DiscountId>MyDiscountId</pem:DiscountId>
</pem:Discount>
</pem:Discounts>
</pem:Sale>
</pem:Sales>

7.3.5.4.3 EmployeeDiscount
It’s possible to specify an employee discount percentage on line level. This requires an employee card to be
present in that basket.

<pem:Sales>
<pem:Sale>
<pem:Uid>Sale001</pem:Uid>
<pem:ArticleId>10187055003</pem:ArticleId>
<pem:Amount>3000</pem:Amount>
<pem:Count>3</pem:Count>
<pem:Discounts>
<pem:Discount>
<pem:Type>EmployeeDiscount</pem:Type>
<pem:Uid>PLU001</pem:Uid>
<pem:Percentage>1250</pem:Percentage>
<pem:DiscountId>MyDiscountId</pem:DiscountId>
</pem:Discount>
</pem:Discounts>
</pem:Sale>

© Cow Hills Retail BV Page 51 of 100

</pem:Sales>

7.3.6 Discounts
The Discounts element allows for definition of explicit discounts for the whole receipt. I.e. if a pre-set amount
of discount applies to a single transaction. The element has the following properties:

Name Commentary Type

DiscountId The discount code, this code is returned in the response for String
registrational purposes. The value is optional.

Type The type of the discount that is applied. Enum

The following types currently exist:

• Amount; discount of a pre set amount

• Percentage; discount in terms of percentage
• AirMilesReceiptAmount; discount based on Airmiles

Amount The amount to be applied as discount, in centimes. This value is Int

mandatory if Type=Amount or Type= AirMilesReceiptAmount.

Percentage The percentage of the total amount to be applied as discount, in Int

centimes. This value is mandatory if Type=Percentage.

ValuePerUnit The value in centimes for the number of Airmiles defined in the Int No
PointsPerUnit element valid for airmiles discount/payment for receipt
discounts

PointsPerUnit The number of Airmiles in centimes used to define the ValuePerUnit Int No
for receipt discounts

An example, to an article of 100,- a discount of 15,- and 10% is applied:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:pem="http://cowhills.nl/EAccount/PEM">
<soapenv:Header/>
<soapenv:Body>
<pem:Calculate>
<pem:Auth>8376cd77-e40e-4b83-b915-024d4af9d5ad</pem:Auth>
<pem:Request LanCode="nl" UsePrePublish="true">
<pem:Sales>
<pem:Sale>
<pem:Uid>Sale001</pem:Uid>
<pem:ArticleId>10187055003</pem:ArticleId>
<pem:GroupId>GROUP001</pem:GroupId>
<pem:Amount>10000</pem:Amount>
<pem:Count>1</pem:Count>
</pem:Sale>
</pem:Sales>
<pem:Discounts>
<pem:Discount>
<pem:Type>Amount</pem:Type>
<pem:DiscountId>CustomDiscount-1</pem:DiscountId>
<pem:Uid>Discount001</pem:Uid>
<pem:Amount>1500</pem:Amount>
</pem:Discount>
<pem:Discount>
<pem:Type>Percentage</pem:Type>
<pem:DiscountId>CustomDiscount-2</pem:DiscountId>
<pem:Uid>Discount002</pem:Uid>

© Cow Hills Retail BV Page 52 of 100

<pem:Percentage>1000</pem:Percentage>
</pem:Discount>
</pem:Discounts>
</pem:Request>
</pem:Calculate>
</soapenv:Body>
</soapenv:Envelope>

The result of the operation:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<CalculateResponse xmlns="http://cowhills.nl/EAccount/PEM">
<CalculateResult Code="Success">
<FinancialResults>
<Result Amount="1500" Count="1" Type="ReceiptAmount" DiscountId="CustomDiscount-1">
<Ref Uid="Sale001" Tier="150"/>
</Result>
<Result Amount="850" Count="1" Type="ReceiptPercentage" DiscountId="CustomDiscount-2">
<Ref Uid="Sale001" Tier="160"/>
</Result>
<Result Amount="956" Desc="Bonus op 10187055003" Count="1" Type="Promotion">
<Ref Uid="Sale001" Tier="200" Code="Bonus_10187055003"/>
</Result>
</FinancialResults>
<Summary>
<PerPemEntry>
<Entry Code="Bonus_10187055003" QtyThis="1" Type="Financial"/>
</PerPemEntry>
</Summary>
</CalculateResult>
</CalculateResponse>
</s:Body>
</s:Envelope>

The following discounts are applied:

• 15,00; the 15,- (amount) discount

• 8,50; 10% on the remaining 85,- (100,- minus the 15,- amount discount)

• Promotional discount of 9,56; 12,5% discount on the remaining 76,50 (85,- minus 8,50; the previously
applied 10% discount)

7.3.7 Coupons
It is possible to add coupons to a calculation request.

Example of a Coupons element:

<pem:Coupons>
<pem:Coupon>
<pem:Uid>COUPON_0001</pem:Uid>
<pem:CouponId>25%MetCoupon</pem:CouponId>
</pem:Coupon>
</pem:Coupons>

Such a coupon is identified as a recognizable generic value/type.

Promotion can be configured in a way that they trigger on a specific coupon being used. In the example a
coupon of the type ‘25%MetCoupon’ is used, in this example the coupon is already known in the configuration.

In order to process the coupon in the calculation the following steps will be taken:

© Cow Hills Retail BV Page 53 of 100

1) The user submits a coupon on a website/the cashier scans a coupon.

2) Coupon recognition and validation occurs.

3) The coupon is identified as type ‘25%MetCoupon’.

4) The coupon type is added to the request.

The following properties exist:

Name Commentary Type

Uid The unique identifier of the element. String

CouponId The generic coupon identifier. String

The coupons used are returned in the response using the value TriggerCouponIds. This can be used to validate
if a coupon is actually used, this way the used coupons can be collected by the supplier (either Treazure or a
third party). For more information on the matter see the paragraph regarding CalculationResponse.

7.3.8 TransactionAttributes
It is possible to have promotions trigger on certain (customer) characteristics provided by the consuming
system. For example, having a promotion trigger on the birthday of a customer. The service does not keep
track of any of these events, they have to be provided (in a TransactionAttribute) and configured in order to
trigger correctly.

The process can be described as below:

1) In the Treazure promotion configuration an event has been configured to trigger if the transaction
attribute ‘VANDAAG_JARIG’ exists.

2) A transaction is created on the consuming system.

3) The consuming system knows today is the birthday of the customer and adds the transaction
attribute ‘VANDAAG_JARIG’ to the transaction and thus the request to Treazure.

In this case the promotion will trigger, because the needed attribute has been supplied.

The following TransactionAttribute properties exist:

Name Commentary Type

Uid The unique identifier of the element. String

Value The trigger value of the transaction attribute (e.g. VANDAAG_JARIG). String

7.3.9 PriorUses
A promotion can be limited to a fixed number of times it can trigger per customer. Treazure, being stateless,
does not keep track of this. Meaning that the consuming system must keep track of how many times a
promotion is used by a certain customer.

In the configuration it is possible to take prior uses and limitations into account.

The process can be described as below:

© Cow Hills Retail BV Page 54 of 100

1) The constuming system retrieves prior uses, for example by using the CustomerVoucher API.

2) For each previously used promotion a PemPriorUse element is registered in the request.

A PriorUse element has the following properties:

Name Commentary Type

Uid The unique identifier of the element. String

Count The number of times the promotion triggered before. Int

PemEntryCode The code of the promotion. String

In the result promotions limited on how many times they may be triggered are clearly identified. It is therefore
of the utmost importance that the consuming system unambiguously communicates the prior uses of each
promotion, if applicable. For more information see the corresponding paragraph; PromotionSummary results.

7.3.10 ShippingCosts
This element allows for specification of shipping costs, it is for example, possible for a retailer to configure
specific shipping costs promotions.

The below example shows a ShippingCosts element with a value of 15 (Euro).

<pem:ShippingCosts>
<pem:ShippingCost>
<pem:Uid>Ship001</pem:Uid>
<pem:Amount>1500</pem:Amount>
</pem:ShippingCost>
</pem:ShippingCosts>

A ShippingCost element has the following properties:

Name Commentary Type

Uid The unique identifier of the element. String

Amount The shipping cost amount. Int

It’s possible to submit multiple ShippingCost elements, discounts however will always be combined into one
discount element.

© Cow Hills Retail BV Page 55 of 100

CalculationResponse
Just like a calculation request the CalculationResponse is in a structured format.

An example of a response:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<CalculateResponse xmlns="http://cowhills.nl/EAccount/PEM">
<CalculateResult seqNr="14" code="Success">
<FinancialResults>
<Result Amount="1499" Desc="Laag 4, Coupon geeft 25%!!!" Count="1"
DiscountType="Promotion">
<Ref uid="Sale001" tier="50000" code="013"/>
<TriggerCouponIds>
<CouponId>123654789</CouponId>
</TriggerCouponIds>
</Result>
</FinancialResults>
<DiscountVoucherResults>
<Result Amount="300">
<Ref uid="Sale001" tier="0" code="LoyaltyNLAV"/>
</Result>
</DiscountVoucherResults>
<Summary>
<PerPemEntry>
<Entry code="013" qtyThis="1" type="Financial"/>
<Entry code="LoyaltyNLAV" qtyThis="1" type="DiscountVoucher"/>
</PerPemEntry>
</Summary>
</CalculateResult>
</CalculateResponse>
</s:Body>
</s:Envelope>

The response has the following properties:

Name Commentary Type

Code The technical code for the executed request. Enum

The following values can be expected:

• Success; calculation was successful

• UnderlayingSystemOffline; the backend is unavailable
• InternalError; an error occurred

SeqNr The number of the promotion configuration (for troubleshooting Int

purposes).
If the request is submitted on the pre-publish environment this value is
not returned (because the configuration is still unrevisioned).

ErrorMessage If an error occurred this field will contain additional information. String

The result will contain assigned promotion line, we will be attending to those in the next few paragraphs.

7.4.1 Complex type: Ref

Results in the response are enriched with the element Ref. See example below:

© Cow Hills Retail BV Page 56 of 100

The Ref element is used to communicatie generic information regarding an assiged promotion.

The following properties exist:

Name Commentary Type

Uid The identifier of the element in the request to which the assigned String
promotion belongs.

Tier The tier on which the promotion has been applied. This can be used to Int
trace back the order in which promotional discounts have been
assigned. The higher the value, the lower in the chain the promotion was
applied.

Code The promotion code of the result. This value can be empty if the String
discount was supplied; for example in the case of a markdown price.

Gid Grouping identifier. This field is to be used for splitting up the items Int
based on assigned discounts.

BaseAmt The base amount in cents for this result. This value is conditional and is Int
for instance returned with an employeecard-discount.

7.4.2 Warnings
Upon calculation it is possible that warnings are generated. For example if an unused language code is
submitted, since calculation can actually continue a warning instead of an error is generated. Note that this is
only one possibility, the example shows another one.

Example of a warning:

A warning has the following properties:

Name Commentary Type

Uid The element causing the warning. String

Msg The warning in tekst, this is a technical message and always in English. It String
is not meant as a textual representation for the end-user.

7.4.3 FinancialResult / FinancialCalculationResult

If a calculation results in a discount, the FinancialResults element will contain all information regarding the
applied discount(s) and the items the discount(s) must be assigned to. The (optional)
FinancialCalculationResult wil contain the discount(s), based on the items they were calculated over. This

© Cow Hills Retail BV Page 57 of 100

FinancialCalculationResult can be used for displaying purposes, when the result must be displayed on the
items the discount was calculated over.

To summarize:

Name Purpose When to use

FinancialResult Booking Generating invoice

FinancialCalculationResult Displaying Temporary view, basket overview, checkout process

An example of a FinancialResults element:

The following properties exist:

Name Commentary Type

Amount The amount in centimes. Int

Desc The description of the discount, in the language selected in the String
request (i.e. matching the language code provided).

Count The number of times the promotion was triggered. Int

DiscountType The type of the applied financial discount. Enum

• Promotion
• EmployeeCard
• CustomerCard
• Plu (markdown)
• ReceiptAmount
• LoyaltyManualAmount (a.o. Airmiles product discounts)
• AirMilesReceiptAmount

TriggerCouponIds If the promotion was triggered by coupons, this element shows String[]
which coupons were ‘used’. It is a reliable indication of which
coupons need to be redeemed.

DiscountId If a discount has been submitted the explicit code is shows in this String
element.

TransactionAttributes The transaction attributes that were used by this financial Complex[]
promotion.

Display The display level of the financial promotion, if specified in the Enum
promotion configuration.

• OnHeader

© Cow Hills Retail BV Page 58 of 100

• OnDetail (default)

Please note that this does not affect the way the discounts are
specified: discounts will always be specified on detail level; this
setting merely indicates that these discounts should be
summarized and displayed to the customer on header level.

BookingType The booking type the promotion is setup for. This determines String
how the discount should be booked logically.

RedeemedLoyaltyPoints Number of redeemed loyalty points (i.e. Airmiles) Int

7.4.3.1 Shipping costs

Discount on shipping costs can be calculated/applied.

Example of a request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:pem="http://cowhills.nl/EAccount/PEM">
<soapenv:Header/>
<soapenv:Body>
<pem:Calculate>
<pem:Auth>8376cd77-e40e-4b83-b915-024d4af9d5ad</pem:Auth>
<pem:Request LanCode="nl" UsePrePublish="false">
<pem:Sales>
<pem:Sale>
<pem:Uid>Sale001</pem:Uid>
<pem:ArticleId>999</pem:ArticleId>
<pem:Amount>9900</pem:Amount>
<pem:Count>1</pem:Count>
</pem:Sale>
</pem:Sales>
<pem:ShippingCosts>
<pem:ShippingCost>
<pem:Uid>Ship001</pem:Uid>
<pem:Amount>1000</pem:Amount>
</pem:ShippingCost>
</pem:ShippingCosts>
</pem:Request>
</pem:Calculate>
</soapenv:Body>
</soapenv:Envelope>

If a discount on shipping costs has been applied this is applied to the Uid of the shipping costs in a
FinancialResult element. For example:

© Cow Hills Retail BV Page 59 of 100

</s:Envelope>

The above example shows a discount of 5,- on the shipping costs.

7.4.4 LoyaltyResult and saved Airmiles

The results of saving programs are returned in the LoyaltyResults element.

Example of a LoyaltyResults element:

The result contains the following properties:

Name Commentary Type

Amount The number of points saved, in centimes. Int

Desc Description of the loyalty programme. String

Type The type of points saved. Enum

Some examples:

• Regular; regular points

• Bonus; bonus points

Program The type of savings programme. Enum

Some examples:

• Airmiles; the Airmiles programme

• Generic; a generic loyalty programme

Count The number of items this loyalty result applies to. Int

7.4.5 IssuedCouponResult
If a calculation results in the issuance of one or more coupons, it is found in this element. A coupon element
has the following properties:

Name Commentary Type

CouponId The ID of the coupon. String

Desc The description of the promotion. String

A generic coupon will be returned. Based on this generic code the consuming party need to register/request a
unique coupon ID.

© Cow Hills Retail BV Page 60 of 100

7.4.6 DiscountVoucherResult
A voucher can be assigned to the next purchase, this is returned using a DiscountVoucherResults element.

Example of a request:

Example of a response:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<CalculateResponse xmlns="http://cowhills.nl/EAccount/PEM">
<CalculateResult Code="Success">
<FinancialResults>
<Result Amount="1250" Desc="Bonus op 10187055003" Count="1" Type="Promotion">
<Ref Uid="Sale001" Tier="200" Code="Bonus_10187055003"/>
</Result>
</FinancialResults>
<IssuedCouponResults>
<Result CouponId="KoffieCouponCode0064">
<Ref Uid="Sale001" Tier="250" Code="CouponVoorGratisKoffie"/>
</Result>
</IssuedCouponResults>
<DiscountVoucherResults>
<Result Amount="875">
<Ref Uid="Sale001" Tier="260" Code="10%KortingsVoucher"/>
</Result>
</DiscountVoucherResults>
<Summary>
<PerPemEntry>
<Entry Code="CouponVoorGratisKoffie" QtyThis="1" Type="IssueCoupon"/>
<Entry Code="10%KortingsVoucher" QtyThis="1" Type="DiscountVoucher"/>
<Entry Code="Bonus_10187055003" QtyThis="1" Type="Financial"/>
</PerPemEntry>
</Summary>
</CalculateResult>
</CalculateResponse>
</s:Body>
</s:Envelope>

In the above example the following has been assigned:

• A financial promotion

• A coupon

• A discount voucher with a value of 8,75; 10% over 87,50 (100,- minus 12,50)

© Cow Hills Retail BV Page 61 of 100

Keep in mind that the service only returns the benefits the customer is entitled to. The actual
generation/registration of the discount voucher is the responsibility of the consuming system.

A discount voucher has the following properties:

Name Commentary Type

Amount The amount in centimes. Int

Desc The description of the promotion. String

7.4.7 TypeValueResult
This type indicates a generic type value promotion has been allotted. This type of promotion (result) can be
used to define an own result in de the Pem API. For example if the customer qualifies for a specific news letter.

Example of such a result:

The result has the following properties:

Name Commentary Type

Type The type configured in the promotion. String

Value The value configured in the promotion. String

Desc The description of the promotion. String

7.4.8 ExtraArticleResult
This type indicates the client has been assigned a promotion for an additional article to be bought for a reduced
amount or to receive it for free.

Example:

The result has the following properties:

Name Commentary Type

Price The price in cents the extra article can be bought for. Can be zero for free Int
articles.

© Cow Hills Retail BV Page 62 of 100

Desc The description of the promotion. String

Options The article options (1 or more). Complex

array

Options- The articles to pick from. ColorId and SizeId can be wildcards (‘*’) or String
>ArticleId, target a specific article variant.
ColorId and
SizeId

7.4.9 MessageResult
This type indicates a configured message has been triggered by the system.

Example:

This result has the following properties:

Name Commentary Type

Desc The description of the promotion. String

Msg The message. String

7.4.10 Summary
The calculation result also provides a total overview of the discounts applied in the form of a summary.

Example of a Summary element:

The following information is embedded:

Name Commentary Type

AirmilesPayment The total value of airmiles payments in the calculation. Int

Keep in mind that the value of the airmiles payment is returned in the
local/configured currency; the consuming system needs to convert these
to the actual amount of airmiles used.

The value is returned in centimes, if the value is 0 it is not returned at all.

© Cow Hills Retail BV Page 63 of 100

Furthermore a summary on promotion level is returned in the form of a PerPemEntry. Each Entry element in
this list has the following properties:

Name Commentary Type

Code The code of the promotion. String

Type Het type promotie. Enum

The following values exist at this moment:

• Financial
• TypeValue
• Loyalty
• IssueCoupon
• DiscountVoucher
The type matches the structure of the result.

QtyThis The number of times this promotion has been used in the calculation. Int

QtyLimit The maximum number of times this promotion can be used. This value Int
can only be returned if a limit has been defined for customer card
holders.

QtyPrior The number of times this promotion has been used prior to the current Int
calculation. This information is submitted in PriorUse elements in the
calculation request. If this information is not submitted, it will not be
included in the result.

© Cow Hills Retail BV Page 64 of 100

7.4.11 Grouping identifier (gid)
Treazure returns a grouping identifier, gid. This identifier indicates that the discount calculation result should
result in a split-up of the provided lines, because a discount only applies to a part of such a provided line.

For instance, a case whereby the following promotions exist:

• Discount A; 10,- discount when buying 3

• Discount B; 50% discount on the cheapest item

Both discounts apply (ie. they are not exclusive).

Take the following request:

This yields the following response (Soap-envelope omitted for readability):

<CalculateResult SeqNr="33" Code="Success">

The Gid-values indicate that the original order sale should be split up on the order. This result should be
interpreted and processed as follows:

Article Id Line No Gid Count Effective discount

10370 1 0 1 • 3,34 → Discount A

© Cow Hills Retail BV Page 65 of 100

• 23,33 → Discount B

10370 2 1 2 • 6,66 → Discount A

10370 3 Rest 1 None

Function: GetInfo
This function allows for functionality to retrieve promotional information on an article. It is an informative
function and can thus be used independently from the basket functions.

This function has the same environmental parameters as the calculcate function. Therefore UsePrePublish,
LanCode, SiteId and CalculationMoment can be used to suit your needs.

The article for which the information is requested must be submitted in the Article element. This element is
identical to the Sale element in terms of structure.

Example of a request:

Example of a response:

As shown above a collection of PemEntry elements is returned. The following properties exist for each of those
elements:

© Cow Hills Retail BV Page 66 of 100

Name Commentary Type

Code The code of the promotion. String

Start The explicit start date of the promotion. DateTime

End The explicit expiration date of the promotion. DateTime

Desc The description of the promotion. String

LongDesc The long (more verbal) description of the promotion. The contents of this String
field will never be returned in the Calculate function, it is purely
informational.

This value will typically be used to provide the cashier more extensive
information regarding the promotion.

Type The type of the promotion. See paragraph CalculationResponse for Enum
possible return values.

Function: GetPemEntryCodesForCustomerCardLimit
This operation is used to request promotion codes which are limited for customer card holders. The result can
be used to retrieve prior uses if a customer is registered in the consuming system.

Example of a request:

It is possible to use the UsePrePublish attribute in the request, usage is the same a in the Calculate operation.

© Cow Hills Retail BV Page 67 of 100

Example of a response:

A collection of codes is returned.

Function: CouponExists
This operation can be used to verify whether a coupon code is currently in the active promotion configuration.
This function can be used by web apps to verify that the used coupon is actually known in a running promotion.

Please note this function has no relation with the coupon API.

Example of a request:

Example of a response:

Note: this means you can verify generic coupons by filling in the barcode, unique coupons require you to query
the CouponRangeIdsee GetCouponInfo and use that string instead.

The result will indicate whether the specified coupon ID is a generic or a unique coupon. If the type of coupon is
unknown this field is omitted.

© Cow Hills Retail BV Page 68 of 100

8 PemConfiguration API
The PemConfiguration API is used to manage the existing promotions.

Please note that this API is only used if the PemCalculation API is not directly connected to a maintenance
system, like the Retail Online Suite (ROS). In that case the promotions can be maintained using the rCos client,
which is a user-friendly system designed to maintain any task performed at head-office.

Structure
The API uses so called Pem entries. A Pem entry can best be described as a promotion/benefit/campaign which
is triggered by the contents of/elements in the basket submitted to the web service. For example a discount
which is triggered only is a customer card is used.

The following entities exist:

Name Commentary

Entry A configuration of a single promotion. This can be either a financial

promotion (discount) or a voucher issuing promotion. It can be connected
to a generic action, like inclusion in a newsletter. A specific type is available
for mailing purposes.

Filter A filter applies to a promotion, they can be translated to the requirements

for a promotion to trigger. The requirements which need to be met can
consist of articles (combination of articles required to trigger) or for
example a customer or employee card.

The filter structure is quite elaborate as it allows for AND- and OR-
constructions (logical con- and disjunction). See the Filter paragraph for
more information.

Tier The tier can be translated to a layer to which a promotion applies. Layer
being the abstract desciption of the concept. It influences priority and
exclusivity; promotions configured to the same tier can exclude one
another. In every calculation the best price for the customer is determined
and returned per tier.

This inevitably means that every tier will validate against the new prices
from the previous one, thus affecting the outcome of the following tier.

General settings Generic Pem settings configured per retailer. These settings include
parameters beyond the scope of a single promotion.

General settings
Beside the individual promotions, some settings can be maintained on a global scale. These settings can be
maintained using the GetPemConfiguration and PushPemConfiguration API’s.

A PemConfiguration has the following properties:

Name Commentary

System tier Promotions work under the retention of so-called tiers; however there are
discounts which are not triggered by promotions. One of those examples is
employee discount.

Sale attribute Attributes used in sales, these can, in turn, be used in promotion filters.

An example of a sale attribute is a brand; promotions can be configured to

only trigger on specific brands. Since the PemCalculation API is not
apprised of any brand information, this information must be specified in
the basket.

Language The language used in maintenance.

Filters
Filters are configured on entry level, requirements for each filter need to be met before a promotion can be
applied. For each configured filter a logical conjunction applies.

Within each filter details can be configured using so-called rules. Rules are the embodiment of the filter, they
contain the defined restrictions. Rules are applied using a logical disjunction.

There are many different rule types, all of which can be added to a filter without restrictions. If a rule type is
not specified, it means no limitation exists; for example if no customer card rule has been set, there will be no
filtering on customer cards.

The following rules exist at this moment:

Name Commentary

Article Restrictions on specified articles, or groups of articles in the basket.

Transaction attribute It is possible to configure external conditions, for example certain

attributes from a CRM system.

Coupon Limitation based on the fact if a certain coupon has been added to the
transaction.

Customer card Restrictions based on the availability of a customer card.

Employee card Restrictions based on the availability of an employee card.

Site Restrictions based on geographical information.

Additionally each filter has the following properties which can be set:

Name Commentary Type Mandatory

Active Defines whether the filter is actually active. If not it Boolean Yes
will be ignored.

Name The name of the filter, this is only used for String Yes
registrational purposes and has no function on how
the filter operates. It is not found in any calculation
response.

MinOccors The number requirement of articles/elements in the Int Yes
MaxOccurs basket which needs to be met.

For example:
• If the promotion must trigger on each article
(e.g. when applying a 1,- discount on each
article) both settings need to be set to 1;
MinOccurs=1, MaxOccurs=1
• If the promotion may only trigger once (e.g.
when issuing coupons) they must be set to:
MinOccurs=1, MaxOccurs=999. Assuming no
more than 999 articles will be added to a
transaction.

MinAmount The amount requirement which needs to be met, Int No

MaxAmount using only articles defined in this filter.

These parameters only apply to article elements. If

they are defined as 0, they do not apply at all.

Identical Defines whether the occurances in the article filter Boolean No, default
only apply to identical articles. = false

For example:
• A promotion is configured for tins of paint,
buy two get one free. This applies to five
individual articles, they have been added tot
he filter. The filter has the Boolean value of
Identical set to true.
• A customer buys three different tins of paint
(all three articles exist in the rules); but since
they are not identical the promotion will not
trigger.
• A customer buys three tins of paint, all three
are the same article and exist as an article
rule; the promotion will trigger because they
are identical.

Article rules
An article rule has the following properties:

Name Commentary Type Mandatory

PluRequirement Defines how the rule deals with markdown prices Enum Yes
(PLU discounts).

The possibilities are:

• DontCare; markdown prices have no
influence
• Required; markdown prices are mandatory
• Disallow; markdown prices are excluded

GroupId The ID of the group from the hierarchy to which the String Yes
rule applies.

This value is mandatory if not article ID is supplied.

ArticleId The ID of the article for which the rule applies. String Yes

This value is mandatory if no group ID is supplied.

ColorId Specific limitation based on color codes. If not String Yes

supplied the wildcard character ‘*’ needs to be filled
in.

SizeId Specific limitation based on size codes. If not supplied String Yes
the wildcard character ‘*’ needs to be filled in.

Exclude Defines whether the filled in characteristics should Boolean No,

either in- or exclude the matching articles for the default=false
rule.

MinPrice Price limitation for the specified article or articles Int No

MaxPrice from the specified group. This applies to the value of
each singular article, if the values have been defined
as 0 this filtering option is ignored.

It’s also possible to add SaleAttribute restrictions to a rule. The following properties apply to such an attribute:

Name Commentary Type Mandatory

Type The type of sale attribute, this type needs to be String Yes
configured in the general Pem settings.

Value The value to which the sale attribute has to comply. String Yes
It’s possible to use the wildcard character ‘*’ at the
start or end of the value. Evaluation of the value will
check if the value starts or ends with the supplied
value.

Note: this value is case-sensitive.

Customer card rule

A customer card rule has the following properties:

Name Commentary Type Mandatory

CustomerCard- Defines which customer card limitations are in Enum Yes

Requirement effect.

The possibilities are:

• DontCare; customer cards are of no
influence
• Required; customer card is required
• Disallow; customer cards are not allowed

CustomerLevelIds The customer levels for which limitations apply. If String array No
not supplied this property is ignored.

LimitCount Defines whether the number of times a Int No
promotion can be used in combination with a
specific customer card is limited.

This setting applies to all transactions linked to a

specific customer card. This way the benefit of the
current promotion can be limited to a predefined
number of times per unique customer. For
example if the value has been set to five; when a
customer benefitted three times last week,
he/she only has two more times he/she can
benefit from this promotion left.

If not supplied this limitation does not apply.

For more information please see the PriorUse

paragraph in the PemCalculation API.

Employee card rule

An employee card rule has the following properties:

Name Commentary Type Mandatory

EmployeeCard- Defines which employee restrictions apply. Enum Yes

Requirement
The possibilities are:
• DontCare; employee cards are of no
influence
• Required; employee card is required
• Disallow; employee cards are not
allowed

EmployeeDiscountType The type of employee discount Enum Yes

The possibilities are:

• Any; type is of no influence
• Regular; promotion only applies to
regular employee discounts
• Meal; promotion only applies to meal
discounts
• Wear; promotion only applies to
corporate clothing discounts

Site rule
The site rule allows for filtering on the dimension Site. This way geographical limitations can be imposed,
restricting the area in which the promotion is in effect. A Site can be configured as an alphanumeric value.

A site rule has the following properties:

Name Commentary Type Mandatory

Sites The collection of sites on which the promotion will String No
be applied.

(Pre)publication
The maintenance API’s allow for configuration of the promotions. Any changes made are instantly available in
calculation requests which use the UsePrePublish=true flag.

The pre-publish mode can be used to test the effect of promotions for a retailer. This can be incorporated in
the maintenance functions of promotions.

If the configuration is satisfactory, publication can commence. The PemPublish function is designed to do this.
PemPublish selects active promotions and general settings, validates them and – if validation is successful –
publishes the new configuration to the Treazure platform. Each publication is identified using a unique
sequence number.

A published configuration is replicated to all calculcation agents known to the system. Treazure is designed to
do this autonomously, within minutes the PemCalculation API will be loaded with the new configuration. The
configuration version will be returned with each calculation result, the value SeqNr should correspond to the
unique sequence number of the publication.

9 Giftcard API (frontoffice)
Giftcard-status
A giftcard can have the following statusses:

• Created

• Active

• Redeemed

• Void

• Expired

• Refunded

Function: GetGiftcardInfo
This function allows for the querying of giftcard information, this function will not change any data.

Example request:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:eac="http://cowhills.nl/EAccount">
<soapenv:Header/>
<soapenv:Body>
<eac:GetGiftcardInfo>
<eac:Auth>f0eb4369-46ec-4143-a171-1f79888dacf3</eac:Auth>
<eac:Parameters LanCode="nl-NL">
<eac:Barcode>9761003001RWCDXTDQ8UBTEAE</eac:Barcode>
</eac:Parameters>
</eac:GetGiftcardInfo>
</soapenv:Body>
</soapenv:Envelope>

Example response:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<GetGiftcardInfoResponse xmlns="http://cowhills.nl/EAccount">
<GetGiftcardInfoResult>
<Giftcard>
<SerialNumber>RWCDXTDQ8UBTEAE</SerialNumber>
<Barcode>9761003001RWCDXTDQ8UBTEAE</Barcode>
<Status>Active</Status>
<ValidUntill>2021-12-31T00:00:00</ValidUntill>
<Balance>5000</Balance>
<BrandName>RetourBetaling</BrandName>
<Ean>9999312345</Ean>
<Refundable>false</Refundable>
<LoadType>Loadable</LoadType>
</Giftcard>
<ReturnCode>Success</ReturnCode>
</GetGiftcardInfoResult>
</GetGiftcardInfoResponse>
</s:Body>
</s:Envelope>

Function: ActivateGiftcard
This enables the selling of giftcards. There are two types of giftcards which can be sold:

• Preloaded

o The ‘LoadAmount’ represents the original value of the card. If the giftcard is sold with a
discount, this is not to be sent to Treazure. Since it is of influence of the value.

• Loadable

o The ‘LoadAmount’ needs to be set to the amount the customer wants to load on the card.

For this function a giftcard reference is needed. Depending on the giftcard product settings (setting
ActivateWithCardId) this is done with a unique card reference (barcode or serial number) or just the product
number (Ean).

The following parameters exist:

Name Commentary

LoadAmount The amount to load. This value is required.

EAN The international article number (formerly known as: European Article Number).
This is used to identify the product (this cross check prevents selling the wrong
physical product for the activated barcode)..

ValidUntill The date this giftcard expires. The provided date is included in the validity period
(it expires at 23:59:59). This value is optional and if not provided the validity rules
of the product are honored.

Currency The currency for the loaded amount. This value is required if the product is
configured as such. This value has to match the product currency.

This function returns an ‘ActivationId’, this can be registered to enable troubleshooting later on. This is also the
ID which needs to be submitted to cancel the activation/sale.

Example request:

Example response:

<ValidUntill>2021-12-31T00:00:00</ValidUntill>
<Balance>5000</Balance>
<BrandName>RetourBetaling</BrandName>
<Ean>9999312345</Ean>
<Refundable>false</Refundable>
<LoadType>Loadable</LoadType>
</Giftcard>
<ActivationId>8f9e9363-0ed9-4758-8c8a-b108b389b039</ActivationId>
</ActivateGiftCardResult>
</ActivateGiftCardResponse>
</s:Body>
</s:Envelope>

Function: CancelActivateGiftcard
It is possible to cancel an activation, the CancelActivateGiftcard function only requires the returned
‘ActivationId’ (returned by the ActivateGiftcard function).

Function: RedeemGiftcard
This function is used to redeem a giftcard, a ‘RedeemId’ is returned.

The following parameters exist:

Name Commentary

RedeemAmount The amount to be redeemed in centimes.

Currency The currency for the redeem amount. This value is required if the product is
configured as such. This value has to match the product currency.

Function: CancelRedeemGiftcard
Apart from activation, redemptions can also be cancelled. Just like the CancelActivateGiftcard, the
CancelRedeemGiftcard needs the Id from the opposing function. In this case that is the ‘RedeemId’.

Function: RefundGiftcard
This function allows for the return of previously sold giftcards.

There are some conditions which need to be met:

• The giftcard product allows for returns

• The giftcard has already been sold successfully

• No redemption has taken place on the giftcard yet

Please note: this function differs from the CancelRedeemGiftcard. Because as opposed to the
CancelActivationGiftcard, this functions updates the status (to ‘Refunded’) rather than reverting to the
previous one. This results in the fact that a refunded giftcard cannot be sold anymore. It is advised this
function is only used when a customer has actually left the shop. If the activation has to be annulled in the
same transaction as activation took place, use CancelActivateGiftcard.

10 Giftcard API (backoffice)
Entities
• Product

• Batch

• Giftcard

Function: CreateProduct
This function allows for the creation of products.

The following parameters exist:

Name Commentary

BrandName n/a

Currency The used currency for the product.

Prefix n/a

Ean The international article number.

SerialNumberDigits n/a

ScratchCodeDigits n/a

LoadType Either ‘Loadable’ or ‘PreLoaded’.

BarcodeType The type of barcode for this product. One of the following:

• Code128

Generates a unique number from A-Z and 0-9.

• Itf2of5

Generates a numerical number. Total barcode length must be even.

RefundMode Either ‘Possible’ or ‘NotPossible’.

LoadAmount The amount to load preloaded cards with.

Description Description of the product, this value is multi lingual.

MarketName Name of the market this giftcard is for.

MaxLoadAmount The max value a giftcard can be loaded with. This value is optional and
only expected with load type ‘Loadable’.

ValidGiftcardTypes Array of strings, the following types are supported:

• empty

For ‘normal’ giftcards.

• LoyaltyVaults

For specific use cases, more values can be added in the future.

Reloadable Whether it is possible to reload the giftcard, after it has been

activated/loaded or fully redeemed.

ActivateWithCardId Whether the giftcard should be activated with the unique card id. If false,
the giftcard can be activated with the Ean only (and Treazure will return
the first elegible giftcard).

CurrencyRequired Whether an explicit currency is required for activating/redeeming giftcards

for this product.

AutoGrowParameters Auto grow parameters for automatically creating new gift card batches
when certain thresholds are reached.

Threshold The threshold value that triggers the creation of the new batch. The
number of

Size The size of the new batch.

ValidUntillDays The number of days the new batch is valid.

GiftcardType The type of giftcard to be used in automatically created batches.

The response contains the following elements:

Name Commentary

ReturnCode The return code of the operation.

ProductId The ID assigned by Treazure to the product.

ParameterName In case of an error, the parameter name that caused it.

ErrorMessage In case of an error, a description of the error.

Function: GetGiftcardProducts
Returns all giftcard products.

Example request:

Example response:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">

<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<GetGiftcardProductsResponse xmlns="http://cowhills.nl/EAccount">
<GetGiftcardProductsResult>
<Products>
<Product>
<CreatedAt>2017-07-04T17:57:55</CreatedAt>
<BrandName>RetourBetaling</BrandName>
<Currency>EUR</Currency>
<Prefix>9761003001</Prefix>
<Ean>9999312345</Ean>
<SerialNumberDigits>15</SerialNumberDigits>
<ScratchCodeDigits>0</ScratchCodeDigits>
<LoadType>Loadable</LoadType>
<LoadAmount>0</LoadAmount>
<ProductId>c022a4de-faa1-478d-b6a2-8ec877875945</ProductId>
</Product>
</Products>
<ReturnCode>Success</ReturnCode>
</GetGiftcardProductsResult>
</GetGiftcardProductsResponse>
</s:Body>
</s:Envelope>

Function: GenerateGiftcards
Creates a new giftcards batch, a batch ID will be returned.

Please note: giftcards, just like coupons, are generated using a background process. This function only creates
the batch, the actual unique numbers will be available a few minutes after, depening on server load.

The following parameters exist:

Name Commentary Data type

NumberOfGiftcards The number of giftcards to generate Int

ValidUntill When the giftcards will expire DateTime

ProductId The ID of the product to generate giftcards for String

ValidFrom From when the giftcard will be valid DateTime

10.4.1 Giftcard uniqueness

When generating new giftcards Treazure will check whether the distribution factor will not get too low. If more
then 1 out of 10.000 possible giftcard serial numbers exist Treazure will not accept the creation of more giftcards.

Since giftcards are created in a batch process this will be verified in the background generation process. The
batch will yield an error status.

Function: GetGiftcardBatches
Returns all batches for a specific giftcard product.

Example request:

<eac:ProductId>c022a4de-faa1-478d-b6a2-8ec877875945</eac:ProductId>
</eac:Parameters>
</eac:GetGiftcardBatches>
</soapenv:Body>
</soapenv:Envelope>

Example response:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<GetGiftcardBatchesResponse xmlns="http://cowhills.nl/EAccount">
<GetGiftcardBatchesResult>
<Batches>
<Batch Created="2017-07-04T16:02:17" ValidUntil="2021-12-31T00:00:00" Qty="10000"
QtyCreated="10000" Id="eb5be602-61d6-428f-a990-4523ba430762" OperatorId="Giftcard" Status="Ready”/>
</Batches>
<ReturnCode>Success</ReturnCode>
<Stats>
<Created>
<Quantity>9999</Quantity>
<TotalBalance>0</TotalBalance>
<TotalStartBalance>0</TotalStartBalance>
</Created>
<Active>
<Quantity>1</Quantity>
<TotalBalance>1500</TotalBalance>
<TotalStartBalance>0</TotalStartBalance>
</Active>
</Stats>
</GetGiftcardBatchesResult>
</GetGiftcardBatchesResponse>
</s:Body>
</s:Envelope>

Function: GetGiftcardBarcodes
Returns all giftcard barcodes from a single batch, this is same batch ID which was returned upon generation.

Example request:

Example response:

Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<GetGiftcardBarcodesResponse xmlns="http://cowhills.nl/EAccount">
<GetGiftcardBarcodesResult>
<Barcodes>
<Gc Bc="97610030012GLHAU8E2X7U3JL" Sn="2GLHAU8E2X7U3JL" St="Created" Sb="0" Ba="0"/>
<Gc Bc="9761003001RWCDXTDQ8UBTEAE" Sn="RWCDXTDQ8UBTEAE" St="Created" Sb="0" Ba="0"/>
</Barcodes>
<ReturnCode>Success</ReturnCode>

</GetGiftcardBarcodesResult>
</GetGiftcardBarcodesResponse>
</s:Body>
</s:Envelope>

Function: UpdateGiftcard
Backend function to edit the status of a single giftcard. It also allows for the reloading of a card.

Function: GetGiftcardHistory
Returns the history of a single giftcard.

Function: UploadGiftcards
This function is used to upload giftcards in the Treazure system. The giftcards are uploaded for a specific product
and assigned to the most recent giftcard batch.

For each giftcard, the following parameters exist:

Name Commentary Type

SerialNumber The serial number of the giftcard. String

ScratchCode The scratch code of the giftcard. String

ValidUntill The date/time untill the giftcard is valid. If not supplied DateTime
the validity rules of the product are used.

ValidFrom The date/time untill the giftcard is valid. If not supplied DateTime
the validity rules of the product are used.

Barcode The unique barcode of the giftcard. String

LoadAmount The amount to load the giftcard with, in cents. Int

Status The initial status of the giftcard. Enum

GiftcardType The giftcard type Enum

The giftcard upload is executed transactional: all giftcards are either succesfully uploaded or all giftcards fail the
upload. If one giftcard fail the upload validations (for instance: barcode already present in system or wrong
combination of parameters) all giftcards fail the upload.

You can only upload up to 100 giftcards at one time. If more giftcards should be uploaded the upload-function
should be executed multiple times.

11 LoyaltyVault
Function: IssueAccount
This function takes the first available account with the status ‘created’ and activates it, the number of this
account is returned in the response. This function requires an available giftcard (type=LoyaltyVault) to be
activated (issued), when no such card is found the following error is returned:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<IssueAccountResponse xmlns="http://cowhills.nl/EAccount">
<IssueAccountResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Account i:nil="true"/>
<ActivationId i:nil="true"/>
<ErrorMessage>backing product missing</ErrorMessage>
<ReturnCode>NotFound</ReturnCode>
</IssueAccountResult>
</IssueAccountResponse>
</s:Body>
</s:Envelope>

Backing product missing can be interpreted as a missing product and/or batch of giftcards ready to activate, the
customer must define the product (type=LoyaltyVault) first, after which cards can be created (batch-wise) to be
used in transactions.

The following parameters exist:

Name Commentary

Comment Comments for the activation.

OperatorId ID of the operator creating the transaction.

PosId ID of the POS on which the activation takes place.

ShopId The international article number.

The response contains the following elements:

Name Commentary

AccountNumber The newly activated account.

ActivationId The transaction ID of the activation.

ReturnCode Operation status code.

Example request:

<eac:OperatorId>654321</eac:OperatorId>
<eac:PosId>01</eac:PosId>
<eac:ReceiptNr>123</eac:ReceiptNr>
<eac:ShopId>0800</eac:ShopId>
</eac:Context>
</eac:Parameters>
</eac:IssueAccount>
</soapenv:Body>
</soapenv:Envelope>

Example response:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<IssueAccountResponse xmlns="http://cowhills.nl/EAccount">
<IssueAccountResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Account>
<AccountNumber>2602C44YPMPL4</AccountNumber>
</Account>
<ActivationId>fad25169c3fe42219460eb4f29eea48f</ActivationId>
<ErrorMessage i:nil="true"/>
<ReturnCode>Success</ReturnCode>
</IssueAccountResult>
</IssueAccountResponse>
</s:Body>
</s:Envelope>

Function: CancelIssueAccount
Cancels a previously activated account.

Example response:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<CancelIssueAccountResponse xmlns="http://cowhills.nl/EAccount">
<CancelIssueAccountResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ReturnCode>Success</ReturnCode>
</CancelIssueAccountResult>
</CancelIssueAccountResponse>
</s:Body>
</s:Envelope>

Function: LoadAccountBalance
Load balance on activated accounts.

The following parameters exist:

Name Commentary

AccountNumber The account on which the balance should be loaded.

Amount When the giftcards will expire

Comment Comments for the activation.

OperatorId ID of the operator creating the transaction.

PosId ID of the POS on which the activation takes place.

ShopId The international article number.

The response contains the following elements:

Name Commentary

Balance The new amount, after load.

ErrorMessage If an error occurred, the message will be populated.

LoadId The transaction ID of the activation.

ReturnCode Operation status code.

Example request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:eac="http://cowhills.nl/EAccount">
<soapenv:Header/>
<soapenv:Body>
<eac:LoadAccountBalance>
<eac:Auth>207a08b6-9e9b-413a-870b-2eba7be9445c</eac:Auth>
<eac:Account>
<eac:AccountNumber>2602C44YPMPL4</eac:AccountNumber>
</eac:Account>
<eac:Parameters>
<eac:Amount>50</eac:Amount>
<eac:Context>
<eac:Comment>Initial load</eac:Comment>
<eac:OperatorId>654321</eac:OperatorId>
<eac:PosId>01</eac:PosId>
<eac:ReceiptNr>124</eac:ReceiptNr>
<eac:ShopId>0800</eac:ShopId>
</eac:Context>
</eac:Parameters>
</eac:LoadAccountBalance>
</soapenv:Body>
</soapenv:Envelope>

Example response:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<LoadAccountBalanceResponse xmlns="http://cowhills.nl/EAccount">
<LoadAccountBalanceResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Balance>50</Balance>
<ErrorMessage i:nil="true"/>
<LoadId>38b5b1dcdb5448dd90cfd0630d4c7b62</LoadId>
<ReturnCode>Success</ReturnCode>
</LoadAccountBalanceResult>
</LoadAccountBalanceResponse>

</s:Body>
</s:Envelope>

Function: CancelLoadAccountBalance
Cancels a previous load by referencing the account number and LoadId.

Example response:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<CancelLoadAccountBalanceResponse xmlns="http://cowhills.nl/EAccount">
<CancelLoadAccountBalanceResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ReturnCode>Success</ReturnCode>
</CancelLoadAccountBalanceResult>
</CancelLoadAccountBalanceResponse>
</s:Body>
</s:Envelope>

Function: GetAccountBalance
Returns the balance for a specific loyalty account and all known historical changes.

Example response:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetAccountBalanceResponse xmlns="http://cowhills.nl/EAccount">
<GetAccountBalanceResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Active>true</Active>
<Balance>100</Balance>
<ErrorMessage i:nil="true"/>
<History>
<Events>
<GiftcardHistoryEvent>
<Comment>Initial load</Comment>
<OperatorId>654321</OperatorId>
<PosId>01</PosId>

<ReceiptNr>124</ReceiptNr>
<RedeemAmount>-50</RedeemAmount>
<ShopId>0800</ShopId>
<Stamp>2019-01-15T17:27:47</Stamp>
<StatusNew>Active</StatusNew>
<StatusOld>Active</StatusOld>
</GiftcardHistoryEvent>
<GiftcardHistoryEvent>
<Comment>Initial load</Comment>
<OperatorId>654321</OperatorId>
<PosId>01</PosId>
<ReceiptNr>124</ReceiptNr>
<RedeemAmount>-50</RedeemAmount>
<ShopId>0800</ShopId>
<Stamp>2019-01-15T17:23:24</Stamp>
<StatusNew>Active</StatusNew>
<StatusOld>Active</StatusOld>
</GiftcardHistoryEvent>
<GiftcardHistoryEvent>
<Comment>Initiate</Comment>
<OperatorId>654321</OperatorId>
<PosId>01</PosId>
<ReceiptNr>123</ReceiptNr>
<RedeemAmount>0</RedeemAmount>
<ShopId>0800</ShopId>
<Stamp>2019-01-15T15:17:00</Stamp>
<StatusNew>Active</StatusNew>
<StatusOld>Created</StatusOld>
</GiftcardHistoryEvent>
<GiftcardHistoryEvent>
<Comment i:nil="true"/>
<OperatorId i:nil="true"/>
<PosId i:nil="true"/>
<ReceiptNr i:nil="true"/>
<RedeemAmount>0</RedeemAmount>
<ShopId i:nil="true"/>
<Stamp>2018-12-10T16:19:12</Stamp>
<StatusNew>Created</StatusNew>
<StatusOld>Created</StatusOld>
</GiftcardHistoryEvent>
</Events>
</History>
<ReturnCode>Success</ReturnCode>
</GetAccountBalanceResult>
</GetAccountBalanceResponse>
</s:Body>
</s:Envelope>

Function: RedeemAccountBalance
Redeem balance from accounts.

The following parameters exist:

Name Commentary

AccountNumber The account on which the balance should be loaded.

Amount When the giftcards will expire

Comment Comments for the activation.

OperatorId ID of the operator creating the transaction.

PosId ID of the POS on which the activation takes place.

ShopId The international article number.

The response contains the following elements:

Name Commentary

Balance The new amount, after load.

ErrorMessage If an error occurred, the message will be populated.

LoadId The transaction ID of the activation.

ReturnCode Operation status code.

Example request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:eac="http://cowhills.nl/EAccount">
<soapenv:Header/>
<soapenv:Body>
<eac:RedeemAccountBalance>
<eac:Auth>07167e14-0182-45fb-b29c-f191a59a894c</eac:Auth>
<eac:Account>
<eac:AccountNumber>2602C44YPMPL4</eac:AccountNumber>
</eac:Account>
<eac:Parameters>
<eac:Amount>25</eac:Amount>
<eac:Context>
<eac:Comment>Enjoy benefits</eac:Comment>
<eac:OperatorId>654321</eac:OperatorId>
<eac:PosId>01</eac:PosId>
<eac:ReceiptNr>124</eac:ReceiptNr>
<eac:ShopId>0800</eac:ShopId>
</eac:Context>
</eac:Parameters>
</eac:RedeemAccountBalance>
</soapenv:Body>
</soapenv:Envelope>

Example response:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<RedeemAccountBalanceResponse xmlns="http://cowhills.nl/EAccount">
<RedeemAccountBalanceResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Balance>75</Balance>
<ErrorMessage i:nil="true"/>
<RedeemId>73dca4fb527f4516a93f4b064a1a4eee</RedeemId>
<ReturnCode>Success</ReturnCode>
</RedeemAccountBalanceResult>
</RedeemAccountBalanceResponse>
</s:Body>
</s:Envelope>

Function: CancelRedeemAccountBalance
Cancels a previous redeem by referencing the account number and RedeemId.

</eac:Account>
<eac:Parameters>
<eac:RedeemId>73dca4fb527f4516a93f4b064a1a4eee</eac:RedeemId>
</eac:Parameters>
</eac:CancelRedeemAccountBalance>
</soapenv:Body>
</soapenv:Envelope>

Example response:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<CancelRedeemAccountBalanceResponse xmlns="http://cowhills.nl/EAccount">
<CancelRedeemAccountBalanceResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ReturnCode>Success</ReturnCode>
</CancelRedeemAccountBalanceResult>
</CancelRedeemAccountBalanceResponse>
</s:Body>
</s:Envelope>

12 EmployeeBalanceVault API
Setup
This API is built on the giftcard engine. It requires a product to be setup. This product has the following
requirements:

• Brand name: EmployeeBalanceVault

• Currency: EMP

• Load type: Account

• Prefix: EMP

• Number of digits serial number: 22

• Number of digits scratch code: 0

• Barcode type: Code128

• Refund: NotPossible

• Reloadable: true

• Gift card types: this dimension is used as the booking periods. Multiple values are supported.

• Auto grow: disable

An open batch must be created for accounts to be stored in. This is default giftcard behavior.

Meta data
For all mutating operations the following info can be supplied:

• ShopId

• PosId

• OperatorId

• ReceiptNumber

• Comment

These values do not influence the behavior of the API, these are merely for registration.

Account identifier
An employee balance account is identified with an employee id and a booking period. The booking period must
be an existing value in the system.

Function: GetAccountBalance
Returns the balance for the specified account. Also, the load and redemption history is returned.

Function: LoadAccountBalance
Loads balance on the specified account.

Function: CancelLoadAccountBalance
Cancels the result of a LoadAccountBalance operation.

Function: RedeemAccountBalance
Redeems balance from a specified account.

Function: CancelRedeemAccountBalance
Cancels the result of a RedeemAccountBalance operation.

Function: CreateNewAccounts
Creates one or more new accounts. Optionally, a starting balance can be provided. Up to 100 accounts can be
created in one batch.

13 Server status API
This API offers service status information. It has no authentication restrictions.

Ping
This method allows for obtaining the service status. There are no input parameters, the function is generally
available.

The response contains the following information:

Name Commentary Type

Up Whether the service and all internal systems are up Boolean

Reason Why the client is down String

DateTimeUtc The server date and time (UTC) DateTime

ClientIp The IP of the client as resolved by Treazure. String

14 Appendix A: General result codes
This appendix describes the different result codes returned by the Treazure platform.

The below result codes are used throughout the entire Treazure platform, some codes will never be returned
in certain functions. The most relevant result codes are mentioned with each function.

The following codes have been implemented:

Name Commentary Http

response
code

AuthenticationFailed This code is used in authentication methods. 401

Note: if an authorized function is called with an invalid

authorization token an exception is returned as opposed
to a result code.

Success Indicates processing was succesful. 200

NotFound Indicates one or more values used in parameters have 200

not been found.

WrongStatus Indicates a mismatch in status for an operation, e.g. an 200

already redeemed coupon has been used for
redemption.

This value is primarily used in the coupon module.

MandatoryParameterMissing An expected (mandatory) parameter is missing in the 400

request.

WrongCancelId Indicates the provided cancel ID is invalid/incorrect. 200

This value is used in the CancelActivateCoupon and

CancelRedeemCoupon functions in the Coupon API.

InvalidParameterValue A used parameter is invalid. 400

UnderlayingSystemOffline This result is returned if the request could not be relayed 503
internally.

This value is used in the Calculate function of the

PemCalculation API.

InternalError This is an internal status code and will not be returned. In 500
the case of internal error an exception error message will
be returned instead.

SyntaxError If the provided syntax fails the schema this error will be 400
returned. For instance when an invalid datatype is
provided.

15 Appendix B: Example use cases
This chapter will describe some use cases for the available API’s. It clarifies how the different API’s can be used
to implement a fully functional solution.

In the examples it is assumed the session token is available. The session token can be obtained using the login
function on the Authentication API.

Promotion can only be used thrice per customer.

This case will cover a promotion which is limited for use in combination with customer cards. This example has
limited the use to three times per unique customer card.

Basic rule:

1) The customer is registered in the consuming system.

When the customer is identified:

• Using the GetPemEntryCodesForCustomerCardLimit (in the PemCalculation API) the (promotion)

codes with trigger limitations are requested.

• The GetCustomerVouchers function (in the CustomerVoucher API) returns the previously registered
vouchers.

On basket mutation:

• The basket is created

o Add PriorUse elements based on the results of GetCustomerVouchers

• The Calculcate function is called:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:pem="http://cowhills.nl/EAccount/PEM">
<soapenv:Header/>
<soapenv:Body>
<pem:Calculate>
<pem:Auth>8376cd77-e40e-4b83-b915-024d4af9d5ad</pem:Auth>
<pem:Request LanCode="nl" UsePrePublish="true">
<pem:Sales>
<pem:Sale>
<pem:Uid>Sale001</pem:Uid>
<pem:ArticleId>AAAAA</pem:ArticleId>
<pem:GroupId>GROUP001</pem:GroupId>
<pem:Amount>25000</pem:Amount>
<pem:Count>2</pem:Count>
<pem:Attribs>
<pem:Attrib>
<pem:Type>ProductieMaand</pem:Type>
<pem:Value>Jan</pem:Value>
</pem:Attrib>
</pem:Attribs>
</pem:Sale>

</pem:Sales>
<pem:CustomerCards>
<pem:CustomerCard>
<pem:Uid>CustomerCard001</pem:Uid>
</pem:CustomerCard>
</pem:CustomerCards>
<pem:PriorUses>
<pem:PemPriorUse>
<pem:Uid>Prior001</pem:Uid>

<pem:PemEntryCode>10xperklant</pem:PemEntryCode>
<pem:Count>9</pem:Count>
</pem:PemPriorUse>
</pem:PriorUses>
</pem:Request>
</pem:Calculate>
</soapenv:Body>
</soapenv:Envelope>

The following result is given:

The summary shows that the promotion only triggered once, the limit was ten times and there were nine prior
uses. Meaning the next time it won’t trigger.

Upon payment:

• Determine the vouchers which need to be redeemed, these can be found in the result of the Calculate
operation. In the above example the Entry elements in the Summary which have the QtyLimit set.

• The RedeemCustomerVoucher operation (in the CustomerVoucher API) allows for the registration of
the vouchers.

Employee discount
This case describes the calculation of employee discounts on purchases.

The following basic rules must be established:

1) The consuming system must know if a customer is entitled to employee discount.

2) The consuming system knows how much discount can be applied to employee purchases.

3) The consuming system know whether employee discounts can be applied to the articles in the basket
(master data).

The flow of the transaction:

1) Articles are added to the basket

2) The basket is created:

a. For each article a flag is set whether employee discount is allowed (or disallowed for that
matter).

b. The EmployeeCard element is added, in this element the discount percentage is defined.

3) The Calculate function is called:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:pem="http://cowhills.nl/EAccount/PEM">
<soapenv:Header/>
<soapenv:Body>
<pem:Calculate>
<pem:Auth>8376cd77-e40e-4b83-b915-024d4af9d5ad</pem:Auth>
<pem:Request LanCode="nl" UsePrePublish="true">
<pem:Sales>
<pem:Sale>
<pem:Uid>Sale001</pem:Uid>
<pem:ArticleId>10187055003</pem:ArticleId>
<pem:Amount>3000</pem:Amount>
<pem:Count>3</pem:Count>
<pem:Flags>
<pem:Flag>EmployeeDiscount</pem:Flag>
</pem:Flags>
</pem:Sale>
</pem:Sales>
<pem:EmployeeCards>
<pem:EmployeeCard>
<pem:Uid>EmployeeCard001</pem:Uid>
<pem:EmployeeDiscountType>Regular</pem:EmployeeDiscountType>
<pem:DiscountPercentage>1000</pem:DiscountPercentage>
</pem:EmployeeCard>
</pem:EmployeeCards>
</pem:Request>
</pem:Calculate>
</soapenv:Body>
</soapenv:Envelope>

4) The result contains the EmployeeCard element.

Markdown prices
A markdown price needs to be identified as such, this way the discount will be visible and recognizable in the
result.

The following basic rules must be established:

1) The prices before and after markdown are known in the consuming system.

2) The basket is created:

a. Markdowned prices are added to the sale element as a Plu type discount.

3) The Calculate function is called:

<soapenv:Header/>
<soapenv:Body>
<pem:Calculate>
<pem:Auth>8376cd77-e40e-4b83-b915-024d4af9d5ad</pem:Auth>
<pem:Request LanCode="nl" UsePrePublish="true">
<pem:Sales>
<pem:Sale>
<pem:Uid>Sale001</pem:Uid>
<pem:ArticleId>10187055003</pem:ArticleId>
<pem:Amount>3000</pem:Amount>
<pem:Count>3</pem:Count>
<pem:Discounts>
<pem:Discount>
<pem:Type>Plu</pem:Type>
<pem:Uid>PLU001</pem:Uid>
<pem:NewPrice>2250</pem:NewPrice>
</pem:Discount>
</pem:Discounts>
</pem:Sale>
</pem:Sales>
</pem:Request>
</pem:Calculate>
</soapenv:Body>
</soapenv:Envelope>

The above example shows that an article has been sold three times with a markdowned price of 7,50; which
brings the total to 22,50 as opposed to 30,-. This discount of 2,50 times the number of articles (three in this
particular case) makes a total markdown of 7,50 over 30,-. The new price (3 x 7,50 = 22,50) must be submitted
in a NewPrice element.

4) Processing the result:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<CalculateResponse xmlns="http://cowhills.nl/EAccount/PEM">
<CalculateResult Code="Success">
<FinancialResults>
<Result Amount="281" Desc="Bonus op 10187055003" Count="3" Type="Promotion">
<Ref Uid="Sale001" Tier="0" Code="Bonus_10187055003"/>
</Result>
<Result Amount="750" Count="3" Type="Plu">
<Ref Uid="Sale001" Tier="-500"/>
</Result>
</FinancialResults>
<Summary>
<PerPemEntry>
<Entry Code="Bonus_10187055003" QtyThis="1" Type="Financial"/>
</PerPemEntry>
</Summary>
</CalculateResult>
</CalculateResponse>
</s:Body>
</s:Envelope>

In the above result the markdown ‘discount’ is visible in the FinancialResults element, there is also another
discount visible, the type clarifies that one is the result of a promotion.

Pregenerating coupons
This case describes a situation in which coupons are generated and issued, for example using physical prints or
mailing.

The following basic rules must be established:

1) The coupons and metadata have to be defined in the consuming system. The metadata consists, at
least, of a description of the coupon and how they will be distribuated etc.

15.4.1 Generating coupons

Coupons are generated in advance, this enables printing and mailing to customers for all kinds of marketing
reasons.

1) To start coupon generation, the function GenerateCoupons in the Coupon API is available. Coupon
generation is background process, the result of the function returns a batch ID. The batch ID can be
used to check the result and progress of the previously started generation.

a. This function has to be called with batchmode PreGenerated, triggering the Treazure
platform to generate coupons.

b. If the parameter AutoActivate is not set to true, the system will return an errormessage.

2) The GetCouponBatches return all batches and their statusses, this makes it easy to check if
generations are complete.

3) If the generation is completed, the GetCoupons functions allows for the request of the generated
coupons. The result of this request can be sent to the printer, this way only generated coupons will be
printed. This functionality is always available and not limited to a one-time use.

15.4.2 Registering a coupon from the customer

Registering a coupon:

1) GetCouponInfo is called with the barcode provided.

2) Depending on the status of the coupon:

a. The customer is informed the coupon has expired/is unknown in the system

b. The coupon is added to the basket

15.4.3 Using a coupon

The consuming system has validated the coupon (either by itself, or by using the Coupon API).

1) Articles are added to the basket

2) The basket is created:

a. Coupon elements are added for registered coupons

3) The Calculate function is called:

<pem:Uid>COUPON_0001</pem:Uid>
<pem:CouponId>CouponCodeVoor20%OpLaarzen</pem:CouponId>
</pem:Coupon>
</pem:Coupons>
</pem:Request>
</pem:Calculate>
</soapenv:Body>
</soapenv:Envelope>

The below is an example of a result:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<CalculateResponse xmlns="http://cowhills.nl/EAccount/PEM">
<CalculateResult Code="Success">
<FinancialResults>
<Result Amount="749" Desc="Bonus op 10187055003" Count="1" Type="Promotion">
<Ref Uid="Sale001" Tier="0" Code="Bonus_10187055003"/>
</Result>
<Result Amount="1049" Desc="20% korting op laarzen met coupon" Count="1"
Type="Promotion">
<Ref Uid="Sale001" Tier="250" Code="20%metcoupon"/>
<TriggerCouponIds>
<CouponId>CouponCodeVoor20%OpLaarzen</CouponId>
</TriggerCouponIds>
</Result>
</FinancialResults>
<Summary>
<PerPemEntry>
<Entry Code="Bonus_10187055003" QtyThis="1" Type="Financial"/>
<Entry Code="20%metcoupon" QtyThis="1" Type="Financial"/>
</PerPemEntry>
</Summary>
</CalculateResult>
</CalculateResponse>
</s:Body>
</s:Envelope>

As seen in the above response message two promotions have been applied; a promotion with description
‘Bonus op 10187055003’ (12,5% discount) and a promotion triggered by a coupon. The used coupon ID is also
visible, which relates to the CouponRangeId which was returned when generating the series.

The financial results are calculated as follows:

• 59,95 (original price)

o 7,49 discount (12,5% of 59,95) – first applied here, because the tier is the lowest (0)

o 10,49 discount (20% of 52,46 [the remained of 59,59 – 7,49]) – applied afterwards, because
it is the second tier (250)

• 41,97 to be paid by the customer

15.4.4 Redeeming a coupon

If the basket is committed and paid for by the customer, coupons can be redeemed.

1) The Calculate function returns which coupons have been used in the transaction (calculation).

2) For these coupons the RedeemCoupon function needs to be called.

3) The result defines whether a requested redeem succeeded or not. The ‘RedeemId’ needs to be saved
for registrational purposes and in case the redeem needs to be reversed.

4) After that the payment needs to take place (either in the shop, or by using iDeal for example).

5) If the payment fails, or the redeem needs to be cancelled for any other reason, they can be cancelled
by using the CancelRedeem function. In order to cancel a redemption, the ‘RedeemId’ needs to be
provided, as saved in step 3. This can happen if two coupons are to be redeemed, but the second
redemption fails.

KCB Mpesa STK Push Api Specification Document
No ratings yet
KCB Mpesa STK Push Api Specification Document
4 pages
API Management
No ratings yet
API Management
568 pages
Midtrans Documentation
No ratings yet
Midtrans Documentation
95 pages
HDFC API Document
100% (1)
HDFC API Document
160 pages
Inventory Strategy: Maximizing Financial, Service and Operations Performance with Inventory Strategy
From Everand
Inventory Strategy: Maximizing Financial, Service and Operations Performance with Inventory Strategy
Edward H. Frazelle
5/5 (2)
Database Caching Strategies Using Redis
No ratings yet
Database Caching Strategies Using Redis
22 pages
SAP Customer Checkout Manager API Guide
No ratings yet
SAP Customer Checkout Manager API Guide
44 pages
banggood-affiliate-apidoc-v1.2.2
No ratings yet
banggood-affiliate-apidoc-v1.2.2
25 pages
IPOS ERPAPIDocumentation 091121 0609 36028
No ratings yet
IPOS ERPAPIDocumentation 091121 0609 36028
55 pages
Example Api Documentation by Mindtrans
No ratings yet
Example Api Documentation by Mindtrans
60 pages
API Management
No ratings yet
API Management
848 pages
Express Checkout Integration Guide
No ratings yet
Express Checkout Integration Guide
110 pages
Setup 2 - REST API Specs For Reward System v1.05 (Confirm Transaction)
No ratings yet
Setup 2 - REST API Specs For Reward System v1.05 (Confirm Transaction)
9 pages
PP API Reference
No ratings yet
PP API Reference
272 pages
Online Transaction and Tokenization API
No ratings yet
Online Transaction and Tokenization API
10 pages
Web Service API: Integration Guide
No ratings yet
Web Service API: Integration Guide
124 pages
Sitecore Connect Developer Guide A4
No ratings yet
Sitecore Connect Developer Guide A4
142 pages
IPG_Integration Guide_API_2024-1
No ratings yet
IPG_Integration Guide_API_2024-1
177 pages
PP Pay Flow Pro XMLPay Guide
No ratings yet
PP Pay Flow Pro XMLPay Guide
162 pages
IPG IntegrationGuide API 2023-1
No ratings yet
IPG IntegrationGuide API 2023-1
162 pages
Happyfox API Manual
No ratings yet
Happyfox API Manual
28 pages
Secupay API Flexv2 en 2
No ratings yet
Secupay API Flexv2 en 2
37 pages
Rest Api
No ratings yet
Rest Api
18 pages
API Testing Guide 1730023081
No ratings yet
API Testing Guide 1730023081
18 pages
Wedobest Requriments
No ratings yet
Wedobest Requriments
37 pages
Learn How To Design REST API in 9 Minutes
No ratings yet
Learn How To Design REST API in 9 Minutes
18 pages
PayPal API Reference
No ratings yet
PayPal API Reference
350 pages
What Are Required For Api Call.: A. Domains
No ratings yet
What Are Required For Api Call.: A. Domains
11 pages
Magento Hosting With Seamless Api Support_ Handling API Conflicts
No ratings yet
Magento Hosting With Seamless Api Support_ Handling API Conflicts
9 pages
Payeezy Direct API Integration Guide: April 2015
No ratings yet
Payeezy Direct API Integration Guide: April 2015
8 pages
API Documentation Complete
No ratings yet
API Documentation Complete
12 pages
SAP API Management
No ratings yet
SAP API Management
690 pages
Headless Questions_Sonali_updated
No ratings yet
Headless Questions_Sonali_updated
30 pages
Api Testing Quick Reference
No ratings yet
Api Testing Quick Reference
15 pages
Template - GA4 Ecommerce Implementation Developer Specification
No ratings yet
Template - GA4 Ecommerce Implementation Developer Specification
5 pages
Hdfc API Doc v1.3 (5)
No ratings yet
Hdfc API Doc v1.3 (5)
172 pages
PayWay API Developers Guide
No ratings yet
PayWay API Developers Guide
48 pages
3scale Networks: Unlock Your Digital Content and Services & Expand Beyond Your Website
No ratings yet
3scale Networks: Unlock Your Digital Content and Services & Expand Beyond Your Website
24 pages
Topic 8 - API
No ratings yet
Topic 8 - API
89 pages
Coffee Shop
No ratings yet
Coffee Shop
13 pages
APIs for Product Managers
No ratings yet
APIs for Product Managers
11 pages
Create Custom REST API in Magento 2-Check Code
No ratings yet
Create Custom REST API in Magento 2-Check Code
32 pages
Authentification: Test Phone Numbers
No ratings yet
Authentification: Test Phone Numbers
1 page
PP NVPAPI DeveloperGuide
No ratings yet
PP NVPAPI DeveloperGuide
266 pages
15 Best Practices For Restful APIs
No ratings yet
15 Best Practices For Restful APIs
110 pages
Sirclo Api: Creating Access Token General Request & Response Format
No ratings yet
Sirclo Api: Creating Access Token General Request & Response Format
20 pages
Internet Bs API
No ratings yet
Internet Bs API
84 pages
PayPal NVP API Developer Guide
100% (1)
PayPal NVP API Developer Guide
165 pages
Magento Hosting With Seamless Api Support_ Handling API Conflicts (2)
No ratings yet
Magento Hosting With Seamless Api Support_ Handling API Conflicts (2)
10 pages
INRDealsAPIDocumentation
No ratings yet
INRDealsAPIDocumentation
23 pages
Test Our APIs
No ratings yet
Test Our APIs
15 pages
Woocommerce All Discounts: User Manual
No ratings yet
Woocommerce All Discounts: User Manual
15 pages
PP MobileCheckout
No ratings yet
PP MobileCheckout
35 pages
FDGG Web Service API
No ratings yet
FDGG Web Service API
109 pages
ProjectMarkingScheme
No ratings yet
ProjectMarkingScheme
2 pages
Banking System API DocumentationV1.0_sample
No ratings yet
Banking System API DocumentationV1.0_sample
14 pages
REST Resource Naming Best Practices
No ratings yet
REST Resource Naming Best Practices
4 pages
RM Batch Processing API Specification - V44 - Jan 26_ 2021
No ratings yet
RM Batch Processing API Specification - V44 - Jan 26_ 2021
440 pages
PostEx-COD API Integration Guide V4.1.9-1
No ratings yet
PostEx-COD API Integration Guide V4.1.9-1
33 pages
Magento_Admin_GCP_Migrate
No ratings yet
Magento_Admin_GCP_Migrate
5 pages
API
No ratings yet
API
50 pages
Sistem Informasi Geografis (Gis) Tempat Wisata Di Kabupaten Tanggamus
No ratings yet
Sistem Informasi Geografis (Gis) Tempat Wisata Di Kabupaten Tanggamus
11 pages
API Doc - PDF - GET
No ratings yet
API Doc - PDF - GET
13 pages
Transform Datacenter Analytics With iDRAC9 Telemetry Streaming
No ratings yet
Transform Datacenter Analytics With iDRAC9 Telemetry Streaming
5 pages
Exploratory Data Analysis (Eda) With Pandas: (Cheatsheet)
No ratings yet
Exploratory Data Analysis (Eda) With Pandas: (Cheatsheet)
7 pages
SAGE X3 Architecture Guide v11
No ratings yet
SAGE X3 Architecture Guide v11
35 pages
Attacking Google Web Toolkit
No ratings yet
Attacking Google Web Toolkit
75 pages
Cloudsearch DG
No ratings yet
Cloudsearch DG
210 pages
2Sr. Java Developer Resume Example Company Name - Jersey City, New Jersey
No ratings yet
2Sr. Java Developer Resume Example Company Name - Jersey City, New Jersey
7 pages
FeuersteinJSON and PLSQL - Match Made in Database
No ratings yet
FeuersteinJSON and PLSQL - Match Made in Database
21 pages
Opp. Satyam Theatre, Durga Bhavani Plaza, Ameerpet, Hyd-16: A) Spring Boot Core
No ratings yet
Opp. Satyam Theatre, Durga Bhavani Plaza, Ameerpet, Hyd-16: A) Spring Boot Core
4 pages
Mobile Id Client Reference Guide V 2 7 PDF
No ratings yet
Mobile Id Client Reference Guide V 2 7 PDF
49 pages
04 Spring Boot Rest Crud
No ratings yet
04 Spring Boot Rest Crud
195 pages
Modified_Android _App_Development_Questionbank
No ratings yet
Modified_Android _App_Development_Questionbank
12 pages
3.123cargo API Specifications v0.55
No ratings yet
3.123cargo API Specifications v0.55
17 pages
IBM BIgData Spark
100% (1)
IBM BIgData Spark
80 pages
TOFFS API USER MANUAL v1.0
No ratings yet
TOFFS API USER MANUAL v1.0
70 pages
Kas-001-API-kaspro Snap API Document v.0.6
No ratings yet
Kas-001-API-kaspro Snap API Document v.0.6
91 pages
Real-Time Arrival Information of The Kowloon Motor Bus Company (1933) Limited
No ratings yet
Real-Time Arrival Information of The Kowloon Motor Bus Company (1933) Limited
16 pages
nse-query-documentation
No ratings yet
nse-query-documentation
3 pages
Gach 3D-31-60
No ratings yet
Gach 3D-31-60
30 pages
Flickr Google Maps Mashup AJAX Maps 2009 Spring
No ratings yet
Flickr Google Maps Mashup AJAX Maps 2009 Spring
14 pages
Madhuri
No ratings yet
Madhuri
8 pages
Template API REST Specification
No ratings yet
Template API REST Specification
26 pages
A Few RPO Exploitation Techniques: MBSD Technical Whitepaper
No ratings yet
A Few RPO Exploitation Techniques: MBSD Technical Whitepaper
18 pages
swimlaneapiv2-1
No ratings yet
swimlaneapiv2-1
359 pages
ULIP VAHAN Integration Requirement
No ratings yet
ULIP VAHAN Integration Requirement
15 pages
JMeter is a Game-Changer for Performance Testing
No ratings yet
JMeter is a Game-Changer for Performance Testing
17 pages
Ecourier Merchant API Document General v5.2
No ratings yet
Ecourier Merchant API Document General v5.2
28 pages