ZALORA

Marketplace Integration Guide for REST API 2.0

ZALORA
Version Date Author Description of changes

1.0 8 Sep 22 Jarrod Goh Initial version with guide for REST API 2.0 for Products

1.1 12 Jan 23 Jarrod Goh Update with REST API 2.0 order integration

ZALORA
1
About this document 3

Introduction to Seller Center 3

Overview of REST API 2.0 4

Getting Started 5
Links to API Documentation 5
Authentication for API 5
Key API Endpoints 6

Guide to Integrating with Zalora Seller Center 8

Stage 1: Account creation in staging environment 9
Stage 2: Products 9
Stage 3: Orders 10

Webhooks 11

Appendix 12
Appendix 1: Product Management 12
Appendix 2: Order Management 13

ZALORA
2
About this document

This document has been created to provide you with an overview of how you can integrate with ZALORA’s
Marketplace platform (a.k.a. Seller Center) via API and includes important links and answers to common
questions you may have. This is not the official API documentation but an integration guide

Introduction to Seller Center

Seller Center (SC) is our User Interface which is used to manage and update your shop and products. An API
integration can enable you to connect your systems to Seller Center, providing various levels of integration
i.e. product creation, stock management, order processing and receive order notifications via webhooks.
Below are URL links to Zalora SC platform:

Environment Instance URL Link

Live Global Seller Center (GSC) https://sellercenter.zalora.com/

MY SC https://sellercenter.zalora.com.my/

SG SC https://sellercenter.zalora.sg/

HK SC https://sellercenter.zalora.com.hk/

TW SC https://sellercenter.zalora.com.tw/

ID SC https://sellercenter.zalora.co.id/

PH SC https://sellercenter.zalora.com.ph/

Staging (Test) GSC https://sellercenter-staging.zalora.com/

MY SC https://sellercenter-staging.zalora.com.my/

SG SC https://sellercenter-staging.zalora.my/

HK SC https://sellercenter-staging.zalora.com.hk/

TW SC https://sellercenter-staging.zalora.com.tw/

ID SC https://sellercenter-staging.zalora.co.id/

PH SC https://sellercenter-staging.zalora.com.ph/

ZALORA
3
Overview of REST API 2.0

Zalora Seller Center provides the possibility for sellers to connect through API. The longest available one is
XML based (or alternatively JSON), so called seller-api (documentation available here) and mainly available
for product and order operations. The existing API has shown that integration with Seller Center can get
complex and doesn’t provide much functionality.

Seller REST API 2.0 was developed with the aim to switch to a new software architecture and improve the
way of communication between sellers and Seller Center. Please refer below for some key differences for
REST API 2.0:
● Product creation endpoints have been split between product set and product. For product creation, a
product set with one product variation needs to be created first. The other product variations are then
added to the product set
● Majority of the product fields have been changed to use attribute ids in the payload, instead of the
field/feed name
● Product endpoints have import endpoints as well using file uploads

ZALORA
4
Getting Started

Links to API Documentation

Once your Seller Center account is created post training, these links will help facilitate your integration. You
can also try out the endpoints using

Environment Instance URL Link

Live Global Seller Center (GSC) https://sellercenter-api.zalora.com/docs/

MY SC https://sellercenter-api.zalora.com.my/docs/

SG SC https://sellercenter-api-staging.zalora.sg/docs/

HK SC https://sellercenter-api.zalora.com.hk/docs/

TW SC https://sellercenter-api.zalora.com.tw/docs/

ID SC https://sellercenter-api.zalora.co.id/docs/

PH SC https://sellercenter-api.zalora.com.ph/docs/

Staging (Test) GSC https://sellercenter-api-staging.zalora.com/docs/

MY SC https://sellercenter-api-staging.zalora.com.my/docs/

SG SC https://sellercenter-api-staging.zalora.sg/docs/

HK SC https://sellercenter-api-staging.zalora.com.hk/docs/

TW SC https://sellercenter-api-staging.zalora.com.tw/docs/

ID SC https://sellercenter-api-staging.zalora.co.id/docs/

PH SC https://sellercenter-api-staging.zalora.com.ph/docs/

Authentication for API

Seller Center REST API 2.0 is not publicly accessible and is based on OAuth2 Authentication. To get the
Application ID and Secret Key please follow the following steps:

Note: The user account used to create the OAuth Applications will appear/will be shown as the user that
performs the system activities for the API calls (create product, update product, update order status, etc.)

● Login to the respective Seller Center system

● Go to Settings > Integration Management
● Navigate to “OAuth Applications” tab
● Click on “Add Application”
● Fill out the form by providing an Application Name and an Authorization redirect URL

ZALORA
5
 ● Click on “Save”
● New application will be created
● Click on “Edit” for the application
● You will be directed to a page with the application details. You can find your Application ID and
Application Secret here

Key API Endpoints

Depending on the volume/size and capabilities, you will need to determine the level of integration for your
brand. You will be required to complete the integration at your end as ZALORA does not offer integration
services at the moment.

The below table outlines the various levels of integration, along with the key API calls required to assist you
with your development and implementation of the integration. Several levels of integration may be combined
or singularly applied. See appendices for basic process flows.

Area Description API Endpoint

Product Products created / GET

updated in seller’s ● /v2/product-sets
system are synced
from seller’s system to ● /v2/product-set/{productSetId}/products
Seller Center ● /v2/product-set/{productSetId}/images
● /v2/prices
● /v2/stock/product-set/{productSetId}
POST
● /v2/product-set
● /v2/product-set/{productSetId}/products
● /v2/product-set/{productSetId}/images
PUT
● /v2/product-set/{productSetId}
● /v2/product-set/{productSetId}/products/{productId}
● /v2/product-set/{productSetId}/products/{productId}/status
● /v2/product-set/{productSetId}/images/{imageId}
● /v2/product/{productId}/prices/{country}
● /v2/stock/product

ZALORA
6
Area Description API Endpoint

Sales Order Enables seller to GET

process orders via ● /v2/orders
their existing systems
● /v2/orders/{orderId}
● /v2/order-items/multiple
● /v2/orders-counters
POST
● /v2/orders/set-invoice-number
● /v2/orders/statuses/set-to-packed-by-marketplace
● /v2/orders/statuses/set-to-ready-to-ship
● /v2/orders/statuses/set-to-cancelled

Webhooks Utilize webhooks to GET

notify of events such ● /v2/webhooks
as for orders and
products. For example, ● /v2/webhook-entities
where possible to POST
notify you of new
● /v2/webhook
orders or products that
have Quality Control DELETE
completed ● /v2/webhook/{uuid}

ZALORA
7
Guide to Integrating with Zalora Seller Center

In summary, the process of API Integration testing will be as below. This guide summarizes the process flow
of API integration testing and some of the mandatory information we need for each stage. You can prepare
this information in advance to speed up the integration testing process.

Stage 1: Account creation in staging environment

User will be granted access to the shared staging account for API Integration testing

Email Address:

Venture
(e.g. SG, MY, GSC)

Stage 2: Product creation

Creating own SKUs in test account? (YES,NO)

SKU Number SKU 1:

Please provide list of SKUs for us to place testing
orders SKU 2:

**During product creation, please ensure that the SKU 3:

brand section is filled as “Test MP Brand” as this is a
SKU 4:
shared staging account which does not tie to any
seller’s brand SKU 5:

Stage 3: Placing Test Orders

Variables of order scenarios may include (Number of SKUs, quantity, payment method, voucher
discount, store credit)

Order Scenario 1 SKU:

Quantity:
Payment Method (Optional):
Voucher discount (Optional):
Store Credit (Optional):

Order Scenario 2 SKU:

Quantity:
Payment Method (Optional):
Voucher discount (Optional):
Store Credit (Optional):

Order Scenario 2 SKU:

Quantity:
Payment Method (Optional):
Voucher discount (Optional):
Store Credit (Optional):

ZALORA
8
Stage 1: Account creation in staging environment

To ensure that the API integration is up in the right manner, the Marketplace Onboarding team can assist in
granting access to ZALORA’s staging environment or facilitating a test order to ensure that data is flowing
across systems correctly.

Please log a ticket via the Seller Center interface with our team by clicking on the “Contact Us” icon at the
top of your Seller Center Page and select the correct term based on your query (for all technical API queries
select “Seller API Integration”). You can also reach out to your respective account managers to assist in
creating a test account.

Stage 2: Products

