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

Live = https://sellercenter-api.theiconic.com.au/docs/

Test (Preprod) = https://sellercenter-api-preprod.theiconic.com.au/docs/

API endpoints

API Endpoints
LIVE	https://sellercenter-api.theiconic.com.au/v2
TEST (Preprod)	https://sellercenter-api-preprod.theiconic.com.au/v2

API Authentication endpoints

This is to be used to generate your bearer token.

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

This is the Seller Center User Interface which is used to manage and update the orders and products.

URLs
LIVE	https://sellercenter.theiconic.com.au
TEST (Preprod)	https://sellercenter-preprod.theiconic.com.au

Integration Calls Summary

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 GET /v2/webhook-entities To create webhook POST /v2/webhook To delete webhook DELETE /v2/webhook/{uuid} To get list of webhooks GET /v2/webhooks
Stock Management	Seller is able to sync their stock count automatically from their ERP system directly to Seller Center - no manual stock updates are required	To update stock PUT /v2/stock/product To check stock level GET /v2/stock/product/{productId} GET /v2/stock/product-set/{productSetId} For other bulk stock update method please refer to FAQ section
Product Creation and Update	Products created/updated in the seller’s system are synced automatically from seller’s system to Seller Center - No manual product creation/updates are required in Seller Center	To find explanation of the fields in the payload GET /v2/product-sets/sample-payload/{categoryId} To get products GET /v2/product-sets GET /v2/product-set/{productSetId}/products To create products POST /v2/product-set (to create a product set with at least one variation) POST /v2/product-set/{productSetId}/products (to create more variations within existing product set) To update products PUT /v2/product-set/{productSetId} PUT /v2/product-set/{productSetId}/products/{productId} PUT /v2/product-set/{productSetId}/products/{productId}/status To update price (country is always AU) PUT /v2/product/{productId}/prices/{country} To update stock PUT /v2/stock/product To add/update image POST /v2/product-set/{productSetId}/images PATCH /v2/product-set/{productSetId}/images/{imageId}
Order Processing	Seller is able to process orders via their existing process in their ERP system – no manual update in Seller Center required for order fulfillment.	To get list of enabled Shipment Providers GET /v2/orders-shipment-providers To get orders Please include filter includeVoucherDetails=true, to have the response to include the voucher amount details Please use the offset and limit filter to retrieve orders. GET /v2/orders GET /v2/orders/{orderId} GET /v2/order-items/multiple To ship orders POST /v2/orders/statuses/set-to-ready-to-ship This call requires all order item ids within the order, the tracking number, and the shipping provider POST /v2/orders/statuses/set-to-shipped This call requires at least one of the order item ids from the order To cancel order POST /v2/orders/statuses/set-to-cancelled
Order Processing using THE ICONIC integrated carrier - Shipped by THE ICONIC	For sellers who are shipping orders using THE ICONIC integrated carrier (Shipped By The Iconic model), there are additional calls to generate, retrieve, and manifest the shipping label	To get orders Please include filter includeVoucherDetails=true, to have the response to include the voucher amount details GET /v2/orders GET /v2/orders/{orderId} GET /v2/order-items/multiple To ship orders POST /v2/orders/statuses/set-to-packed-by-marketplace This call requires all order item ids within the order, and the shipping provider. Tracking number is not required to be specified. This call will result in the shipping label creation POST /v2/orders/statuses/set-to-ready-to-ship This call requires all order item ids within the order, and the shipping provider. Tracking number is not required to be specified. POST /v2/order-pickup-requests This call requires all order item ids within the order. This generates the labels and notifies the carrier that the orders are ready for pickup. POST /v2/orders/statuses/set-to-shipped This call requires at least one of the order item ids from the order To get order document POST /v2/orders/export-document GET /filemanager/v1/files/download/{uuid} To cancel orders POST /v2/orders/statuses/set-to-cancelled
Full Integration	Complete end to end integration including Product Creation, Stock Update and Product Updates such as content.	All API calls for Stock Management, Product Creation, and Order Processing
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 GET /v2/export-products 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 GET /v2/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, stock, or image.	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 GET /v2/template/... Then fill up the file, and import it via the relevant API import call POST /v2/import/...

Integration Calls Details & Examples

Retrieve Orders

