Retail API Release

Reference Guide
2020.1
1 REVISION HISTORY

Version Reason for change Author Date

1 - 77 Archived details Emma Girschik 3/12/15

78 Update document with precision information about discounts Emma Girschik 19/7/16
to reduce instances of mis-use
79 Add in more info for AfterPay refunds – job 112273 Emma Girschik 21/7/16
80 Add in new optional parameter UpdatedAfter to Products and Nilusha Fernando 22/9/16
ProductsSimple endpoints to retrieve products updated after
a specific timestamp.
81 Clarify / fix detail on person update time stamp format Emma Girschik 17/10/16
82 Add new optional element <AccountId> into payment section Nilusha Fernando 02/11/16
in the order create call to allow AP21 to uniquely identify a
payment gateway when multiple merchant account ids exist
within a single merchant account
83 Fix <OrderInstructions> references – field is not currently Emma Girschik 8/12/16
supported
84 Add changes to allow sites nominate despatch location when Nilusha Fernando 12/12/16
AP21 ship from store rules active
85 Edit person updatetimestamp details to make it clearer that Nilusha Fernando 31/01/17
the date/time passed in the PUT must match the current
record.
86 Fix up reference id for how to look up loyalty types – Emma Girschik 29/5/17
previously was incorrectly listed as rgidx 271 when actually it
should be 366
87 Add new <PointsPartner> element to Orders call Nilusha Fernando 20/7/17
88 Modification to Order Payment Reference field. For AfterPay Emma Girschik 1/8/17
payments, this should be the AfterPay Order ID for successful
refund in store.
89 Add in Returns endpoint for posting returns for Mail Orders Emma Girschik 7/8/17
90 Added in job 113368 – new error 5146 for orders Emma Girschik 16/10/17
91 Fix carrier length for returns – was incorrectly documented as Emma Girschik 4/12/17
250 when should be 12
92 Add in SLA element to Orders endpoint - v2018 Nilusha Fernando 8/2/18
93 V2018 onwards - Add in version_3.0 breaking change details – Emma Girschik 14/2/18
person loyalties can now be removed via Persons endpoint.
Prior to this version, it was only possible to add and edit
loyalty details.
94 Clarify that can unlock vouchers if post “lock” request with 0 Emma Girschik 4/4/18
seconds. Was not clear in the document.
95 Fix up details for discount on orders – code not mandatory Emma Girschik 23/4/18
96 Update data types for Gift Voucher Number- Order payment Mike Sutton 21/05/18
and Gift Voucher endpoints
97 New endpoint for stock changes – job 113805 Emma Girschik 29/5/18

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 2 of 197

 98 Change Orders endpoint to pass AuthorityToLeave – job Nilusha Fernando 14/6/18
114054
99 Add Retail Reward end points to retrieve reward program Nilusha Fernando 27/8/18
details and change Person endpoint to retrieve reward details
– Job 114021

100 Update Reward Programs and Reward Account end points to Nilusha Fernando 24/10/18
include spend to next tier, spend to next reward and tier
details – Job 114021
101 Add in 114415 / 114321 – Products endpoint filter for updated Emma Girschik 4/12/18
date / time modified to also consider price changes as an
update
102 Add in Rewards Gift endpoints (Job 114430) Nilusha Fernando 7/12/18
103 Change Orders endpoint to post reward $ and gift Nilusha Fernando 17/01/19
redemptions. Add in discount type 4 (Reward Redemption
Discount) -Job 114430
104 Custom Data added to product list and single product Mike Sutton 12/04/19
endpoints - Job 114882 2019.1 and Version 4 licensing
required.
105 Changes to Free stock endpoint – 114655 in version 2019.2 Emma Girschik 1/7/19
106 Changes to add in Order posting of tax rates from web site Emma Girschik 9/7/19
when price includes tax
107 Changes to add points, reward and gift issue id when Nilusha Fernando 11/7/19
retrieving a person’s reward account – Job 114982
108 Add ExpectedDeliveryDate to Orders endpoint – 115191 Nilusha Fernando 12/10/19
109 Add Zip payments information to Order Details – Job 114942 San Mathew 16/10/19
110 Add VoucherGateway to Order endpoint – Job 115136 Thida Zaw 22/01/20
111 Sized endpoint updated to include a new filter to optionally Emma Girschik 30/3/20
include sizes for items out of stock (previously always
included) - Job 115896
112 Add Docket Number and Program Id to Person endpoint – Job Thida Zaw 26/05/20
115851
113 Add a new endpoint for Custom Data Template and Custom Thida Zaw 26/05/20
Data to Person endpoint – Job 114928

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 3 of 197

2 CONTENTS

1 Revision History ......................................................................................................................................... 2

2 Contents .................................................................................................................................................... 4

3 Introduction ............................................................................................................................................... 5

4 Minimum Requirements............................................................................................................................ 9

5 Sandbox ................................................................................................................................................... 10

6 Overview .................................................................................................................................................. 11

7 References ............................................................................................................................................... 17

8 Navigation tree ........................................................................................................................................ 30

9 Products ................................................................................................................................................... 34

10 Colours ................................................................................................................................................. 60

11 Sizes ..................................................................................................................................................... 62

12 Persons ................................................................................................................................................ 64

13 Carts ..................................................................................................................................................... 82

14 Orders .................................................................................................................................................. 95

15 Returns .............................................................................................................................................. 135

16 Sales History ...................................................................................................................................... 141

17 Gift Vouchers ..................................................................................................................................... 148

18 Free Stock .......................................................................................................................................... 154

19 Stock changes .................................................................................................................................... 161

20 Rewards ............................................................................................................................................. 164

21 Stores ................................................................................................................................................. 192

22 Shipments .......................................................................................................................................... 194

23 Additional Error Responses ............................................................................................................... 197

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 4 of 197

3 INTRODUCTION

The Apparel21 Retail Application Programming Interface (API) is an interface which provides interaction with
the Apparel21 system for the purpose of online shopping and enquiries.

It is used by website developers implementing E-tailing applications which interact with Apparel21
resources.

Use of this API requires the purchase of an Apparel21 Retail API license by the retailer. See Further
Assistance for contacting Apparel21.

1.1 AUDIENCE

This guide is intended for developers who are building web-enabled applications that retrieve information
from and update details to Apparel21.

This guide will also be used by the retailer who is expected to be the first point of contact for enquiries
from developers. Many of the data fields and values used in relation to the API will be dependent upon
configurations specific to that retailer.

1.2 REQUIRED KNOWLEDGE AND SKILLS

Use of this guide assumes

 Familiarity with XML

 Basic understanding of web services
 Knowledge of a programming language for developing a web service
 An understanding of retail commerce systems and payment gateways
 Familiarity with the apparel industry.

1.3 ARCHITECTURE

The API is a web service using the REST (Representational State Transfer) architectural style. The following
verbs are used

 GET
 PUT
 POST

The DELETE function is not used in this API.

The payload for all requests and responses is in XML.

1.4 API VERSIONS AND UPDATES

From time to time new versions of the API will be released to provide new or modified functionality.

In the ‘details’ section for each resource, the “HTTP header Accept:Version_” column shows when an
element was introduced to the payload. If a version other than 1 is required it must be requested in the
accept header of the call.

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 5 of 197

To check the Retail API version and payload version supported by an installed API, access the root page of
the endpoint.

Minor version changes will be released for non-breaking changes such as introducing new elements or
attributes. Developers should ignore new elements in the payload (if they are not required) and be aware
that elements may not remain in a particular order although they will remain at the same level in the XML
hierarchy.

Major version changes can also be applied to changed behaviour like the automatic removal of data if not
supplied. i.e. In one version it may not be removed when not supplied but in another version it may be
removed.

Major version changes have the potential to introduce changes which break the client’s software. For
example if a new element (or attribute for an existing element) is required on submit payloads, like a PUT
call, this would be a breaking change. All changes are documented in the Retail API Change Log.

Before installing a new version of the API, the business must be aware of the possible impact and discuss it
with the website developer.

1.5 ASSUMPTIONS / CONSTRAINTS

1. “Click and collect” and “Ship from store” – these features are NOT standard in Apparel21 – if you
want to use these, there is additional configuration with associated fees. Contact Sales and CRM
team to discuss further.
2. A single currency applies to all transactions for a single “web store”
3. For order fulfilment from warehouse – one warehouse for one web store
4. Apparel21 POS is integrated with Temando interface and allows seamless integration with carries to
retrieve consignment note numbers and print delivery labels.
5. In-store generated Credit Notes cannot be redeemed via Retail API

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 6 of 197

 6. If orders are posted with ‘pre-authorised’ payment details, it is not possible to update the payment
details with the final payment transaction Id. Refunds for these transactions will not be able to be
processed through Apparel21 Mail Order or in store using “authorisation” number.
7. Each order can only be delivered to one person / location, including gift voucher purchases. Where
purchasing multiple vouchers, each voucher will be delivered to the same location.
8. Order confirmation email to the customer assumed to be generated from web system. Apparel21
does not supply confirmation email.
9. Despatch confirmation emails can be supplied by Apparel21 using Mailer module (optional) or
alternatively, use Supply Master to provide this information.
10. Apparel21 does supply gift voucher email. Gift voucher purchase email from web site NOT
supported.
11. Apparel21 generates customer email for pick up in store packing confirmation. Web site email NOT
supported for this task.
12. All elements posted must start with a capital letter. E.g. <Name> is valid but <name> is NOT valid
13. Website can supply own order reference but it MUST be unique for each new order.
14. Email address must be unique within a brand or division. Person is identified in the Retail API via
email address, brand/division combination.
15. Click and collect (buy online pick up in store) and despatch from store orders must be FULLY paid at
time of order and NOT at time of pick up.
16. Orders containing gift vouchers MUST be fulfilled by the warehouse. They cannot be submitted as
‘Click and Collect’ or ‘Despatch from store’ orders.
17. Online returns are supported as long as returned to warehouse – does not cater for “pick up in
store” or “Despatch from store” returns. These returns should be done in store rather than online.

1.6 DEFINITION OF TERMS

Acronym or Term Description

API Application Programming Interface

A set of routines, protocols, and tools for building software applications.

Customer Same as online shopper. A consumer who directly buys goods from a seller in real-
time.

Generic Interface This is a function provided in Apparel21 to enhance the configuration options,
Translation allowing businesses to customise their system.

GIT See Generic Interface Translation

Id Id refers to a system generated unique number for an object.

Online shopper A consumer who directly buys goods from a seller in real-time.

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 7 of 197

 Person A term used within Apparel21 to store details for an online shopper.

Product A garment (piece of clothing), or accessory (bag, shoe, etc).

A product can have more than one colour and/or size, but is still considered a single
product record in Apparel21.

Reference Code Reference Codes are assigned to a Reference Group. These are customisable by
client. E.g. Pants, Jackets, Skirts

Reference Group Reference Groups in Apparel21 are various attributes used to describe products and
other business entities at a higher level. E.g. Product Type

Reference Type See Reference Group. E.g. Product Type

Retailer A business utilising the Apparel21 application for its retail operations.

Shopping Cart A virtual shopping basket where items are ‘stored’ while browsing an online
catalogue.

SKU Stock Keeping Unit. The lowest level of representation of a product to size and
colour detail if applicable.

Style See Product.

1.7 FURTHER ASSISTANCE

If further information is required contact the Apparel21 Support Centre

Phone +613 8415 9393

Email [email protected]

Website www.Apparel21.com

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 8 of 197

4 MINIMUM REQUIREMENTS
1.8 APPAREL 21 SOFTWARE

The minimum version of Apparel21 software required to use the Retail API is 2011.1

Refer to the section API Version to ensure you are using the correct documentation for the Apparel21
version.

Use of the API also requires the Mail Order and Retail modules to be licensed and setup. An additional
warehouse license may also be required. Contact your Apparel21 consultant for further advice on these
requirements.

1.9 SYSTEMS

 32 or 64 bit operating system

 Windows IIS v7 – configured to host MVC
 .Net 3.5 minimum - If installing .Net4 make sure .Net3.5 has been installed first
 Oracle client connectivity must be available to both the TEST and LIVE schemas

1.10 SERVICES

The Apparel21 Retail API must be installed and configured. Refer to separate documentation for the
installation and configuration of the API.

Apparel21 consultants will liaise with their customers to establish the configurations for Apparel21. They will
set up and configure ‘test’ and ‘live’ systems for use with the API and provide the information required for
the API configuration settings.

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 9 of 197

5 SANDBOX
All URI’s referenced in this document are able to access the sandbox using the base

https://retailapi.apparel21.com/RetailAPI

Log in to the secure web server using the following credentials

Username bassapi
Password RedWider8642

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 10 of 197

6 OVERVIEW

The Apparel21 Retail API provides resources to support online shopping and enquiries.

The API caters for a single currency but allows ‘pricing customers’ to be set up to cater for shoppers that
are not required to pay tax on goods purchased.

The included resources are:

 look up existing shopper details, including loyalties

 create new shopper
 navigation tree hierarchy - product references to display a navigation tree
 product information - colour and size information
 stock information by store
 store information. E.g. address details
 shopping cart to get latest prices, promotions and freight as defined in the Apparel21
system
 create new orders – shopper, products, payment details, despatch from warehouse,
despatch from store or pick up in store
 create new returns / exchange orders
 gift voucher selling
 gift voucher redemption
 look up sales history for shopper, including all store transactions as well as web sales

As Apparel21 is extensively customisable and configurable, terminology and descriptions will change
depending on how clients have implemented Apparel21.

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 11 of 197

1.11 SAMPLE WORK FLOW

1.11.1 BUY ONLINE AND DESPATCH FROM WAREHOUSE

Retail API – sample work flow

Shopper Web application Apparel21 API

Post ‘Person’ Create Person,

Shopper account

Create account
request return person Id

Get Product Product Reference

Reference Type Type Ids
Build product hierarchy

Product Reference
Get navigation tree Descriptions and
nodes

Display navigation
Browse products
tree

Get List of Products Products by

(simple) Reference Id

Display products

Get Single Product Products with

Select product
by Id (detail) colours and sizes

Add product to cart Update web cart

Submit Cart for Calculate cart

Finalise order
pricing pricing

Display final price,

Confirm Order
request payment
Shopping process

Enter payment Process payment, Generate Order in

details Post order Apparel21

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 12 of 197

1.11.2 BUY ONLINE AND PICK UP IN STORE (CLICK AND COLLECT)

Click and Collect

Phase
Customer

Checkout Pick Up In
Log on to website Browse Products Collect Order
Store
Web Developer

Send Order
Request/ Send Order Confirmation email
Recieve
Retail API

GET FreeStock by Create Customer

Store Order
Apparel21

Update Customer
Report on Customer
Create POS Notify POS of Order ready to Complete Customer
Orders (salesperson
Customer Order Customer Order collect (Email Order
web)
Customer)
Store Staff

Pack Customer
Order

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 13 of 197

1.11.3 BUY ONLINE AND DESPATCH FROM STORE – TEMANDO INTEGRATION

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 14 of 197

1.12 USE OF IDS

Apparel21 product codes and other business elements can be modified. Therefore rather than using
“product code” or “return reason code” as a method of communicating between the web and Apparel21
databases, it is preferable to communicate data using unchanging Ids.

Some items, such as products will have a Code AND an Id.

- Code - user friendly product code used by the business to represent the item. Used for verbal
communications.
- Id – system generated unchanging unique number. Not user friendly.

Where the document refers to Id, it is referring to the number.

e.g Product id 12345 code DRES0001 and description STRIPED MAXI DRESS

1.13 API CALLS

A standard API call is formed by three parts

Request part Notes

1. URL with parameters Country code is mandatory parameter for all calls to
the API. Country code controls pricing and tax
rates. Country code maps to a setting in Apparel21
back office.

2. HTTP headers The payload version required should be included in

 “Content-type:text/xml” for GET, POST the request header (Accept:version_2.0). If not
and PUT supplied, only version 1 elements apply.
 “Accept:version_x”

3. XML payload body (for PUT and POST, not

for GET)

Examples for Create a person

1 HTTP POST Request

http://retailapi.apparel21.com/RetailAPI/Persons/?countryCode=AU

2 HTTP POST Request HTTP header

Content-type: text/xml
Accept:version_2.0

3 HTTP POST Request XML payload body

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 15 of 197

 <Person>
<Title>Mr</Title>
<Firstname>John</Firstname>
<Surname>Hill</Surname>
<Sex>M</Sex>
<References>
<Reference>
<ReferenceTypeId>373</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>1781</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>1782</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>1801</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>1501</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>27</ReferenceTypeId>
<Id />
</Reference>
</References>
<Addresses>
<Billing>
<ContactName />
<AddressLine1>101 Cremorne St</AddressLine1>
<AddressLine2 />
<City>CREMORNE</City>
<State>VIC</State>
<Postcode>3121</Postcode>
<Country>AUSTRALIA</Country>
</Billing>
</Addresses>
</Person>

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 16 of 197

7 REFERENCES

Reference Groups in Apparel21 are various attributes used to describe products and other business entities
at a higher level.

Product Reference Groups are used to enable the grouping of products into similar categories and are able
to be queried by the API. Product Reference details can be retrieved by the API to determine the order or
hierarchy in which the products are displayed or grouped.

These are customisable by client. Examples of some product references are shown below.

As depicted above, Brand, Department, Class, etc. are setup as reference groups. They are referred to in
the API as reference types.

The corresponding codes ICED, Accessories, Shirts are reference codes.

For a client site, these reference groups can be selected to control navigation as shown in the section
Navigation Tree.

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 17 of 197

Reference Groups are also used for other fields in Apparel21.

- Return reasons

The API has several resources to obtain Reference details depending on the information required.

Reference Types This resource will list all Reference Types in Apparel21. The payload can be used to
obtain the Id of a Reference Type to enable the values for that reference Type to be
listed.

E.g. Product Department

References This resource requires a Reference Type Id and optionally a Reference Code to be
entered. The payload will list all valid Reference Types that are children of the
Reference Type.

E.g. Shoes, Jackets, Pants are References within “Product Department” reference
type.

Product Reference Lists the Reference Types specific to ‘Products’.

Types
E.g. “Product Department”, “Season”

Product Colour Lists Product Colour Reference Codes. These are the references that exist at the
Reference Codes product / colour level. These references are NOT available as part of the navigation
tree or standard product extract due to payload size considerations.

This extract is suited to those businesses that extract all information on a daily /
weekly basis and organise the navigation with the web application.

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 18 of 197

1.14 REFERENCE DETAILS

1.14.1 REFERENCE TYPES

GET response
Field Format Max Comment Example Reference References HTTP
Length Types Header
Accept:
Version
_
ReferenceTypes
ReferenceType ReferenceType is a sub-element of ReferenceTypes
Id Integer 22 This is the unique identifier of the reference type 1221 Yes 1.0
Code Alpha 8 Code for this reference type Season Yes 1.0
Name Alpha 40 Extended description of reference type Season Yes 1.0
References
ReferencesByType ReferencesByType is a sub-element of References
ReferenceTypeId Integer 22 The Id entered in the request parameter 1221 Yes 1.0
ReferenceTypeCode Alpha 8 Code for this reference type Season Yes 1.0
ReferenceTypeName Alpha 40 Extended description of reference type Season Yes 1.0
Reference Reference is a sub-element of References
ReferenceTypeId Integer 22 The Id entered in the request parameter 1221 Yes 1.0
Id Integer 22 The Id entered in the request parameter 4884 Yes 1.0
Code Alpha 8 Code for this reference type Autumn Yes 1.0
Name Alpha 40 Extended description of reference type Autumn Yes 1.0

1.14.2 PRODUCT REFERENCE TYPES

Field Format Max Comment Example GET HTTP
Length Response Header
Accept:Ver
sion_
Id Integer 22 This Id describes which object the list of reference groups refers to. For products 1 Yes 1.0
the value is 1.
Name Alpha 30 Name of object Style Yes 1.0

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 19 of 197

 ReferenceTypes Reference Types is a sub-element of ProductReferenceTypes
Sequence Integer 22 Sequence of the reference type within the hierarchy 1 Yes 1.0
ReferenceTypeId Integer 22 Unique Id for this reference type 257 Yes 1.0
Code Alpha 8 Code for this reference type Brand Yes 1.0
Name Alpha 40 Extended description of reference type Product Brand Yes 1.0

1.14.3 PRODUCT COLOURS REFERENCES

Field Format Max Comment Example GET response HTTP

Length Header
Accept:Vers
ion_
ProductColoursReferences
ProductColourReference ProductColourReference is a sub-element of ProductColoursReferences
ClrId Integer 22 The Id of a colour that relates to a particular style 1451 Yes 2.0
RowNumber Integer 22 Consecutive number of the row returned in the response 28 Yes 2.0
References
Reference Reference is a sub-element of References
ReferenceTypeId Integer 22 Unique Id for the reference type set against the product colour 1221 Yes 2.0
Id Alpha 8 The id assisgned to the product colour reference type 4885 Yes 2.0

1.14.4 PERSON REFERENCES

Field Format Max Comment Example GET response HTTP

Length Header
Accept:Vers
ion_
PersonReferenceTypes
Id Integer 22 Id of the object for Person – fixed to 12 12 Yes 1.0
Name Alpha 6 Name of the object – always “Person” Person Yes 1.0
ReferenceTypes
Reference Reference is a sub element of Reference Types

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 20 of 197

 Sequence Integer 22 Sequence of this reference type within the hierarchy (can be up to 10) 2 Yes 1.0
ReferenceTypeId Integer 22 Id of reference type 1261 Yes 1.0
Code Alpha 15 Code of this reference type – user friendly Pref Yes 1.0
Name Alpha 30 Longer name of this reference type – user friendly Preferences Yes 1.0

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 21 of 197

 1.15 RETRIEVE REFERENCE TYPES

The Reference Type details are retrieved by submitting a GET to the following URI. All Reference Type Ids
will be returned.

1.15.1 URI REQUEST FORMAT

/ReferenceTypes/{id}?countryCode={countryCode}

1.15.2 REQUEST PARAMETERS

Field Required Comment
Country Code Mandatory Country Code of shopper
Id Optional Id of Reference Type

1.15.3 EXAMPLE REQUEST

GET https://retailapi.apparel21.com/RetailAPI/ReferenceTypes/?countryCode=AU

Content-type: text/xml
Accept:version_2.0

1.15.4 EXAMPLE RESPONSE

<ReferenceTypes>
<ReferenceType>
<Id>1</Id>
<Code>Class</Code>
<Name>Product Class</Name>
</ReferenceType>
<ReferenceType>
<Id>211</Id>
<Code>CmplReas</Code>
<Name>Completed Reason</Name>
</ReferenceType>
<ReferenceType>
<Id>1969</Id>
<Code>Coil #</Code>
<Name>Coil Number</Name>
</ReferenceType>
<ReferenceType>
<Id>426</Id>
<Code>ColrType</Code>
<Name>Colour Type</Name>
</ReferenceType>
<ReferenceType>
<Id>100</Id>
<Code>Comments</Code>
<Name>Comments</Name>
</ReferenceType>
<ReferenceType>
<Id>2</Id>
<Code>Comp Grp</Code>
<Name>Component Group</Name>
</ReferenceType>
<ReferenceType>
<Id>22</Id>
<Code>Company</Code>
<Name>Company</Name>
</ReferenceType>
….etc…..
</ReferenceTypes>

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 22 of 197

1.15.5 SUCCESS RESPONSE
HTTP Response
200

1.15.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text
404

1.16 RETRIEVE REFERENCE CODES

The reference codes for a particular Reference Type Id are retrieved by submitting a GET to the following
URI.

1.16.1 URI REQUEST FORMAT

/References/{referencetypeId}/{refcodeId}?CountryCode={countryCode}

1.16.2 REQUEST PARAMETERS

Field Required Comment
Country Code Mandatory Country Code of shopper
ReferenceTypeId Mandatory Reference Type Id to be queried
RefcodeId Optional Reference Code Id

1.16.3 EXAMPLE REQUEST

GET https://retailapi.apparel21.com/RetailAPI/References/1?countryCode=AU

Content-type: text/xml
Accept:version_2.0

1.16.4 EXAMPLE RESPONSE

<ReferencesbyType>
<ReferenceTypeId>1</ReferenceTypeId>
<ReferenceTypeCode>Class</ReferenceTypeCode>
<ReferenceTypeName>Product Class</ReferenceTypeName>
<References Type="Array">
<Reference>
<ReferenceTypeId>1</ReferenceTypeId>
<Id>2368</Id>
<Code>Accessories</Code>
<Name>Accessories</Name>
</Reference>
<Reference>
<ReferenceTypeId>1</ReferenceTypeId>
<Id>6723</Id>
<Code>Belts</Code>
<Name>Belts</Name>
</Reference>
<Reference>
<ReferenceTypeId>1</ReferenceTypeId>
<Id>2797</Id>
<Code>Dresses</Code>

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 23 of 197

 <Name>Dresses</Name>
</Reference>
….etc…..
</References>
</ReferencesbyType>

1.16.5 SUCCESS RESPONSE

HTTP Response
200

1.16.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text
404

1.17 RETRIEVE PRODUCT REFERENCE TYPES

The Reference Type details for products are retrieved by submitting a GET to the following URI. The Ids
returned will be used to retrieve the product navigation tree.

1.17.1 URI REQUEST FORMAT

/ProductReferenceTypes?countryCode={countryCode}

1.17.2 REQUEST PARAMETERS

Field Required Comment
Country Code Mandatory Country Code of shopper
ExtendedRefs Optional “True” to return all product references (not just style
references) can be up to 20.

1.17.3 EXAMPLE REQUEST

GET
https://retailapi.apparel21.com/RetailAPI/ProductReferenceTypes?countryCode=AU&ExtendedRefs=true

Content-type: text/xml
Accept:version_2.0

1.17.4 EXAMPLE RESPONSE

<ProductReferenceTypes xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Id>99</Id>
<Name>Product</Name>
<ReferenceTypes Type="Array">
<Reference>
<Sequence>1</Sequence>
<ReferenceTypeId>257</ReferenceTypeId>
<Code>Range</Code>
<Name>Product Range</Name>
</Reference>
<Reference>

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 24 of 197

 <Sequence>2</Sequence>
<ReferenceTypeId>1021</ReferenceTypeId>
<Code>Season</Code>
<Name>Product Season</Name>
</Reference>
<Reference>
<Sequence>3</Sequence>
<ReferenceTypeId>1</ReferenceTypeId>
<Code>Prod Grp</Code>
<Name>Product Group</Name>
</Reference>
<Reference>
<Sequence>4</Sequence>
<ReferenceTypeId>1201</ReferenceTypeId>
<Code>StockTyp</Code>
<Name>Stock Type</Name>
</Reference>
<Reference>
<Sequence>5</Sequence>
<ReferenceTypeId>258</ReferenceTypeId>
<Code>Label</Code>
<Name>Product Label</Name>
</Reference>
<Reference>
<Sequence>6</Sequence>
<ReferenceTypeId>1621</ReferenceTypeId>
<Code>COrigin</Code>
<Name>Country of Origin</Name>
</Reference>
<Reference>
<Sequence>7</Sequence>
<ReferenceTypeId>315</ReferenceTypeId>
<Code>Batch Tp</Code>
<Name>Batch Type</Name>
</Reference>
<Reference>
<Sequence>11</Sequence>
<ReferenceTypeId>2</ReferenceTypeId>
<Code>Comp Grp</Code>
<Name>Component Group</Name>
</Reference>
<Reference>
<Sequence>13</Sequence>
<ReferenceTypeId>19</ReferenceTypeId>
<Code>Story</Code>
<Name>Story</Name>
</Reference>
</ReferenceTypes>
</ProductReferenceTypes>

1.17.5 SUCCESS RESPONSE

HTTP Response
200

1.17.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text
404

1.18 RETRIEVE PRODUCT COLOUR REFERENCE CODES

The Product Colour Reference Codes are retrieved by submitting a GET to the following URI.

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 25 of 197

1.18.1 URI REQUEST FORMAT

/ProductColourReferences?countryCode={countryCode}

1.18.2 REQUEST PARAMETERS

Field Required Comment
Country Code Mandatory Country Code of shopper

1.18.3 EXAMPLE REQUEST

GET https://retailapi.apparel21.com/RetailAPI/ProductColourReferences?countryCode=AU

Content-type: text/xml
Accept:version_2.0

1.18.4 EXAMPLE RESPONSE

<ProductColoursReferences>
<ProductColourReference>
<ClrId>2443</ClrId>
<RowNumber>1</RowNumber>
<References Type="Array">
<Reference>
<ReferenceTypeId>1168</ReferenceTypeId>
<Id />
</Reference>
</References>
</ProductColourReference>
<ProductColourReference>
<ClrId>2444</ClrId>
<RowNumber>2</RowNumber>
<References Type="Array">
<Reference>
<ReferenceTypeId>1168</ReferenceTypeId>
<Id />
</Reference>
</References>
</ProductColourReference>
<ProductColourReference>
<ClrId>2802</ClrId>
<RowNumber>3</RowNumber>
<References Type="Array">
<Reference>
<ReferenceTypeId>1168</ReferenceTypeId>
<Id />
</Reference>
</References>
</ProductColourReference>
<ProductColourReference>
<ClrId>3804</ClrId>
<RowNumber>4</RowNumber>
<References Type="Array">
<Reference>
<ReferenceTypeId>1168</ReferenceTypeId>
<Id />
</Reference>
</References>
</ProductColourReference>
<ProductColourReference>
<ClrId>3863</ClrId>
….etc…..

1.18.5 SUCCESS RESPONSE

HTTP Response
200

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 26 of 197

1.18.6 ERROR RESPONSE
HTTP Error API Error Code API Error Text
404

1.19 RETRIEVE PRODUCT COLOUR REFERENCE CODES FOR A SINGLE PRODUCT COLOUR

The Product Colours References are retrieved by submitting a GET to the following URI.

1.19.1 URI REQUEST FORMAT

/ProductColourReferences/clrid/?countryCode={countryCode}

1.19.2 REQUEST PARAMETERS

Field Required Comment
Country Code Mandatory Country Code of shopper
ClrId Mandatory Unique Id of the style / colour

1.19.3 EXAMPLE REQUEST

GET https://retailapi.apparel21.com/RetailAPI/ProductColourReferences/1002?countryCode=AU

Content-type: text/xml
Accept:version_2.0

1.19.4 EXAMPLE RESPONSE

<ProductColourReferences>
<ClrId>1002</ClrId>
<RowNumber>1</RowNumber>
<References Type="Array">
<Reference>
<ReferenceTypeId>1002</ReferenceTypeId>
<Id />
</Reference>
</References>
</ProductColourReferences>

1.19.5 SUCCESS RESPONSE

HTTP Response
200

1.19.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text
404

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 27 of 197

1.20 RETRIEVE PERSON REFERENCE CODES

The Person References are retrieved by submitting a GET to the following URI.

1.20.1 URI REQUEST FORMAT

/PersonReferenceTypes/?countryCode={countryCode}

1.20.2 REQUEST PARAMETERS

Field Required Comment
CountryCode Mandatory Country Code of shopper

1.20.3 EXAMPLE REQUEST

GET https://retailapi.apparel21.com/RetailAPI/PersonReferenceTypes?countryCode=AU

Content-type: text/xml
Accept:version_2.0

1.20.4 EXAMPLE RESPONSE

<Id>12</Id>
<Name>Person</Name>
<ReferenceTypes Type="Array">
<Reference>
<Sequence>1</Sequence>
<ReferenceTypeId>1281</ReferenceTypeId>
<Code>SType</Code
><Name>Store Type</Name>
</Reference>
<Reference>
<Sequence>2</Sequence>
<ReferenceTypeId>1321</ReferenceTypeId>
<Code>PerType</Code>
<Name>Person Type</Name>
</Reference>
<Reference>
<Sequence>3</Sequence>
<ReferenceTypeId>1361</ReferenceTypeId>
<Code>AgeGrp</Code>
<Name>Age Group</Name>
</Reference>
<Reference>
<Sequence>4</Sequence>
<ReferenceTypeId>361</ReferenceTypeId>
<Code>State</Code>
<Name>State</Name>
</Reference>
<Reference>
<Sequence>5</Sequence>
<ReferenceTypeId>27</ReferenceTypeId>
<Code>SalesRep</Code>
<Name>Sales Rep</Name>
</Reference></ReferenceTypes>
</PersonReferenceTypes>

1.20.5 SUCCESS RESPONSE

HTTP Response
200

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 28 of 197

1.20.6 ERROR RESPONSE
HTTP Error API Error Code API Error Text
404

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 29 of 197

8 NAVIGATION TREE

This resource provides a tree of product references which can be used to construct a navigation path for
finding products. The structure and levels of the tree is defined by the query providing the product
reference types to navigate by. Up to 5 levels can be requested.

Refer to Product References for further detail.

1.21 NAVIGATION TREE DETAILS

Each reference tree consists of up to 5 levels of nodes. The following is a description of fields for one level.

Field Format Max Comment Example GET HTTP