When creating products via API please always include all the required fields listed below. Refer to Appendix
1 for the suggested call sequence for product creation and update

For all products, the following are mandatory fields (highlighted in yellow are fields that are mandatory for
product creation in ZALORA and are non-editable after the SKU has been created in ZALORA’s back end).
SkuSupplierConfig and ParentSku should be the same value.

● SkuSupplierConfig
● ParentSku
● SellerSku
● Shipment Type
● Name
● Brand
● PrimaryCategory
● SubCatType
● Color
● ColorFamily
● Price
● Sizesystembrand
● Variation
● Gender
● Material
● Description
● CareLabel
● Measurements

Majority of the fields above are sent in the attributes array, and are sent using the attribute id. The attribute
ids may differ between staging and live environment, and also across the various Seller Center instances.
Therefore, the attribute ids need to map accordingly for the respective environment.

For product creation and update, it is very important to input the correct values for the product fields so the
product is informative to the customer and the product will be created successfully.

In general, products are grouped into Attribute Sets (Apparel, Shoes, Accessories, Glasses, Underwear and
Swimwear, Beauty). Some product fields are available for a specific Attribute Set (e.g. Shoes will have
ZALORA
9
optional fields of “UpperMaterial”, “InnerMaterial”, “SoleMaterial”, “InnerSoleMaterial” etc). Mandatory fields
are standard across the Attribute Sets. Please refer to the attached spreadsheet for all category mappings -
Link

The shipment type of the product is defaulted based on your model. If you are under the Fulfillment by
Zalora model, the product shipment type will be defaulted as “Fulfillment by Zalora”, otherwise, it will default
to “Dropshipping”.

Refer below for an example of request for product set creation

ZALORA
10
Stage 3: Orders

Order Processing
The order flow is as follows. Please note that order fulfillment/processing is only applicable is you are on
dropship model. If you are on Fulfilled by Zalora (FBZ) model, then you only need to get the order
information. Refer to Appendix 2 for the suggested call sequence for order processing.

1. Order is pending
a. Get orders from GET /v2/orders
b. Use OrderId obtained from 1a to call GET /v2/order-items to get order item details
c. Rather than polling the API at regular intervals, it is suggested to use webhooks. You can
subscribe to different events and the data will be sent to your callback url.

2. Seller prints stock checklist to pick items from inventory (optional, for seller to print a picking list)

3. Seller sets order to packed status (mandatory, confirming the shipping provider is required here and
ZALORA automatically retrieves Tracking number from shipping provider via API). If you are a FBS
seller, then you’ll need to provide the Tracking number.
a. Use OrderItemIds from 1b to call POST /v2/orders/statuses/set-to-packed-by-marketplace to
set to packed status.
b. Example request

4. Seller sets the invoice number of the order item(s) for the package
a. Use OrderItemIds from 1b to call POST /v2/orders/set-invoice-number to update the invoice
number.
b. Invoice number is set at package level. Order items in the same package will have the same
invoice number.

5. Seller prints invoice and shipping label

a. Use OrderIds to call POST /v2/orders/export-document to get the shipping labels and invoice
by using documentType ‘shippingLabel’ and ‘invoice’ respectively.
b. The document will be exported in pdf and you can use the ‘downloadLinks’ in the response
together with the Seller Center instance URL (refer page 3) to download the document.
c. Example response

ZALORA
11
6. Seller assembles the package (together with documents printed in 5)

7. Seller sets order to ready to ship status (mandatory, this is seller's indication that seller is ready for the
shipping provider to pickup the order)
a. Use POST /v2/orders/statuses/set-to-ready-to-ship. You can omit the following parameters as
the information if they are not applicable. Tracking number will be automatically assigned if
the 3PL is integrated
i. trackingNumber
ii. shipmentProvider
iii. accessKey
iv. documentUrl
v. invoiceEncodedXml
b. Example request

ZALORA
12
Webhooks

Webhooks can be created via API calls or Seller Center interface. Navigate to Settings > Integration
Management > Webhooks - link: https://sellercenter.zalora.com.my/webhook/webhook (change the URL
accordingly based on your country).

We recommend utilizing these where possible to reduce the API load against the API such as Order feeds
and Quality Control feeds.

ZALORA
13
Appendix

Appendix 1: Product Management

ZALORA
14
Appendix 2: Order Management

ZALORA
15