Call	GET /v2/orders
In the request	If we leave all the filter empty, response will output 100 max orders. You can use offset and limit in the filter to get through pagination Always set “includeVoucherDetails=true” so that voucher information is returned
In the response	The response includes order level and order item level info The response includes voucher info like below per order item if it is part of a seller funded promotion

Seller funded voucher calculation.

Paid amount indicates the amount of our customer payment. To actually find out what is seller payment :

In the item section if there is voucher code value, then it will be UnitPrice- Amount
In the item section if there is no voucher code value , then it will be UnitPrice

"unitPrice": 79.9,

          "taxAmount": 5.45,

          "taxPercent": 10,

          "paidPrice": 59.92,

          "paidCommission": null,

          "shippingFee": 0,

               ],

          "vouchers": [

            {"code": "campaign_16482",

              "amount": 19.98,

              "voucherSellerShare": 100,

              "cashbackSellerShare": 100,

              "cashbackPercentage": 0,

              "amountFundedBySeller": "19.98",

              "cashbackAmountFundedBySeller": "0.00"
            }

There are also finance endpoints available that provide the transaction breakdown for each order item, however these are only populated after the order has been shipped or returned

Action Orders

To mark order to Ready To Ship status

Call

POST /v2/orders/statuses/set-to-ready-to-ship

Required

All order item ids within the order.

Tracking Number.

a valid Shipment Provider.

{"orderItems": 
[    {"id": 14299838},

    {"id": 14299839},

    {"id": 14299840}
],
  "trackingNumber": "123abcdefghij",

  "shippingProvider": "AusPost"
}

To mark order to Shipped status

Call	POST /v2/orders/statuses/set-to-shipped
Required	At least one of the order item ids

{
  "orderItemIds": [
    14299839
  ]
}

Action Orders with Integrated Carrier (Shipped by The ICONIC)

To generate label

Call

POST /v2/orders/statuses/set-to-packed-by-marketplace

Required

All order item ids within the order.

A valid Shipment Provider.

{  "orderItems": 
[
    {"orderItemId": 14301851},
    {"orderItemId": 14301852}
],
    "shippingProvider": "Omni Channel Integration"
}

To retrieve label via API

Call	POST /v2/orders/export-document
Required	Can specify at least one of the order item ids, or can specify order id
In the response	There will be uuid
Call	Then using uuid from above, do GET /filemanager/v1/files/download/{uuid}

{
  "orderItemIds": [14301851],
  "documentType": "shippingParcel",
  "format": "pdf"
}

To mark order to Ready to Ship status

Call

POST /v2/orders/statuses/set-to-ready-to-ship

Required

All order item ids within the order.

A valid Shipment Provider.

{
  "orderItems": 
[
    {"id": 14301852},
    {"id": 14301851}
],
  "shippingProvider": "Omni Channel Integration"
}

To send manifest info to carrier for orders to be picked up

Call	POST /v2/order-pickup-requests
Required	All order item ids within the order

{
  "orderItemIds": [
    14301851,
    14301852
  ]
}

To mark order to Shipped status

Call	POST /v2/orders/statuses/set-to-shipped
Required	At least one of the order item ids

{
  "orderItemIds": [
   14301851
  ]
}

Create Product

Create Product Set

What	This is creating the shell of the product, with one variation (size) in it, with price.
Call	POST /v2/product-set
Response	The response will provide product set id
Note	Additional calls that can help provide insights on various field mapping GET /v2/product-sets/sample-payload/{categoryId} To know the brand id , do GET /v2/brands To know the attributes relevant to the categories, and the values , do GET /v2/category/{categoryId} or GET /v2/attribute-sets/{attributeSetId}/attributes

{  "name": "testsku123",
  "price": 100,
  "status": "active",
  "sellerSku": "testsellersku123",
  "description": "Experience the ultimate expression of functionality at BrandName with the Women's Block Shell Jacket. Our model is wearing size *. She usually wears a size 8 and is 177cm tall.",
  "brandId": 171,
  "variation" :"S",
  "primaryCategoryId": 308,
  "categories": [
    771
  ],
  "attributes": {
        "13": "263487011",
        "14": "2",
        "17": "16233",
        "19": "16565",
        "20": "313",
        "41": "0.2",
        "58": "Black",
        "60": "Forever Black",
        "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"]
  }
  }

Create Additional Products