Length Response Header
Accept:V
ersion_
Level Integer 1 Level of Node 2 Yes 1.0
NodeId Integer 22 Unique Id for node. This is useful 2 Yes 1.0
for storing the nodes in a
browser object.
ReferenceTypeId Integer 22 Id of the refence type 257 Yes 1.0
ReferenceId Integer 22 Id of reference. A reference is an 6326 Yes 1.0
instance of a reference type.
ReferenceCode Alpha 15 Reference Code Mens Yes 1.0
ReferenceName Alpha 40 Reference Name Mens Yes 1.0
ProductQuery Alpha 250 A string which is used as query 1,2405:2,63 Yes 1.0
parameter to the the products 26
resource to get a list of products
satisfying this node.
Format is sequence,reference
code index:sequence,reference
code index
Sequence = reference position
on the product
Reference code index = unique
identifier for reference code,
e.g. 12345 = Womens
ProductQueryNames Alpha 250 Description of the references Commune, Yes 1.0
building up this node. Mens
LevelProductQuery Alpha 250 Product query string for this level 2,6326 Yes 1.0
only.

1 01 C R EM OR NE ST C R EM OR NE V I C 3 12 1 AC N 0 0 5 9 97 90 0 P H : 61 3 84 1 5 9 3 0 0 F A X : 6 1 3 9 4 2 7 1 7 52 W W W . A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 30 of 197

RETRIEVE NAVIGATION TREE

Perform a GET on the following URI to detect the product reference (navigation) tree types available from
the Apparel21 installation. The parameter values for levels are the reference type ids as retrieved
previously. Typically these would be stored in a configuration file at the website provider.

1.21.1 URI REQUEST FORMAT

ReferenceTree?countryCode={countryCode}&level1={id1}&level2={id2}&level3={id3}&level4={id4}&level5=
{id5}

1.21.2 REQUEST PARAMETERS

Field Required Comment
Country Code Mandatory Country Code of shopper
Level 1 Mandatory ReferenceTypeId of the first level of hierarchy
Level 2 Optional ReferenceTypeId of the second level of hierarchy
Level 3 Optional ReferenceTypeId of the third level of hierarchy
Level 4 Optional ReferenceTypeId of the fourth level of hierarchy
Level 5 Optional ReferenceTypeId of the fifth level of hierarchy

1.21.3 EXAMPLE REQUEST

For this example we will use SubBrand, Division and Product Group in the navigation tree.

GET
https://retailapi.apparel21.com/RetailAPI/ReferenceTree?countrycode=AU&level1=1041&level2=1004&lev
el3=1

Content-type: text/xml
Accept:version_2.0

1.21.4 EXAMPLE RESPONSE

<ReferenceTree>
<Reference>
<Level>1</Level>
<NodeId>1</NodeId>
<ReferenceTypeId>258</ReferenceTypeId>
<ReferenceId>10991</ReferenceId>
<ReferenceCode>BONZ</ReferenceCode>
<ReferenceName>Bonez Streetwear</ReferenceName>
<ProductQuery>1,10991</ProductQuery>
<ProductQueryNames>Bonez Streetwear</ProductQueryNames>
<LevelProductQuery>1,10991</LevelProductQuery>
<Children>
<Reference>
<Level>2</Level>
<NodeId>2</NodeId>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 31 of 197

 <ReferenceTypeId>257</ReferenceTypeId>
<ReferenceId>6326</ReferenceId>
<ReferenceCode>Mens</ReferenceCode>
<ReferenceName>Mens</ReferenceName>
<ProductQuery>1,10991:2,6326</ProductQuery>
<ProductQueryNames>Bonez Streetwear, Mens</ProductQueryNames>
<LevelProductQuery>2,6326</LevelProductQuery>
<Children>
<Reference>
<Level>3</Level>
<NodeId>3</NodeId>
<ReferenceTypeId>1</ReferenceTypeId>
<ReferenceId>2797</ReferenceId>
<ReferenceCode>Dresses</ReferenceCode>
<ReferenceName>Dresses</ReferenceName>
<ProductQuery>1,10991:2,6326:3,2797</ProductQuery>
<ProductQueryNames>Bonez Streetwear, Mens, Dresses</ProductQueryNames>
<LevelProductQuery>3,2797</LevelProductQuery>
<Children />
</Reference>
</Children>
</Reference>
<Reference>
<Level>2</Level>
<NodeId>4</NodeId>
<ReferenceTypeId>257</ReferenceTypeId>
<ReferenceId>5063</ReferenceId>
<ReferenceCode>Women</ReferenceCode>
<ReferenceName>Womens</ReferenceName>
<ProductQuery>1,10991:2,5063</ProductQuery>
<ProductQueryNames>Bonez Streetwear, Womens</ProductQueryNames>
<LevelProductQuery>2,5063</LevelProductQuery>
<Children>
<Reference>
<Level>3</Level>
<NodeId>5</NodeId>
<ReferenceTypeId>1</ReferenceTypeId>
<ReferenceId>2364</ReferenceId>
<ReferenceCode>Jackets</ReferenceCode>
<ReferenceName>Jackets</ReferenceName>
<ProductQuery>1,10991:2,5063:3,2364</ProductQuery>
<ProductQueryNames>Bonez Streetwear, Womens , Jackets</ProductQueryNames>
<LevelProductQuery>3,2364</LevelProductQuery>
<Children />
</Reference>
</Children>
</Reference>
</Children>
</Reference>
<Reference>
<Level>1</Level>
<NodeId>6</NodeId>
<ReferenceTypeId>258</ReferenceTypeId>
<ReferenceId>2405</ReferenceId>
<ReferenceCode>COMM</ReferenceCode>
<ReferenceName>Commune</ReferenceName>
<ProductQuery>1,2405</ProductQuery>
<ProductQueryNames>Commune</ProductQueryNames>
<LevelProductQuery>1,2405</LevelProductQuery>
<Children>
<Reference>
<Level>2</Level>
<NodeId>7</NodeId>
<ReferenceTypeId>257</ReferenceTypeId>
<ReferenceId>4060</ReferenceId>
<ReferenceCode>Accessories</ReferenceCode>
<ReferenceName>Accessories</ReferenceName>
<ProductQuery>1,2405:2,4060</ProductQuery>
<ProductQueryNames>Commune, Accessories</ProductQueryNames>
<LevelProductQuery>2,4060</LevelProductQuery>
<Children>
<Reference>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 32 of 197

 <Level>3</Level>
<NodeId>8</NodeId>
<ReferenceTypeId>1</ReferenceTypeId>
<ReferenceId>2368</ReferenceId>
<ReferenceCode>Accessories</ReferenceCode>
<ReferenceName>Accessories</ReferenceName>
<ProductQuery>1,2405:2,4060:3,2368</ProductQuery>
<ProductQueryNames>Commune, Accessories, Accessories</ProductQueryNames>
<LevelProductQuery>3,2368</LevelProductQuery>
<Children />
</Reference>
….etc…..

When a user clicks on a particular node, the associated products can be retrieved via the ProductQuery
elements.
<ProductQuery>1,2405:2,4060:3,2368</ProductQuery>

Note: Record details of this element will be used in the products endpoint.

1.21.5 SUCCESS RESPONSE

HTTP Response
200

1.21.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text
404

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 33 of 197

9 PRODUCTS

The API retrieves relevant product information necessary for the customer to browse products on the
website. The detail includes

 Description
 Colour and size information
 Pricing
 Stock availability
 Barcodes
 Product Reference Code details

There are six different methods of obtaining product information.

The following resources construct product detail in three levels – product, colour and SKU – with pricing
and stock availability.
List of products
Single product by Id
Products you might like

The following resources do not provide SKU level detail including stock availability.
Get list of products – simple
Single product by Id – simple
Product notes by Id
Product colour notes by colour Id

There may be many colours for a product and each colour is able to have up to 30 sizes (SKU).

Colour References
Products are sometimes grouped at the colour level using Colour References. A list of products with similar
colour references can be obtained using the Clr Id on the Product detail and using the request listed in
Product Colours References.

Pricing
By size, there are three price fields:

Price = Current price for today’s date

OriginalPrice = Original price (price with no start or end date)
RetailPrice = Current price for today’s date from price scheme set in Generic Interface Translation table for
SALESNET_RRP. This may not be the same price scheme as the store.

Promotional pricing set up in Apparel21 Retail Promotions is only applied when the Cart is submitted.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 34 of 197

The Markdown Status element and filter at the product / colour level can be used to see if the current price
is a permanent or temporary markdown. This is useful for tagging products for a different area of the
website. For example, permanent markdown product / colours can be moved to a “clearance” section of
the website. Note: The item MUST have an “ORIGINAL” price for this to be effective. The Original price is
the price with NO effective date range.

Custom Data
Available for RetailAPI 2019.1 and later.
Apparel21 has introduced Custom Data types that can be added to products. The new custom data allows
businesses to further enrich the information about their products. As part of enriching data, the Retail API
has been updated to allow web developers to retrieve the custom data to use within the web environment.

To utilise the new version 4 API functionality, the header of the call will need to be updated to specify
‘version 4’

content-type: text/xml

Accept: version_4.0

In order to make the new Custom Data available to web developers, and the extra information that
businesses can add to their products, two product calls have been updated to retrieve the Custom Data.

Full product call

/Products?countryCode={countryCode}&CustomData=true

Single product call

/Products/{id}?countryCode={countryCode}&CustomData=true

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 35 of 197

1.22 PRODUCT DETAILS

GET responses
Field Format Max Comment Example List of Single Products List of Single Product Product HTTP
Products Product by you might products - product – notes colour Header
Length
Id like simple simple notes Accept:
Version
_
Id Integer 22 Id for the product 34053 Yes Yes Yes Yes Yes Yes No 1.0
RowNumber Integer 22 The row number 27 Yes Yes Yes Yes Yes No No 1.0
of this product for
this query
Code Alpha 10 The product code EMC4 Yes Yes Yes Yes Yes No No 1.0
Name Alpha 30 Description of Dririder Target Yes Yes Yes Yes Yes No No 1.0
product Gloves
Description Alpha 254 Comments Waterproof Yes Yes Yes Yes Yes No No 1.0
specified for a gloves to keep
product you dry
SizeRange Alpha 30 Size range name – 6-14 Yes Yes Yes No No No No 1.0
blank for non
sized products
UpdateTimeStamp Alpha 256 Date/time the last 2010-08- Yes Yes No Yes Yes No No 2.0
update was made 30T11:33:09
to the product on
the style table or
the prices for that
style changing for
“today” (does not
include stock
quantity changes)

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 36 of 197

 GET responses
Field Format Max Comment Example List of Single Products List of Single Product Product HTTP
Products Product by you might products - product – notes colour Header
Length
Id like simple simple notes Accept:
Version
_
OriginalPriceFrom Num(22,2) 22 Original lowest 79.95 No No No Yes Yes No No 1.0
price of the
product
PriceFrom Num(22,2) 22 Current lowest 69.95 No No No Yes Yes No No 1.0
price of the
product
OriginalPriceTo Num(22,2) 22 Original Highest 109.95 No No No Yes Yes No No 1.0
price of the
product
PriceTo Num(22,2) 22 Current Highest 99.95 No No No Yes Yes No No 1.0
price of the
product
References The list of
reference Ids for
this product.
Reference Reference is a
sub-element of
references.
ReferenceTypeId Integer 22 The reference 257 Yes Yes Yes No No No No 1.0
type Id
Id Integer 22 The reference Id 6326 Yes Yes Yes No No No No 1.0
of this reference
type for this
product

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 37 of 197

 GET responses
Field Format Max Comment Example List of Single Products List of Single Product Product HTTP
Products Product by you might products - product – notes colour Header
Length
Id like simple simple notes Accept:
Version
_
CustomData List of Cards of Yes Yes No No No No No 4.0
Custom Data on
product level

Cards Alpha Type=”Array” Yes Yes No No No No No 4.0

Card Alpha Name=”” Yes Yes No No No No No 4.0

Fields Alpha Type=”Array” Yes Yes No No No No No 4.0

Field Alpha, Name=”” Summer, Yes Yes No No No No No 4.0

Number, 2134558, YES,
Boolean,D 2019-03-30
ate

ListValues Alpha Type=”Array” Yes Yes No No No No No 4.0

Value Alpha, Summer, Yes Yes No No No No No 4.0

Number, 2134558, YES,
Boolean, 2019-03-30
Date

Clrs The list of colours

for this product
Clr Clr is a sub-
element of Clrs

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 38 of 197

 GET responses
Field Format Max Comment Example List of Single Products List of Single Product Product HTTP
Products Product by you might products - product – notes colour Header
Length
Id like simple simple notes Accept:
Version
_
Id Integer 22 The Id for this 542 Yes Yes Yes No No No Yes 1.0
colour for this
product
ProductId Integer 22 The product Id 34053 Yes Yes Yes No No No No 1.0
which is the
parent of this
colour
Sequence Integer 22 The sequence of 1 Yes Yes Yes No No No No 1.0
this colour within
this product.
Code Alpha 21 Colour code Noir Yes Yes Yes No No No No 1.0
Name Alpha 61 Colour Name Noir comme poix Yes Yes Yes No No No No 1.0
21
TypeCode Alpha The global type BLK Yes Yes Yes No No No No 1.0
code for this
colour. There
could be many
unique
representations
of a colour for
different
products. This
type code is a
way of grouping
into similar types.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 39 of 197

 GET responses
Field Format Max Comment Example List of Single Products List of Single Product Product HTTP
Products Product by you might products - product – notes colour Header
Length
Id like simple simple notes Accept:
Version
_
eg, Black, Noire,
Nera are all
representations
of Black
TypeName Alpha 61 The global type Black Yes Yes Yes No No No No 1.0
name for this
colour
MarkdownStatus Alpha 9 Permanent / Permanent Yes Yes No No No No No 1.0
Temporary /
TempPermanent
/ None – this
indicates whether
the item is a
clearance item or
not. If permanent
markdown, this
indicates a
clearance product
/ colour.
TempPermanent
is a permanently
marked down
item with a
temporary

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 40 of 197

 GET responses
Field Format Max Comment Example List of Single Products List of Single Product Product HTTP
Products Product by you might products - product – notes colour Header
Length
Id like simple simple notes Accept:
Version
_
markdown in
place.
CustomData List of Cards of Yes Yes No No No No No 4.0
Custom Data on
colour level

Cards Alpha Type=”Array” Yes Yes No No No No No 4.0

Card Alpha Name=”” Yes Yes No No No No No 4.0

Fields Alpha Type=”Array” Yes Yes No No No No No 4.0

Field Alpha, Name=”” Summer, Yes Yes No No No No No 4.0

Number, 2134558, YES,
Boolean,D 2019-03-30
ate

ListValues Alpha Type=”Array” Yes Yes No No No No No 4.0

Value Alpha, Summer, Yes Yes No No No No No 4.0

Number, 2134558, YES,
Boolean, 2019-03-30
Date

SKUs The list of sizes

for a colour

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 41 of 197

 GET responses
Field Format Max Comment Example List of Single Products List of Single Product Product HTTP
Products Product by you might products - product – notes colour Header
Length
Id like simple simple notes Accept:
Version
_
SKU SKU is the lowest
level
representation
for a product.
SKU is a sub-
element of SKUs
Id Integer 22 Unique Id for this 55623 Yes Yes Yes No No No No 1.0
size for this
colour
ClrId Integer 22 Id of parent 542 Yes Yes Yes No No No No 1.0
colour
Sequence Integer 22 Sequence of this 2 Yes Yes Yes No No No No 1.0
size within the
colour
SizeCode Alpha 7 Code of the size S Yes Yes Yes No No No No 1.0
OriginalPrice Num (10,2) 10 The original price 32.99 Yes Yes Yes No No No No 1.0
of this size
i.e. Price with no
start / end date
Price Number 10 The current price 18.5 Yes Yes Yes No No No No 1.0
(10,2) of this size – price
for today
RetailPrice Number 10 The current price 30.00 Yes Yes Yes No No No No 1.0
(10,2) for this size in

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 42 of 197

 GET responses
Field Format Max Comment Example List of Single Products List of Single Product Product HTTP
Products Product by you might products - product – notes colour Header
Length
Id like simple simple notes Accept:
Version
_
SalesNet_RRP
interface table.
Might not be the
same price as the
store price
scheme.
Barcode Text The default 9312345111111 Yes
barcode for this
size
Freestock Integer 22 The free stock 27 Yes Yes Yes No No No No 1.0
available for sale.
This is based on a
formula set up in
a Generic
Interface
Translation in
Apparel21
NextAvailable Date (yyyy- 10 The next available 2001-07-29 Yes Yes Yes No No No No 1.0
mm-dd) date of stock for
this size
calculated from
incoming
Purchase Orders
in Apparel21.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 43 of 197

 GET responses
Field Format Max Comment Example List of Single Products List of Single Product Product HTTP
Products Product by you might products - product – notes colour Header
Length
Id like simple simple notes Accept:
Version
_
GlobalSequence Integer 22 The global 562 Yes Yes Yes No No No No 1.0
sequence for the
size. For example
size S might be
defined for many
products and
within each size it
has a different
sequence, but
this global
sequence defines
this size uniquely
within the whole
product range.
ProductNoteTypes The list of
Product Note
Types for this
product.
ProductNoteType Product Note
Type is a sub-
element of
Product Note
Types

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 44 of 197

 GET responses
Field Format Max Comment Example List of Single Products List of Single Product Product HTTP
Products Product by you might products - product – notes colour Header
Length
Id like simple simple notes Accept:
Version
_
Code Alpha 40 Code of Product Styling No No No No No Yes No 2.0
Note Type
Name Alpha 40 Description of Styling Hints No No No No No Yes No 2.0
Product Note
Type
Note Deserialise unlimited Note details You can wear No No No No No Yes No 2.0
d saved for the this dress day or
Xhtml 1.0 product in night
deserialised xhtml
1.0 format in
table
OBJECT_NOTE.
Note length
depends on
Oracle version.
Note to be re-
serialised into
xhtml 1.0.
ProductColourNoteTypes The list of
Product Colour
Note Types for
this product.
ProductColourNoteType Product Colour
Note Type is a

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 45 of 197

 GET responses
Field Format Max Comment Example List of Single Products List of Single Product Product HTTP
Products Product by you might products - product – notes colour Header
Length
Id like simple simple notes Accept:
Version
_
sub-element of
Product Colour
Note Types
Code Alpha 40 Code of Product Styling No No No No No No Yes 2.0
Note Type
Name Alpha 40 Description of Styling Hints No No No No No No Yes 2.0
Product Note
Type
Note Deserialise unlimited Note details Colour does not No No No No No No Yes 2.0
d saved for the fade
Xhtml 1.0 product colour in
deserialised xhtml
1.0 format in
table
OBJECT_NOTE.
Note length
depends on
Oracle version.
Note to be re-
serialised into
xhtml 1.0.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 46 of 197

1.23 RETRIEVE PRODUCT LIST FOR NAVIGATION REFERENCE

This GET request will return a list of all products based on the Product Reference Id. The query parameter
is plugged in from the reference tree as described in Navigation tree. This is a detailed view of products.

1.23.1 URI REQUEST FORMAT

/Products?countryCode={countryCode}&query={queryString}&order={orderBy}&sizeFilter={sizeCode}&colo
urFilter={colourCode}&updatedAfter={updateTimestamp}&startRow={startRow}&pageRows={pageRows}&
CustomData=true

1.23.2 REQUEST PARAMETERS

Field Required Comment
Country Code Mandatory Country Code of shopper
Query Optional Sequence and Product Reference Type. Up to 5 combinations can be
entered.

For example, if want to filter products to only Product Type Jackets, and
Gender Womens, need to identify Product Type sequence and Gender
sequence and unique index for Womens and Jackets.

1,123:2,234

Means that product reference position 1 and reference code index 123
AND product reference position 2 and reference code index 234 will be
filtered.

order Optional valid values are a series of product fields and sort sequence
concatenated as
{id:asc}
{code:desc}
{name:asc}
{description:asc}
{price:asc}
Multiple fields may be selected to define the sequencing of the products
in the result.

sizeFilter Optional A size code to filter the products by size. The range of valid size codes can
be obtained from the Sizes endpoint which is defined in section 11 Sizes

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 47 of 197

 colourFilter Optional A colour code to filter the products by colour. The range of valid colour
codes can be obtained from the colours endpoint which is defined in
section 1.31 Retrieve Colour List

ExtendedRefs Optional Set to “True” to get all product references (up to 20), not just limited to
style references. If NOT “true”, only “style” references (up to 10) are
returned. This was introduced from version 2015.2 onwards.
updatedAfter Optional Allows web developers to retrieve products updated after a specific
timestamp.
Valid date formats: YYYY-MM-DDTHH:MM:SS, YYYY-MM-DDTHH:MM,
YYYY-MM-DD
The timestamp format used to query should match the head office
database date/time settings.
This was introduced from version 2016.3 onwards.
From version 2019, the behaviour of this filter also considers a
markdown starting or ending or other price change as an update. Stock
changes are NOT considered by this filter.
startRow Optional Starting position of products returned
pageRows Optional Number of products returned
CustomData Optional Include Custom Data in returned product information. Set to “True” to
get all valid Custom Data values.

1.23.3 EXAMPLE REQUEST

GET

https://retailapi.apparel21.com/RetailAPI/Products?countryCode=AU&query=1,1506:3,1441&order={name
:asc}&startRow=1&pageRows=40

Content-type: text/xml
Accept:version_2.0

This will return up to 40 products per page, which belong to Commune, Accessories, Accessories
references starting at the first product.

1.23.4 EXAMPLE RESPONSE

<Products>
<Product>
<Id>7126</Id>
<RowNumber>1</RowNumber>
<Code>NAB32</Code>
<Name>Dririder Off Road Tail Bag</Name>
<Description />
<RrpText>RRP</RrpText>
<UpdateTimeStamp>2005-08-17T09:15:23</UpdateTimeStamp>
<References Type="Array">
<Reference>
<ReferenceTypeId>258</ReferenceTypeId>
<Id>2405</Id>
</Reference>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 48 of 197

 <Reference>
<ReferenceTypeId>257</ReferenceTypeId>
<Id>4060</Id>
</Reference>
<Reference>
<ReferenceTypeId>1</ReferenceTypeId>
<Id>2368</Id>
</Reference>
<Reference>
<ReferenceTypeId>2229</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>1168</ReferenceTypeId>
<Id>2390</Id>
</Reference>
<Reference>
<ReferenceTypeId>1169</ReferenceTypeId>
<Id>7185</Id>
</Reference>
</References>
<Clrs Type="Array">
<Clr>
</Clrs>
</Product>
….etc…..

1.23.5 SUCCESS RESPONSE

HTTP Response
200

1.23.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text
404
404 5034 Invalid pagination parameters

1.24 RETRIEVE DETAILS FOR A SINGLE PRODUCT

This request will return full details for a single product using a Product Id retrieved previously.

Perform a GET on the following endpoint.

1.24.1 URI REQUEST FORMAT

/Products/{id}?countryCode={countryCode}

1.24.2 REQUEST PARAMETERS

Field Required Comment
Id Mandatory Id of the Product
Country Code Mandatory Country Code of shopper
markdownStatus Optional Filter for colours based on their price status. Valid values are:
 Permanent
 Temporary

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 49 of 197

  None
CustomData Optional Include Custom Data in returned product information. Set to “True” to
get all valid Custom Data values

1.24.3 EXAMPLE REQUEST

GET
https://retailapi.apparel21.com/RetailAPI/Products/1024?countryCode=AU&markdownStatus=None&Cust
omData=true

Content-type: text/xml
Accept:version_4.0

1.24.4 EXAMPLE RESPONSE

<Product
<Id>5481</Id>
<RowNumber>1</RowNumber>
<Code>0011</Code>
<Name>SLEEVELESS ONESIE SUIT</Name>
<Description>ROYALTY FREE IMAGE</Description>
<SizeRange>6-14</SizeRange>
<RrpText>MSRP</RrpText>
<UpdateTimeStamp>2015-04-29T16:54:59</UpdateTimeStamp>
<References Type="Array">
<Reference>
<ReferenceTypeId>257</ReferenceTypeId>
<Id>1342</Id>
</Reference>
<Reference>
<ReferenceTypeId>1021</ReferenceTypeId>
<Id>5045</Id>
</Reference>
<Reference>
<ReferenceTypeId>1</ReferenceTypeId>
<Id>3281</Id>
</Reference>
<Reference>
<ReferenceTypeId>1201</ReferenceTypeId>
<Id>3081</Id>
</Reference>
<Reference>
<ReferenceTypeId>258</ReferenceTypeId>
<Id>12103</Id>
</Reference>
<Reference>
<ReferenceTypeId>1621</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>315</ReferenceTypeId>
<Id>2981</Id>
</Reference>
</References>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 50 of 197

 <CustomData>
<Cards Type="Array">
<Card Name="Envimo Attributes">
<Fields Type="Array">
<Field Name="Extended Description">Best outfit ever</Field>
<Field Name="Available from">2019-03-20</Field>
<Field Name="Activity">
<ListValues Type="Array">
<Value>Camping</Value>
<Value>Fishing</Value>
<Value>Hiking</Value>
</ListValues>
</Field>
<Field Name="New Arrivals">false</Field>
</Fields>
</Card>
</Cards>
</CustomData>
<Clrs Type="Array">
<Clr>
<Id>6123</Id>
<ProductId>5481</ProductId>
<Sequence>1</Sequence>
<Code>001</Code>
<Name>MULTICOLOURED - Rainbow Colour</Name>
<TypeCode>001</TypeCode>
<TypeName>MULTICOLOURED - Rainbow Colour</TypeName>
<MarkdownStatus>Permanent</MarkdownStatus>
<CustomData>
<Cards Type="Array">
<Card Name="Envimo Attributes">
<Fields Type="Array">
<Field Name="Available from">2019-03-20</Field>
<Field Name="New Arrivals">false</Field>
</Fields>
</Card>
</Cards>
</CustomData>
<SKUs Type="Array">
<SKU>
<Id>12431</Id>
<ClrId>6123</ClrId>
<Sequence>1</Sequence>
<SizeCode>6</SizeCode>
<OriginalPrice>200</OriginalPrice>
<Price>5</Price>
<RetailPrice>200</RetailPrice>
<FreeStock>-345</FreeStock>
<NextAvailable />
<GlobalSequence>1</GlobalSequence>
</SKU>
Etc…

1.24.5 SUCCESS RESPONSE

HTTP Response
200

1.24.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 51 of 197

 404

1.25 RETRIEVE PRODUCTS YOU MIGHT LIKE

This returns a list of products that have been grouped as similar in Apparel21. It enables products to be
suggested to shoppers as products “you might like”.

Perform a GET on the following URI

1.25.1 URI REQUEST FORMAT

/Products/{id}/YouMightLikeProducts?countryCode={countryCode}

1.25.2 REQUEST PARAMETERS

Field Required Comment
Id Mandatory Id of the product
CountryCode Mandatory Country code of the shopper

1.25.3 EXAMPLE REQUEST

GET https://retailapi.apparel21.com/RetailAPI/Products/1155/YouMightLikeProducts?countryCode=AU

Content-type: text/xml
Accept:version_2.0

1.25.4 EXAMPLE RESPONSE

<Products>
<Product>
<Id>7543</Id>
<RowNumber>1</RowNumber>
<Code>1CZBCC</Code>
<Name>JACKET</Name>
<Description />
<RrpText>RRP</RrpText>
<UpdateTimeStamp>2007-06-23T16:39:47</UpdateTimeStamp>
<References Type="Array">
<Reference>
<ReferenceTypeId>258</ReferenceTypeId>
<Id>5482</Id>
</Reference>
<Reference>
<ReferenceTypeId>257</ReferenceTypeId>
<Id>5063</Id>
</Reference>
<Reference>
<ReferenceTypeId>1</ReferenceTypeId>
<Id>2364</Id>
</Reference>
<Reference>
<ReferenceTypeId>2229</ReferenceTypeId>
<Id />

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 52 of 197

 </Reference>
<Reference>
<ReferenceTypeId>1168</ReferenceTypeId>
<Id>6323</Id>
</Reference>
<Reference>
<ReferenceTypeId>1169</ReferenceTypeId>
<Id>7185</Id>
</Reference>
</References>
<Clrs Type="Array">
<Clr>
<Id>8823</Id>
<ProductId>7543</ProductId>
<Sequence>3</Sequence>
<Code>001</Code>
<Name>Black</Name>
<TypeCode>001</TypeCode>
<TypeName>Black</TypeName>
<SKUs Type="Array">
<SKU>
<Id>18224</Id>
<ClrId>8823</ClrId>
<Sequence>3</Sequence>
<SizeCode>S</SizeCode>
<OriginalPrice>74.95</OriginalPrice>
<Price>74.95</Price>
<RetailPrice>0</RetailPrice>
<FreeStock>44</FreeStock>
<NextAvailable />
<GlobalSequence>3</GlobalSequence>
</SKU>
<SKU>
<Id>18225</Id>
<ClrId>8823</ClrId>
<Sequence>4</Sequence>
<SizeCode>M</SizeCode>
<OriginalPrice>74.95</OriginalPrice>
<Price>74.95</Price>
<RetailPrice>0</RetailPrice>
<FreeStock>4</FreeStock>
<NextAvailable />
<GlobalSequence>4</GlobalSequence>
</SKU>
<SKU>
….etc…..

1.25.5 SUCCESS RESPONSE

HTTP Response
200

1.25.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text
404
403 5096 Free Stock Formula is invalid in the GIT setup
403 5097 Future Stock Formula is invalid in the GIT setup

1.26 RETRIEVE SIMPLE LIST OF PRODUCTS

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 53 of 197

This query will return a list of products with fewer details than provided with “Get list of Products”. It can
be used to present the shopper with the initial display of products without the colours and sizes and will
considerably reduce the response payload.

1.26.1 URI REQUEST FORMAT

/ProductsSimple?countryCode={countryCode}&query={queryString}&updatedAfter={updateTimestamp}&o
rder={orderBy}&startRow={startRow}&pageRows={pageRows}

1.26.2 REQUEST PARAMETERS

Field Required Comment
CountryCode Mandatory Country Code of the shopper
Query String Optional Sequence and Product Reference Type. Up to 5
combinations can be entered.

updatedAfter Optional Allows web developers to retrieve products updated after

a specific timestamp.
Valid date formats: YYYY-MM-DDTHH:MM:SS, YYYY-MM-
DDTHH:MM, YYYY-MM-DD
The timestamp format used to query should match the
head office database date/time settings.
This was introduced from version 2016.3 onwards.
From version 2019, this filter was extended to consider
price changes for “today” as a product update. Prior to
this, only product changes were considered.
Order Optional valid values are a series of product fields and sort
sequence concatenated as
{id:asc}
{code:desc}
{name:asc}
{description:asc}
{price:asc}

Multiple fields may be selected to define the sequencing

of the products in the result.

startRow Optional Starting product number

pageRows Optional Number of products per page

1.26.3 EXAMPLE REQUEST

GET
https://retailapi.apparel21.com/RetailAPI/ProductsSimple?countryCode=AU&query=1,1506:3,1441&order
={name:asc}&startRow=1&pageRows=40

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 54 of 197

 Content-type: text/xml
Accept:version_2.0

1.26.4 EXAMPLE RESPONSE

<ProductsSimple>
<ProductSimple>
<Id>6264</Id>
<RowNumber>1</RowNumber>
<Code>M2</Code>
<Name>MRP 2</Name>
<Description />
<OriginalPriceFrom>79.95</OriginalPriceFrom>
<PriceFrom>79.95</PriceFrom>
<OriginalPriceTo>79.95</OriginalPriceTo>
<PriceTo>79.95</PriceTo>
<AvailableStock>0</AvailableStock>
<UpdateTimeStamp>2010-06-03T10:03:43</UpdateTimeStamp>
</ProductSimple>
<ProductSimple>
<Id>7126</Id>
<RowNumber>2</RowNumber>
<Code>NAB32</Code>
<Name>Dririder Off Road Tail Bag</Name>
<Description />
<OriginalPriceFrom>79.95</OriginalPriceFrom>
<PriceFrom>79.95</PriceFrom>
<OriginalPriceTo>79.95</OriginalPriceTo>
<PriceTo>79.95</PriceTo>
<AvailableStock>0</AvailableStock>
<UpdateTimeStamp>2005-08-17T09:15:23</UpdateTimeStamp>
</ProductSimple>
</ProductsSimple>

1.26.5 SUCCESS RESPONSE

HTTP Response
200

1.26.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text
404
400 5034 Invalid pagination parameters

1.27 RETRIEVE SIMPLE DETAILS FOR A SINGLE PRODUCT

This GET request will return ‘simple’ details for a single product using the Product Id retrieved previously.

1.27.1 URI REQUEST FORMAT

/ProductsSimple/{id}?countryCode={countryCode}

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 55 of 197

1.27.2 REQUEST PARAMETERS
Field Required Comment
Id Mandatory Id of the Product
Country Code Mandatory Country Code of shopper

