Skip to main content

REST API Integration Overview - Fulfilled by THE ICONIC / Consignment Flow

  • Updated
      •  

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 

 

FBI Flow

 

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

https://sellercenter-api.theiconic.com.au/v2

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

https://sellercenter.theiconic.com.au

TEST (Preprod)

https://sellercenter-preprod.theiconic.com.au

 

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

  • 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

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

  • GET /v2/stock/product/{productId}
  • GET /v2/stock/product-set/{productSetId}

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

  • 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 add/update image

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

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

  • GET /v2/orders
  • GET /v2/orders/{orderId}

Finance transactions

Order financial transactions can be retrieved using finance endpoints

GET /v2/finance/transactions

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

  • 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 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

  • GET /v2/template/...

Then fill up the file, and import it via the relevant API import call

  • POST /v2/import/...


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.

SC_Seller_Rest_API_Product_Order_Flow_-_Frame_1.jpg

 

Order Management Process Map

Integration Calls Details & Examples

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) 

 

Retrieve Stock

What This see stock level of each individual product id
Call

GET  /v2/stock/product-set/{productSetId}
Get list of stock for Products based on product set, with consignment and multi-warehouse depending on the configuration


GET /v2/stock/product/{productId}
Get stock for a Product, with consignment and multi-warehouse depending on the configuration
Required Either product set id , or product id 
Response  The response will show available FBI stock quantify for a particular sku  
{
"productId": 6528496,
"sellerSku": "LB0528 : LB0528_STN_XL",
"shopSku": "LO569AA00LH-11415806",
"name": "Lotus No Chafe Phone Pocket 14cm Bike Shorts",
"quantity": 0,
"reservedStock": 0,
"preVerificationStock": 0,
"available": 2,
"consignments": {
"received": 2,
"quarantined": 0,
"defective": 0,
"canceled": 0,
"returned": 0,
"failed": 0
},
"warehouses": [],
"sellableStock": 2,
"nonSellableStock": 0
}

 

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

 

Voucher information

Seller funded voucher calculation. 

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

  1. In the item section if there is voucher code value, then it will be UnitPrice- Amount 
  2. 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

 

Order Financial Transactions

Call GET /v2.1/finance/transactions
In the request

Optional date period can be utilised as filter 
In the response

The response provides the order number, and the financial transactions related to that order such as revenue, commissions, etc.

 

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"
}

 

 

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 

Related articles