What	This is to create additional variations (sizes) to an existing product set
Call	POST /v2/product-set
Required	Product set id
Response	The response will provide individual product ids for each variation.

{  "sellerSku": "testsku456",
  "status": "active",
  "variation": "M",
  "productIdentifier": "4602321233234"
}

Add Image

Call	POST /v2/product-set/{productSetId}/images
Required	Product set id

{
  "position": 2,
  "displayUrl": "https://static.theiconic.com.au//p/1648909-3757-9098461-3.jpg"
}

Update Image

Call

PATCH /v2/product-set/{productSetId}/images/{imageId}

Required

Product set id.

Image id (can be obtained by doing GET /v2/product-set/{productSetId}/images)

Add Stock

What	This adds stock to each individual product id
Call	PUT /v2/stock/product
Required	Individual product id

[
  { "productId": 3708630,
    "quantity": 12}
]

Update Price

Call

PUT /v2/product/{productId}/prices/{country}

Required

Individual product id.

Country value is always AU.

{
  "price": 50,
  "salePrice": 45,
  "saleStartDate": "2024-11-10",
  "saleEndDate": "2024-11-11"
}

Update Product Set

What	This updates information at the product set level
Call	PUT /v2/product-set/{productSetId}
Required	Product set id
Note	We only need to specify the field that we want to change. In example below we are only changing : The description of the product The Season (attribute id 17), to be value Winter 20 (value 16233)

{
  "description": "Experience chg desc",
  "attributes": 
   {"17": "16233"}
}

Update Product

To update product level info like seller sku, barcode ean (product identifier), or status, use this call instead

PUT /v2/product-set/{productSetId}/products/{productId}

Add Product Set Into a Group (Colour Grouping)

What	This adds a product set into a group, to be grouped with other products sets, for example for colour grouping. You can create a new group, or add product set into an existing group name.
Call	POST /v2/product-set/{productSetId}/group
Required	Product set id

{  "name": "group_name"}

Bulk Function

Import endpoints can be used to bulk create/update products, price, stock.

Example bulk stock update :

GET /v2/template/stock-update, this triggers the csv template that can be downloaded to be populated. Uuid information will be available in the response
GET /filemanager/v1/files/download/{uuid} , this is to download the csv from step 1 above
POST /v2/import/stock-update, to upload file from abov. Job queue will be created in the background for the system to process the job. Optionally to see the progress of completion of the job you can do GET /v2/feed/{uuid}/status

Example bulk price update :

Do GET /v2/template/price-update, this triggers the csv template that can be downloaded to be populated. Uuid information will be available in the response
GET /filemanager/v1/files/download/{uuid} , this is to download the csv from step 1 above
Do POST /v2/import/product-update. Job queue will be created in the background for the system to process the job. Optionally to see the progress of completion you can do GET /v2/feed/{uuid}/status

Integration Flow

Product Management Process Map

Image can be viewed at full resolution by right click-open image in new tab.

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 : What are the different methods for updating stock levels, and what limits apply to each method

PUT /v2/stock/product - synchronous endpoint which has limit of 100. This endpoint provides the fastest method for updating stock, as the stock levels are adjusted immediately upon request execution, allowing you to see the results instantly.

POST /v2/import/product-stock-update-xml - asynchronous endpoint that receives XML request and saves it for later processing in background. This endpoint has no limits, however processing occurs in the background, so depending on the system load, you may see it can complete either within 5 seconds or 5 minutes or more.

POST /v2/import/stock-update - same as previous but instead of XML , it is based on CSV file upload via the API endpoint.

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 : I cannot see some of the orders in the response when I do GET /v2/orders

Please use the offset and limit filter in the request to apply pagination in your result, as the order call will give you just the max 100 orders in the response. You can also narrow down your result by applying further filters like retrieving orders based on the status/createdAt/updatedAt dates.

The same applies for product endpoint, there are limited response given when retrieving all products, however using offset will ensure you can get all results in pagination format.

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

Overview

API Documentation and Endpoints

Integration Calls Summary

Integration Calls Details & Examples

Retrieve Orders

Action Orders

Action Orders with Integrated Carrier (Shipped by The ICONIC)

Create Product

Add Image

Add Stock

Update Price

Update Product Set

Add Product Set Into a Group (Colour Grouping)

Bulk Function

Integration Flow

Order Management Process Map

FAQs

Related articles