1.27.3 EXAMPLE REQUEST

GET https://retailapi.apparel21.com/RetailAPI/ProductsSimple/1024?countryCode=AU

Content-type: text/xml
Accept:version_2.0

1.27.4 EXAMPLE RESPONSE

<ProductSimple">
<Id>7126</Id>
<RowNumber>1</RowNumber>
<Code>NAB32</Code>
<Name>Dririder Off Road Tail Bag</Name>
<Description />
<OriginalPriceFrom>79.95</OriginalPriceFrom>
<PriceFrom>79.95</PriceFrom>
<OriginalPriceTo>79.95</OriginalPriceTo>
<PriceTo>79.95</PriceTo>
<AvailableStock>0</AvailableStock>
<UpdateTimeStamp>2005-08-17T09:15:23</UpdateTimeStamp>
</ProductSimple>

1.27.5 SUCCESS RESPONSE

HTTP Response
200

1.27.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text
404

1.28 RETRIEVE PRODUCT NOTES

This GET request will return the note types and notes stored in AP21 for a product using the Product Id
retrieved previously. If no notes exist for a Product Id, no notes are returned.

1.28.1 URI REQUEST FORMAT

/ProductNotes/{id}?countryCode={countryCode}

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 56 of 197

1.28.2 REQUEST PARAMETERS
Field Required Comment
Id Mandatory Id of the Product
Country Code Mandatory Country Code of shopper

1.28.3 EXAMPLE REQUEST

GET https://retailapi.apparel21.com/RetailAPI/ProductNotes/1155?countryCode=AU

Content-type: text/xml
Accept:version_2.0

1.28.4 EXAMPLE RESPONSE

<ProductNoteTypes>
<ProductNoteType>
<Code>Web Description</Code>
<Name>Web Description for Retail API</Name>
<Note>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"&gt;
&lt;html&gt;
&lt;head&gt;
&lt;meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8"
/&gt;&lt;title&gt;
&lt;/title&gt;
&lt;style type="text/css"&gt;
.cs2E86D3A6{text-align:center;text-indent:0pt;margin:0pt 0pt 0pt 0pt}
.cs5EFED22F{color:#000000;background-color:transparent;font-family:Times New
Roman; font-size:12pt; font-weight:normal; font-style:normal; }
.csB86C8CFE{color:#000000;background-color:transparent;font-family:Times New
Roman; font-size:12pt; font-weight:bold; font-style:normal; }
.cs91B7CE26{color:#000000;background-color:#FFFF80;font-family:Times New
Roman; font-size:12pt; font-weight:normal; font-style:normal; }
&lt;/style&gt;
&lt;/head&gt;
&lt;body&gt;
&lt;span&gt;&lt;p class="cs2E86D3A6"&gt;&lt;span class="cs5EFED22F"&gt;Heavyweight
Cotton Drill Coverall with 3M &lt;/span&gt;&lt;span class="csB86C8CFE"&gt;50mm&lt;/span&gt;&lt;span
class="cs5EFED22F"&gt; 8910 Reflective Tape&lt;/span&gt;&lt;/p&gt;&lt;p
class="cs2E86D3A6"&gt;&lt;span class="cs91B7CE26"&gt;Two hoops around body and a hoop around each
arm and leg&lt;/span&gt;&lt;/p&gt;&lt;/span&gt;&lt;/body&gt;
&lt;/html&gt;
</Note>
</ProductNoteType>
</ProductNoteTypes>

1.28.5 SUCCESS RESPONSE

HTTP Response
200

1.28.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 57 of 197

 404

1.29 RETRIEVE PRODUCT COLOUR NOTES

This GET request will return the note types and notes stored in AP21 for a product colour using the ClrId
retrieved previously. If no notes exist for a ClrId, no notes are returned.

1.29.1 URI REQUEST FORMAT

/ProductColourNotes/{id}?countryCode={countryCode}

1.29.2 REQUEST PARAMETERS

Field Required Comment
Id Mandatory Id of the Product Colour
Country Code Mandatory Country Code of shopper

1.29.3 EXAMPLE REQUEST

GET https://retailapi.apparel21.com/RetailAPI/ProductColourNotes/1200?countryCode=AU

Content-type: text/xml
Accept:version_2.0

1.29.4 EXAMPLE RESPONSE

<ProductColourNoteTypes
<ProductColourNoteType>
<Code>Note1</Code>
<Name>Note1</Name>
<Note>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"&gt;
&lt;html
xmlns="http://www.w3.org/1999/xhtml"&gt;
&lt;head&gt;
&lt;meta http-equiv="Content-Type" content="text/html; charset=utf-8"
/&gt;&lt;title&gt;
&lt;/title&gt;
&lt;style type="text/css"&gt;
.cs95E872D0{text-align:left;text-indent:0pt;margin:0pt 0pt 0pt 0pt}
.csCF6BBF71{color:#000000;background-color:transparent;font-family:Times New
Roman;font-size:12pt;font-weight:normal;font-style:normal;}
&lt;/style&gt;
&lt;/head&gt;
&lt;body&gt;
&lt;p class="cs95E872D0"&gt;&lt;span class="csCF6BBF71"&gt;Blue
Note2&lt;/span&gt;&lt;/p&gt;&lt;/body&gt;
&lt;/html&gt;

</Note>
</ProductColourNoteType>
<ProductColourNoteType>
<Code>Note2</Code>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 58 of 197

 <Name>Note2</Name>
<Note>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"&gt;
&lt;html
xmlns="http://www.w3.org/1999/xhtml"&gt;
&lt;head&gt;
&lt;meta http-equiv="Content-Type" content="text/html; charset=utf-8"
/&gt;&lt;title&gt;
&lt;/title&gt;
&lt;style type="text/css"&gt;
.cs95E872D0{text-align:left;text-indent:0pt;margin:0pt 0pt 0pt 0pt}
.csCF6BBF71{color:#000000;background-color:transparent;font-family:Times New
Roman;font-size:12pt;font-weight:normal;font-style:normal;}
&lt;/style&gt;
&lt;/head&gt;
&lt;body&gt;
&lt;p class="cs95E872D0"&gt;&lt;span class="csCF6BBF71"&gt;Blue
Note&lt;/span&gt;&lt;/p&gt;&lt;/body&gt;
&lt;/html&gt;
</Note>
</ProductColourNoteType>
</ProductColourNoteType

1.29.5 SUCCESS RESPONSE

HTTP Response
200

1.29.6 ERROR RESPONSE

None

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 59 of 197

10 COLOURS

The colours resource retrieves a list of colours that are active for the reference ids provided.

1.30 COLOUR DETAILS

Field Format Max Comment Example GET Response HTTP Header
Length Accept:Versio
n_
Code Alpha 21 Colour Code Noir Yes 1.0
Name Alpha 61 Colour Name Noir comme poix Yes 1.0
Row Number Num 1 Row Number 1 Yes 1.0

1.31 RETRIEVE COLOUR LIST

1.31.1 URI REQUEST FORMAT

Colours?countryCode={countryCode}&query={queryString}

1.31.2 REQUEST PARAMETERS

Field Required Comment
CountryCode Mandatory Country code of the shopper
Query Optional Sequence and Product Reference Type.
Up to 5 combinations can be entered.

1.31.3 EXAMPLE REQUEST

GET https://retailapi.apparel21.com/RetailAPI/Colours?countryCode=AU&query=1,1506

Content-type: text/xml
Accept:version_2.0

1.31.4 EXAMPLE RESPONSE

<Colours>
<Colour>
<Code>BLK</Code>
<Name>Black</Name>
<RowNumber>1</RowNumber>
</Colour>
<Colour>
<Code>BLK/BLU</Code>
<Name>BLACK / BLUE</Name>
<RowNumber>2</RowNumber>
</Colour>
<Colour>
<Code>BLK/GRY</Code>
<Name>BLACK / GREY</Name>
<RowNumber>3</RowNumber>
</Colour>
<Colour>
<Code>BLK/RED</Code>
<Name>BLACK / RED</Name>
<RowNumber>4</RowNumber>
</Colour>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 60 of 197

 Etc……

1.31.5 SUCCESS RESPONSE

HTTP Response
200

1.31.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text
404

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 61 of 197

11 SIZES

The sizes resource retrieves a list of sizes that are active for the reference ids provided.

1.32 SIZE DETAILS

Field Format Max Comment Example GET Response HTTP Header

Length Accept:Version_
Code Alpha 6 Size Code S Yes 1.0
Row Number Num 1 Row Number 1 Yes 1.0

1.33 RETRIEVE SIZE LIST

1.33.1 URI REQUEST FORMAT

/Sizes?countryCode={countryCode}&query={queryString}

1.33.2 REQUEST PARAMETERS

Field Required Comment
CountryCode Mandatory Country code of the shopper
Query Optional Sequence and Product Reference Type.
Up to 5 combinations can be entered.
includeOutOfStock Optional true / false. Defaults to false if not supplied.
If false, sizes for products not in stock are not
included. If set to true, sizes will be included in the
results, even if the products don’t have stock
currently.

1.33.3 EXAMPLE REQUEST

GET
https://retailapi.apparel21.com/RetailAPI/Sizes?countryCode=AU&query=1,1506&includeOutOfStock=true

Content-type: text/xml
Accept:version_2.0

1.33.4 EXAMPLE RESPONSE

<Sizes>
<Size>
<Code>8</Code>
<Name>1</Name>
<RowNumber>1</RowNumber>
</Size>
<Size>
<Code>9</Code>
<RowNumber>2</RowNumber>
</Size>
<Size>
<Code>10</Code>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 62 of 197

<RowNumber>3</RowNumber>
</Size>
<Size>
<Code>6</Code>
<RowNumber>4</RowNumber>
</Size>
<Size>
<Code>XS</Code>
<RowNumber>5</RowNumber>
</Size>
<Size>
etc……

1.33.5 SUCCESS RESPONSE

HTTP Response
200

1.33.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text
404

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 63 of 197

12 PERSONS

‘Persons’ is a term used within Apparel21 to store details for people who purchase goods from a retail store.
When an online shopper creates an account, a Person record must be created in Apparel21 and include
email address and other contact and delivery details. In Apparel21 the Person is attached to a predefined
‘Customer’ record which is used to determine the pricing, discounts and freight for the shopper.

The email address is used to login to the website and complete an order. Persons can be be created,
updated and retrieved by the API. It is possible to create persons with the same email address for different
brands or divisions in the same database. The person’s email address must be unique within a brand or
division as it is used as the primary lookup.

Person email address is a mandatory field for all creates.

Custom Data

Custom Data feature has been extended to Persons in Version 2020.1 with job 114928 to allow businesses
to capture more information around retail customers (Persons).

A new GET endpoint is added to assist web developers for getting the list of custom data templates
available on a web warehouse. Besides, details of a single template can be retrieved by supplying the
template name.

Get list of custom data templates available for the web warehouse

/Persons/customdatatemplates?countryCode={countryCode}

Get a single template by template name

/Persons/customdatatemplates/{template name}?countryCode={countryCode}

A new request parameter ‘CustomData’ is added for getting a single Person with custom data.

/Persons/{Id}?countryCode={CountryCode}&CustomData=true

The POST and PUT endpoints have been enhanced to allow the creating and updating Persons with Custom
Data.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 64 of 197

1.34 PERSON DETAILS

GET HTTP
Field Format Max Comment Example GET Timestamp POST PUT Header
Length Response Response Request Request Accept:V
ersion_
Id Integer 22 Id of the Person 101231 Yes Yes No Yes 1.0
Code Alpha 10 Code generated by API SMITJOHN22 Yes Yes No No 1.0
Title Alpha 10 Salutation Mr Yes No Yes Optional 1.0
Initials Alpha 6 Initials JJ Yes No Yes Optional 1.0
Firstname Alpha 20 First name John Yes No Yes Yes 1.0
Surname Alpha 20 Surname Smith Yes No Yes Yes 1.0
Sex Alpha 1 Sex M Yes No Optional Optional 1.0
Accepted values are
“M” = Male
“F”= Female
“NS” = Non-specific
Blank
Other values can be passed but won’t
display in store or at head office.
DateOfBirth Date 10 Date of birth 1984-12-25 Yes No Optional Optional 1.0
(yyyyy-MM-
dd)
StartDate Date 10 Date of addition 2011-03-25 Yes No Optional Optional 1.0
(yyyyy-MM-
dd)
JobTitle Alpha 20 Title Office Admin Yes No Optional Optional 1.0
Password Alpha 50 Hashed of password provided by xyzH334oQ12 No No Yes Optional 1.0
website. This is stored by the API and
required for subsequent GET requests for
person.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 65 of 197

 GET HTTP
Field Format Max Comment Example GET Timestamp POST PUT Header
Length Response Response Request Request Accept:V
ersion_
UpdateTimeStamp Timestamp 22 D/MM/CCYY HH:MM:SS tt – must be 6/05/2010 Yes Yes No Yes 1.0
supplied when updating a person using 4:32:15 PM
“PUT” request as this is how the API
determines that the latest person data is
being updated.
Date time passed in the “PUT” must
match the current record being updated.
Note – Do a “GET” to get the current
date/time and regurgitate that in the
“PUT”.
Privacy Alpha 5 Must be “true” or “false”. True = this True Yes No Optional Optional 1.0
person has requested privacy. If not
supplied, the default value in Apparel21
will be “false”.
DocketNumber Alpha 50 Docket number which is passed along D19800002202 No No Optional No 2.0
in QR code URL. Refer to Job 115895
for details
RewardProgramId Integer 38 Unique identifier of the reward 1001 No No Optional No 2.0
program. Refer to Job 115895 for
details
References
Reference Reference is a sub element of
References
ReferenceTypeId Integer 22 Id of reference group – e.g. id of “Opt Yes No Yes Optional 1.0
In?” reference
Id Integer 22 Id of reference code – e.g. id of “Yes” Yes No Yes Optional 1.0
CustomData List of custom data cards Yes No Optional Optional 2.0
Cards Alpha Type="Array" Yes No Optional Optional 2.0

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 66 of 197

 GET HTTP
Field Format Max Comment Example GET Timestamp POST PUT Header
Length Response Response Request Request Accept:V
ersion_
Card Alpha Name="" Marketing data Yes No Optional Optional 2.0
Fields Alpha Type="Array" Yes No Optional Optional 2.0
Field Alpha Name="" Social influencer Yes No Optional Optional 2.0
Number 45789357
Boolean True
Date 2020-05-25
ListValues Alpha Type="Array" Yes No Optional Optional 2.0
Value Alpha English Yes No Optional Optional 2.0
Addresses There are two addresses as part of the
person resource - Billing and Delivery.
The following field definitions are
common for both. Billing and Delivery
are sub-elements of Addresses.
AddressLine1 Alpha 50 Address line 1 Level 2 Yes No Yes1 Optional 1.0
AddressLine2 Alpha 50 Address line 2 21 Cremorne Yes No Yes1 Optional 1.0
Street
City Alpha 50 City Cremorne Yes No Yes1 Optional 1.0
State Alpha 50 State VIC Yes No Yes1 Optional 1.0
Postcode Alpha 10 Post code or ZIP code 3121 Yes No Yes1 Optional 1.0
Country Alpha 20 Country Australia Yes No Yes1 Optional 1.0
Note 1: At least 1 address field must be
completed for both Billing and Delivery
detail
Contacts Contacts consist of Email and Phone
numbers.
Email Alpha 250 Email address. This must be unique John.Smith@APP Yes No Optional Optional 1.0
within each company/division AREL21.COM – if not
(configured business by business). supplied,
existing

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 67 of 197

 GET HTTP
Field Format Max Comment Example GET Timestamp POST PUT Header
Length Response Response Request Request Accept:V
ersion_
email
will be
cleared
Phones Phones is a sub element of Contacts
Home Alpha 250 Home phone 03 94275120 Yes No Optional Optional 1.0
Mobile Alpha 250 Mobile Phone 0421 552 654 Yes No Optional Optional 1.0
Work Alpha 250 Work phone 84159300 Yes No Optional Optional 1.0
Loyalties Prior to version 3.0, this section is
optional. If not supplied, loyalty
information will not be updated.
WARNING: From version 3.0+, if loyalty
information is not supplied it will
inactivate any loyalties linked to the
person being updated.
Loyalty Loyalty is a sub reference of Loyalties
Id Integer 22 Id of loyalty record 123456 Yes No No Yes if 1.0
updating
existing
loyalty –
No to
create a
new
loyalty
on an
existing
person
LoyaltyTypeId Integer 22 Id of Loyalty Type record –– Loyalties are 30861 Yes No Yes Yes 1.0
found under group id 366
LoyaltyType Alpha 40 Description of loyalty VIP Gold loyalty Yes No No No 1.0

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 68 of 197

 GET HTTP
Field Format Max Comment Example GET Timestamp POST PUT Header
Length Response Response Request Request Accept:V
ersion_
CardNo Alpha 250 Loyalty card number. LM12345678 Yes No Optional Yes 1.0
All supplied numbers must begin with
LM.
If not supplied for a POST person, it is
generated automatically using Apparel21
standard logic. E.g. L prefix, loyalty ID,
PERIDX
Expiry Date yyyy- 10 Expiry date of loyalty card for this person 2015-10-29 Optional No Optional Optional 1.0
MM-dd
Balance Integer 22 Loyalty balance as shown in Persons 100 Optional No 1.0
loyalty “balance” column Optional Optional

CreditStatus Number 22 Extended loyalties only 1321 Optional No 1.0

Displayed at store and head office under Optional Optional
Credit Status field
Message Alpha 250 Extended loyalties only You are 100 Optional No 1.0
Message to display at POS points from Optional Optional
updating to Gold
JoinDate Date yyyy- 10 Extended loyalties only 2014-10-01 Optional No 1.0
MM-dd Date of joining loyalty program Optional Optional

StatusId Integer 22 Extended loyalties only 1231 Optional No 1.0

Id of Loyalty Status record –– Status idx Optional Optional
are found under group of 437.
Typically used to determine active and
inactive statuses.
RewardsAccounts List of rewards programs a person 1.0
belongs to. Currently, limited to a single
program.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 69 of 197

 GET HTTP
Field Format Max Comment Example GET Timestamp POST PUT Header
Length Response Response Request Request Accept:V
ersion_
Account Summary of reward account details 1.0

Id Number 38 This is the unique identifier of the 1 Yes No 1.0

rewards account of the person No No

ProgramId Number 38 Rewards Program Id 1 Yes No 1.0

No No

ProgramName Alpha 250 Rewards Program Name Apparel21 Yes No 1.0

Rewards Program No No

TierId Number 38 Tier Id 1 Yes No 1.0

No No

TierName Alpha 250 Tier Name Bronze Yes No 1.0

No No

Currency Currency consists of Code and Format.

Code Alpha 50 Currency Code associated with the AUD Yes No No No 1.0
person
Format Alpha 50 Format of currency display in Ap21 #,##0.00 'Aud' Yes No No No 1.0

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 70 of 197

1.35 RETRIEVE PERSON DETAILS

The Person details are retrieved by submitting a GET. The following URI will return person records that
match the parameters entered.

1.35.1 URI REQUEST FORMAT

/Persons?countryCode={countryCode}&surname={surname}&firstname={firstname}&phone={phone}&ema
il={email}&code={code}&password={password}

1.35.2 REQUEST PARAMETERS

Field Required Comment
CountryCode Mandatory Country Code of Shopper
Surname Optional
Firstname Optional
Email Optional Email address used to uniquely identify the person.

Phone Optional May be one of either

- Home
- Mobile or
- Work phone number
Code Optional Person Code
Password Optional Password of the Person
LoyaltyOnly Optional If set to “true” will retrieve only loyalty customers on a
GET and will limit the email uniqueness check to loyalty
customers only on PUT and POST requests.

1.35.3 EXAMPLE REQUEST

GET
https://retailapi.apparel21.com/RetailAPI/Persons?countryCode=AU&[email protected]
m

Content-type: text/xml
Accept:version_2.0

1.35.4 EXAMPLE RESPONSE

<Person
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Id>1241</Id>
<Code>HILLJO00</Code>
<Title>MR</Title>
<Initials>JH</Initials>
<Firstname>JOHN</Firstname>
<Surname>HILL</Surname>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 71 of 197

 <Sex>M</Sex>
<DateOfBirth />
<StartDate>2006-03-02</StartDate>
<JobTitle></JobTitle>
<Privacy>True</Privacy>
<UpdateTimeStamp>15/09/2014 2:05:34 PM</UpdateTimeStamp>
<References Type="Array">
<Reference>
<ReferenceTypeId>373</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>1781</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>1782</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>1801</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>1501</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>27</ReferenceTypeId>
<Id />
</Reference>
</References>
<IsAgent>false</IsAgent>
<Addresses>
<Billing>
<ContactName />
<AddressLine1>1 SWAN ST</AddressLine1>
<AddressLine2 />
<City>RICHMOND</City>
<State>VIC</State>
<Postcode>3121</Postcode>
<Country>AUSTRALIA</Country>
</Billing>
</Addresses>
<Contacts>
<Email>[email protected]</Email>
<Phones>
<Home>0384159300</Home>
<Mobile />
<Work />
</Phones>
</Contacts>
<Currency>
<Code />
<Format />
</Currency>
<Loyalties Type="Array">
<Loyalty>
<Id>1261</Id>
<LoyaltyTypeId>8561</LoyaltyTypeId>
<LoyaltyType>VIP</LoyaltyType>
<CardNo>L011241</CardNo>
<Expiry>2014-09-28</Expiry>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 72 of 197

 <Balance />
<CreditStatus />
<Message />
<JoinDate />
<StatusId />
</Loyalty>
<Loyalty>
<Id>1262</Id>
<LoyaltyTypeId>10570</LoyaltyTypeId>
<LoyaltyType>Staff Loyalty 40%</LoyaltyType>
<CardNo>L40</CardNo>
<Expiry />
<Balance />
<CreditStatus />
<Message />
<JoinDate>2014-09-11</JoinDate>
<StatusId />
</Loyalty>
</Loyalties>
<RewardsAccounts>
<Account>
<Id>1</Id>
<ProgramId>1</ProgramId>
<ProgramName>Apparel21 Rewards Program</ProgramName>
<TierId>1</TierId>
<TierName>Bronze</TierName>
</Account>
</RewardsAccounts>
</Person>

1.35.5 SUCCESS RESPONSE

HTTP Response
200

1.35.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text
404 5008 No data found
400 5013 More than one person satisfies filter
403 5144 Invalid date value: 0011-03-02

1.36 RETRIEVE SINGLE PERSON DETAILS

This request will return full details for a single person using the Person Id retrieved previously.

1.36.1 URI REQUEST FORMAT

Perform a GET on the following endpoint.

/Persons/{id}?countryCode={countryCode}

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 73 of 197

1.36.2 REQUEST PARAMETERS
Field Required Comment
Id Mandatory Id of the Person
Country Code Mandatory Country Code of shopper
CustomData Optional Include Custom Data in returned Person. Set to “True” to get all
valid Custom Data values

1.36.3 EXAMPLE REQUEST

GET https://retailapi.apparel21.com/RetailAPI/Persons/4881?countryCode=AU&CustomData=true

Content-type: text/xml
Accept:version_2.0

1.36.4 EXAMPLE RESPONSE

<Person
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Id>1241</Id>
<Code>HILLJO00</Code>
<Title>MR</Title>
<Initials>JH</Initials>
<Firstname>JOHN</Firstname>
<Surname>HILL</Surname>
<Sex>M</Sex>
<DateOfBirth />
<StartDate>2006-03-02</StartDate>
<JobTitle></JobTitle>
<Privacy>True</Privacy>
<UpdateTimeStamp>15/09/2014 2:05:34 PM</UpdateTimeStamp>
<References Type="Array">
<Reference>
<ReferenceTypeId>373</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>1781</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>1782</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>1801</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>1501</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>27</ReferenceTypeId>
<Id />
</Reference>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 74 of 197

 </References>
<CustomData>
<Cards Type="Array">
<Card Name="Special request">
<Fields Type="Array">
<Field Name="Special request from customer">Prefer to receive
a catalogue</Field>
</Fields>
</Card>
<Card Name="Marketing information ">
<Fields Type="Array">
<Field Name="SMS ">true</Field>
<Field Name="Email">true</Field>
</Fields>
</Card>
<Card Name="hobby and interest"> <!—No data for this card-->
<Fields Type="Array">
<Field Name="List of interests">
<ListValues Type="Array"/>
</Field>
<Field Name="Interests">
<ListValues Type="Array"/>
</Field>
</Fields>
</Card>
</Cards>
</CustomData>
<IsAgent>false</IsAgent>
<Addresses>
<Billing>
<ContactName />
<AddressLine1>1 SWAN ST</AddressLine1>
<AddressLine2 />
<City>RICHMOND</City>
<State>VIC</State>
<Postcode>3121</Postcode>
<Country>AUSTRALIA</Country>
</Billing>
</Addresses>
<Contacts>
<Email>[email protected]</Email>
<Phones>
<Home>0384159300</Home>
<Mobile />
<Work />
</Phones>
</Contacts>
<Currency>
<Code />
<Format />
</Currency>
<Loyalties Type="Array">
<Loyalty>
<Id>1261</Id>
<LoyaltyTypeId>8561</LoyaltyTypeId>
<LoyaltyType>VIP</LoyaltyType>
<CardNo>L011241</CardNo>
<Expiry>2014-09-28</Expiry>
<Balance />
<CreditStatus />
<Message />
<JoinDate />
<StatusId />

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 75 of 197

 </Loyalty>
<Loyalty>
<Id>1262</Id>
<LoyaltyTypeId>10570</LoyaltyTypeId>
<LoyaltyType>Staff Loyalty 40%</LoyaltyType>
<CardNo>L40</CardNo>
<Expiry />
<Balance />
<CreditStatus />
<Message />
<JoinDate>2014-09-11</JoinDate>
<StatusId />
</Loyalty>
</Loyalties>
<RewardsAccounts>
<Account>
<Id>1</Id>
<ProgramId>1</ProgramId>
<ProgramName>Apparel21 Rewards Program</ProgramName>
<TierId>1</TierId>
<TierName>Bronze</TierName>
</Account>
</RewardsAccounts>
</Person>

1.36.5 SUCCESS RESPONSE

HTTP Response
200

1.36.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text
404

1.37 RETRIEVE SINGLE PERSON LAST UPDATE TIMESTAMP

This request will return the last update timestamp for a single person using the Person Id retrieved
previously. The timestamp returned is required when updating a person record and is used to check that
the record being updated has not been modified since the record was retrieved.

1.37.1 URI REQUEST FORMAT

Perform a GET on the following endpoint.

/Persons/{id}/UpdateTimeStamp/?CountryCode={CountryCode}

1.37.2 REQUEST PARAMETERS

Field Required Comment
Id Mandatory Id of the Person
Country Code Mandatory Country Code of shopper

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 76 of 197

1.37.3 EXAMPLE REQUEST

GET https://retailapi.apparel21.com/RetailAPI/Persons/4881/UpdateTimeStamp/?countryCode=AU

Content-type: text/xml
Accept:version_2.0

1.37.4 EXAMPLE RESPONSE

<PersonUpdateTimeStamp>
<PersonId>101451</PersonId>
<UpdateTimeStamp>2012-10-09T10:47:16</UpdateTimeStamp>
</PersonUpdateTimeStamp>

1.37.5 SUCCESS RESPONSE

HTTP Response
200

1.37.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text
404

1.38 CREATE NEW PERSON

Prior to a shopper generating an order through the website they must be created as a Person in Apparel21.
A Person is created by submitting a POST to the following URI. Only one Person can be created at a time.

1.38.1 URI REQUEST FORMAT

/Persons/?countryCode={countryCode}

1.38.2 REQUEST PARAMETERS

Field Required Comment
CountryCode Mandatory Country Code of Shopper

1.38.3 EXAMPLE REQUEST

POST https://retailapi.apparel21.com/RetailAPI/Persons/?countryCode=AU

Content-type: text/xml
Accept:version_2.0

1.38.4 EXAMPLE PAYLOAD

<Person>
<Title>MS</Title>
<Initials>AM</Initials>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 77 of 197

 <Firstname>ALICE</Firstname>
<Surname>MCGINTY</Surname>
<References Type="Array">
<Reference>
<ReferenceTypeId>373</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>1781</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>1782</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>1801</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>1501</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>27</ReferenceTypeId>
<Id />
</Reference>
</References>
<CustomData>
<Cards Type="Array">
<Card Name="My_sample_data"> <!—If no data, pass the card with empty value fields -->
<Fields Type="Array">
<Field Name="My card_No">LMI01234567890123</Field>
<Field Name="Preferred language">
<ListValues Type="Array">
<Value>English</Value>
</ListValues>
</Field>
<Field Name="MID_Line">45789357</Field>
<Field Name="Collect">true</Field>
<Field Name="Usage">true</Field>
<Field Name="Disclosure">true</Field>
<Field Name="Allow_Contact">false</Field>
<Field Name="Email_Status">true</Field>
<Field Name="SMS_Status">false</Field>
<Field Name="DirectMail_Status">true</Field>
<Field Name="Terms and Condition">true</Field>
</Fields>
</Card>
</Cards>
</CustomData>
<IsAgent>false</IsAgent>
<Addresses>
<Billing>
<ContactName />
<AddressLine1>1 SWAN ST</AddressLine1>
<AddressLine2 />
<City>RICHMOND</City>
<State>VIC</State>
<Postcode>3121</Postcode>
<Country>AUSTRALIA</Country>
</Billing>
</Addresses>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 78 of 197

 <Contacts>
<Email>[email protected]</Email>
</Contacts>
<Loyalties Type="Array">
<Loyalty>
<LoyaltyTypeId>10570</LoyaltyTypeId>
<CardNo>L4012345</CardNo>
<Expiry />
<Balance />
<CreditStatus />
<Message />
<JoinDate>2014-09-11</JoinDate>
<StatusId />
</Loyalty>
</Loyalties>
</Person>

1.38.5 SUCCESS RESPONSE

HTTP Response
201 Newly created person referenced by the URI returned in the location
header field.

1.38.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text
400 5000 Surname is required
400 5001 Firstname is required
400 5003 Code must be blank to create new person
400 5004 Email is required
400 5005 Billing address is required
400 5006 Email already exists for other person
400 5089 Reference id is invalid
400 5090 Reference id is invalid for the reference type
400 5091 Reference id is required for the reference type id 9999
400 5099 Invalid date format. Valid format is ‘yyyy-MM-dd’
This occurs when Start Date or Date of Birth date formats are incorrect.
400 5111 Invalid privacy flag ‘xxxx’ – must be ‘true’ or ‘false
400 5109 Invalid numeric value: ‘xxx’
400 5101 Loyalty type is empty
400 5106 Invalid loyalty type id: ‘xxxx’
400 5103 Person already has a loyalty card of type: ‘xxxx’
400 5102 Loyal card number ‘xxx’ is being used
400 5104 Loyalty card number ‘xxx’ is invalid. It should start with ‘LM’ OR ‘L1’
400 5105 Loyalty card number is empty
403 5014 Size of field XXXX, 9999 is too long. Maximum length is 9999.
403 5209 A person is already attached to docket Dxxxxxx
403 5210 Docket Number Dxxxxxx is not valid
403 5193 Card name ‘xxxxx’ is invalid
403 5194 Card name is missing
403 5195 Field name ‘xxxxx’ is invalid
403 5196 Field value ‘xxxx’ is invalid for Field: 'XXXXX'

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 79 of 197

 403 5197 Field type is invalid. Field: ‘XXXX’
403 5198 Field length is invalid. Field: 'TextXX'; Field Value: 'xxx'
403 5199 Nonnumeric data found for numeric field. Field: ‘XXX’;Field Value: ‘xxx’
403 5200 Invalid value range. Field: 'NumberXXX'; Field Value: 'number'
403 5201 Invalid date format. Valid format is 'yyyy-MM-dd'. Field: 'DateXXX'; Field
Value: 'dd-mm-yyyy'
403 5202 Invalid reference. Field: XXXX
403 5203 Multiple values not allowed. Field: 'Tag List XXX'
403 5204 Invalid list value. Field: 'Tag List XX' ; List Value: ‘xxx’
403 5205 Record not exist
403 5206 No Person Template Found

1.39 UPDATE EXISTING PERSON

Update details for a Person by submitting a PUT to the following URI.

Note: all person data not supplied in the payload will be cleared off the person account except for Custom
Data which still remains the same.

As person data can be updated in many places of Apparel21 (retail API, POS, Person Maintenance), it is
essential to get the latest person data before posting an update so that no changes are lost. To determine
whether the latest data is being supplied, the “update time stamp” element is used. This supplied
information must match the current status of the person for an update to be successful.

1.39.1 URI REQUEST FORMAT

/Persons/{id}?countryCode={countryCode}

1.39.2 REQUEST PARAMETERS

Field Required Comment

Id Mandatory Person id retrieved from the person GET
CountryCode Mandatory Country Code of Shopper

