Overview
This document provides an overview of how to integrate with THE ICONIC’s Marketplace platform and Seller Center using the API. The sections covered in this document are listed below
- Endpoints and documentations
- API calls
- API flows
- Frequently Asked Questions including payload examples
Seller Center 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. stock management, order processing and product creation.
For information on how to connect and authorise, please refer to this page REST API Authorisation
API Documentation and Endpoints
API documentation can be found below
Live = https://sellercenter-api.theiconic.com.au/docs/
Test (Preprod) = https://sellercenter-api-preprod.theiconic.com.au/docs/
API endpoints can be found below
|
API Endpoints |
|
|
LIVE |
|
|
TEST (Preprod) |
https://sellercenter-api-preprod.theiconic.com.au/v2 |
API Authentication endpoints can be found below
|
API Authentication Endpoints |
|
|
LIVE |
https://sellercenter-api.theiconic.com.au/oauth/client-credentials |
|
TEST (Preprod) |
https://sellercenter-api-preprod.theiconic.com.au/oauth/client-credentials |
Seller Center URL can be found below. This is User Interface which is used to manage and update the orders and products.
|
URLs |
|
|
LIVE |
|
|
TEST (Preprod) |
|
Integration
Depending on the volume/size and capabilities, your system will determine the level of integration for your brand. Depending on the level of integration and your Stock Management System (ERP) you may have the capacity to complete the integration internally if you have an in-house developer.
The below table outlines the various levels of integration, along with the coding (API calls) required to assist you with your internal development and implementation of the integration. Several levels of integration may be combined or singularly applied. Basic suggested process flows are available within this help center.
To view details of each API call and to try them out directly, please visit:
Live = https://sellercenter-api.theiconic.com.au/docs/
Test (Preprod) = https://sellercenter-api-preprod.theiconic.com.au/docs/
|
Integration Level |
Advantages |
API calls to be implemented (as a guide) |
|
Webhooks |
Webhooks can be created and utilised to notify you of new orders or products that have Quality Control completed for example. |
To get list of webhook entities
To create webhook
To delete webhook
To get list of webhooks
|
|
Stock Management |
Stock level for each product can be retrieved via the V2 stock endpoints. To retrieve the product set id or product id, use the product endpoints listed in the product section below. |
To check stock level
|
|
Product Creation and Update |
Products can be created using the V2 product set and product endpoints. The first step is to use the product set endpoint to create a product set with at least one variation (size). The product set id will be provided in the response. Then using the product endpoint, additional variations (sizes) can be created under the set. The individual product id will be provided in the response. |
To find explanation of the fields in the payload
To get products
To create products
To update products
To update price (country is always AU)
To add/update image
|
|
Order Processing |
Orders are able to be retrieved using the V2 order endpoints. The response will include the order status and transaction information such as Unit price and any applicable Seller Funded Voucher Discount amount. |
To get orders Please include filter includeVoucherDetails=true, to have the response to include the voucher amount details
|
|
Full Integration |
Complete end to end integration including Product Creation, Stock Update and Product Updates such as content. |
All API calls for Stock Management, Order Processing and Product Creation
|
|
File Export |
Seller is able to trigger a job to export a file. Seller is also able to get a list of export jobs that have been submitted. |
To trigger export job
The response will contain the csv file name. To open the file, append this file name to the Seller Center website url, or, it will also be accessible in the Seller Center UI menu File Manager. To get list of exports
|
|
File Import |
Seller is able to import an xslx file via API. This can be used as a bulk function to create/update products or images. |
First get the required template , the response will either provide a link to download the file, or an export id which means the file is available in the Seller Center website menu System - File Manager and can be downloaded from there
Then fill up the file, and import it via the relevant API import call
|
Integration Flow
Product Management Process Map
Image can be viewed at full resolution by right click>open image in new tab.
Once product set and products have been created, the respective product set ids or product ids can be used to retrieve stock levels for individual products, using the stock endpoints.
Order Management Process Map
FAQs
Q : Show me an example of product creation flow
Step 1. After identifying all the necessary attribute values, first step is to create the product set. This is like the shell of the product containing the top level information such as colour, description, gender etc.
At least one variation (size) needs to be specified in this call , as well as the price.
*variation is a special attribute that needs to be specified as it's own text value in the payload, as opposed to as an attribute id.
The call is POST /v2/product-set
The response will provide a product set id
So for example at this stage you would have created a blue shirt product, with size S.
{
"name": "blueshirt",
"price": 100,
"status": "active",
"sellerSku": "abc",
"description": "Experience the ultimate shirt",
"brandId": 171,
"variation" :"S",
"primaryCategoryId": 308,
"categories": [
771
],
"attributes": {
"13": "263487011",
"14": "2",
"17": "16233",
"19": "16565",
"20": "313",
"41": "0.2",
"58": "Blue",
"60": "Blue Noir",
"61": ["457"],
"90": "Cold machine wash separately inside out. Wash before wearing.",
"92": "76% Cotton, 16% Lyocell, 5% Polyester, 3% Elastane",
"95": "- Waist: 65cm; Front Rise: 26cm; Inleg: 68cm (Size AU 8)",
"98": "997",
"127": "1807",
"130": "2501",
"174": false,
"242": "5000",
"243": "5005",
"275": ["5109"],
"276": ["5117"],
"382": ["23589"]
}
}
Step 2. After the product set has been created, using the product set id from above, you can start adding other variation into this set, for example create each size M, L, XL and so forth for this blue shirt.
The call is POST /v2/product-set/{productSetId}/products
The response will provide you with all the individual product ids.
So for example at this stage you will then have a blue tshirt with size S and size M
{
"sellerSku": "abcd1",
"status": "active",
"variation": "M",
"productIdentifier": "965511248452126"
}
Step 3. After the product set and all the product id (size variations) have been created, you can now add stock for each individual product id
The call is PUT /v2/stock/product
[
{
"productId": 5283,
"quantity": 12
}
]
Q : How do I change the price
Use call PUT /v2/product-set/{productSetId}/prices
You need to know the product set id, and at least one of the product ids.
The country value is always AU
[
{
"productId": 1234567,
"country": "AU",
"price": 80.00,
"salePrice": 40.00,
"saleStartDate": "2024-10-30",
"saleEndDate": "2024-10-31"
}
]
Q : How do I know what the fields mean in the product creation payload
Do a sample call GET /v2/product-sets/sample-payload/{categoryId} , or GET /v2/category/{categoryId} , or GET /v2/attribute-sets/{attributeSetId}/attributes, to identify various attribute mappings.
Q : I have the same product but just different colours, how do I group them together
For each product in different colour, you will need to create its own product set. Then for all these different product sets, you add them into a group using this call POST /v2/product-set/{productSetId}/group
This will ensure the color dots for those products are linked together as shown below.
Q : How do I find out the order unit amount and the relevant discounts
Ensure in your GET /v2/orders call you include 'includeVoucherDetails=true'
In the response, if there is a seller funded voucher amount (i.e. the sku is part of a campaign) , then under the order item voucher section you will see the voucher code and the amount. Your calculation will be unitPrice minus the amount under that voucher section.
If there is no voucher information, your calculation will just be the unitPrice.
"unitPrice": 109,
"taxAmount": 7.93,
"taxPercent": 10,
"paidPrice": 87.2,
"paidCommission": 20.93,
"shippingFee": 0,
"shippingServiceCost": null,
"walletCredits": 0,
"storeCredits": 0,
"shippingVoucherAmount": 0,
...
},
"vouchers": [
{
"code": "campaign_25944",
"amount": 21.8,
"voucherSellerShare": 0,
"cashbackSellerShare": 0,
"cashbackPercentage": 0,
"amountFundedBySeller": "0.00",
"cashbackAmountFundedBySeller": "0.00"
}
],
"manifestStatus": null,
"isPickupRequestSent": false,
"discountAmount": 21.8
You can also use finance endpoints, such as GET /v2/finance/transactions, to check transactions related to an order item, including the commission calculation. However, with this endpoint, the transaction is only generated once the order status has been updated to shipped.
Q : Is there any rate limit for the calls
Refer to the Rate limit section in the API Documentation page
Q : Why do I get error response 403 Forbidden
Ensure that the product or order in your request is from the seller shop associated with your OAuth credentials. You won't be able to update or query items belonging to a different seller shop than the one linked to your credentials
Otherwise if the issue persists, log the query to the helpdesk email