1.39.3 EXAMPLE REQUEST

PUT https://retailapi.apparel21.com/RetailAPI/Persons/4881?countryCode=AU

Content-type: text/xml
Accept:version_2.0

1.39.4 EXAMPLE PAYLOAD

<Person>
<Title>Mr</Title>
<Firstname>Fred</Firstname>
<Surname>Smith</Surname>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 80 of 197

 <Sex>M</Sex>
<UpdateTimeStamp>11/11/2014 3:54:30 PM</UpdateTimeStamp>
<References>
<Reference>
<ReferenceTypeId>373</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>1781</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>1782</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>1801</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>1501</ReferenceTypeId>
<Id />
</Reference>
<Reference>
<ReferenceTypeId>27</ReferenceTypeId>
<Id />
</Reference>
</References>
<CustomData>
<Cards Type="Array">
<Card Name="Special request">
<Fields Type="Array">
<Field Name="Special request from customer">Prefer to receive a
catalog via post</Field>
</Fields>
</Card>
<Card Name="Marketing information "> <!--This clears out data from card-->
<Fields Type="Array">
<Field Name="SMS "/>
<Field Name="Email"/>
<Field Name="Address"/>
</Fields>
</Card>
</Cards>
</CustomData>
<Addresses>
<Billing>
<ContactName />
<AddressLine1>101 Cremorne St</AddressLine1>
<AddressLine2 />
<City>CREMORNE</City>
<State>VIC</State>
<Postcode>3121</Postcode>
<Country>AUSTRALIA</Country>
</Billing>
</Addresses>
</Person>

1.39.5 SUCCESS RESPONSE

HTTP Response
200

1.39.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text
400 5000 Surname is required
400 5001 Firstname is required

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 81 of 197

 400 5003 Code must be blank to create new person
400 5004 Email is required
400 5005 Billing address is required
400 5006 Email already exists for other person
400 5010 Person has been updated by another user – Update Time Stamp has
changed from date/time to date/time

This occurs if user is updating an existing person but either hasn’t

supplied an “updated time stamp” element or has supplied one that
is out of date.

400 5089 Reference id is invalid

400 5090 Reference id is invalid for the reference type
400 5091 Reference id is required for the reference type id 9999
400 5099 Invalid date format. Valid format is ‘yyyy-MM-dd’
This occurs when Start Date or Date of Birth date formats are
incorrect.
403 5014 Size of field XXXX, 9999 is too long. Maximum length is 9999.
403 5193 Card name ‘xxxxx’ is invalid
403 5194 Card name is missing
403 5195 Field name ‘xxxxx’ is invalid
403 5196 Field value ‘xxxx’ is invalid for Field: 'XXXXX'
403 5197 Field type is invalid. Field: ‘XXXX’
403 5198 Field length is invalid. Field: 'TextXX'; Field Value: 'xxx'
403 5199 Nonnumeric data found for numeric field. Field: ‘XXX’;Field Value:
‘xxx’
403 5200 Invalid value range. Field: 'NumberXXX'; Field Value: 'number'
403 5201 Invalid date format. Valid format is 'yyyy-MM-dd'. Field: 'DateXXX';
Field Value: 'dd-mm-yyyy'
403 5202 Invalid reference. Field: XXXX
403 5203 Multiple values not allowed. Field: 'Tag List XXX'
403 5204 Invalid list value. Field: 'Tag List XX' ; List Value: ‘xxx’
403 5205 Record not exist
403 5206 No Person Template Found

1.40 GET LIST OF CUSTOM DATA TEMPLATES

A new GET endpoint is added to assist web developers for getting the list of custom data templates
available on a web warehouse. Besides, details of a single template can be retrieved by supplying the
template name.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 82 of 197

Field Format Comment Example Single HTTP
template Header
by name
Accept:Versi
on

CustomData List of custom data Yes 2.0

templates

Template Alpha Yes 2.0

Name Alpha Template name Yes 2.0

ImageUrl Alpha A web-based image https://apparel21.com/wp- Yes 2.0

URL content/uploads/2018/07/hero
_p.jpg

Fields Alpha Type="Array" Yes 2.0

Field Alpha Yes 2.0

Label Alpha Label for data field Yes 2.0

Type Alpha Data type of data Text Yes 2.0

field. There are 6
data types available. Memo

Date

Number

Checkbox

TagList

Length Number For Text data type 1000 Yes 2.0

Min Number For Number data 0 Yes 2.0

type

Max Number For Number data 1000 Yes 2.0

type

Alpha For TagList datatype False Yes 2.0

TagListMultiSelect
True

IsAdhocList Alpha For TagList datatype False Yes 2.0

True

Tags Alpha Type="Array" Yes 2.0

Tag Alpha Yes 2.0

Value Alpha For TagList datatype Australia Yes 2.0

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 83 of 197

1.40.1 URI REQUEST FORMAT

/Persons/customdatatemplates?countryCode={countryCode}

1.40.2 REQUEST PARAMETERS

Field Required Comment
CountryCode Mandatory Country Code of Shopper

1.40.3 EXAMPLE REQUEST

GET http://v-devserver2012/intldocretailapi/Persons/customdatatemplates?countryCode=AU

Content-type: text/xml
Accept:version_2.0

1.40.4 EXAMPLE RESPONSE

<CustomData xmlns:xsd="http://www.w3.org/2001/XMLSchema" mlns:xsi="http://www.w3.org/2001/XMLSchema-
instance">
<Template>
<Name>Special request</Name>
<ImageUrl/>
<Fields Type="Array">
<Field>
<Label>Special request from customer</Label>
<Type>Memo</Type>
</Field>
</Fields>
</Template>
<Template>
<Name>Marketing information </Name>
<ImageUrl/>
<Fields Type="Array">
<Field>
<Label>SMS </Label>
<Type>Checkbox</Type>
</Field>
<Field>
<Label>Email</Label>
<Type>Checkbox</Type>
</Field>
<Field>
<Label>ID</Label>
<Type>Number</Type>
<Min>0</Min>
<Max>10000</Max>
</Field>
</Fields>
</Template>
</CustomData>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 84 of 197

1.40.5 SUCCESS RESPONSE
HTTP Response
200

1.40.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text
403 5015 No person template available for the warehouse
403 5206 No person template found

1.41 GET A SINGLE TEMPLATE BY TEMPLATE NAME

1.41.1 URI REQUEST FORMAT

/Persons/customdatatemplates/{template name}?countryCode={countryCode}

1.41.2 REQUEST PARAMETERS

Field Required Comment
Template name Mandatory Name of the custom data template
CountryCode Mandatory Country Code of Shopper

1.41.3 EXAMPLE REQUEST

GET http://v-
devserver2012/intldocretailapi/Persons/customdatatemplates/hobby%20and%20interest?countryCode=A
U

Content-type: text/xml
Accept:version_2.0

1.41.4 EXAMPLE RESPONSE

<CustomData xmlns:xsd=http://www.w3.org/2001/XMLSchema mlns:xsi="http://www.w3.org/2001/XMLSchema-
instance">
<Template>
<Name>hobby and interest</Name>
<ImageUrl/>
<Fields Type="Array">
<Field>
<Label>List of interests</Label>
<Type>TagList</Type>
<TagListMultiSelect>False</TagListMultiSelect>
<IsAdhocList>False</IsAdhocList>
<Tags Type="Array">
<Tag>
<Value>Arts and crafts</Value>
</Tag>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 85 of 197

 <Tag>
<Value>Cooking</Value>
</Tag>
<Tag>
<Value>Gaming</Value>
</Tag>
<Tag>
<Value>Movie</Value>
</Tag>
<Tag>
<Value>Music</Value>
</Tag>
<Tag>
<Value>Sports</Value>
</Tag>
</Tags>
</Field>
</Fields>
</Template>
</CustomData>

1.41.5 SUCCESS RESPONSE

HTTP Response
200

1.41.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text
403 5015 No person template available for the warehouse
403 5206 No person template found

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 86 of 197

13 CARTS

The Shopping Cart is presented to the API to validate the contents and apply latest prices, promotions and
freight as defined in Apparel21.

When you PUT a shopping cart to the API, the prices are checked and tax and any promotional discounts
are calculated. Prices are not checked for products that are Gift Vouchers, the API will accept the price that
is passed with the product.

Freight charges are also added as defined in the Apparel21 back office setup. The returned Cart
information can be used to generate the Order XML payload then call the API to create the actual Order. It
is not mandatory to use to Cart function to generate the order payload.

Note: the contents of a cart are not stored by the API or Apparel21.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 87 of 197

1.42 CART DETAILS

Field Format Max Comment Example PUT PUT HTTP

Length Request Response Header
Accept:V
ersion_
Id Integer 22 Order Id 96854213 Optional As per 1.0
request
OrderNumber Alpha 30 Unique Order Number W0000125 Optional As per 1.0
request
PersonId Integer 22 Unique Person Id 3583 Optional As per 1.0
request
SyncedAt Date(YYYY- 10 Cart synchronisation date 7/07/2011 Optional Yes 1.0
MM-DD) 12:10:57 PM
TotalQuantity Number 22 Total quantity of ordered products 125 Optional Yes 1.0
TotalTax Num(22,2) 22 Tax value calculated by API based on TaxPercent and 10.95 No Yes 1.0
CartDetail.Value)
TotalDiscount Num(22,2) 22 Discount value (Calculated by API base on Sum of 20.16 Optional Yes 1.0
CartDetail.Discount)
TotalDue Num(22,2) 22 Due value (Calculated by API base on Sum of individual product final 2000.25 Optional Yes 1.0
value + freight value)
TotalWeight Num(22,2) 22 Total weight of goods (Calculated by API base on 1000 Optional Yes 1.0
CartDetail.UnitWeight * CartDetail.Quantity)
TaxAdjustment Num(22,2) 22 Tax adjustment value. Product prices are initially shown with the tax 25 No Yes 1.0
rate based on the default Pricing Customer set up in Apparel21. If
the tax rate for the final customer is different to this an adjustment
value will be provided.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 88 of 197

 Field Format Max Comment Example PUT PUT HTTP
Length Request Response Header
Accept:V
ersion_
Addresses There are two addresses as part of the Order resource - Billing and
Delivery. The following field definitions are common for both.
Billing and Delivery are sub-elements of addresses.
AddressLine1 Alpha 50 Address line 1 Level 2 Optional As per 1.0
request
AddressLine2 Alpha 50 Address line 2 21 Cremorne Optional As per 1.0
request
Street
State Alpha 50 State VIC Optional As per 1.0
request
Postcode Alpha 10 Post code or ZIP code 3121 Optional As per 1.0
request
Country Alpha 20 Country Australia Optional As per 1.0
request

Contacts Contacts consists of Email and Phone numbers.

Email Alpha 250 Email address. This is mandatory as it is used to uniquely identify AJIT.CHANDRAN Optional As per 1.0
request
the person. @APPAREL21.C
OM
Phones Phones is a sub element of Contacts
Home Alpha 250 Home phone 03 94275120 Optional As per 1.0
request
Mobile Alpha 250 Mobile Phone 0421 552 654 Optional As per 1.0
request
Work Alpha 250 Work phone 84159300 Optional As per 1.0
request
CartDetails Contains a list of CartDetail
CartDetail CartDetail is a sub-element of CatDetails

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 89 of 197

 Field Format Max Comment Example PUT PUT HTTP
Length Request Response Header
Accept:V
ersion_
Id Integer 22 Number generated by API, position of the CartDetail in the 1 Optional Yes 1.0
CartDetails list, for reference purpose only
Sequence Integer 22 Number generated by API, position of the orderDetail in the 10 Optional As per 1.0
request
OrderDetails list, for reference purpose only
ProductId Integer 22 Unique Product Id 3641 Optional Yes 1.0
ColourId Integer 22 Unique Colourl Id 2566 Optional Yes 1.0
SkuId Integer 22 Unique SKU Id 1234 Yes Yes 1.0
ProductCode Alpha 10 Unique Product Code W00123 Optional Yes 1.0
ProductName Alpha 30 Product Name Long Sleeve Optional Yes 1.0
Shirt
21 Optional
ColourCode Alpha Colour Code BLK Yes 1.0
ColourName Alpha 61 Colour Name Black Optional Yes 1.0
SizeCode Alpha 7 Size Code XL Optional Yes 1.0
Quantity Num(22,2) 22 Quantity of product 100 Yes Yes 1.0
Price Num(22,2) 22 Price of the CartDetail 210 Optional Yes 1.0
Discount Num(22,2) 22 Discount of the CartDetail 50 Optional Yes 1.0
Value Num(22,2) 22 Net Value (Price * Quantity) 160.25 Optional Yes 1.0
UnitWeight Num(22,2) 22 Unit Weight 50.5 Optional Yes 1.0
Discounts Discounts is a sub-element of Cart Detail
Id Integer 22 Number generated by API, position of the Discount in the Discounts 123 Optional As per 1.0
request
list, for reference purpose only
Parentid Integer 22 Parent CartDetail Id 1 Optional As per 1.0
request
DiscountType Alpha 50 API defined Type of Discount ManualDiscount Optional As per 1.0
request

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 90 of 197

 Field Format Max Comment Example PUT PUT HTTP
Length Request Response Header
Accept:V
ersion_
Manual Discount, Promotion Discount, Loyalty Discount or
unknown
DiscountTypeId Integer 22 API defined Discount Type Id 1 Optional As per 1.0
request
1 for ManualDiscount, 2 for PromotionDiscount, 3 for
LoyaltyDiscount
PromoId Integer 22 API defined Promotion Id 1080 (for Buy 2 Optional As per 1.0
request
get 10% off a
TIE)
loyaltyId Integer 22 API defined Loyalty Id 109605 (for Optional As per 1.0
request
Member)
Sequence Integer 22 Number generated by API, position of the Discount in the Discounts 0 Optional As per 1.0
request
list, for reference purpose only
Description Alpha 50 API generated Description of Discount Loyalty discount Optional As per 1.0
request
Member
Percentage Num(22,2) 22 Discount percentage in number 20 Optional As per 1.0
request
Value Num(22,2) 22 Discount Value 10 Optional As per 1.0
request
TaxPercent Num(22,2) 22 Tax percentage in number (12.5 for 12.5%) 12.5 Optional As per 1.0
request
SelectedFreightOption Selected Freight Option
Id Integer 22 Freight Id (Read from Apparel21 system GIT, provided by Apparel21 123 Optional As per 1.0
request
Consultant)
Name Alpha 250 Freight Name Fox Freight Optional As per 1.0
request
Service
Value Num(22,2) 22 Freight Value 156 Optional As per 1.0
request

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 91 of 197

 Field Format Max Comment Example PUT PUT HTTP
Length Request Response Header
Accept:V
ersion_
FreightOptions List of Freight Options available 1.0
Id Integer 22 Freight Id (Read from Apparel21 system GIT) 123 Optional As per 1.0
request
Name Alpha 250 Freight Name Fox Freight Optional As per 1.0
request
Service
Value Num(22,2) 22 Freight Value 156 Optional As pear 1.0
request

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 92 of 197

1.43 SUBMIT CART

The Cart details are submitted by a PUT to the following URI.

1.43.1 URI REQUEST FORMAT

/Carts/{id}?countryCode={countryCode}

1.43.2 REQUEST PARAMETERS

Field Required Comment

Id Mandatory Your Id for the cart
CountryCode Mandatory Country Code of Shopper

1.43.3 EXAMPLE REQUEST

PUT https://retailapi.apparel21.com/RetailAPI/Carts/1234?countryCode=AU

Content-type: text/xml
Accept:version_2.0

1.43.4 REQUEST PAYLOAD

<Cart>
<PersonId>101451<PersonId>
<CartDetails>
<CartDetail>
<Id>829</Id>
<SkuId>21503</SkuId>
<Quantity>2</Quantity>
<Price>69.95/Price>
<Value>139.90</Value>
</CartDetail>
</CartDetails>
</Cart>

1.43.5 SUCCESS RESPONSE

HTTP Response
200

1.43.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text
400 5033 No products in cart
403 5014 Size of field XXXX, 9999 is too long. Maximum length is 9999.

1.43.7 RESPONSE PAYLOAD

<Cart>
<SyncedAt>2012-10-09T12:05:47</SyncedAt>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 93 of 197

 <TotalQuantity>2</TotalQuantity>
<TotalTax>12.72</TotalTax>
<TotalDiscount>0</TotalDiscount>
<TotalDue>139.90</TotalDue>
<TotalWeight>0</TotalWeight>
<CartDetails Type="Array" TotalRows="1">
<CartDetail>
<Id>1</Id>
<ProductId>8843</ProductId>
<ColourId>10702</ColourId>
<SkuId>21503</SkuId>
<ProductCode>00122</ProductCode>
<ProductName>Cotton Drill Overall </ProductName>
<ColourCode>S-331</ColourCode>
<ColourName>S- Safety Orange</ColourName>
<SizeCode>57</SizeCode>
<Quantity>2</Quantity>
<Price>69.95</Price>
<Discount>0</Discount>
<Value>139.90</Value>
<UnitWeight>0</UnitWeight>
<TaxPercent>10</TaxPercent>
</CartDetail>
</CartDetails>
<SelectedFreightOption>
<Id />
<Name />
<Value>0</Value>
</SelectedFreightOption>
<FreightOptions>
<FreightType>
<Id>161</Id>
<Name>Express</Name>
<Value>10</Value>
</FreightType>
<FreightType>
<Id>162</Id>
<Name>Standard</Name>
<Value>10</Value>
</FreightType>
</FreightOptions>
<TaxAdjustment>0</TaxAdjustment>
</Cart>

Tax, discounts and freight charges will be applied to the cart based on the configurations in Apparel21.

If tax is adjusted based on the customer settings in Apparel21, an adjustment to the standard website tax
rate will be displayed here.

The cart update should be performed as products are added, deleted and/or quantities modified or if the
date changes.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 94 of 197

14 ORDERS

To create an order, either use the detail returned from the Cart PUT response, or generate the order detail
independently.

The information at the root level of the Order payload contains detail about the customer (person),
payment information, freight, and contact details. If Person details, i.e. address are changed when the
order is posted, changes will be saved against that order only. The Person master file record is not
modified unless the API receives a PUT to the person record.

The order detail contains product information to SKU level that the customer has ordered including

 Product Code
 Size (if applicable)
 Colour (if applicable)
 Pricing
 Discounts (if applicable)

When the order is created in Apparel21 it is comprised of detail generated from the API and default
information from Apparel21. Order details can also include orders entered directly into Apparel21, not via
the website. This could be in store orders, telephone orders, returns and exchanges.

1.43.8 PRODUCT AND FREIGHT PRICING

The pricing shown on the order for products and freight can be generated from
- the cart PUT response
- generated from the website
- a combination of the above
In some instances the website will need to post pricing it has generated, for example freight rates or a
special charge that does not have the price setup in Apparel21. When these details are added to the create
order payload, they should show the tax rate that applies to the price that has been sent. For example if
the Freight was $10 and no tax applied the tax percentage should be shown as ‘0’.

<OrderDetail>
…….
<Quantity>1</Quantity>
<Price>10</Price>
<Value>10</Value>
<TaxPercent>0</TaxPercent>
…….
</OrderDetail>

1.43.9 PAYMENTS

Apparel21 Retail API requires payment information for all posted orders. Payment totals must match the
posted order total.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 95 of 197

There are three types of payment possible;

1. Credit Card – shopper has paid for the order via website payment gateway (including
PayPal,SecurePay or Afterpay)
2. Direct Debit – shopper will deposit money into back account as a separate process
3. Zip – shopper has paid for the order via website with Zip payment gateway

Note: Direct Debit payment method is NOT available for Click and collect / buy online pick up in store
orders.

Note: POST Orders will be rejected where the payment is not equal to the Price X Quantity and the
<TotalDiscount> or <Discount> elements are incorrect or missing.

1.43.10 GIFT VOUCHERS

Gift voucher sales are processed in the same manner as a standard product sale (using a product id for gift
voucher product). However, there are additional elements available for voucher sales;

- Voucher Type
- Voucher Number (optional – normally not supplied) – used for when third party is selling/activating
a physical gift voucher and number is already known
- Email subject – for emailed gift vouchers
- Personalised message – message for recipient
- Email – address for emailed gift vouchers
- SenderName – friendly name for sender of gift voucher e.g. Mummy – used to print on the
voucher
- ReceiverName – friendly name for receiver of gift voucher e.g. Daddy – used to print on the
voucher

Refer to the Section Gift Vouchers for detail required when selling a gift voucher. If the Gift Voucher does
not have a value in Apparel21 the value of the voucher must be sent by the API.

Gift Voucher type products cannot be ordered for orders that are Click & Collect (i.e. An order where the
PickupStoreId differs from the web.config warehouse).

1.43.11 RETURNS

The API supports entry of a pending return of stock to the warehouse (introduced in version 2.3).

Return quantities are entered as negative quantity and must have a return reason code assigned with
optional text notes.

Valid return reason ids are retrieved as References. To obtain list of return reason ids with their code and
long name, this is retrieved as ReferenceTypeId = 272.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 96 of 197

1.43.12 US EXTENDED TAX – VARIABLE TAX ON TOP OF PRICES

The Apparel21 Retail API will accept Tax Percentages where the Tax will be calculated and added on to the
Product Price. It also supports where price includes tax – see Website tax rates – prices include tax section
for more information.

To use this functionality to add the tax on to the Product Price the <PriceIncludeTax> element in the
<Order> header should be set to false
<Order>
<OrderNumber>POST_Orders310520131110</OrderNumber>
<DeliveryInstructions>Step:POST 'Orders', to create an order with a single product ,
no discounts, no Freight.</DeliveryInstructions>
<PricesIncludeTax>false</PricesIncludeTax>

The Tax Percentage is be sent through on each <Order Detail> using the <TaxPercent> element
<OrderDetail>
<Id>57285</Id>
<Sequence>1</Sequence>
<ProductId>6184</ProductId>
<ColourId>7109</ColourId>
<SkuId>17081</SkuId>
<ProductCode>AUTOITEM1</ProductCode>
<ProductName>Automation - Style Only</ProductName>
<ColourCode>-</ColourCode>
<ColourName>-</ColourName>
<SizeCode>-</SizeCode>
<Quantity>1</Quantity>
<Price>45.90</Price>
<Value>51.64</Value>
<TaxPercent>12.5</TaxPercent>
</OrderDetail>

The <Value> element should equal <Price>+<Price>*<TaxPercent> - if this is not specified the Order will
POST with the correct financials.

The GET Orders will return the <TaxPercent> specified even if it was not used (e.g Australian Store). Do not
pass a tax rate for Non-US Stores to avoid confusion.

1.43.13 WEBSITE TAX RATES – VARIABLE TAXES WITH PRICE INCLUSIVE OF TAX

For some European websites, the collected tax rates might vary depending on the customer’s delivery
address. The prices may continue to be inclusive of tax but the tax proportion varies.

Where the website is calculating the tax rate, it can be passed through to Apparel21 against the order (but
NOT the GET CART call).

The element <UseSubmittedTaxRates>true</UseSubmittedTaxRates> against the order implies that the tax
rates will be coming from detail items. If tax is to be supplied, each item must be posted with a
<TaxPercent> element with the tax rate to be used.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 97 of 197

1.43.14 DISCOUNTS

Discounts can be supplied to the order. There are four types of discounts:

 1 = Discount applied by the website

 2 = Discount from an Apparel21 promotion – using promotion id as supplied when submit cart
 3 = Discount from Apparel21 loyalty calculation – using loyalty id as supplied when submit cart
 4 = Discount from reward redemption – using redemption details as supplied when submit cart

Many manual discounts (type 1) can apply to a single detail. Only one promotion, one loyalty discount and
one reward redemption discount can apply to a single detail line.

When using multiple discounts, they need to be supplied in the sequence of type 1, type 2, type 3 and then
type 4.

Discount values should correspond to currency precision. For example, if the orders is for AUD, discount of
1.99 is acceptable but 1.9999 is not acceptable because AUD supports 2 decimal currency only.

As well as supplying the discount amount, Apparel21 supports update of discount reason and web discount
information.

Discount reason (Reason id) can be supplied for each manual discount. These reasons link to Apparel21
reason codes. The list of reasons can be read by getting Reference type 271 codes.

Alternatively, if the website itself is calculating discount information, this can be passed through to the
order so that the Customer Service team can view the details in the Apparel21 screens when servicing
shopper queries. The following four fields are text fields that have no bearing on the discount calculation
but are used to post web discount information for visibility only.

1. WebDiscount
2. WebPromotion
3. WebCampaign
4. WebCoupon

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 98 of 197

1.44 ORDER DETAILS

Field Format Max Comment Example GET POST Request HTTP

Length Response Header
Accept:
Version_
Id Integer 22 Unique Order Id generated by API 96854213 Yes No 1.0
RowNumber Integer 10 Number generated by API, position of the 10 Yes No 1.0
order in the Order list, for reference
purpose only
OrderNumber Alpha 30 If left blank for a POST request, the API W0000125 Yes Optional 1.0
will generate a unique order number. If
an OrderNumber is entered, this will be
known in Apparel21 as Customer Order
Number

UseSubmittedTaxRate true / false Accepts ‘true’ or ‘false’. If set to ‘true’ the true If supplied Optional 1.0
Tax Percent field MUST be supplied originally
against each item purchased (including
freight and gift vouchers). This model is
for when price is including tax.
PricesIncludeTax true/false - Prices include tax. Needs to be set to False True No No 2.0
for US Extended Tax orders only. If not
supplied, it is assumed that price does
NOT include tax.
PersonId Integer 22 Unique Person Id generated by API 3583 Yes Yes 1.0
WarehouseId Integer 22 Id of the Web Store 4141 Yes No 2.0

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 99 of 197

 Field Format Max Comment Example GET POST Request HTTP
Length Response Header
Accept:
Version_
OrderDateTime Date(YYYY- 10 Order date time. This is the date that the 2011-07-11T00:00:00 Yes Optional 1.0
MM- website delivers, not the Head Office date.
DDTHH:M
M:SS)
TotalQuantity Num(22,2) 22 Total quantity of ordered products 125 Yes No 1.0
TotalTax Num(22,2) 22 Tax value. 10.95 Yes No 1.0
TotalDiscount Num(22,2) 22 Discount value 20.16 Yes No 1.0
TotalDue Num(22,2) 22 Due amount value (Sum of individual 2000.25 Yes No 1.0
product final value + freight value)
TotalPayment Num(22,2) 22 Payment value 2000.25 Yes No 1.0
PickupStoreId Num(22,2) 22 Id of Store the product will be picked up or 4141 Yes Optional 1.0
despatched from – required if Customer is
collecting from a Retail Store as a “Click
and Collect” order. Optional for “Despatch
from Store” orders.

When PickupStore specified and despatch

type is “Despatch From Store” order is
created against specified despatch
location.

DespatchType Alpha 20 Allows values ClickAndCollect, DespatchFromStore Yes Optional 2.0

DespatchFromStore,
DespatchFromWarehouse or Blank.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 100 of 197
 Field Format Max Comment Example GET POST Request HTTP
Length Response Header
Accept:
Version_
DespatchFromWarehouse is the default
value. A blank DespatchType is treated as
a normal warehouse despatch order.

Optional for ClickAndCollect orders.

Required only when eCommerce site is

passing the despatch location to AP21.
Eg: when shopper offered 3 HR delivery
option on website.
ExpectedDeliveryDate Date Can be used to nominate an expected 2019-12-10 Yes Optional 2.0
delivery date for an order. Typically, used
for week day after hours or Saturday
deliveries to let carrier know when the
customer is expecting the delivery.

Must be in yyyy-MM-dd format.

Does NOT support passing a time.

Carrier
Id Number Index of carrier id reference code. Id or 1767 No Optional 2.0
Code can be passed.
Code Alpha 15 Reference code name of Carrier. Id or TNT No Optional 2.0
Code can be passed.
ServiceType

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 101 of 197
 Field Format Max Comment Example GET POST Request HTTP
Length Response Header
Accept:
Version_
Id Number Index of the Service Type reference code. 1780 Yes Optional 2.0
Id or Code can be passed.
Code Alpha 15 Reference code name of Service Type. Id Express Yes Optional 2.0
or Code can be passed.
SLA
Id Number Index of the SLA reference code. Value 16784 Yes Optional 2.0
sent gets ignored when a
<selectedfreight> is passed - SLA tied to
selectedfreight option in GIT is saved
against the web order.

Added in v2018.
Code Alpha 15 Reference code name of SLA. Value sent SameDay Yes Optional 2.0
gets ignored when a <selectedfreight> is
passed - SLA tied to selectedfreight option
in GIT is saved against the web order.

Added in v2018.
DeliveryInstructions Alpha 250 Delivery Instructions Deliver on Monday Yes Optional 1.0
UnattendedDeliveryOpti Alpha 16 Optional. AuthorityToLeave Yes Yes 2.0
on Valid values are ‘AuthorityToLeave’ or
‘None’. If not passed, defaults to ‘None’.
Added in v2018.1.
Addresses Addresses consists of Billing and Delivery
Billing Billing is a sub-element of Addresses

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 102 of 197
 Field Format Max Comment Example GET POST Request HTTP
Length Response Header
Accept:
Version_
AddressLine1 Alpha 50 Address line 1 Level 2 Yes Yes1 1.0
AddressLine2 Alpha 50 Address line 2 21 Cremorne Street Yes Yes1 1.0
City Alpha 50 City Cremorne Yes Yes1 1.0
State Alpha 50 State VIC Yes Yes1 1.0
Postcode Alpha 10 Post code or ZIP code 3121 Yes Yes1 1.0
Country Alpha 20 Country Australia Yes Yes1 1.0
Note 1: At least 1 Billing field must be
completed for a POST
Delivery Delivery is a sub-element of Addresses
ContactName Alpha 100 Contact Name Jane Smith Yes Yes1 Mandatory if sale is 1.0
for Gift Voucher
CompanyName Alpha 50 Company Name against Delivery Address Apparel21 Yes No 1.0
only. Must have head office configuration
to display on reports / labels
AddressLine1 Alpha 50 Address line 1 Level 2 Yes Yes1 1.0
AddressLine2 Alpha 50 Address line 2 21 Cremorne Street Yes Yes1 1.0
City Alpha 50 City Cremorne Yes Yes1 1.0
State Alpha 50 State VIC Yes Yes1 1.0
Postcode Alpha 10 Post code or ZIP code 3121 Yes Yes1 1.0
Country Alpha 20 Country Australia Yes Yes1 1.0
Note 1: At least 1 Delivery field must be
completed for a POST
Contacts Contacts consists of Email and Phone
numbers.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 103 of 197
 Field Format Max Comment Example GET POST Request HTTP
Length Response Header
Accept:
Version_
Email Alpha 250 Email address. This is mandatory as it is ajit.chandran@apparel21. Yes Yes 1.0
used to uniquely identify the person’s com
billing email.

Phones Phones is a sub element of Contacts

Home Alpha 250 Home phone 03 94275120 Yes Optional 1.0
Mobile Alpha 250 Mobile Phone 0421 552 654 Yes Optional 1.0
Work Alpha 250 Work phone 84159300 Yes Optional 1.0
DeliveryContacts DeliveryContacts consists of Email and
Phone numbers.
Email Alpha 250 Delivery email address. This doesn’t need [email protected] No Optional 2.0
to be supplied if it is the same as the
Contact email address. If this is NOT
supplied, the Contact email address will be
used as the delivery reference at POS for
searching for sales or managing freight
bookings.

The Delivery email address is also used for

delivery of purchased gift vouchers if the
Voucher – Email element hasn’t been
supplied at the voucher level.
Phones Phones is a sub element of Delivery
Contacts

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 104 of 197
 Field Format Max Comment Example GET POST Request HTTP
Length Response Header
Accept:
Version_
Home Alpha 250 Home phone 03 94275120 Yes Optional 1.0
Mobile Alpha 250 Mobile Phone 0421 552 654 Yes Optional 1.0
Work Alpha 250 Work phone 84159300 Yes Optional 1.0
GiftId Integer Unique identifier for gift reward 123 Yes No 1.0
OrderDetails Contains a list of OrderDetail.
OrderDetail OrderDetail is a sub-element of
OrderDetails. One per original order,
product, colour, size, status.
Id Integer 22 Unique OrderDetail Id generated by API. 1234 Optional No 1.0
Web orders will contain a value. Any
phone orders or non-web orders included
will be blank. This value is only populated
for web orders.
Sequence Integer 10 Number generated by API, position of the 10 Yes No 1.0
orderDetail in the OrderDetails list, for
reference purpose only
ProductId Integer 22 Unique Product Id 3641 Yes No 1.0
ColourId Integer 22 Unique Colourl Id 2566 Yes No 1.0
SkuId Integer 22 Unique SKU Id 1234 Yes Yes 1.0
ProductCode Alpha 10 Unique Product Code W00123 Yes No 1.0
ProductName Alpha 30 Product Name Long Sleeve Shirt Yes No 1.0
21
ColourCode Alpha Colour Code BLK Yes No 1.0
ColourName Alpha 61 Colour Name Black Yes No 1.0
SizeCode Alpha 7 Size Code XL Yes No 1.0
Quantity Num(22,2) 22 Quantity of product. Negative for returns. 100 Yes Yes 1.0

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 105 of 197
 Field Format Max Comment Example GET POST Request HTTP
Length Response Header
Accept:
Version_
Price Num(22,2) 22 Price of the orderDetail 210 Yes Yes 1.0
Discount Num(22,2) 22 Discount of the orderDetail 50 Yes No 1.0
Value Num(22,2) 22 Net Value 160 Yes Yes 1.0
QuantityTaken Num(22,2) 22 Applies to ‘Click and Collect’ and 1 Yes No 2.0
‘Despatch from Store’ orders only.
For ‘Click and Collect’ orders this is the
Quantity taken (collected) from the Retail
Store.
For ‘Despatch from Store’ orders this is
the Quantity shipped from the Retail
Store.

QuantityPacked Num(22,2) 22 Applies to ‘Click and Collect’ and 2 Yes No 2.0

‘Despatch from Store’ orders only.
Quantity Packed at the retail store – ready
to be collected or despatched.

GiftWrap Alpha 5 Is this item to be gift wrapped? True = True Yes Optional 1.0
Yes, False = No. If not supplied, it is
assumed that the item is NOT to be gift
wrapped.
GiftWrapMessage Alpha 1000 This is the message for gift wrapping. If Happy birthday, Mum. Yes Optional 1.0
this is supplied but GiftWrap field is not, it
will be assumed that the item is to be gift
wrapped.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 106 of 197
 Field Format Max Comment Example GET POST Request HTTP
Length Response Header
Accept:
Version_
SenderName Alpha 50 Friendly name for gift voucher sender. Mummy Yes Optional 1.0
Text that can be picked up on email or
print out of voucher.
ReceiverName Alpha 50 Friendly name for gift voucher receiver. Daddy Yes Optional 1.0
Text that can be picked up on email or
print out of voucher.
ExtraVoucherInform Information for sold Gift Vouchers
ation ExtraVoucherInformation contains
VoucherType, EmailSubject and
PersonalisedMessage and is a sub-
element of OrderDetail
VoucherType Alpha 15 Must be valid Voucher Type Reference Online email No Yes – if Product id is a 2.0
gift voucher
Code from RetVouch in AP21
VoucherNumber Integer 22 Optional field used when a specific gift 123456789 No Optional 2.0
voucher number is sold. If not supplied
(most common), Apparel21 will assign the
next available number.
EmailSubject Alpha 4000 Entered as Subject line of the email or part Happy Birthday! No Optional 2.0
of the letter that accompanies a mail type
voucher
Email Alpha Email address for voucher to be delivered [email protected] No Optional 2.0
to. If not supplied, emailed voucher will om
be sent to DeliveryContacts-Email address.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 107 of 197
 Field Format Max Comment Example GET POST Request HTTP
Length Response Header
Accept:
Version_
PersonalisedMessage Alpha 4000 Body of email that sends the voucher. Can Hope you have a really No Optional 2.0
form part of the letter that accompanies great day on Friday
mail vouchers.
TaxPercent Num(22,2) 22 Tax percentage numeric value (12.5 for 12.5 Yes Only if using Price 1.0
12.5%). excludes tax = true
Must be the value read from the Cart. If or Use submitted
the developer does not use the CART tax rate = true
function to obtain this information, the
correct tax to apply must be entered.
Order creation Total tax calculation will
use this value.

ReturnReasonId Integer 22 Unique Return Reason Id. Get list of valid 45 Yes Yes – mandatory 2.0
reason ID codes using – References for for returns
Reference Type = 272.
ReturnReasonNotes Alpha Text notes Faulty zip Optional Optional 2.0
Carrier Alpha 40 Carrier name against a despatched sale. Toll Ipec Yes No 2.0
This is the carrier that has been used to
deliver the goods. No value if not
“shipped”. Carrier passed in the order
header when creating an order will be
returned.
Note – Only works for Warehouse despatch orders.
Shipment endpoint must be used to retrieve carrier
for Despatch from Store orders.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 108 of 197
 Field Format Max Comment Example GET POST Request HTTP
Length Response Header
Accept:
Version_
CarrierUrl Alpha 150 URL for Carrier’s website. This is set in the https://online.toll.com.au Yes – No 2.0
Apparel21 back office against the carrier /trackandtrace/index.jsp when
code. Useful for track and trace lookup. retrieving
Note – Only works for Warehouse despatch orders. all Orders
Shipment endpoint must be used to retrieve carrier
only
for Despatch from Store orders.
ConNote Alpha 20 Consignment note number against a TL000859 Yes – No 2.0
despatched sale. No value if not when
“shipped”. retrieving
Note – Only works for Warehouse despatch orders. all Orders
Shipment endpoint must be used to retrieve connote
only
for Despatch from Store orders.
Status Alpha 10 The status of the ordered / transaction Shipped Yes No 2.0
quantity.
 Processing = outstanding order
 Shipped = Positive value retail
sale
 Cancelled = ordered line that was
never shipped
 Returned = negative value retail
sale
Zero freight charges on an order that are
not copied to the invoice appear with a
status of “cancelled”.
ServiceType

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 109 of 197
 Field Format Max Comment Example GET POST Request HTTP
Length Response Header
Accept:
Version_
Id Number Index of the Service Type reference code. 162 Yes No 2.0
This returns the id of the service type
passed during an Order Post.
Code Alpha 15 Reference code name of Service Type. This Road Yes No 2.0
returns the code of the service type
passed during an Order Post.
Discounts Contains a list of Discounts and is a sub-
element of OrderDetail.
Non-web orders do not have discount sub
elements.
Discount Discount is a sub-element of Discounts
Id Alpha 22 Discount Id generated by API 1 No No 1.0

ParentId Alpha 22 Parent OrderDetail Id of the Discount 1 No No 1.0

DiscountType Alpha 50 ManualDiscount, PromotionDiscount or ManualDiscount No No 1.0

LoyaltyDiscount
DiscountTypeId Integer 22 1 = manual Discount, 2 = Promotion 2 No Yes 1.0
Discount, 3 = Loyalty Discount, 4 = Reward
Redemption Discount
If using multiple against one product item,
discounts MUST be in order of 1, 2, 3 and
then 4 in the payload.
ReasonId Integer 22 Only relevant for manual discounts. i.e. 1231 No Optional (only for 1.0
Discount Type ID = 1 type 1 discounts)

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 110 of 197
 Field Format Max Comment Example GET POST Request HTTP
Length Response Header
Accept:
Version_
This links to the reason id for the discount.
Look up reason idx using reference type id
271
If not supplied for manual discounts (type
1, the “online” discount reason will be
used.
PromoId Alpha 22 Promotion ID in Apparel21 1010 No Yes (only for type 2 1.0
discounts)
LoyaltyId Alpha 22 Loyalty ID in Apparel21 – RCIDX of loyalty 2020 No Yes (only for type 3 1.0
discounts)
program in table REFCODE (see RGIDX 366
to get list).
Sequence Alpha 22 Default as “0” 0 No No 1.0

Description Alpha 280 Description of the discount Promotion Discount Buy No No 1.0
1 get 1 free
Percentage Num(22,4) 22 Discount percentage for 10% show 10 10 No No 1.0

Value Num(22,2) 22 Value of Discount 9.9 No Yes 1.0

TaxPercent Num(22,2) 22 Tax percentage for 10% show 10 10 No Optional 1.0

WebDiscount Alpha 250 Text from website regarding discount Shop and save No Optional 1.0
reason. Is displayed in Mail Order screen
for the customer service team to see what
discounts where applied.
WebPromotion Alpha 250 Promotion code used in website. This SHOPNSAVE No Optional 1.0
doesn’t link to Apparel21 promotions. This
field is used so that web promotion codes
can be viewed in Mail order screen so that

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 111 of 197
 Field Format Max Comment Example GET POST Request HTTP
Length Response Header
Accept:
Version_
Customer Service team can answer
shopper queries.
WebCampaign Alpha 250 Campaign code used in website. This is for W1231321 No Optional 1.0
information only. It is displayed in
Apparel21 Mail order so that Customer
service can answer shopper queries.
WebCoupon Alpha 250 Coupon code used in website. This is for QUICDISC No Optional 1.0
information only. It is displayed in
Apparel21 Mail order so that Customer
Service can answer shopper queries.
Redemption Redemption is a sub-element of Discount. 1.0

AccountId Number This is the unique identifier of the person 861 No Optional 1.0
reward account.
Amount Number Redeem reward amount when redeeming 10 No Optional (Either 1.0
reward $. Optional. Amount, GiftId or
Request Id must be
passed)
GiftId Integer Unique identifier for gift when redeeming 261 Yes Optional (Either 1.0
gifts. Optional. Amount, GiftId or
Request Id must be
passed)
RequestId Alpha 250 This can be used only when rewards are 6A4CFBB9-094E-422F- No Optional (Either 1.0
redeemed using the Redeem Reward or 8EC6-947946455C0F Amount, GiftId or
Redeem Gift endpoints in an

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 112 of 197
 Field Format Max Comment Example GET POST Request HTTP
Length Response Header
Accept:
Version_
‘unconfirmed’ state. All unconfirmed Request Id must be
rewards get automatically confirmed passed)
when the order successfully posts. Won’t
be reversed if the call fails.

The request id must match the GUID value

that was posted in the redeem reward /
redeem gift calls.

The amount / gift being redeemed must

match the amount / gift that was specified
in the Redeem call. Optional.

SelectedFreightOption Selected Freight option

Blank if non-web order.
Id Number 22 Freight Id. (Read from Apparel21 system 123 Yes Optional 1.0
GIT, provided by Apparel21 Consultant).

Cannot specify freight id for

‘ClickAndCollect’. Allowed only for
despatch type orders.

If an order has to be despatched using a

specific carrier/service type via Temando
(eg: 3HR delivery), the freight option can

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 113 of 197
 Field Format Max Comment Example GET POST Request HTTP
Length Response Header
Accept:
Version_
be configured in the GIT set up and passed
to Apparel21. This requires Apparel21
head office set up to map Apparel21
carrier/service type values accepted by
the Temando system.
Please refer to an Apparel21 consultant
for more information.

Name Alpha 250 Freight Name. Fox Freight Service Yes Optional 1.0

Value Num(22,2) 22 Freight Value. This is freight amount 156 Yes Optional 1.0
including tax.
Cannot specify freight value for
‘ClickAndCollect’.orders. Allowed only for
warehouse or store despatch orders.

TaxPercent Num 22,2 Tax percentage for freight. 13%

Note: It is assumed that freight ‘Value’
passed is inclusive of tax. When extended
tax is used, the tax percentage passed will
be used to calculate the tax amount the
when order is imported into Apparel21.
Payments Contains a list of PaymentDetail
PaymentDetail PaymentDetail is a sub-element of
Payments

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 114 of 197
 Field Format Max Comment Example GET POST Request HTTP
Length Response Header
Accept:
Version_
Id Integer 22 Unique payment id generated 123 Yes No 1.0
automatically by Apparel21.
Sequence Integer 22 Line sequence, default as 0 123 Yes No 1.0

Origin Alpha 50 Origin of payment. CreditCard Yes Yes 1.0

The value entered here MUST be either
“CreditCard”,
“DirectDebit” (only if not pick up in store
or if no payments to be posted), Zip
(required for Zip payments) or
“GiftVoucher”
Other values will be rejected by the API.
For SecurePay, PayPal and AfterPay, this
should be “CreditCard”
For Zip, this should be “Zip”
VoucherNumber Alpha 50 Gift Voucher Number if GV used for 700125 Yes No 2.0
payment
ValidationId Alpha 50 Gift voucher validation id – obtained by cfde12b5-3b5c-4c3d- No Yes – for gift voucher 2.0
payment only
validating voucher before using it to pay a089-aca58a8c44dd
for order.
CardType Alpha 250 Payment Card Type VISA Yes Optional 1.0

Stan Alpha 250 Payment standard reference. This is the 405555 Yes Optional 1.0
value of “txnID” in the Securepay and
PayPal response and is mandatory if
refunds are to be issued against this
payment in Apparel21 Mail order screen.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 115 of 197
 Field Format Max Comment Example GET POST Request HTTP
Length Response Header
Accept:
Version_
This is displayed as EFT Stan in Apparel21
Retail Transactions. This should be the
AfterPay Order ID for AfterPay paments.

Zip-This is value of the “id” in the Zip

response which is the id of purchase
request.This is mandatory if refunds are to
be issued against Zip payment in Apparel21
Mail Order screen.
AuthCode Alpha 250 Payment authorisation code. This is an 512 Yes Optional 1.0
information field and NOT required for
refunds to be processed.
This is displayed as EFT Auth No in
Apparel21 Retail Transactions.
AccountType Alpha 250 Payment account type Credit Yes Optional 1.0

Settlement Alpha 250 Settlement reference 20110625 Yes Optional 1.0

Reference Alpha 250 Payment Reference 13525233_22255 Yes Optional 1.0

SecurePay - this is the value of
“purchaseOrderNo” in the Securepay
response and is mandatory if refunds are
to be issued against this payment.
PayPal – this is the PayPal payment
resource. This is common for all
sales/refunds around a single order.
There needs to be a value in this field for

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 116 of 197
 Field Format Max Comment Example GET POST Request HTTP
Length Response Header
Accept:
Version_
PayPal refunds but the value isn’t used for
anything.
AfterPay – this should be the AfterPay
Merchant Order Id. This is listed as
mandatory for successful refund in store
and at head office, but the actual value is
not used for refunds. This is due to
inconsistency in AfterPay system that may
change in the future. We recommend
putting the AfterPay Merchant Order Id in
this field always, regardless.
Zip- this is the value of the ‘refCode’ that is
in the Zip response. This value is not used
by Zip to process refunds, but it is
mandatory if Zip payments are to be
refunded from Mail Order screen.
Other payment types – can be supplied
This is EFT Ref in Apparel21 Retail
Transactions.
Amount Num(22,2) 22 Payment amount. This must equal the 500.5 Yes Yes 1.0
Order amount when posting a new order.
Negative amounts appearing mean a
credit.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 117 of 197
 Field Format Max Comment Example GET POST Request HTTP
Length Response Header
Accept:
Version_
Message Alpha 4000 Message Purchased on Monday Yes Optional 1.0
with an amount of 100
dollars
VoucherGateway Alpha 15 Reference code name of Gift Voucher Web GV Gateway Yes Optional 2.0
Gateway which is set up in Code
Maintenance.It indicates that the gift
voucher in the payment is issued from a
3rd party (Gift Voucher Gateway). Refer to
Job 115136 for more detail.
MerchantId Alpha 100 Nominate the merchant ID that the Aa7g2BD4hHDDUrhXD8N Yes Optional 1.0
payment was posted against. This is used j0N1UZ41lTVVSHNRpsEm
by Apparel21 to map to the correct bcSpOlSLwGm3UfEGdI0zt
payment gateway for future refunds of
this payment.
Optional for SecurePay payments – if not
supplied, the default SecurePay account
will be used
Mandatory for PayPal payments – this
corresponds to RestAPI PayPal Client ID –
must have MailOrder app created in
PayPal.
Mandatory for AfterPay payments – this
corresponds to the MerchantId set up for
AfterPay.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 118 of 197
 Field Format Max Comment Example GET POST Request HTTP
Length Response Header
Accept:
Version_
Mandatory for Braintree payments – this
corresponds to the Merchant Id set up for
Braintree.
AccountId Alpha 100 Nominate the merchant account ID that AP21_MERCHANT_NZ Yes Optional 1.0
the payment was posted against. This Is
used by Apparel21 to map to the correct
payment gateway for future refunds of
this payment.
Mandatory for Braintree payments - this
corresponds to the Braintree Merchant
Account Id for the relevant currency.
Braintree allows multiple merchant
accounts IDs within a single merchant
account.
Not used for SecurePay, Paypal or
AfterPay payments.
Currency Currency consists of Code and Format.
Code Alpha 50 Currency Code associated with the person AUD Yes No 2.0
Format Alpha 50 Format the currency is displayed in #,##0.00 'Aud' Yes No 2.0
Apparel21
PointsPartner PointsPartner consists of
MembershipNumber
Id Number 30 Apparel21 reference code index value 123 Yes No 2.0
Name Alpha 40 Apparel21 reference code name Quantas Yes No 2.0
MembershipNumber Alpha 100 Third party loyalty card membership 55555565444879 Yes Yes 2.0
number. Value passed is only validated

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 119 of 197
 Field Format Max Comment Example GET POST Request HTTP
Length Response Header
Accept:
Version_
against partner prefix defined in
Apparel21.
It is assumed that the membership
number passed has been pre validated on
the web site.

1.44.1 SUCCESS RESPONSE

HTTP Response
200

1.44.2 ERROR RESPONSE

HTTP Error API Error Code API Error Text
404
403 5082 The store pickup Id is invalid. Store does not exist.
403 5083 Gift vouchers cannot be added to pick up in store orders
403 5092 Invalid order date. Valid format is 'yyyy-MM-dd HH:mm:ss’
403 5014 Size of field XXXX, 9999 is too long. Maximum length is 9999.
403 5128 Voucher 9999 has already been issued
403 5056 The voucher does not exist
403 5071 The voucher number is invalid. For example, if supplied it in invalid format.
403 5127 Voucher 9999 cannot be sold – this is when it is a promotional voucher.
403 5059 The voucher is no longer valid – it belongs to a suspended range of vouchers
403 5130 Membership Number XXXXXX does not match any known points partner
403 5088 Sku value and discount should be negative for return
403 5145 Invalid discount value: -40. Discount sign should be the same as Quantity sign

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 120 of 197
 403 5146 All lines with promotions must have a ’PromoId’ element
403 5150 Unattended delivery option is invalid
403 5186 Tax rate cannot be empty when UseSubmmitedTaxRate is true.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 121 of 197
1.45 RETRIEVE ORDERS FOR A PERSON

To retrieve previously created orders for a person use a GET on the following URI. Only orders created via
the web or Mail Order will be returned. These orders do not include retail sale transactions, Customer
Orders created at a POS store or wholesale orders with the person attached. This endpoint should be used
when the latest status of orders is required as the information is read from the Sales Order tables.

1.45.1 URI REQUEST FORMAT

/Persons/{personId}/Orders/?countryCode={countryCode}&startRow={startRow}&pageRows={pageRows}

1.45.2 REQUEST PARAMETERS

Field Required Comment
PersonId Mandatory Id of the Person the orders are requested for
CountryCode Mandatory Country code of the shopper
StartRow Optional Starting position of orders returned
PageRows Optional Number of order returned

1.45.3 EXAMPLE REQUEST

GET
https://retailapi.apparel21.com/RetailAPI/Persons/4881/Orders/?countryCode=AU&startRow=1&pageRow
s=20

Content-type: text/xml
Accept:version_2.0

1.45.4 EXAMPLE PAYLOAD

<Orders>
<Order>
<Id>20784</Id>
<RowNumber>1</RowNumber>
<OrderNumber>W0000124</OrderNumber>
<PersonId>3583</PersonId>
<OrderDateTime>2011-07-11T00:00:00</OrderDateTime>
<TotalQuantity>2</TotalQuantity>
<TotalTax>16.33</TotalTax>
<TotalDiscount>0</TotalDiscount>
<TotalDue>147</TotalDue>
<TotalPayment>147</TotalPayment>
<DeliveryInstructions>Please leave on front porch. beware of dangerous dog
</DeliveryInstructions>
<UnattendedDeliveryOption>AuthorityToLeave</UnattendedDeliveryOption>
<Addresses>
<Billing>
<AddressLine1>73 Linlithgow Avenue</AddressLine1>
<AddressLine2 />

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 122 of 197
 <City>GREYTHORN</City>
<State>VIC</State>
<Postcode>3152</Postcode>
<Country>AUSTRALIA</Country>
</Billing>
<Delivery>
<CompanyName> Apparel21 <CompanyName>
<AddressLine1>37 Swan Street</AddressLine1>
<AddressLine2 />
<City>GREYTHORN</City>
<State>VIC</State>
<Postcode>3152</Postcode>
<Country>AUSTRALIA</Country>
</Delivery>
</Addresses>
<Contacts>
<Email>[email protected]></Email>
<Phones>
<Home>012351235</Home>
<Mobile>012341234</Mobile>
<Work />
</Phones>
</Contacts>
<OrderDetails Type="Array" TotalRows="2">
<OrderDetail>
<Id>56025</Id>
<Sequence>1</Sequence>
<ProductId>3641</ProductId>
<ColourId>4082</ColourId>
<SkuId>4323</SkuId>
<ProductCode>Beanie</ProductCode>
<ProductName>WInter Beanie</ProductName>
<ColourCode>BLU</ColourCode>
<ColourName>Blue</ColourName>
<SizeCode>1</SizeCode>
<Quantity>1</Quantity>
<Price>147</Price>
<Discount>0</Discount>
<Value>147</Value>
<TaxPercent>12.5</TaxPercent>
<Status>Processing</Status>
<GiftWrap>true</Status>
<GiftWrapMessage>Happy birthday, Mum.</GiftWrapMessage>
<SenderName />
<ReceiverName />
</OrderDetail>
<OrderDetail>
<Id>56026</Id>
<Sequence>2</Sequence>
<ProductId>4222</ProductId>
<ColourId>4742</ColourId>
<SkuId>5482</SkuId>
<ProductCode>FRGHTMO</ProductCode>
<ProductName>Ladies Freight</ProductName>
<ColourCode>-</ColourCode>
<ColourName>-</ColourName>
<SizeCode>-</SizeCode>
<Quantity>1</Quantity>
<Price>0</Price>
<Discount>0</Discount>
<Value>0</Value>
<TaxPercent>11</TaxPercent>
<Carrier/>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 123 of 197
 <CarrierUrl/>
<ConNote/>
<ServiceType>
<Id>162</Id>
<Code>Road</Code>
</ServiceType>

<Status>Processing</Status>
<GiftWrap>false</Status>
<SenderName />
<ReceiverName />
</OrderDetail>
</OrderDetails>
<SelectedFreightOption>
<Id />
<Name />
<Value>0</Value>
</SelectedFreightOption>
<Payments>
<PaymentDetail>
<Id>2791</Id>
<Sequence>0</Sequence>
<Origin>CreditCard</Origin>
<CardType>TEST</CardType>
<Stan>986516</Stan>
<AuthCode />
<AccountType />
<Settlement>20101129</Settlement>
<Reference>Apparel21Dev:100032</Reference>
<MerchantId>JGH123</MerchantId>
<AccountId>AP21_MERCHANT_AU</AccountId>
<Amount>147</Amount>
<Message>payment_statusCURRENTbank_reference986516remote_ip203.36.237.106card_typeTESTpaymen
t_number100032countryAUorder_id77response_amount158.02response_textApproved or completed
successfullyresponse_code00settlement_date20101129actioncomplete_direct_onesummary_code0vendor_nameA
pparel21Devpayment_referenceTEST Payment Only - DO NOT
CHARGEperson_id9585payment_groupNEWcurrencyAUD$controllerorderspayment_date1290986516</Message>
</PaymentDetail>
</Payments>
</Order>
<Order>
<Id>20785</Id>
<RowNumber>2</RowNumber>
<OrderNumber>W0000125</OrderNumber>
<PersonId>3583</PersonId>
<OrderDateTime>2011-07-11T00:00:00</OrderDateTime>
<TotalQuantity>2</TotalQuantity>
<TotalTax>16.33</TotalTax>
<TotalDiscount>0</TotalDiscount>
<TotalDue>147</TotalDue>
<TotalPayment>147</TotalPayment>
<DeliveryInstructions>Please leave on front porch. beware of dangerous
dog.</DeliveryInstructions>
<Addresses>
<Billing>
<AddressLine1>73 Linlithgow Avenue</AddressLine1>
<AddressLine2 />
<City>GREYTHORN</City>
<State>VIC</State>
<Postcode>3152</Postcode>
<Country>AUSTRALIA</Country>
</Billing>
<Delivery>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 124 of 197
 <AddressLine1>37 Swan Street</AddressLine1>
<AddressLine2 />
<City>GREYTHORN</City>
<State>VIC</State>
<Postcode>3152</Postcode>
<Country>AUSTRALIA</Country>
</Delivery>
</Addresses>
<Contacts>
<Email> [email protected]</Email>
<Phones>
<Home>012351235</Home>
<Mobile>012341234</Mobile>
<Work />
</Phones>
</Contacts>
<DeliveryContacts>
<Email> [email protected]</Email>
<Phones>
<Home>012351235</Home>
<Mobile>012341234</Mobile>
<Work />
</Phones>
</DeliveryContacts>
<OrderDetails Type="Array" TotalRows="2">
<OrderDetail>
<Id>56027</Id>
<Sequence>1</Sequence>
<ProductId>3641</ProductId>
<ColourId>4082</ColourId>
<SkuId>4323</SkuId>
<ProductCode>Beanie</ProductCode>
<ProductName>WInter Beanie</ProductName>
<ColourCode>BLU</ColourCode>
<ColourName>Blue</ColourName>
<SizeCode>1</SizeCode>
<Quantity>1</Quantity>
<Price>147</Price>
<Discount>0</Discount>
<Value>147</Value>
<TaxPercent>12.5</TaxPercent>
<Carrier/>
<CarrierUrl/>
<ConNote/>
<SenderName />
<ReceiverName />
<Status>Processing</Status>
</OrderDetail>
<OrderDetail>
<Id>56028</Id>
<Sequence>2</Sequence>
<ProductId>4222</ProductId>
<ColourId>4742</ColourId>
<SkuId>5482</SkuId>
<ProductCode>FRGHTMO</ProductCode>
<ProductName>Ladies Freight</ProductName>
<ColourCode>-</ColourCode>
<ColourName>-</ColourName>
<SizeCode>-</SizeCode>
<Quantity>1</Quantity>
<Price>0</Price>
<Discount>0</Discount>
<Value>0</Value>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 125 of 197
 <TaxPercent>11</TaxPercent>
<Carrier/>
<CarrierUrl/>
<ConNote/>
<SenderName />
<ReceiverName />
<Status>Processing</Status>
</OrderDetail>
</OrderDetails>
<SelectedFreightOption>
<Id />
<Name />
<Value>0</Value>
</SelectedFreightOption>
<Payments>
<PaymentDetail>
<Id>2792</Id>
<Sequence>0</Sequence>
<Origin>CreditCard</Origin>
<CardType>TEST</CardType>
<Stan>986516</Stan>
<AuthCode />
<AccountType />
<Settlement>20101129</Settlement>
<Reference>Apparel21Dev:100032</Reference>
<Amount>147</Amount>
<Message>payment_statusCURRENTbank_reference986516remote_ip203.36.237.106card_typeTESTpaymen
t_number100032countryAUorder_id77response_amount158.02response_textApproved or completed
successfullyresponse_code00settlement_date20101129actioncomplete_direct_onesummary_code0vendor_nameA
pparel21Devpayment_referenceTEST Payment Only - DO NOT
CHARGEperson_id9585payment_groupNEWcurrencyAUD$controllerorderspayment_date1290986516</Message>
</PaymentDetail>
</Payments>
<PointsPartner>
<Id>16044</Id>
<Name>Quantas</Name>
<MembershipNumber>1234999629624</MembershipNumber>
</PointsPartner>
</Order>
</Orders>

1.45.5 EXAMPLE PAYLOAD – SHIP FROM STORE ORDER WHERE DESPATCH LOCATION
DETERMINED OUTSIDE OF APPAREL 2 1
<Order>
<PersonId>1841</PersonId>
<PickupStoreId>8981</PickupStoreId>
<Carrier>
<Id>1156</Id>
<Code/>
</Carrier>
<ServiceType>
<Id>162</Id>
<Code />
</ServiceType>
<SLA>
<Id>16784</Id>
<Code/>
</SLA>
<DespatchType>DespatchFromStore</DespatchType>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 126 of 197
 <ExpectedDeliveryDate>2019-10-13</ExpectedDeliveryDate>
<DeliveryInstructions>Please leave on front porch. Beware of dangerous dog.</DeliveryInstructions>
<UnattendedDeliveryOption>AuthorityToLeave</UnattendedDeliveryOption>
<Addresses>
<Billing>
<AddressLine1>73 Linlithgow Avenue</AddressLine1>
<AddressLine2></AddressLine2>
<City>GREYTHORN</City>
<State>VIC</State>
<Postcode>3152</Postcode>
<Country>AUSTRALIA</Country>
</Billing>

<Delivery>
<AddressLine1>37 Swan Street</AddressLine1>
<AddressLine2></AddressLine2>
<City>GREYTHORN</City>
<State>VIC</State>
<Postcode>3152</Postcode>
<Country>AUSTRALIA</Country>
</Delivery>
</Addresses>
<Contacts>
<Email>[email protected]</Email>
<Phones>
<Home>0399526532</Home>
<Mobile>045231218521</Mobile>
</Phones>
</Contacts>
<DeliveryContacts>
<Email>[email protected]</Email>
<Phones>
<Home>0413837276</Home>
</Phones>
</DeliveryContacts>
<OrderDetails>
<OrderDetail>
<SkuId>12431</SkuId>
<Quantity>1</Quantity>
<Value>150</Value>
<Price>150</Price>
<TaxPercent>0</TaxPercent>
</OrderDetail>
</OrderDetails>
<Payments>
<PaymentDetail>
<Origin>CreditCard</Origin>
<CardType>VISA</CardType>
<Amount>150</Amount>
</PaymentDetail>
</Payments>
<PointsPartner>
<Id>16044</Id>
<Name>Quantas</Name>
<MembershipNumber>1234999629624</MembershipNumber>
</PointsPartner>
</Order>

1.45.6 SUCCESS RESPONSE

HTTP Response

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 127 of 197
 200

1.45.7 ERROR RESPONSE

HTTP Error API Error Code API Error Text
404
400 5034 Invalid pagination parameters

1.46 RETRIEVE SINGLE ORDER FOR A PERSON

This endpoint is used to obtain confirmation that an order has been generated in Apparel21 and to obtain
the (Customer) Order Number if this has not been generated by the website. The information is retrieved
from the temporary websales table, not from the sord table. It should not be used to obtain updated order
status or other detail that has been added in the back office. To obtain the latest order information use the
endpoint that retrieves all orders for a person.

When multiple gift vouchers are purchased, the GET Order endpoint will not list the email addresses
associated with each gift voucher.

1.46.1 URI REQUEST FORMAT

/Persons/{personId}/Orders/{orderId}/?countryCode={countryCode}&startRow={startRow}&pageRows={pa
geRows}

1.46.2 REQUEST PARAMETERS

Field Required Comment

personId Mandatory Id of the Person the orders are requested for
orderId Mandatory Id of the Order to be retrieved
CountryCode Mandatory Country code of the shopper
startRow Optional Starting position of orders returned
pageRows Optional Number of order returned

1.46.3 EXAMPLE REQUEST

GET
https://retailapi.apparel21.com/RetailAPI/Persons/4881/Orders/1740/?countryCode=AU&startRow=1&pag
eRows=20

Content-type: text/xml
Accept:version_2.0

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 128 of 197
1.46.4 EXAMPLE RESPONSE

< Order>
<Id>1740</Id>
<RowNumber>1</RowNumber>
<OrderNumber>W0000202</OrderNumber>
<PersonId>3583</PersonId>
<OrderDateTime>2011-07-26T15:09:19</OrderDateTime>
<TotalQuantity>1</TotalQuantity>
<TotalTax>0</TotalTax>
<TotalDiscount>0</TotalDiscount>
<TotalDue>147</TotalDue>
<TotalPayment>147</TotalPayment>
<DeliveryInstructions>Please leave on front porch. beware of dangerous dog.</DeliveryInstructions>
<UnattendedDeliveryOption>AuthorityToLeave</UnattendedDeliveryOption>
<Addresses>
<Billing>
<AddressLine1>73 Linlithgow Avenue</AddressLine1>
<AddressLine2 />
<City>GREYTHORN</City>
<State>VIC</State>
<Postcode>3152</Postcode>
<Country>AUSTRALIA</Country>
</Billing>
<Delivery>
<AddressLine1>37 Swan Street</AddressLine1>
<AddressLine2 />
<City>GREYTHORN</City>
<State>VIC</State>
<Postcode>3152</Postcode>
<Country>AUSTRALIA</Country>
</Delivery>
</Addresses>
<Contacts>
<Email> [email protected]</Email</Email>
<Phones>
<Home>012351235</Home>
<Mobile>012341234</Mobile>
<Work />
</Phones>
</Contacts>
<DeliveryContacts>
<Email> [email protected]</Email</Email>
<Phones>
<Home>012351235</Home>
<Mobile>012341234</Mobile>
<Work />
</Phones>
</DeliveryContacts>
<OrderDetails Type="Array" TotalRows="1">
<OrderDetail>
<Id>1840</Id>
<Sequence>1</Sequence>
<ProductId>3641</ProductId>
<ColourId>4082</ColourId>
<SkuId>4323</SkuId>
<ProductCode>Beanie</ProductCode>
<ProductName>WInter Beanie</ProductName>
<ColourCode>BLU</ColourCode>
<ColourName>Blue</ColourName>
<SizeCode>1</SizeCode>
<Quantity>1</Quantity>
<Price>147</Price>
<Discount>0</Discount>
<Value>147</Value>
<TaxPercent>0</TaxPercent>
<Carrier/>
<CarrierUrl/>
<ConNote/>
<SenderName/>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 129 of 197
 <ReceiverName/>
<Status>Processing</Status>
<ServiceType>
<Id>162</Id>
<Code>Road</Code>
</ServiceType>
</OrderDetail>
</OrderDetails>
<SelectedFreightOption>
<Id />
<Name />
<Value>0</Value>
</SelectedFreightOption>
<Payments>
<PaymentDetail>
<Id>761</Id>
<Sequence>0</Sequence>
<Origin>CreditCard</Origin>
<CardType>TEST</CardType>
<Stan>986516</Stan>
<AuthCode />
<AccountType />
<Settlement>20101129</Settlement>
<Reference>Apparel21Dev:100032</Reference>
<Amount>147</Amount>
<Message>payment_statusCURRENTbank_reference986516remote_ip203.36.237.106card_typeTESTpayment_
number100032countryAUorder_id77response_amount158.02response_textApproved or completed
successfullyresponse_code00settlement_date20101129actioncomplete_direct_onesummary_code0vendor_nameA
pparel21Devpayment_referenceTEST Payment Only - DO NOT
CHARGEperson_id9585payment_groupNEWcurrencyAUD$controllerorderspayment_date1290986516</Message>
</PaymentDetail>
</Payments>
<PointsPartner>
<Id>16044</Id>
<Name>Quantas</Name>
<MembershipNumber>1234999629624</MembershipNumber>
</PointsPartner>
</Order>

1.46.5 SUCCESS RESPONSE

HTTP Response
200

1.46.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text
404
1.47 CREATE NEW ORDER

Orders are created via a POST request to the following URI. When the 201 response is received the
Location header will provide the URI required to query the new order. This can be used to retrieve the
Customer Order number if it was not provided in the post.

When multiple gift vouchers are purchased, a Delivery Address may be specified in each Order Detail
element, if omitted the gift voucher(s) will be delivered to the Email in Delivery Contact element.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 130 of 197
1.47.1 URI REQUEST FORMAT

/Persons/{personId}/Orders/?countryCode={countryCode}

1.47.2 REQUEST PARAMETERS

Field Required Comment
PersonId Mandatory Id of the Person the orders are requested for
CountryCode Mandatory Country code of the shopper

1.47.3 EXAMPLE REQUEST

POST https://retailapi.apparel21.com/RetailAPI/Persons/101451/Orders/?countryCode=AU

Content-type: text/xml
Accept:version_2.0

1.47.4 EXAMPLE PAYLOAD

<Order>
<OrderNumber>7894567</OrderNumber>
<PersonId>101451</PersonId>
<Addresses>
<Billing>
<AddressLine1>101 Cremorne St</AddressLine1>
</Billing>
<Delivery>
<AddressLine1>37 Swan Street</AddressLine1>
</Delivery>
</Addresses>
<UnattendedDeliveryOption>AuthorityToLeave</UnattendedDeliveryOption>
<Contacts>
<Email>[email protected]</Email>
</Contacts>
<OrderDetails>
<OrderDetail>
<SkuId>21503</SkuId>
<Quantity>1</Quantity>
<Price>59.90</Price>
<Value>59.90</Value>
<TaxPercent>10.00</TaxPercent>
</OrderDetail>
</OrderDetails>
<Payments>
<PaymentDetail>
<Id>7781</Id>
<Origin>CreditCard</Origin>
<CardType>TEST</CardType>
<Stan>986516</Stan>
<AuthCode/>
<AccountType/>
<Settlement>20111129</Settlement>
<Reference>Ref1</Reference>
<Amount>59.90</Amount>
<Message>payment_statusCURRENTbank_ </Message>
</PaymentDetail>
</Payments>
<PointsPartner>
<MembershipNumber>5542645628473</MembershipNumber>
</PointsPartner>
</Order>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 131 of 197
1.47.5 EXAMPLE ORDER DETAIL PAYLOAD FOR GIFT VOUCHER SALE
………….
<Delivery>
<ContactName>Curtis Malasky</ContactName>
<AddressLine1>21 Cremorne St</AddressLine1>
<AddressLine2>Level 2</AddressLine2>
<City>RICHMOND</City>
<State>VIC</State>
<Postcode>3333</Postcode>
<Country>NEW ZEALAND</Country>
</Delivery>
</Addresses>
<DeliveryContacts>
<Email>[email protected]</Email>
</DeliveryContacts>
<Contacts>
<Email>[email protected]</Email>
<Phones>
<Home>0499999999</Home>
<Mobile>0488888888</Mobile>
<Work>0477777777</Work>
</Phones>
</Contacts>
<OrderDetails Type="Array" TotalRows="8">
<OrderDetail>
<Id>1</Id>
<SkuId>6321</SkuId>
<Quantity>1</Quantity>
<Price>105</Price>
<Discount>0</Discount>
<Value>105</Value>
<SenderName>Mummy</SenderName>
<ReceiverName>Daddy</ReceiverName>
<ExtraVoucherInformation>
<VoucherType>GV_API_EMAIL</VoucherType>
<EmailSubject>Gift Voucher for mail 001</EmailSubject>
<PersonalisedMessage>Happy Birthday! Buy yourself something pretty
</PersonalisedMessage>
<Email>[email protected]</Email>
</ExtraVoucherInformation>
<TaxPercent>0</TaxPercent>
</OrderDetail>

1.47.6 EXAMPLE ORDER PAYMENT DETAIL FOR REDEEMING A GIFT VOUCHER

<PaymentDetail>
<Origin>GiftVoucher</Origin>
<VoucherNumber>7060120</VoucherNumber>
<ValidationId>3e5d3a6c-1efc-4e7b-adcf-10761c7fdda2</ValidationId>
<Amount>6.56</Amount>
</PaymentDetail>

1.47.7 RESPONSE HEADER FORMAT

/Persons/{personId}/Orders/{Orderid}/?countryCode={countryCode}

1.47.8 RESPONSE PARAMETERS

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 132 of 197
The Response Header’s transport location provides a URI that can be used to query the order that was
created.
Field Comment
URL URL to be used to query order
personId Id of the Person the order is created for
Orderid Id of the order created
CountryCode Country code of the shopper

1.47.9 EXAMPLE RESPONSE

https://retailapi.apparel21.com/RetailAPI/Persons/9585/Orders/9999?countryCode=AU

1.47.10 SUCCESS RESPONSE

HTTP Response
201

1.47.11 ERROR RESPONSE

HTTP Error API Error Code API Error Text
500
400 5004 Email is required
400 5005 Billing address is required
400 5021 Delivery address is required
400 5025 Person Id in payload mismatch with person id in URI
400 5026 Payment does not match order due value
403 5028 Invalid payment origin
403 5055 The voucher cannot be used online
403 5056 The voucher does not exist
403 5059 The voucher is no longer valid
403 5061 Incorrect ValidationId
403 5062 The voucher has insufficient funds
403 5065 The voucher has expired
403 5066 The voucher must be used in full
403 5067 The voucher has pending payments and cannot be processed
403 5068 The request is not supported on current database
403 5069 The email address is invalid in delivery section
403 5070 Multiple payments with same voucher number
403 5071 The voucher number is invalid
403 5072 Contact name is required
403 5073 In-store voucher cannot be purchased online
403 5074 Invalid voucher type
403 5075 Invalid email subject
403 5076 Voucher type is required
403 5077 The quantity of the gift voucher should be one
403 5082 The store pickup Id is invalid. Store does not exist

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 133 of 197
 403 5083 Gift Vouchers are only allowed on a ‘Despatch from Warehouse’
order
403 5084 Return reason id is missing
403 5085 Return reason id is invalid
403 5086 Return reason id/note not required
403 5087 Returns are only allowed on a ‘Despatch from Warehouse’ order
403 5088 Sku value and discount should be negative for return
403 5094 Order value does not match Sku price
403 5095 Delivery Contacts in payload mismatch with database version. An
email cannot be put on an order detail line with Database version
before 2013.1
403 5100 MerchantId xxxx is invalid” – this means that the merchant ID
supplied in the payload doesn’t match any payment gateways
configured in Apparel21. This is found in Code Maintenance /
SPayGate – Sales Payment Gateway reference.
403 5107 Invalid gift wrap flag ‘true’ – Must be ‘true’ or ‘false’
403 5113 Discount_reason_id not required for loyalty or promotion type
discounts
403 5114 Despatch type xxx is invalid
403 5115 Id xxx is not a valid Carrier/Service Type
403 5116 Code xxx is not a valid Carrier/Service Type
403 5119 Pickup Store Id is required for Click and Collect orders
403 5120 Pickup Store Id is not valid for Despatch from Warehouse orders
403 5123 Selected Freight Option element is not valid for Customer Pickup
403 5014 Size of field XXXX, 9999 is too long. Maximum length is 9999.
403 5129 SKU 99999999 is not valid (only first one will display if multiple
invalid)
403 5130 Membership Number XXXXXX does not match any known points
partner
403 5150 Unattended delivery option is invalid
403 5175 Redemption element missing from Rewards Redemption discount
403 5176 Redemption element must specify one and only one of the following
elements: Amount, GiftId or RequestId
403 5177 Transaction with RequestId '{0}' for AccountId '{1}' does not exist
403 5178 Cannot redeem rewards/gifts for multiple rewards accounts on the
same order
403 5179 Value of Discount does not match Amount in Redemption element
403 5180 Gift can only be redeemed on an OrderDetail with a Quantity of 1
403 5181 Only one rewards redemption discount can exist per OrderDetail
403 5182 Gift redemption must be a 100% discount
403 5183 RequestId '{0}' cannot be used to redeem more than the original
request.
403 5184 The total of all redemption discounts (including gift discounts) using
RequestId '{0}' must be the same as the original request.
403 5189 Invalid expected delivery date. Valid format is 'yyyy-MM-dd'
403 5190 Expected delivery date cannot be passed for 'ClickAndCollect' orders

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 134 of 197
15 RETURNS

The Returns endpoint is used to create a return request. Posting a new return will generate an “exchange
order” transaction in Apparel21 awaiting receipt. This functionality is designed for use to create
transactions in advance of the stock arriving in the warehouse.

All returns are posted against an original web order. This endpoint was introduced in Apparel21 version
2017.2 and at that date was limited to web order returns only and does not allow return of POS sales.

The return posting response includes a URL to look up order status. When GET on this response URL, there
is a <ReturnAuthorisationNumber> element that can be used as the authorisation for this return. This is the
“exchange order” number for Apparel21 processing and represents this specific return.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 135 of 197
1.48 RETURN DETAILS
Field Format Max Comment Example GET Response POST Request HTTP
Length Header
Accept:Ver
sion_
ReturnOrder
Id Integer 22 Unique Order Id generated by API 96854213 Yes No 2.0
OrderNumber Alpha 30 If left blank for a POST request, the API will W0000125-R Yes Optional 2.0
generate a unique order number. If an
OrderNumber is entered, this will be known in
Apparel21 as Customer Order Number

OrigOrderNum Alpha 30 This is the link between the return and the W0000125 Yes Yes 2.0
origianl ecommerce order. This is the website
reference for the order. This is either passed
from the website (common) when the original
roder was created or created automatically by
Apparel21 if not supplied on original order
(rare).
PersonId Integer 22 Apparel21 PersonID (person idx) 3583 Yes Yes 2.0
ReturnAuthorisationNumber Integer 22 Apparel21 generated exchange order number 123456 Yes No 2.0
for the return. This cannot be posted from the
website. GET on the return posted to look up
this number to supplier to the shopper for
using as the reference number for this return.
OrderDetails Contains a list of OrderDetail.
OrderDetail OrderDetail is a sub-element of OrderDetails.
One per original order, product, colour, size,
status.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 136 of 197
 Field Format Max Comment Example GET Response POST Request HTTP
Length Header
Accept:Ver
sion_
SkuId Integer 22 Unique SKU Id being returned – must be on the 1234 Yes Yes 2.0
original order
Quantity Num(22,2) 22 Negative quantity for return quantity. E.g. -2 100 Yes Yes 2.0
to return 2 units of the SKUid
ReturnReasonID Integer 22 Apparel21 return reason index code. Must 10365 Yes Yes 2.0
match codes in reference group 272.
ReturnReasonNotes Alpha 250 Notes on return reason – comment text Didn’t like the fit Yes Optional 2.0
Carrier Alpha 12 Text to indicate carrier that will be used to ship A Post Yes Optional 2.0
the stock back to the warehouse. Is copied to
the Delivery Instructions for the exchange
order that is created.
ConNote Alpha 50 Text to indicate consignment note / tracking ID TA123156421541 Yes Optional 2.0
for the stock shipment back to the warehouse.
Is copied to the Delivery Instructions for the
exchange order that is created.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 137 of 197
1.49 POST A NEW RETURN

1.49.1 URI REQUEST FORMAT

/Persons/{PersonID}/Orders/{OrderID}/Returns?countryCode={countryCode}

1.49.2 REQUEST PARAMETERS

Field Required Comment
PersonId Mandatory Id of the Person the orders are requested for
OrderId Mandatory ID of the original order that the return relates to
CountryCode Mandatory Country code of the shopper

1.49.3 EXAMPLE REQUEST

POST https://retailapi.apparel21.com/RetailAPI/Persons/1241/Orders/12354/Returns?countryCode=AU

Content-type: text/xml
Accept:version_2.0

1.49.4 EXAMPLE PAYLOAD

<ReturnOrder>
<OrderNumber>2017080706R</OrderNumber>
<OrigOrderNum>20170807-06</OrigOrderNum>
<PersonId>1241</PersonId>
<OrderDetails>
<OrderDetail>
<SkuId>1784</SkuId>
<Quantity>-1</Quantity>
<ReturnReasonId>10365</ReturnReasonId>
<Carrier>EMS</Carrier>
<ConNote>ABC1234</ConNote>
</OrderDetail>
</OrderDetails>
</ReturnOrder>

1.49.5 SUCCESS RESPONSE

HTTP Response
201

1.49.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text
500
403 5135 Person ID is missing from the return order
403 5136 Person ID from URL is different to payload
403 5052 The order number already exists
403 5133 Origianl order number 20170804-999 is not valid
403 5138 Origianl Order Number is missing from the payload

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 138 of 197
 403 5139 SKUID 1785 not found on original order
403 5140 Some of the quantities are greater than zero
403 5085 Return reason id 103695 is invalid
403 5142 Carrier name is too long
403 5141 ConNote is too long
403 5143 Some of the quantities are missing or equals to zero

1.50 LOOK AT THE STATUS O F A RETURN

1.50.1 URI REQUEST FORMAT

GET
https://retailapi.apparel21.com/RetailAPI/Persons/1241/Orders/12354/Returns/12345?countryCode=AU

Content-type: text/xml
Accept:version_2.0

1.50.2 REQUEST PARAMETERS

Field Required Comment
PersonId Mandatory Id of the Person the orders are requested for
OrderId Mandatory ID of the original order that the return relates to
ReturnID Mandatory Order ID of the return
CountryCode Mandatory Country code of the shopper

1.50.3 EXAMPLE RESPONSE

<ReturnOrder xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Id>62347</Id>
<RowNumber>0</RowNumber>
<OrderNumber>20170804-01-R</OrderNumber>
<PersonId>1241</PersonId>
<WarehouseId>9441</WarehouseId>
<OrderDateTime>2017-08-04T13:57:43</OrderDateTime>
<TotalQuantity>-4</TotalQuantity>
<TotalTax>0</TotalTax>
<TotalDiscount>0</TotalDiscount>
<TotalDue>-100</TotalDue>
<TotalPayment>0</TotalPayment>
<PickupStoreId />
<DeliveryInstructions />
<DespatchType>DespatchFromWarehouse</DespatchType>
<Addresses />
<Contacts>
<Email />
<Phones>
<Home />
<Mobile />
<Work />
</Phones>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 139 of 197
 </Contacts>
<DeliveryContacts>
<Email />
<Phones>
<Home />
<Mobile />
<Work />
</Phones>
</DeliveryContacts>
<OrderDetails Type="Array" TotalRows="1">
<OrderDetail>
<Id>195132</Id>
<Sequence>1</Sequence>
<ProductId>1101</ProductId>
<ColourId>1322</ColourId>
<SkuId>1784</SkuId>
<ProductCode>SHIRT0001</ProductCode>
<ProductName>DOUBLE PKT SHIRT</ProductName>
<ColourCode>001</ColourCode>
<ColourName>MULTICOLOURED</ColourName>
<SizeCode>8</SizeCode>
<Quantity>-4</Quantity>
<Price>25</Price>
<Discount>0</Discount>
<Value>-100</Value>
<TaxPercent>0</TaxPercent>
<QuantityTaken>0</QuantityTaken>
<QuantityPacked>0</QuantityPacked>
<ReturnReasonId>10365</ReturnReasonId>
<ReturnReasonNotes />
<GiftWrap>false</GiftWrap>
<GiftWrapMessage />
<SenderName />
<ReceiverName />
<Carrier>EMS</Carrier>
<CarrierUrl />
<ConNote>ABC1234</ConNote>
<Status>Processing</Status>
</OrderDetail>
</OrderDetails>
<SelectedFreightOption>
<Id />
<Name />
<Value>0</Value>
<TaxPercent xsi:nil="true" />
</SelectedFreightOption>
<Payments />
<Currency>
<Code />
<Format />
</Currency>
<PricesIncludeTax>false</PricesIncludeTax>
<PointsPartner>
<Id />
<Name />
<MembershipNumber />
</PointsPartner>
<OrigOrderNum>20170804-01</OrigOrderNum>
<ReturnAuthorisationNumber>6026</ReturnAuthorisationNumber>
</ReturnOrder>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 140 of 197
16 SALES HISTORY

It is possible to look up retail history for a shopper; including store sales, head office telephone / mail sales
and web system sales. History is for despatched / picked up sales only, items still on order not visible using
this feature.

The Transaction Header contains information about the type of transaction, when and where it was done,
and what currency was used.

The Transaction Detail contains product information to SKU level that the customer has purchased
including

 Product Code
 Size (if applicable)
 Colour (if applicable)
 Pricing

The Transaction Discount Detail contains discount information, such as the type, reason and amount of
discount applied.

Transactions for a person that are NOT included are:

 Wholesale orders with the person attached

 Debtor sales (these are rare and more wholesale in nature)
 Customer orders (these are treated as a Sale transaction when the order is paid)
 Account payments (this is just a reduction of a customer’s debt incurred in a previous sale)

Where the sale is generated from an order, it can be linked back to the original customer order using the
OrderNumber element. This is the customer order number reference supplied when posting orders,
manually entering orders in store or system generated if not supplied.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 141 of 197
1.51 SALES HISTORY DETAILS

Field Format Max Comment Example GET HTTP

Length Response Header
Accept:
Version_
Transactions Contains a list of transactions
Transaction Transaction is a sub-element of transactions
RowNumber Integer 10 Number generated by API, position of the transaction in the list, for 1 Yes 2.0
reference purpose only
Id Integer 22 Identifier for the transaction from the source table RET_TRANH 13753 Yes 2.0
Number Alpha 30 Unique Transaction Number from the source table RET_TRANH. D55500000135 Yes 2.0
W used for web orders, H used for mail orders, D used for docket
numbers
OrderNumber Alpha 30 Where the sale was created from an order, this is the shopper’s order W00001231 Yes 2.0
number supplied when creating the order. Is same as
<OrderNumber> used when posting order.
Type Alpha 30 The description of the type of transaction, being: Sale Yes 2.0
Sale (includes exchanges and returns, and items paid for on account,
includes gift cards purchased)
Layby
Layby Update
Special Order
Special Order Update
SaleDate Date(YYYY- 10 The date the sale/layby was considered complete. 2011-08-26T00:00:00 Yes 2.0
MM-DD) Includes a fixed time of 00:00:00 which can be ignored.
Reflects the configuration chosen for the system parameter 537
‘Layby/Special Orders Posting Method’ as to whether a cash or

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 142 of 197
 Field Format Max Comment Example GET HTTP
Length Response Header
Accept:
Version_
accrual method is used to account for the transaction. i.e. Sale date is
defined by the customer, but transaction date is a system-generated
date which differs from sale date for laybys and special orders.
StoreCode Integer 3 Retail store code that the transaction is associated with from the 555 Yes 2.0
source table WHSE
StoreName Alpha 30 Retail store name that the transaction is associated with. Melbourne Yes 2.0
Currency Code Alpha 15 The currency code used for the transaction AUD Yes 2.0
Currency Format #,##0.00 The currency format used for the transaction #,##0.00 ‘AUD’ Yes 2.0
Carrier Alpha For eCommerce transactions only, the freight carrier name attached Ipec Yes 2.0
to the sale.
CarrierUrl Alpha For eCommerce transactions only, the website address for the carrier https://online.toll. Yes 2.0
to look up transactions. This is set up in Code Maintenance under the com.au/trackandtrace
/index.jsp
Carrier reference group.
ConNote Alpha For eCommerce transactions only, the consignment note number TN1211213213 Yes 2.0
assigned to the delivery.
ServiceType Alpha For eCommerce transactions that have a consignment note number, Road Yes 2.0
this shows the carrier service type used for the delivery.
Details Contains a list of details of the transaction
Detail Detail is a sub-element of Details
Id Integer 22 Identifier for the transaction details row from the source table 15882 Yes 2.0
RET_TRAND
Sequence Integer 10 Sequence number assigned at POS to indicate the order in which the 0 Yes 2.0
product/discount was selected during the transaction.
ProductCode Alpha 10 Unique Product Code W00123 Yes 2.0
ProductName Alpha 30 Product Name Long Sleeve Shirt Yes 2.0

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 143 of 197
 Field Format Max Comment Example GET HTTP
Length Response Header
Accept:
Version_
ColourCode Alpha 21 Colour Code BLK Yes 2.0
ColourName Alpha 61 Colour Name Black Yes 2.0
SizeCode Alpha 7 Size Code XL Yes 2.0
Quantity Num(22,2) 22 Quantity of product purchased 1 Yes 2.0
Price Num(22,2) 22 Price of the product including GST for a single product, before 29.99 Yes 2.0
discounts applied
Value Num(22,2) 22 Price paid for the quantity purchased including GST and including any 25.99 Yes 2.0
discounts,
TaxPercentage Num(22,2) 22 Tax percentage numeric value (12.5 for 12.5%). 12.5 Yes 2.0
Discounts Contains a list of Discounts
Discount Discount is a sub-element of Discounts
Id Alpha 22 Discount identifier from source table RET_TRAND 15908 Yes 2.0
Sequence Alpha 22 Sequence number assigned at POS to indicate the order in which the 3 Yes 2.0
product/discount was selected during the transaction.
Type Alpha 50 Discount, Promotion or Loyalty Loyalty Yes 2.0
Reason Alpha Description of the reason for the discount. Loyalty Yes 2
For Discount type, this is the description of the discount reason used
For Promotion type, this is the name of the promotion
For Loyalty type, this is the text ‘Loyalty‘ used as the discount type
Amount Num(22,2) 22 Value of Discount 4 Yes 2
Percentage Num(22,2) 22 Discount percentage 15 Yes 2

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 144 of 197
1.52 RETRIEVE SALES HISTORY FOR A PERSON

To retrieve previously created transactions for a person use a GET on the following URI.

1.52.1 URI REQUEST FORMAT

/Persons/{personId}/RetailTransactions/?countryCode={countryCode}&startRow={startRow}&pageRows={p
ageRows}

1.52.2 REQUEST PARAMETERS

Field Required Comment
personId Mandatory Id of the Person the transactions are requested
for
CountryCode Mandatory Country code of the shopper
startRow Optional Starting position of transactions returned
pageRows Optional Number of transactions rows returned
OrderNumber Optional Filter sales for selected Order Number (web
order number)

1.52.3 EXAMPLE REQUEST

GET
https://retailapi.apparel21.com/RetailAPI/Persons/4883/RetailTransactions/?countryCode=AU&&OrderNu
mber= W12345&startRow=1&pageRows=20

Content-type: text/xml
Accept:version_2.0

1.52.4 EXAMPLE PAYLOAD

<Transactions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" Type="Array" TotalRows="15" PageStartRow="0"
PageRows="0">
<Transaction>
<RowNumber>1</RowNumber>
<Id>13748</Id>
<Number>D55500000130</Number>
<OrderNumber>W12345</OrderNumber>
<Type>Sale</Type>
<SaleDate>2011-08-26T00:00:00</SaleDate>
<StoreCode>555</StoreCode>
<StoreName>Curtis 2011.2 POS</StoreName>
<Currency>
<Code>AUD</Code>
<Format>#,##0.00 'AUD'</Format>
</Currency>
<Carrier>Ipec</Carrier>
<CarrierUrl>https://online.toll.com.au/trackandtrace/index.jsp</CarrierUrl>
<ConNote>TND112131231</ConNote>
<ServiceType>Road</ServiceType>
<Details Type="Array" TotalRows="1">
<Detail>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 145 of 197
 <Id>15882</Id>
<Sequence>0</Sequence>
<ProductCode>AUTOITEM1</ProductCode>
<ProductName>Automation - 1 Style</ProductName>
<ColourCode>-</ColourCode>
<ColourName>-</ColourName>
<SizeCode>-</SizeCode>
<Quantity>-1</Quantity>
<Price>45.9</Price>
<Value>-45.9</Value>
<TaxPercentage>12.5</TaxPercentage>
<Discounts Type="Array" TotalRows="0" />
</Detail>
</Details>
</Transaction>
<Transaction>
<RowNumber>2</RowNumber>
<Id>13753</Id>
<Number>D55500000135</Number>
<OrderNumber>W12345</OrderNumber>
<Type>Sale</Type>
<SaleDate>2011-08-26T00:00:00</SaleDate>
<StoreCode>555</StoreCode>
<StoreName>Curtis 2011.2 POS</StoreName>
<Currency>
<Code>AUD</Code>
<Format>#,##0.00 'AUD'</Format>
</Currency>
<Carrier>Ipec</Carrier>
<CarrierUrl>https://online.toll.com.au/trackandtrace/index.jsp</CarrierUrl>
<ConNote>TND112131222</ConNote>
<ServiceType>Road</ServiceType>
<Details Type="Array" TotalRows="5">
<Detail>
<Id>15905</Id>
<Sequence>0</Sequence>
<ProductCode>AUTOITEM2</ProductCode>
<ProductName>Automation - Styles, 1 Size</ProductName>
<ColourCode>CAM1-Beading</ColourCode>
<ColourName>CANVAS 123 123 123 123 123 123 Beading</ColourName>
<SizeCode>-</SizeCode>
<Quantity>1</Quantity>
<Price>29.99</Price>
<Value>25.99</Value>
<TaxPercentage>12.5</TaxPercentage>
<Discounts Type="Array" TotalRows="1">
<Discount>
<Id>15906</Id>
<Sequence>1</Sequence>
<Type>Discount</Type>
<Reason>POS Loyalty 1</Reason>
<Amount>4</Amount>
<Percentage>15</Percentage>
</Discount>
</Discounts>
</Detail>
<Detail>
<Id>15907</Id>
<Sequence>2</Sequence>
<ProductCode>AUTOITEM2</ProductCode>
<ProductName>Automation - Styles, 1 Size</ProductName>
<ColourCode>CAM-Beading</ColourCode>
<ColourName>Camel Beading</ColourName>
<SizeCode>-</SizeCode>
<Quantity>1</Quantity>
<Price>29.99</Price>
<Value>25.99</Value>
<TaxPercentage>12.5</TaxPercentage>
<Discounts Type="Array" TotalRows="1">
<Discount>
<Id>15908</Id>
<Sequence>3</Sequence>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 146 of 197
 <Type>Discount</Type>
<Reason>POS Loyalty 1</Reason>
<Amount>4</Amount>
<Percentage>15</Percentage>
</Discount>
</Discounts>
</Detail>
<Detail>
<Id>15909</Id>
<Sequence>4</Sequence>
<ProductCode>AUTOITEM2</ProductCode>
<ProductName>Automation - Styles, 1 Size</ProductName>
<ColourCode>ATL-Beading</ColourCode>
<ColourName>ATLANTIC Beading</ColourName>
<SizeCode>-</SizeCode>
<Quantity>1</Quantity>
<Price>29.99</Price>
<Value>25.99</Value>
<TaxPercentage>12.5</TaxPercentage>
<Discounts Type="Array" TotalRows="1">
<Discount>
<Id>15910</Id>
<Sequence>5</Sequence>
<Type>Discount</Type>
<Reason>POS Loyalty 1</Reason>
<Amount>4</Amount>
<Percentage>15</Percentage>
</Discount>
</Discounts>
</Detail>
</Details>
</Transaction>
</Transactions>

1.52.5 SUCCESS RESPONSE

HTTP Response
200

1.52.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text
404
400 5034 Invalid pagination parameters

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 147 of 197
17 GIFT VOUCHERS

Gift Vouchers are able to be sold and redeemed though the API. Gift vouchers sold online can be used in
store. Gift vouchers sold in store can be used online (as long as they are “secure” type vouchers with a
PIN).

Note: Exception is gift voucher sales for “Click and Collect” and “Despatch from Store” orders. No online
gift voucher sales can be picked up in store or despatched from store, they must be despatched from
warehouse. The DespatchType element during an order post must be either blank or
‘DespatchFromWarehouse’.

1.53 SELLING GIFT VOUCHERS

Only “secure” gift vouchers can be sold. This means a PIN must be entered when they are redeemed. An
additional field for “Delivery Contact email address” has been added to the Cart and Orders endpoint. This
allows the voucher to be ordered by the shopper but delivered to another person.

Based on the settings in the Apparel21 back office for the Voucher Type, the gift voucher can be either emailed
or posted to the recipient. The ExtraVoucherInformation values able to be posted in the Order may be used
to form part of the letter, voucher or email that is sent to the voucher recipient. The use of this information
will vary between sites. While a basic template will be provided for the voucher and letter formats, an
allowance must be made for the unique configuration that will be required for the documentation.

If using a third party to sell physical gift vouchers, it is possible to nominate a specific voucher number on the
order to ensure that this is the voucher that is activated. This is optional. In the majority of cases, the voucher
number is assigned by Apparel21 once the order is received.

1.54 REDEEMING GIFT VOUCHERS

Any voucher redeemed through the API - promotional or gift - must be a secure voucher type. This means
that a PIN is mandatory.

To redeem a Gift Voucher or Promotional voucher through the API, the voucher must first be validated. A
new endpoint has been provided to request the validation id for voucher redemptions. The request will
include the redemption value and the response will provide an available amount. The validation includes a
check that the voucher is being used in full if it is a “give change” type voucher, the amount field is used for
this validation (and no other validation).

The order POST will return an error if an attempt is made to redeem an amount greater than the available
amount.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 148 of 197
1.55 VOUCHER LOOK UP / VALIDATION DETAILS
Field Format Max Comment Example GET Response GET HTTP
Length (inquiry) Response Header
(valiation) Accept:Ve
rsion_
Voucher
Voucher Number Alpha 50 Number of the gift or promotional voucher 60000226 Yes Yes 2.0
Expiry Date Date/Time 22 Identifier for the transaction from the source table 2017-02- Yes Yes 2.0
RET_TRANH 17T00:00:00
Original Amount Num(22,2) Num(22,2) Original Amount of the voucher 100 Yes Yes 2.0
Used Amount Num(22,2) Num(22,2) Amount of the voucher that has been spent 10.50 Yes Yes 2.0
Available Amount Num(22,2) Num(22,2) The amount that is now available to spend using the 89.50 Yes Yes 2.0
voucher. This value may be affected by expiry date or
write-off rules.
Validation id Alpha 36 Validation Id required when the voucher is redeemed 2f093406- No Yes 2.0
eab4-4ada-
(used as payment on a sale). The id will remain valid bb4b-
until another validation id is requested. aa2786ef2a01

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 149 of 197
1.56 GIFT VOUCHER ENQUIRY

The balance of a voucher can be checked using a GET request to the following URI.

1.56.1 URI REQUEST FORMAT

/Voucher/{voucher number}?pin={pinnumber}&?countryCode={countryCode}

1.56.2 REQUEST PARAMETERS

Field Required Comment
voucher number Mandatory Number of the Gift or Promotional Voucher
pin Mandatory PIN of the Voucher
CountryCode Mandatory Country code of the shopper

1.56.3 EXAMPLE REQUEST

GET https://retailapi.apparel21.com/RetailAPI/Voucher/6000226?pin=1084&countryCode=AU

Content-type: text/xml
Accept:version_2.0

1.56.4 EXAMPLE RESPONSE

</Voucher>
<VoucherNumber>6000226</VoucherNumber>
<ExpiryDate>2017-02-17T00:00:00</ExpiryDate>
<OriginalAmount>100</OriginalAmount>
<UsedAmount>0</UsedAmount>
<AvailableAmount>100</AvailableAmount>
</Voucher>

1.56.5 SUCCESS RESPONSE

HTTP Response
200

1.56.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text
403 5068 The request is not supported on current database
403 5055 The voucher cannot be used online (it is not secure)
403 5056 The voucher does nto exist (it is suspended)
403 5057 The voucher has not been issued
403 5059 The voucher is no longer valid
403 5054 The voucher has already been redeemed
403 5053 The pin is invalid
404

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 150 of 197
1.57 GIFT VOUCHER VALIDATION

The voucher must be validated prior to using the voucher as payment on a sale. The validation is obtained
using a GET request to the following URI.

1.57.1 URI REQUEST FORMAT

/Voucher/GVValid/{voucher number}?pin={pinnumber}&amount={amount}&countryCode={countryCode}

1.57.2 REQUEST PARAMETERS

Field Required Comment
Voucher number Mandatory Number of the gift or promotional Voucher
Pin Mandatory PIN of the voucher
Amount Mandatory Amount of the voucher that will be used – this is only used for checking
that “give change” vouchers will be used in full
CountryCode Mandatory Country code of the shopper

1.57.3 EXAMPLE REQUEST

GET
https://retailapi.apparel21.com/RetailAPI/Voucher/GVValid/500005?pin=5885&amount=75&countryCode=
AU

Content-type: text/xml
Accept:version_2.0

1.57.4 EXAMPLE RESPONSE

<Voucher>
<VoucherNumber>6080044</VoucherNumber>
<ExpiryDate>2017-02-17T00:00:00</ExpiryDate>
<OriginalAmount>100</OriginalAmount>
<UsedAmount>0</UsedAmount>
<AvailableAmount>100</AvailableAmount>
<ValidationId>2f093406-eab4-4ada-bb4b-aa2786ef2a01</ValidationId>
</Voucher>

1.57.5 SUCCESS RESPONSE

HTTP Response
200

1.57.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text
403 5068 The request is not supported on current database

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 151 of 197
 403 5060 Invalid request amount parameters
403 5055 The voucher cannot be used online
403 5056 The voucher does not exist
403 5057 The voucher has not been issued
403 5059 The voucher is no longer valid
403 5054 The voucher has already been redeemed
403 5053 The PIN is invalid
403 5056 The voucher has expired
403 5066 The voucher must be used in full
403 5067 The voucher has pending payments and cannot be processed
404

1.58 GIFT VOUCHER LOCKING (OPTIONAL)

Any businesses not using the POST ORDERS endpoint to post eCommerce orders directly into Apparel21 will
have issues with the use of gift vouchers where the same gift voucher is used twice within the timeframe of
the order being placed and the time of its creation in Apparel21.

To avoid these issues, there is an endpoint that can be used to lock the voucher. This is designed to be
used immediately after the order is posted. A validation id is required to lock the order.

Once a voucher is locked, it cannot be validated for another order.

The lock is released from the voucher when the order is posted into Apparel21 or when the timeframe for
locking expires.

If website needs to unlock a purchase order before expiry time, this can be achieved by posting
LockSeconds of 0 (zero) to release the lock.

1.58.1 URI REQUEST FORMAT

/Voucher/Lock/{voucher number}?ValidationId={validation id}&LockSeconds={number of seconds until lock

expiry}/?countryCode={countryCode}

1.58.2 REQUEST PARAMETERS

Field Required Comment
Voucher number Mandatory Number of the gift or promotional Voucher
ValidationId Mandatory ValidationID
LockSeconds Optional Number of seconds that voucher is to be locked for (if not supplied, lock
is applied for 3600 seconds = 1 hour).

To unlock voucher, post another lock request with lock seconds of zero.

CountryCode Mandatory Country code of the shopper

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 152 of 197
1.58.3 EXAMPLE REQUEST

PUT
https://retailapi.apparel21.com/RetailAPI/Voucher/Lock/500005?validationid=lloiol9987mlk&lockseconds=
900&countryCode=AU

Content-type: text/xml
Accept:version_2.0

1.58.4 SUCCESS RESPONSE

HTTP Response
200

1.58.5 ERROR RESPONSE

HTTP Error API Error Code API Error Text
403 5061 Incorrect validation id

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 153 of 197
18 FREE STOCK

The Free Stock resource retrieves available stock at retail stores (and optionally warehouses if configured at
head office to do so). The ‘available stock’ quantity will be determined by the “POS Free” calculation in
Apparel21. This will enable a shopper to purchase goods online and collect from a store that is convenient
for them.

Only stores or warehouses that have a positive free stock value will be returned.

The Stores resource is used to obtain address and contact details for the store/s. If returning warehouses,
this information cannot be looked up and must be configured in the web system.

95666 Retail API Look up stock by Store

Shopper/ Website Retail API

Shopper Views
Product Information
Product

GET FreeStock

Shopper views Stock

Availability

GET Stores

Shopper makes
purchase decision
Purchase

The product queried can be

 Coloured and sized

 Coloured but not sized
 Not coloured or sized
For each type of product, the request can be made by StyleId, or ClrId or Skuid, which leads to different
output xml documents.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 154 of 197
The data for the FreeStock query is stored in the attributes, not the values assigned to an element. Refer to
the example payloads following.

The root level will be the request index type (StyleId, ClrId or Skuid) unless the style level of the product is
lower than that, in which case the root will be its style level. To illustrate, if the request passes in a ClrId
for a T-shirt that is coloured and sized, you will get an XML tree with clr as root element and skus as
children.

Product attributes
Request Style / Colour / Sized Style / Colour Style
Style Root = style Root = style Root = style
Children = clr / SKU Children = clr
Colour Root = clr Root = clr Root = style
Children = SKU
SKU Root = sku Root = sku Root = style

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 155 of 197
1.59 FREE STOCK DETAILS

Field Attribute Format Max Comment Example GET HTTP Header

Length Response Accept:Versi
on_
Style or Clr or The field name will be the level requested. The level of detail Name=”Jeans &amp; Yes1 2.0
Sku returned will be determined by the product setup and request Sizes"
made. StyleIdx="6186"
Name Alpha 30 Name of the node that was requested Jeans &amp; Sizes
Style,clr or Integer 22 Id of the level requested Styleidx=6186
skuidx
Clr Alpha 82 The Clr name and Clridx Name="APRICOT" Yes2 2.0
ClrIdx="7116"
Name Alpha 60 Name of the colour APRICOT
Clridx Integer 22 Id of the clr 7116
Sku Alpha 29 The Sku name and skuidx Name="2" Yes3 2.0
SkuIdx="13211
Name Alpha 7 Name of the size 2
Skuidx Integer 22 Id of the SKU 13211
Store Store is repeated for each store with free stock.
Store Alpha 30 Name, Storeid and StoreNumber Name="Swanston St Yes 2.0
Shop"
StoreId="7501"
StoreNumber="234"
FreeStock="991"
Name Alpha ? Name of the store Swanston St Shop
StoreId Alpha 22 Store Id 7501 Yes 2.0

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 156 of 197
 Field Attribute Format Max Comment Example GET HTTP Header
Length Response Accept:Versi
on_
StoreNumber Integer 3 Store Number 234 Yes 2.0
FreeStock Integer ?? Free stock quantity – from ‘POS Free’ formula in Apparel21 back 991 Yes 2.0
office
Notes
1 - if Style requested
2 - if Style requested for product that has style / clr / sku
3 – if Style or colour requested

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 157 of 197
1.60 RETRIEVE FREESTOCK DETAILS

To retrieve a list of freestock, use a GET on one of the following URI’s.

1.60.1 URI REQUEST FORMATS

/Freestock/style/{styleid}?countryCode={countryCode}

/Freestock/clr/{clr}?countryCode={countryCode}

/Freestock/sku/{skuid}?countryCode={countryCode}

1.60.2 REQUEST PARAMETERS

Field Required Comment
Style or clr or sku Mandatory One of these values must be entered
Styleid or clrid or skuid Mandatory The id of the primary field
CountryCode Mandatory Country code of the shopper

1.60.3 EXAMPLE REQUEST BY STYLE

GET https://retailapi.apparel21.com/RetailAPI/Freestock/style/1155?countryCode=AU

Content-type: text/xml
Accept:version_2.0

1.60.4 EXAMPLE PAYLOAD – REQUEST BY STYLE

<Style Name="Jeans &amp; Sizes" StyleIdx="6186">
<Clr Name="APRICOT" ClrIdx="7116">
<Sku Name="1" SkuIdx="13210">
<Store Name="Swanston St Shop" StoreId="7501" StoreNumber="234" FreeStock="991" />
<Store Name="George St Store" StoreId="108864" StoreNumber="212" FreeStock="879" />
</Sku>
<Sku Name="2" SkuIdx="13211">
<Store Name="Swanston St Shop" StoreId="7501" StoreNumber="234" FreeStock="999" />
<Store Name="George St Store" StoreId="108864" StoreNumber="212" FreeStock="999" />
</Sku>
<Sku Name="3" SkuIdx="13212">
<Store Name="George St Store" StoreId="108864" StoreNumber="212" FreeStock="980" />
<Store Name="Swanston St Shop" StoreId="7501" StoreNumber="234" FreeStock="999" />
</Sku>
<Sku Name="4" SkuIdx="13213">
<Store Name="Swanston St Shop" StoreId="7501" StoreNumber="234" FreeStock="998" />
<Store Name="George St Store" StoreId="108864" StoreNumber="212" FreeStock="993" />
</Sku>
<Sku Name="5" SkuIdx="13214">
<Store Name="George St Store" StoreId="108864" StoreNumber="212" FreeStock="993" />
<Store Name="Swanston St Shop" StoreId="7501" StoreNumber="234" FreeStock="999" />
</Sku>
</Clr>
<Clr Name="AVOCADO" ClrIdx="7117">

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 158 of 197
 <Sku Name="1" SkuIdx="13224">
<Store Name="Pitt St Store" StoreId="109864" StoreNumber="100" FreeStock="4" />
<Store Name="George St Store" StoreId="108864" StoreNumber="212" FreeStock="996" />
<Store Name="Swanston St Shop" StoreId="7501" StoreNumber="234" FreeStock="996" />
</Sku>
<Sku Name="2" SkuIdx="13225">
<Store Name="George St Store" StoreId="108864" StoreNumber="212" FreeStock="999" />
<Store Name="Swanston St Shop" StoreId="7501" StoreNumber="234" FreeStock="999" />
</Sku>
<Sku Name="3" SkuIdx="13226">
<Store Name="George St Store" StoreId="108864" StoreNumber="212" FreeStock="792" />
<Store Name="Swanston St Shop" StoreId="7501" StoreNumber="234" FreeStock="982" />
</Sku>
<Sku Name="4" SkuIdx="13227">
<Store Name="Swanston St Shop" StoreId="7501" StoreNumber="234" FreeStock="996" />
<Store Name="George St Store" StoreId="108864" StoreNumber="212" FreeStock="987" />
</Sku>
<Sku Name="5" SkuIdx="13228">
<Store Name="Swanston St Shop" StoreId="7501" StoreNumber="234" FreeStock="976" />
<Store Name="George St Store" StoreId="108864" StoreNumber="212" FreeStock="996" />
</Sku>
</Clr>
<Clr Name="BANANA" ClrIdx="7118">
<Sku Name="1" SkuIdx="13238">
<Store Name="George St Store" StoreId="108864" StoreNumber="212" FreeStock="998" />
<Store Name="Swanston St Shop" StoreId="7501" StoreNumber="234" FreeStock="999" />
</Sku>
<Sku Name="2" SkuIdx="13239">
<Store Name="George St Store" StoreId="108864" StoreNumber="212" FreeStock="999" />
<Store Name="Swanston St Shop" StoreId="7501" StoreNumber="234" FreeStock="999" />
</Sku>
<Sku Name="3" SkuIdx="13240">
<Store Name="George St Store" StoreId="108864" StoreNumber="212" FreeStock="998" />
<Store Name="Swanston St Shop" StoreId="7501" StoreNumber="234" FreeStock="999" />
</Sku>
<Sku Name="4" SkuIdx="13241">
<Store Name="George St Store" StoreId="108864" StoreNumber="212" FreeStock="691" />
<Store Name="Swanston St Shop" StoreId="7501" StoreNumber="234" FreeStock="978" />
</Sku>
<Sku Name="5" SkuIdx="13242">
<Store Name="Swanston St Shop" StoreId="7501" StoreNumber="234" FreeStock="999" />
<Store Name="George St Store" StoreId="108864" StoreNumber="212" FreeStock="998" />
</Sku>

1.60.5 EXAMPLE REQUEST BY CLR

GET https://retailapi.apparel21.com/RetailAPI/Freestock/clr/1200?countryCode=AU

Content-type: text/xml
Accept:version_2.0

1.60.6 EXAMPLE PAYLOAD – REQUEST BY CLR

<Clr Name="Jeans &amp; Sizes AVOCADO" ClrIdx="7117">

<Sku Name="1" SkuIdx="13224">
<Store Name="Pitt St Store" StoreId="109864" StoreNumber="100" FreeStock="4" />
<Store Name="George St Store" StoreId="108864" StoreNumber="212" FreeStock="996" />

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 159 of 197
 <Store Name="Swanston St Shop" StoreId="7501" StoreNumber="234" FreeStock="996" />
</Sku>
<Sku Name="2" SkuIdx="13225">
<Store Name="George St Store" StoreId="108864" StoreNumber="212" FreeStock="999" />
<Store Name="Swanston St Shop" StoreId="7501" StoreNumber="234" FreeStock="999" />
</Sku>
<Sku Name="3" SkuIdx="13226">
<Store Name="George St Store" StoreId="108864" StoreNumber="212" FreeStock="792" />
<Store Name="Swanston St Shop" StoreId="7501" StoreNumber="234" FreeStock="982" />
</Sku>
<Sku Name="4" SkuIdx="13227">
<Store Name="Swanston St Shop" StoreId="7501" StoreNumber="234" FreeStock="996" />
<Store Name="George St Store" StoreId="108864" StoreNumber="212" FreeStock="987" />
</Sku>
<Sku Name="5" SkuIdx="13228">
<Store Name="Swanston St Shop" StoreId="7501" StoreNumber="234" FreeStock="976" />
<Store Name="George St Store" StoreId="108864" StoreNumber="212" FreeStock="996" />
</Sku>
</Clr>

1.60.7 EXAMPLE REQUEST BY SKU

GET https://retailapi.apparel21.com/RetailAPI/Freestock/sku/1461?countryCode=AU

Content-type: text/xml
Accept:version_2.0

1.60.8 EXAMPLE PAYLOAD – REQUEST BY SKU

<Sku Name="Jeans &amp; Sizes AVOCADO 1" SkuIdx="13224">
<Store Name="Pitt St Store" StoreId="109864" StoreNumber="100" FreeStock="4" />
<Store Name="George St Store" StoreId="108864" StoreNumber="212" FreeStock="996" />
<Store Name="Swanston St Shop" StoreId="7501" StoreNumber="234" FreeStock="996" />
</Sku>

1.60.9 SUCCESS RESPONSE

HTTP Response
200

1.60.10 ERROR RESPONSE

HTTP Error API Error Code API Error Description
404 5008 No data found
400 5081 Sku index should be an integer
400 5081 Clr index should be an integer
400 5081 Style index should be an integer
400 5081 Store ID should be an integer
400 5080 You don’t have security for the requested store

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 160 of 197
19 STOCK CHANGES

The Stock Changes resource retrieves details of free stock for stores and the web store since a date / time.
This endpoint is designed to get differences only and is not optimised for getting a full stock feed. It is
intended that this be used to pick up recent changes since last feed. For items that have changed, the free
stock value is the NEW available free stock and not the difference between last feed.

Note: Payload response size will vary depending on the changes made between last request so to avoid
large payload responses, it is suggested that requests are either for shorter periods of time OR for a limited
warehouse. i.e. Could do one warehouse / store at a time to limit payload response size.

The available filters for this endpoint are StoreID. To get details of the stores, use the resource Stores.

The response for this endpoint includes SKUID. To get details of the products, use the resource Products.

1.61 STOCK CHANGES DETAILS

Field Attribute Format Comment Example HTTP Header

Accept:Version_
Store One section for each store / 1.0
warehouse
Storeid Integer Id of store / warehouse 8981
LastChanged Date/time Date / time of last update 2018-05-
29T14:202:07.76
SKU One section for each SKU that has
changed for store / warehouse
skuid Integer Identifier of style / colour / size 30823 1.0
freeStock Integer Free Stock value 4

1.62 RETRIEVE STOCK CHANGED DETAILS

To retrieve a list of stock changes, use a GET on the following URI.

1.62.1 URI REQUEST FORMATS

/StockChanged?ChangedSince={date time}&StoreId={storeid}&countryCode={countryCode}

1.62.2 REQUEST PARAMETERS

Field Required Comment
StockChanged Mandatory Date/time to get changes since.
StoreId Optional The id of the warehouse or store. Used to filter
response to a single warehouse / store. If not
supplied, changes for all stores and the web
store stock are returned.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 161 of 197
 CountryCode Mandatory Country code of the shopper

1.62.3 EXAMPLE REQUEST

GET https://retailapi.apparel21.com/RetailAPI/StockChanged?ChangedSince=2018-05-
28T11:00:00&countryCode=AU

Content-type: text/xml
Accept:version_1.0

1.62.4 EXAMPLE PAYLOAD RESPONSE

<stockByStore xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance" changedSince="2018-05-28T11:00:00">
<store storeid="8981" lastChanged="2018-05-29T14:20:07.76">
<sku skuid="34145" freeStock="4" />
<sku skuid="34447" freeStock="-15" />
<sku skuid="31460" freeStock="-1" />
<sku skuid="21804" freeStock="0" />
<sku skuid="33069" freeStock="-1" />
<sku skuid="30823" freeStock="-13" />
</store>
<store storeid="9001" lastChanged="2018-05-29T14:57:39.514">
<sku skuid="19702" freeStock="-207" />
<sku skuid="35723" freeStock="1" />
<sku skuid="35721" freeStock="1" />
<sku skuid="35724" freeStock="1" />
<sku skuid="19701" freeStock="-272" />
<sku skuid="1784" freeStock="-287" />
<sku skuid="35722" freeStock="1" />
</store>
<store storeid="9041" lastChanged="2018-05-29T14:09:06.187">
<sku skuid="31460" freeStock="1" />
<sku skuid="35723" freeStock="1" />
<sku skuid="35721" freeStock="1" />
<sku skuid="35724" freeStock="1" />
<sku skuid="35722" freeStock="1" />
<sku skuid="34447" freeStock="3" />
<sku skuid="33069" freeStock="2" />
</store>
<store storeid="9441" lastChanged="2018-05-29T15:44:18">
<sku skuid="1784" freeStock="1978" />
<sku skuid="30823" freeStock="22" />
<sku skuid="34561" freeStock="38" />
<sku skuid="28811" freeStock="100" />
<sku skuid="19701" freeStock="57" />
<sku skuid="34145" freeStock="36" />
<sku skuid="19702" freeStock="-201" />
<sku skuid="33069" freeStock="25" />
<sku skuid="34447" freeStock="11" />
<sku skuid="31460" freeStock="23" />
<sku skuid="15382" freeStock="-2" />
<sku skuid="12431" freeStock="394" />
<sku skuid="12432" freeStock="24556" />
<sku skuid="21804" freeStock="12" />
</store>
</stockByStore>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 162 of 197
1.62.5 SUCCESS RESPONSE
HTTP Response
200

1.62.6 ERROR RESPONSE

HTTP Error API Error Code API Error Description
400 5147 Warehouse doesn’t exist: {0}
400 5148 No company is attached to widx {0}
400 5147 Invalid ChangedSince value: ‘{0}’. Valid format is ‘yyyy-MM-ddTHH:MM:SS
403 5097 Stock formula not set up

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 163 of 197
20 REWARDS

The API retrieves retail reward / gift information necessary to display shopper reward balance on the
website. At present, a person can only be attached to a single rewards program. Rewards can be $ or gifts.

API includes ability to:

 Retrieve list of rewards programs

 Retrieve account information details including tier information, list of available points and rewards
/ gifts
 Retrieve transaction history of all rewards, gifts and points issued / redeemed to and from an
account
 Add person to a rewards program (create an account)
 Update person’s reward account tier details
 Add new rewards / gifts to a person account
 Add new points to a person account
 Redeem points from a person account
 Redeem rewards / gifts from a person account
 Confirm redemption – allows confirming an unconfirmed request
 Reverse a redemption request – can only be done within 24 hours of request

The reward ‘account’ that a person belongs to can be retrieved using the Persons call.

Sequence of API calls for a reward / gift redemption:

Option 1 - If the website calls the order create call directly (i.e. can handle failure of order call)

 Get Reward Account Details – to look up rewards balance or gifts available

 Post Order – Spread reward $ discount across all order items and pass reward $ redemption as
discount type 4.
When redeeming a gift, post gift SKU as a 100% discounted item (discount type 4).

Option 2 – If using third parties and need to decouple the reward redemption call from the order create
call

 Get Reward Account Details – to look up rewards balance or gifts available

 Redeem Reward or Gift (with autoconfirm = false)
 Post Order – Spread reward $ discount across all items and pass reward redemption discount
(discount type 4) and request id (GUID). When redeeming a gift, post gift SKU as 100%
discounted item (discount type 4). The Post Order call automatically confirms the reward
redemption request.
 Confirm reward redemption request (if want to confirm before post order call).

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 164 of 197
1.63 REWARD PROGRAMS DETAILS

Field Format Max Comment Example GET HTTP Header

Length Response Accept:Version_

RewardPrograms Retrieves a list of all reward programs

Program Program is a sub-element of
RewardPrograms
Id Integer This is the unique identifier of the reward 1 Yes 1.0
program
Name Alpha 250 Name of reward program Apparel21 Rewards Yes 1.0
Description Alpha 250 Description of reward program Apparel21 Rewards Yes 1.0
Program
Tiers Retrieves a list of all tiers of a reward
program
Tier Tier is a sub-element of Tiers. A program has
at least one tier.
Id Integer This is the unique identifier of the tier 1 Yes 1.0
Name Alpha 250 Tier name Bronze Yes 1.0
Description Alpha 250 Tier description Bronze Tier Yes 1.0
Sequence Integer Tier sequence within program. Lower number 1 Yes 1.0
means lower tier.
AccrualSpend Number Spend $ value required to accrue number of 1 Yes 1.0
points.
AccrualPoints Integer Number of points accrued for each $ spend 1 Yes 1.0
eg: Every $1 accrues 1 point

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 165 of 197
 AutoRewardPointThreshold Integer Reward issuing rate i.e. total number of 100 Yes 1.0
points to reach before system automatically
converts total points to issue a reward
Eg: For every 100 points issue $10 reward
AutoRewardValue Number Reward $ amount issued when the points 10 Yes 1.0
threshold is met.
Eg: Every 100 points issue $10 reward
AutoRewardGiftId Number Gift id issued when points threshold is met. 22 Yes 1.0
Eg: March Gift
TierPointBonus Integer Tier starting points bonus accrued when 50 Yes 1.0
moving from a lower tier to a higher tier. Eg:
Tier welcome bonus points
TierRewardBonus Number Tier starting rewards bonus accrued when $20 Yes 1.0
moving from a lower tier to a higher tier.
eg: Sign up $20 reward bonus usable on first
sale
TierGiftBonusId Number Tier starting bonus gift earned when moving 145 Yes 1.0
from a lower tier to a higher tier.
Eg: Welcome to Gold Gift
DefaultPointsExpiry Default points expiry period for new points Yes 1.0
Months Integer Points expiry months 12 Yes 1.0
Days Integer Points expiry days 0 Yes 1.0
DefaultRewardExpiry Default reward expiry period for new rewards Yes 1.0
Months Integer Rewards expiry months 12 Yes 1.0
Days Integer Rewards expiry days 0 Yes 1.0
PreventDemotionPeriod Period a reward account is locked from being Yes 1.0
demoted. Shopper can still achieve a higher
tier but won’t be demoted even if they don’t
maintain spend.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 166 of 197
 Months Integer Number of months demotion is prevented 12 Yes 1.0
Days Integer Number of days demotion is prevented 7 Yes 1.0
QualifySpend Integer Spend to qualify to achieve a tier $300 Yes 1.0
QualifyPeriod Rolling period that Apparel21 uses to sum up 12 Yes 1.0
historical transactions to calculate a person’s
tier.
Months Integer Qualifications spend in months 12 Yes 1.0
Days Integer Qualifications spend in days 14 Yes 1.0
Gifts Retrieves a list of gifts defined for the Yes 1.0
reward program
Gift Gift is a sub-element of Gifts Yes 1.0
Id Integer Unique identifier of the gift. Yes 1.0
Name Alpha 250 Name of gift March gift - Bronze Yes 1.0
Description Alpha 250 Gift description March gift for Bronze Yes 1.0
Tier customers
GiftStyles GiftStyles is a sub-element of Gift Yes 1.0
Style Style is a sub-element of GiftStyles Yes 1.0
Id Integer 22 Unique identifier of the style 123 Yes 1.0
Code Alpha 10 Style code CAND Yes 1.0
Name Alpha 30 Style description Pack of Candles Yes 1.0

1.64 REWARD ACCOUNT DETAILS

Field Format Max Comment Example GET POST PUT HTTP Header
Length Response Response Response Accept:Version_
RewardAccount Retrieve reward account
details

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 167 of 197
Field Format Max Comment Example GET POST PUT HTTP Header
Length Response Response Response Accept:Version_
Id Integer This is the unique 1 Yes No No 1.0
identifier of the person
reward account
ProgramId Integer This is the unique 1 Yes Yes - No 1.0
identifier of the reward Mandatory
program
ProgramName Alpha 250 Name of reward Family & Yes No No 1.0
program Friends
TierId Integer This is the unique 1 Yes Optional – Optional – 1.0
identifier of the tier Must be Tier id to
valid for promot
the account to
program – must be
valid for
the
program
TierName Alpha 250 Tier name Bronze Yes No No 1.0
PersonId Integer Person idx 1841 Yes Yes - Optional – 1.0
Mandatory When
provided,
validates
account id
and person
AvailablePoints Integer Available points balance 353 Yes No No 1.0
(unexpired)
AvailableRewards Number Available rewards $ 30 Yes No No 1.0
balance (unexpired)

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 168 of 197
Field Format Max Comment Example GET POST PUT HTTP Header
Length Response Response Response Accept:Version_
JoinDate Date Date person joined the 2018-01-01 Yes No No 1.0
rewards program YYYY-
MM-DD
TierJoinDate Date Date person achieved a 2018-01-01 Yes No No 1.0
tier YYYY-MM-DD
TierLockedUntilDate Date Next Tier calculation will 2018-01-25 Yes Optional - Optional – 1.0
be done after this date sets to null sets to null
YYYY-MM-DD when not when not
passed passed
PointsToNextReward Integer Points to accrue to next 386 Yes No No 1.0
(Nullable) reward. Can be blank.
SpendToNextReward Number Spend to incur to 86 Yes No No 1.0
(Nullable) achieve next reward.
Can be blank.
NextTierId Integer Will be blank if reward 41 Yes No No 1.0
(Nullable) program has no tiers or
shopper is on last tier.
SpendToNextTier Number Spend to incur to next 386 Yes No No 1.0
(Nullable) tier if shopper belongs to
a tiered rewards
program. Can be blank.
PointsList
Accrual
IssueId Number UniqueIdx of points 42181 Yes No No 1.0
accrual
CreatedDateTime Date Date points accrued 2018-01-15 Yes No No 1.0

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 169 of 197
Field Format Max Comment Example GET POST PUT HTTP Header
Length Response Response Response Accept:Version_
Description Alpha 250 Points accrual reason Social Media Yes No No 1.0
post
Total Integer Total points accrued 100 Yes No No 1.0
Redeemed Integer Number of points that 20 Yes No No 1.0
have already been
redeemed
PendingRedemption Integer Points that have been 10 Yes No No 1.0
redeemed, but are still in
a pending state and can
be reversed
Available Integer Points available balance 70 Yes No No 1.0
ExpiryDate Date Date points expire (can Yes No No 1.0
no longer be drawn
from)
RewardsList 1.0
Reward 1.0
IssueId Number UniqueIdx of issued 164321 Yes No No 1.0
reward
CreatedDateTime Date Date reward issued 1/1/2018 Yes No No 1.0
Description Alpha 250 Reward description Birthday Yes No No 1.0
Total Number Total value of reward $20 Yes No No 1.0
Redeemed Number Reward $ redeemed $5 Yes No No 1.0
PendingRedemption Number Reward value that has $3 Yes No No 1.0
been redeemed, but is
still in a pending state
and can be redeemed

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 170 of 197
Field Format Max Comment Example GET POST PUT HTTP Header
Length Response Response Response Accept:Version_
Available Number Reward $ balance $12 Yes No No 1.0
available to redeem
ExpiryDate Date Date reward expires (can 2019/1/1 Yes No No 1.0
no longer be drawn
from). YYYY-MM-DD
IssueReason Reward issue reason 1.0
Id Number Reference code idx of 17666 Yes Yes (id or No 1.0
issue reason code
required)
Code Alpha 30 Reference code of the Birthday Yes Yes (id or No 1.0
issue reason code
required)
Name Alpha 250 Reference code name of Birthday Yes No No 1.0
the issue reason Reward
GiftList Yes No No 1.0
Gift Yes No No 1.0
IssueId Number UniqueIdx of issued gift 301 Yes No No 1.0
CreateDateTime Date Date/Time gift added to 2018-12- Yes No No 1.0
reward account 05T15:00:19
Description Alpha 250 Gift issue description March Gift Issue Yes No No 1.0
GiftId Integer Unique Gift Id 26 Yes No No 1.0
GiftName Alpha 250 Name of gift March Gift Gift Yes No No 1.0
ExpiryDate Date Gift expiry date YYYY- 2019/1/1 Yes No No 1.0
MM-DD
IssueReason Gift issue reason 1.0

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 171 of 197
Field Format Max Comment Example GET POST PUT HTTP Header
Length Response Response Response Accept:Version_
Id Number Reference code idx of 17668 Yes Yes (id or No 1.0
issue reason code
required)
Code Alpha 30 Reference code of the Gold Tier Gift Yes Yes (id or No 1.0
issue reason code
required)
Name Alpha 250 Reference code name of Gold Tier Gift Yes No No 1.0
the issue reason

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 172 of 197
1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 173 of 197
1.65 REWARD TRANSACTIONS DETAILS

Field Format Max Comment Example HTTP Header

Length Accept:Versio
n_
RewardTransactions 1.0
Transactions 1.0
TransactionDateTime Date Date Time of transaction 2018-08-22T15:19:10 1.0
Description Alpha 250 Description of Birthday Reward 1.0
transaction – For retail
and web orders consists
of transaction type and
store name
Source Alpha 250 Transaction source – eg: Retail API 1.0
Retail, CSV, Websales,
Account Management,
Tier Bonus, Retail API
etc.
Reference Alpha 250 This is the order number D0123455 1.0
for web orders, docket
number for retail sales
or reference given when
adding points/rewards
via CSV or API.
Blank for sign up bonus.
Spend Number Spend contributing to 100 1.0
points accrual. Zero if
directly adding points.
Points Integer Total points adjustment. 50 1.0
Positive if adding points,
negative if redeeming or
negatively accruing
points through returns.
Can be positive or
negative.
RewardAmount Number Total reward 10 1.0
adjustment. Positive if
adding reward, negative
if redeeming reward.
GiftId Integer 1.0
GiftName Alpha 250 1.0
NewGift Alpha 5 True only on transaction true 1.0
gift is issued. False all
other instances.
RedeemedGiftSkuId Number SKUIDX of gift redeemed 1541 1.0

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 174 of 197
 Field Format Max Comment Example HTTP Header
Length Accept:Versio
n_
Confirmed Integer Confirmed flag (0- True 1.0
Unconfirmed, 1-
Confirmed). If
unconfirmed and
REVERSED does not
equal 1, the transaction
is pending and may be
reversed.

1.66 REWARD POST DETAILS

Field Format Comment Example HTTP Header
Accept:Version_
RewardPost
RequestId Alpha(250) Globally unique request 5AFC78B8-A622-438B- 1.0
identifier. Must be a GUID. 9ABE-AE9665827837
Mandatory.
PersonId Number Identity of the person. When 1841 1.0
passed, person and accountId in
request must match.
Amount Integer Must be positve 5 1.0
PointsCost Number Points cost of reward. Must be 50 1.0
zero or positive. Defaults to zero
when not provided.
Description Alpha(250) Reward description. Optional Birthday 1.0
Reference Alpha(250) Reference for reward. Optional. BRT1 1.0
ExpiryDate Date Expiry date in YYYY-MM-DD 2018-09-30 1.0
format. Uses tier diefault ifnot
passed.

1.67 GIFT POST DETAILS

Field Format Comment Example HTTP Header
Accept:Version_
GiftPost
RequestId Alpha(250) Globally unique request 5AFC78B8-A622-438B- 1.0
identifier. Must be a GUID. 9ABE-AE9665827837
Mandatory.
PersonId Number Identity of the person. When 1841 1.0
passed, person and accountId in
request must match.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 175 of 197
Field Format Comment Example HTTP Header
Accept:Version_
GiftId Integer Unique identifier for gift 5 1.0
PointsCost Number Points cost of reward. Must be 50 1.0
zero or positive. Defaults to zero
when not provided.
Description Alpha(250) Reward description. Optional Birthday 1.0
Reference Alpha(250) Reference for reward. Optional. BRT1 1.0
ExpiryDate Date Expiry date in YYYY-MM-DD 2018-09-30 1.0
format. Uses tier diefault if not
passed.

1.68 POINTS POST DETAILS

Field Format Comment Example HTTP Header
Accept:Version_
PointsPost
RequestId Alpha(250) Globally unique request 5AFC78B8-A622-438B- 1.0
identifier. Must be a GUID. 9ABE-AE9665827838
Mandatory.
PersonId Number Identity of the person. Optional. 1841 1.0
When passed, person and
accountId in request must match.
Points Integer Number of points to add. Must 50 1.0
be positive.
Description Alpha(250) Reward description. Optional Birthday 1.0
Reference Alpha(250) Reference for reward. Optional. BRT1 1.0
ExpiryDate Date Expiry date in YYYY-MM-DD 2018-09-30 1.0
format. Uses tier diefault ifnot
passed.
1.69 REWARD REDEEM DETAILS
Field Format Comment Example HTTP Header
Accept:Version_
RewardRedemption
AutoConfirm Alpha True or False. When set to True 1.0
true, confirmed automatically
and cannot be reversed.
RequestId Alpha(250) Globally unique request 5AFC78B8-A622-438B- 1.0
identifier. Must be a GUID. 9ABE-AE9665827838
Mandatory.
PersonId Number Identity of the person. 1841 1.0
Optional. When passed,
person and accountId in
request must match.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 176 of 197
Field Format Comment Example HTTP Header
Accept:Version_
Amount Number Rewards $ to redeem. Must 50 1.0
be positive.
Description Alpha(250) Reward redemption Birthday 1.0
description. Optional.
Reference Alpha(250) Reference for reward BRT1 1.0
redemption. Optional.

1.70 GIFT REDEEM DETAILS

Field Format Comment Example HTTP Header
Accept:Version_
GiftRedemption
AutoConfirm Alpha True or False. When set to True 1.0
true, confirmed automatically
and cannot be reversed.
RequestId Alpha(250) Globally unique request 5AFC78B8-A622-438B- 1.0
identifier. Must be a GUID. 9ABE-AE9665827838
Mandatory.
PersonId Number Identity of the person. 1841 1.0
Optional. When passed,
person and accountId in
request must match.
RedeemedSkuId Number SKUIDX of gift being 6861 1.0
redeemed
GiftId Integer Unique identifier of gift. 50 1.0
Description Alpha(250) Gift redeem description. Birthday 1.0
Optional.
Reference Alpha(250) Reference for gift BRT1 1.0
redemption. Optional.

1.71 POINTS REDEEM DETAILS

Field Format Comment Example HTTP Header
Accept:Version_
PointsRedemption
AutoConfirm Alpha True or False. When set to True 1.0
true, confirmed automatically
and cannot be reversed.
RequestId Alpha(250) Globally unique request 5AFC78B8-A622-438B- 1.0
identifier. Must be a GUID. 9ABE-AE9665827838
Mandatory.
PersonId Number Identity of the person. 1841 1.0
Optional. When passed,

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 177 of 197
Field Format Comment Example HTTP Header
Accept:Version_
person and accountId in
request must match.
Points Integer Number of points to reddem. 50 1.0
Must be positive.
Description Alpha(250) Reward redemption Birthday 1.0
description. Optional.
Reference Alpha(250) Reference for reward BRT1 1.0
redemption. Optional.

1.72 RETRIEVE LIST OF REW ARD PROGRAM DETAILS

This GET request will return a list of all rewards programs available in Apparel21.

1.72.1 URI REQUEST FORMAT

/rewards/programs{/programId}?countryCode={countryCode}

1.72.2 REQUEST PARAMETERS

Field Required Comment
Country Code Mandatory Country Code of shopper
Program Optional Reward Program Id – when not specified, returns all programs

1.72.3 EXAMPLE REQUEST

GET

https://retailapi.apparel21.com/RetailAPI/Rewards/Programs?countryCode=AU

Content-type: text/xml
Accept:version_1.0

1.72.4 EXAMPLE RESPONSE

<RewardPrograms>
<Program>
<Id>1</Id>
<Name>Apparel21 Rewards Program</Name>
<Description>Apparel21 Rewards Program</Description>
<Tiers Type="Array">
<Tier>
<Id>1</Id>
<Name>Bronze</Name>
<Description>Bronze Tier</Description>
<Sequence>1</Sequence>
<AccrualSpend>1</AccrualSpend>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 178 of 197
 <AccrualPoints>1</AccrualPoints>
<AutoRewardPointThreshold>100</AutoRewardPointThreshold>
<AutoRewardValue>10</AutoRewardValue>
<AutoRewardGiftId />
<TierPointsBonus>0</TierPointsBonus>
<TierRewardsBonus>0</TierRewardsBonus>
<TierGiftBonusId />
<DefaultPointsExpiry>
<Months>12</Months>
<Days>0</Days>
</DefaultPointsExpiry>
<DefaultRewardExpiry>
<Months>12</Months>
<Days>0</Days>
</DefaultRewardExpiry>
<PreventDemotionPeriod>
<Months>0</Months>
<Days>0</Days>
</PreventDemotionPeriod>
<QualifySpend>0</QualifySpend>
<QualifyPeriod>
<Months>0</Months>
<Days>0</Days>
</QualifyPeriod>
</Tier>
<Tier>
<Id>2</Id>
<Name>Silver</Name>
<Description>Silver Tier</Description>
<Sequence>2</Sequence>
<AccrualSpend>1</AccrualSpend>
<AccrualPoints>2</AccrualPoints>
<AutoRewardPointThreshold>100</AutoRewardPointThreshold>
<AutoRewardValue>20</AutoRewardValue>
<AutoRewardGiftId />
<TierPointsBonus>0</TierPointsBonus>
<TierRewardsBonus>0</TierRewardsBonus>
<TierGiftBonusId />
<DefaultPointsExpiry>
<Months>12</Months>
<Days>0</Days>
</DefaultPointsExpiry>
<DefaultRewardExpiry>
<Months>12</Months>
<Days>0</Days>
</DefaultRewardExpiry>
<PreventDemotionPeriod>
<Months>12</Months>
<Days>0</Days>
</PreventDemotionPeriod>
<QualifySpend>300</QualifySpend>
<QualifyPeriod>
<Months>12</Months>
<Days>0</Days>
</QualifyPeriod>
</Tier>
<Id>3</Id>
<Name>Gold</Name>
<Description>Gp;d</Description>
<Sequence>3</Sequence>
<AccrualSpend>100</AccrualSpend>
<AccrualPoints>2</AccrualPoints>
<AutoRewardPointThreshold>100</AutoRewardPointThreshold>
<AutoRewardValue>20</AutoRewardValue>
<AutoRewardGiftId>21</AutoRewardGiftId>
<TierPointsBonus>0</TierPointsBonus>
<TierRewardsBonus>0</TierRewardsBonus>
<TierGiftBonusId />
<DefaultPointsExpiry>
<Months>12</Months>
<Days>0</Days>
</DefaultPointsExpiry>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 179 of 197
 <DefaultRewardExpiry>
<Months>12</Months>
<Days>0</Days>
</DefaultRewardExpiry>
<PreventDemotionPeriod>
<Months>12</Months>
<Days>0</Days>
</PreventDemotionPeriod>
<QualifySpend>5000</QualifySpend>
<QualifyPeriod>
<Months>12</Months>
<Days>0</Days>
</QualifyPeriod>
</Tier>
</Tiers>
<Gifts Type="Array">
<Gift>
<Id>2</Id>
<Name>August Gifts</Name>
<Description>August Gifts</Description>
<GiftStyles Type="Array" />
</Gift>
<Gift>
<Id>1</Id>
<Name>March Gifts</Name>
<Description>March Gifts</Description>
<GiftStyles Type="Array">
<Style>
<Id>6861</Id>
<Code>CAP</Code>
<Name>STRAW COWBOY - CAPPICINO</Name>
</Style>
<Style>
<Id>7201</Id>
<Code>Bottles</Code>
<Name>BOTTLE CAP OSFA</Name>
</Style>
</GiftStyles>
</Gift>
</Gifts>
</Program>
<Program>
…….
…..
</Program>
</RewardPrograms>

1.73 RETRIEVE REWARD ACCOUNT DETAILS

This GET request retrieves all account information details including a person’s current tier details, spend to
next reward / tier detaisl and list of available accrued points and issued rewards that are not expired.

1.73.1 URI REQUEST FORMAT

/rewards/accounts/{accountId}?countryCode={countryCode}

1.73.2 REQUEST PARAMETERS

Field Required Comment
Account Id Mandatory Account id of the reward program that the shopper belongs to
Country Code Mandatory Country Code of shopper

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 180 of 197
1.73.3 EXAMPLE REQUEST

GET

https://retailapi.apparel21.com/RetailAPI/Rewards/Accounts/1?countryCode=AU

Content-type: text/xml
Accept:version_1.0

1.73.4 EXAMPLE RESPONSE

<RewardAccount>
<Id>1</Id>
<ProgramId>1</ProgramId>
<ProgramName>Apparel21 Rewards Program</ProgramName>
<TierId>1</TierId>
<TierName>Bronze</TierName>
<PersonId>1841</PersonId>
<TierLockedUntilDate>2019-09-19</TierLockedUntilDate>
<AvailablePoints>100</AvailablePoints>
<AvailableRewards>25</AvailableRewards>
<JoinDate>2018-09-11</JoinDate>
<TierJoinDate>2018-09-19</TierJoinDate>
<PointsToNextReward>86</PointsToNextReward>
<SpendToNextReward>86</SpendToNextReward>
<NextTierId>41</NextTierId>
<SpendToNextTier>386</SpendToNextTier>
<PointsList Type="Array">
<Accrual>
<AccrualId>42181</AccrualId>
<CreatedDateTime>2018-08-22T15:19:10</CreatedDateTime>
<Description>Free Points</Description>
<Total>100</Total>
<Redeemed>0</Redeemed>
<PendingRedemption>0</PendingRedemption>
<Available>100</Available>
<ExpiryDate>2019-08-22</ExpiryDate>
</Accrual>
</PointsList>
<RewardsList Type="Array">
<Reward>
<RewardId>163421</RewardId>
<CreatedDateTime>2018-08-22T15:24:44</CreatedDateTime>
<Description>Birthday Reward</Description>
<Total>25</Total>
<Redeemed>0</Redeemed>
<PendingRedemption>0</PendingRedemption>
<Available>25</Available>
<ExpiryDate>2019-08-22</ExpiryDate>
<IssueReason>
<Id>17665</Id>
<Code>Birthday Reward </Code>
<Name>Birthday Reward </Name>
</IssueReason>
</Reward>
</RewardsList>
<GiftList Type="Array">
<Gift>
<IssueId>301</IssueId>
<CreatedDateTime>2018-12-05T15:00:19</CreatedDateTime>
<Description>Test March Gift</Description>
<GiftId>21</GiftId>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 181 of 197
 <GiftName>March Gift</GiftName>
<Available>true</Available>
<ExpiryDate>2019-12-05</ExpiryDate>
<IssueReason>
<Id>17666</Id>
<Code>Random</Code>
<Name>Random Reward</Name>
</IssueReason>
</Gift>
</GiftList>
</RewardAccount>

1.74 CREATE AN ACCOUNT FOR A PERSON

Do a POST on the below URI to add a person to a rewards program. This creates a reward account for the
person and marks the new account as active. Person Id is an optional element.

If the person was already a member of another reward program, the old account gets deactivated and the
new account is activated intead.

Assigning a person to an existing ‘inactive’ account, reactivates the old reward account.

When a tier is not passed, the person is assigned the default tier.

1.74.1 URI REQUEST FORMAT

/rewards/accounts?countryCode={countryCode}

1.74.2 REQUEST PARAMETERS

Field Required Comment
Country Code Mandatory Country Code of shopper

1.74.3 EXAMPLE REQUEST

POST

https://retailapi.apparel21.com/RetailAPI/Rewards/Accounts?countryCode=AU

Content-type: text/xml
Accept:version_1.0

1.74.4 EXAMPLE PAYLOAD

<RewardAccount>
<ProgramId>21</ProgramId>
<TierId>21</TierId>
<TierLockedUntilDate>2019-08-22</TierLockedUntilDate>
<PersonId>2541</PersonId>
</RewardAccount>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 182 of 197
1.74.5 EXAMPLE RESPONSE

<RewardAccount>
<Id>21</Id>
<ProgramId>21</ProgramId>
<ProgramName>Family and Friends Rewards Program</ProgramName>
<TierId>21</TierId>
<TierName>Bronze</TierName>
<PersonId>2541</PersonId>
<TierLockedUntilDate>2019-08-22</TierLockedUntilDate>
</RewardAccount>

1.75 UPDATE REWARD ACCOUNT TIER DETAILS

Do a PUT on the below URI to update a person’s tier information.

1.75.1 URI REQUEST FORMAT

/rewards/accounts/{accountid}?countryCode={countryCode}

1.75.2 REQUEST PARAMETERS

Field Required Comment
Account Id Mandatory Identity of the shopper reward account
Country Code Mandatory Country Code of shopper

1.75.3 EXAMPLE REQUEST

PUT

https://retailapi.apparel21.com/RetailAPI/Rewards/Accounts?countryCode=AU

Content-type: text/xml
Accept:version_1.0

1.75.4 EXAMPLE PAYLOAD

<RewardAccount>
<TierId>22</TierId>
<TierLockedUntilDate>2019-09-01</TierLockedUntilDate>
<PersonId>2541</PersonId>
</RewardAccount>

1.75.5 EXAMPLE RESPONSE

<RewardAccount>
<Id>21</Id>
<ProgramId>21</ProgramId>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 183 of 197
 <ProgramName>Family and Friends Rewards Program</ProgramName>
<TierId>22</TierId>
<TierName>Silver</TierName>
<PersonId>2541</PersonId>
<TierLockedUntilDate>2019-09-01</TierLockedUntilDate>
</RewardAccount>

1.76 RETRIEVE LIST OF TRANSACTIONS FOR A REWARD ACCOUNT

Do a GET on the below URI to retrieve a history of all points and reward accruals and redemptions.

1.76.1 URI REQUEST FORMAT

/rewards/accounts/{accountId}/transactions?countryCode={countryCode}

1.76.2 REQUEST PARAMETERS

Field Required Comment
Account Id Mandatory Identity of the reward account of shopper
Country Code Mandatory Country Code of shopper
From Date Optional Earliest date to retrieve transaction from yyyy-MM-dd format

1.76.3 EXAMPLE REQUEST

POST

https://retailapi.apparel21.com/RetailAPI/Rewards/Accounts/1/Transactions?countryCode=AU

Content-type: text/xml
Accept:version_1.0

1.76.4 EXAMPLE RESPONSE

<RewardTransaction>
<Transaction>
<TransactionDateTime>2018-08-22T15:19:10</TransactionDateTime>
<Description>Free Points</Description>
<Source>CSV</Source>
<Reference>XYZ1234</Reference>
<Spend>0</Spend>
<Points>100</Points>
<RewardAmount>0</RewardAmount>
<GiftId />
<GiftName />
<NewGift>false</NewGift>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 184 of 197
 <RedeemedGiftSkuId />
<Confirmed>true</Confirmed>
</Transaction>
<Transaction>
<TransactionDateTime>2018-08-22T15:24:44</TransactionDateTime>
<Description>March Gift</Description>
<Source>Account Management</Source>
<Reference />
<Spend>0</Spend>
<Points>0</Points>
<RewardAmount>0</RewardAmount>
<GiftId>21</GiftId>
<GiftName>March Gift</GiftName>
<NewGift>true</NewGift>
<RedeemedGiftSkuId />
<Confirmed>true</Confirmed> </Transaction>
<Transaction>
<TransactionDateTime>2018-12-07T10:05:52</TransactionDateTime>
<Description>Redeem March Reward</Description>
<Source>RetailAPI</Source>
<Reference>Redeen March Reward API</Reference>
<Spend>0</Spend>
<Points>0</Points>
<RewardAmount>0</RewardAmount>
<GiftId>21</GiftId>
<GiftName>March Gift</GiftName>
<NewGift>false</NewGift>
<RedeemedGiftSkuId>15541</RedeemedGiftSkuId>
<Confirmed>true</confirmed>
</Transaction>
</RewardTransactions>

1.77 ADD NEW REWARDS TO AN ACCOUNT

Do a POST on the below URI to issue new rewards to a reward account.

1.77.1 URI REQUEST FORMAT

/rewards/accounts/{accountId}/rewards/?countryCode={countryCode}

1.77.2 REQUEST PARAMETERS

Field Required Comment
Account Id Mandatory Identity of the reward account of shopper
Country Code Mandatory Country Code of shopper

1.77.3 EXAMPLE REQUEST

POST

https://retailapi.apparel21.com/RetailAPI/Rewards/Accounts/1/Rewards/?countryCode=AU

Content-type: text/xml
Accept:version_1.0

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 185 of 197
1.77.4 EXAMPLE PAYLOAD

<RewardPost>
<PersonId>1841</PersonId>
<RequestId>5AFC78B8-A622-438B-9ABE-AE9665827838</RequestId>
<Amount>25</Amount>
<Description>Insta posts</Description>
<Reference>SM1</Reference>
<ExpiryDate>2019-08-30</ExpiryDate>
<IssueReason>
<Id>17666</Id>
</IssueReason>
</RewardPost>

1.78 ADD NEW GIFTS TO AN ACCOUNT

Do a POST on the below URI to issue new gifts to a reward account.

1.78.1 URI REQUEST FORMAT

/rewards/accounts/{accountId}/Gifts/?countryCode={countryCode}

1.78.2 REQUEST PARAMETERS

Field Required Comment
Account Id Mandatory Identity of the reward account of shopper
Country Code Mandatory Country Code of shopper

1.78.3 EXAMPLE REQUEST

POST

https://retailapi.apparel21.com/RetailAPI/Rewards/Accounts/1/Gifts/?countryCode=AU

Content-type: text/xml
Accept: version_1.0

1.78.4 EXAMPLE PAYLOAD

<GiftPost>
<RequestId>63850e00-9ba03-406a-bae8-368e21d74c9g</RequestId>
<PersonId>1841</PersonId>
<GiftId>22</GiftId>
<Description>August Gift Issue API</Description>
<Reference>AUG123</Reference>
<ExpiryDate>2019-08-12</ExpiryDate>
<IssueReason>
<Id>17666</Id>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 186 of 197
 </IssueReason>
</GiftPost>

1.79 ADD NEW POINTS TO AN ACCOUNT

Do a POST on the below URI to accrue points to a person’s reward account.

1.79.1 URI REQUEST FORMAT

/rewards/accounts/{accountId}/points/?countryCode={countryCode}

1.79.2 REQUEST PARAMETERS

Field Required Comment
Account Id Mandatory Identity of the reward account of shopper
Country Code Mandatory Country Code of shopper

1.79.3 EXAMPLE REQUEST

POST

https://retailapi.apparel21.com/RetailAPI/Rewards/Accounts/1/Points?countryCode=AU

Content-type: text/xml
Accept:version_1.0

1.79.4 EXAMPLE PAYLOAD

<PointsPost>
<RequestId>5AFC78B8-A622-438B-9ABE-AE9665827837</RequestId>
<PersonId>1841</PersonId>
<Points>100</Points>
<Description>Social Media Posts</Description>
<Reference>SMP123</Reference>
<ExpiryDate>2019-01-01</ExpiryDate>
</PointsPost>

1.80 REDEEM REWARD

Do a POST on the below URI to redeem a reward from an account.

1.80.1 URI REQUEST FORMAT

/rewards/accounts/{accountId}/rewards/redemptions?countryCode={countryCode}

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 187 of 197
1.80.2 REQUEST PARAMETERS
Field Required Comment
Account Id Mandatory Identity of the reward account of shopper
Country Code Mandatory Country Code of shopper

1.80.3 EXAMPLE REQUEST

POST

https://retailapi.apparel21.com/RetailAPI/Rewards/Accounts/1/Rewards/Redemptions?countryCode=AU

Content-type: text/xml
Accept:version_1.0

1.80.4 EXAMPLE PAYLOAD

<RewardRedemption>
<AutoConfirm>true</AutoConfirm>
<RequestId>5AFC78B8-A622-438B-9ABE-AE9665827837</RequestId>
<PersonId>1841</PersonId>
<Amount>10.50</Amount>
<Description>Redeem reward</Description>
<Reference>RED123</Reference>
</RewardRedemption>

1.81 REDEEM GIFT

Do a POST on the below URI to redeem a gift from an account.

1.81.1 URI REQUEST FORMAT

/rewards/accounts/{accountId}/gifts/redemptions?countryCode={countryCode}

1.81.2 REQUEST PARAMETERS

Field Required Comment
Account Id Mandatory Identity of the reward account of shopper
Country Code Mandatory Country Code of shopper

1.81.3 EXAMPLE REQUEST

POST

https://retailapi.apparel21.com/RetailAPI/Rewards/Accounts/1/Gifts/Redemptions?countryCode=AU

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 188 of 197
 Content-type: text/xml
Accept:version_1.0

1.81.4 EXAMPLE PAYLOAD

<GiftRedemption>
<AutoConfirm>false</AutoConfirm>
<RequestId>5AFC78B8-A622-438C-9ABE-AE9665127819</RequestId>
<PersonId>1841</PersonId>
<GiftId>21</GiftId>
<RedeemedSkuId>15541</RedeemedSkuId>
<Description>Redeem March Reward</Description>
<Reference>Redeen March Reward API</Reference>
</GiftRedemption>

1.82 REDEEM POINTS

Do a POST on the below URI to redeem a points from an account.

1.82.1 URI REQUEST FORMAT

/rewards/accounts/{accountId}/points/redemptions?countryCode={countryCode}

1.82.2 REQUEST PARAMETERS

Field Required Comment
Account Id Mandatory Identity of the reward account of shopper
Country Code Mandatory Country Code of shopper

1.82.3 EXAMPLE REQUEST

POST

https://retailapi.apparel21.com/RetailAPI/Rewards/Accounts/1/Points/Redemptions?countryCode=AU

Content-type: text/xml
Accept:version_1.0

1.82.4 EXAMPLE PAYLOAD

<PointsRedemption>
<AutoConfirm>true</AutoConfirm>
<RequestId>5AFC78B8-A622-438B-9ABE-AE9665827817</RequestId>
<PersonId>1841</PersonId>
<Points>30</Points>
<Description>Redeem points</Description>
<Reference>RED456</Reference>
</PointsRedemption>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 189 of 197
1.83 CONFIRM UNCONFIRMED REQUEST

Do a POST on the below URI to confirm an unconfirmed request and commit the pending redemption of
points or rewards.

1.83.1 URI REQUEST FORMAT

/rewards/confirmation?countryCode={countryCode}&requestId={requestId}

1.83.2 REQUEST PARAMETERS

Field Required Comment
Country Code Mandatory Country Code of shopper
Request Id Mandatory Request Id (GUID)

1.83.3 EXAMPLE REQUEST

POST

https://retailapi.apparel21.com/RetailAPI/Rewards/Confirmation?countryCode=AU&requestId=5AFC78B8-
A622-438B-9ABE-AE9665827817

Content-type: text/xml
Accept:version_1.0

1.84 REVERSE UNCONFIRMED REQUEST

Do a POST on the below URI to rollback redemption request. This can only be done within 24 hours of a
redemption request.

1.84.1 URI REQUEST FORMAT

/rewards/reversal?countryCode={countryCode}&requestId={requestId}

1.84.2 REQUEST PARAMETERS

Field Required Comment
Country Code Mandatory Country Code of shopper
Request Id Mandatory Request Id (GUID recommended)

1.84.3 EXAMPLE REQUEST

POST

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 190 of 197
https://retailapi.apparel21.com/RetailAPI/Rewards/Reversal?countryCode=AU&requestId=5AFC78B8-
A622-438B-9ABE-AE9665827817

Content-type: text/xml
Accept:version_1.0

1.85 SUCCESS RESPONSE

HTTP Response
200 OK
201 Created

1.86 ERROR RESPONSE

HTTP Error API Error Code API Error Description
403 5152 AccountId 'XXX' does not exist
403 5153 XXX is not a positive number
403 5154 XXX is neither zero nor a positive number
403 5155 PersonId 'XXX' does not match AccountId 'YYY'
403 5156 Not enough points available to redeem
403 5157 Not enough rewards available to redeem
403 5158 'RequestId' URL parameter is mandatory
403 5159 TierId 'XXX' is not valid for ProgramId 'YYY'
403 5160 Failed to create account for PersonId 'XXX' and ProgramId 'YYY'
403 5161 Account already exists for PersonId 'XXX' and ProgramId 'YYY'
403 5162 ProgramId 'XXX' does not exist
403 5163 RequestId 'XXX has already been processed
403 5164 RequestId is mandatory"
403 5165 Account XXX is corrupt
403 5166 Person XXX is not valid
403 5167 AccountId 'XXX' is not valid for the API web store
403 5168 ProgramId 'XXX' is not valid for the API web store
403 5169 AccountId 'XXX' has changed since update was requested
403 5170 Rewards Error: XXX
403 5171 No gift with GiftId XXX available to redeem
403 5172 GiftId XXX not valid for AccountId XXX
403 5173 RedeemedSkudId XXX is invalid for GiftId XXX
403 5174 AccountId XXX is not associated with an active program

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 191 of 197
21 STORES

The Stores resource retrieves store details to enable a shopper to purchase goods online and collect from a
store that is convenient for them. The FreeStock resource is created in conjunction with Stores to display
available stock by SKU.

1.87 STORE DETAILS

Field Format Max Comment Example GET HTTP

Length Response Header
Accept:
Version_
Store Lists Store details
StoreId Integer 22 Identifier for the Store 108864 Yes 2.0
Code Alpha 30 Store Code GEORGESTS Yes 2.0
StoreNo Integer 3 Store Number 100 Yes 2.0
Name Alpha 30 Retail Store Name George St Store Yes 2.0
Address1 Alpha 50 1st line of the store address 110 Cremorne St Yes 2.0
Address2 Alpha 50 2nd line of the store address Level 2 Yes 2.0
City Alpha 50 City of the store Cremorne Yes 2.0
State Alpha 50 State VIC Yes 2.0
Postcode Integer 10 Postcode of the store 3131 Yes 2.0
Country Alpha 20 Country of the Store Australia Yes 2.0
Email Alpha 250 Email address of the store [email protected] Yes 2.0

1.88 RETRIEVE STORE DETAILS

To retrieve a list of stores use a GET on the following URI.

1.88.1 URI REQUEST FORMAT

/Stores/{StoreId}?countryCode={countryCode}

1.88.2 REQUEST PARAMETERS

Field Required Comment
StoreId Optional Id of the Store to request details for a single
store
CountryCode Mandatory Country code of the shopper

1.88.3 EXAMPLE REQUEST

GET https://retailapi.apparel21.com/RetailAPI/Stores/2701?countryCode=AU

Content-type: text/xml

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 192 of 197
 Accept:version_2.0

1.88.4 EXAMPLE PAYLOAD

<Store>
<StoreId>108864</StoreId>
<Code>GEORGESTS</Code>
<StoreNo>100</StoreNo>
<Name>George St Store</Name>
<Address1>110 Cremorne St</Address1>
<Address2>Level 2</Address2>
<City>Cremorne</City>
<State>VIC</State>
<Postcode>3131</Postcode>
<Country>Australia</Country>
<Email>[email protected]</Email>
</Store>

1.88.5 SUCCESS RESPONSE

HTTP Response
200 OK
201 Created

1.88.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text
404
400 5081 Store ID should be an integer
403 5080 You don’t have security for the requested store
403 5014 Size of field XXXX, 9999 is too long. Maximum length is 9999.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 193 of 197
22 SHIPMENTS

The Shipments resource retrieves shipment details for all orders that have been despatched from either the
warehouse or retail stores. If an order has been despatched in multiple shipments, the response will return
all shipments with corresponding Carrier and Consignment note details.

1.89 SHIPMENT DETAILS

Field Form Max Comment Example GET HTTP

at Length Response Header
Accept:
Version_
Shipment Lists Shipment details
CarrierName Alpha 22 Name of carrier TNT Yes 2.0
International
CarrierUrl Alpha 30 URL of carrier. Returns a www.TNT.com Yes 2.0
value only if carrier is a valid
reference code in Apparel21,
otherwise returns blank.
ConNote Alpha 50 Consignment Note Number GE292474889AU Yes 2.0
of shipment
DespatchDate Date Date of despatch 2014-11-17 Yes 2.0
Contents Lists of contents Yes 2.0
Content Yes 2.0
ProductCode Alpha Product Code
ColourCode Alpha Colour Code
SizeCode Alpha Size Code
SkuId Integ 22 Id of the SKU 12300 Yes 2.0
er
Quantity Num( 22 Quantity of SKU 1 Yes 2.0
22,2)

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 194 of 197
1.90 RETRIEVE SHIPMENT DETAILS

To retrieve a list of shipment details for an order perform a GET on the following URI.

1.90.1 URI REQUEST FORMAT

/Persons/{PersonId}/Shipments/{OrderId}?countryCode={countryCode}

1.90.2 REQUEST PARAMETERS

Field Required Comment
PersonId Mandatory Id of the Person the orders are requested for
OrderId Mandatory Id of the Order to request shipment details for
a single order
CountryCode Mandatory Country code of the shopper

1.90.3 EXAMPLE REQUEST

GET https://retailapi.apparel21.com/RetailAPI/persons/4323/shipments/3323?countryCode=AU

Content-type: text/xml
Accept:version_2

1.90.4 EXAMPLE PAYLOAD

</Shipments>
</Shipment>
<Shipment>
<CarrierName/>
<CarrierUrl/>
<ConNote>connote1-pos</ConNote>
<DespatchDate>2015-04-16T00:00:00</DespatchDate>
<Contents>
<Content>
<ProductCode>JL 0006</ProductCode>
<ColourCode/>
<SizeCode/>
<SkuId>17722</SkuId>
<Quantity>2</Quantity>
</Content>
<Content>
<ProductCode>JL 0007</ProductCode>
<ColourCode>SDB</ColourCode>
<SizeCode/>
<SkuId>17725</SkuId>
<Quantity>1</Quantity>
</Content>
<Content>
<ProductCode>JL 0008</ProductCode>
<ColourCode>SDB</ColourCode>

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 195 of 197
 <SizeCode>XL</SizeCode>
<SkuId>17739</SkuId>
<Quantity>1</Quantity>
</Content>
</Contents>
</Shipment>
<Shipment>
<CarrierName>Toll</CarrierName>
<CarrierUrl>http://www.toll.com/</CarrierUrl>
<ConNote>mo2</ConNote>
<DespatchDate>2015-04-16T00:00:00</DespatchDate>
<Contents>
<Content>
<ProductCode>JL 0007</ProductCode>
<ColourCode>SDB</ColourCode>
<SizeCode/>
<SkuId>17725</SkuId>
<Quantity>1</Quantity>
</Content>
</Contents>
</Shipment>
</Shipments>

1.90.5 SUCCESS RESPONSE

HTTP Response
200

1.90.6 ERROR RESPONSE

HTTP Error API Error Code API Error Text

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 196 of 197
23 ADDITIONAL ERROR RESPONSES
The following are common error codes.

HTTP Error API Error Code API Error Text

403 5015 SQL Error
403 5029 The country has not been setup at head office
403 5030 You don’t have security for the requested store
403 5031 Final customer not defined for country
403 5036 Invalid warehouse code in API web site configurations file
403 5122 Request content type is not XML
403 5121 Cannot deserialise payload

These errors can be resolved by contacting an Apparel21 consultant.

1 01 C R EM OR NE ST C R EM OR NE VI C 3 12 1 AC N 0 0 5 9 9 7 9 0 0 P H : 6 1 3 8 41 5 93 0 0 F A X : 6 13 9 4 27 1 75 2 W W W .A P P A R EL 2 1 .C OM

RETAIL API GUIDE - 2020.1 Apparel21 Reference Guide Page 197 of 197