I need to create product , Why TIKI called it is a “product request” ?

Because Tiki need to review your product data, document… both automatically and manually before bringing your products to the shelves.

TIKI product data is different from your original data so we need to transform it a bit. Base on TIKI ‘s product structure each variant will be become a brand new Tiki product. It means 1 product request made from 1 product from your side can create one or more product in Tiki side.

TIKI will update your request status step by step.

• queuing -> processing | Create product request
• From this you can track your request detail via this API
• md_waiting_approve | After that legal team will check your certificate file please take a look at our theory here
• bot_waiting_approve | TIKI have a AI system to help check your content automatically help your process faster
• awaiting_approve | Finally , content team will check product content carefully
• approved | your request become product , and its status will be inactive , please active it whenever you want to sell product in TIKI

Maybe it can be rejected by some reason such as image invalid,attribute not found,… please check via tracking method,
fix it then create a new one because product request was rejected can’t be updated anymore

Alright, you can create products on TIKI easily by following these steps:

• Choose category of your product
• Select list attribute by category
• Mapping attribute from your system to TIKI attribute
• Select list certificate files required by category & brand ( if existed )
• Prepare the certificate files then upload it as image
• OK Done, let’s create product in TIKI

Create product request flow

1. Search TIKI categories using this endpoint → map with your original category

Request

Make the following request to get call categories. These data is enough for you to build the category tree for user to select category. Categories may change, you should update it once a day by re-fetch all categories.

GET https://api.tiki.vn/integration/v2/categories

Response

Above request will return a response with the following format.

{
    "data": [
        {
            "id": 6445,
            "name": "Magazines",
            "description": "English Magazines",
            "parent_id": 320,
            "is_primary": true,
            "is_product_listing_enabled": true,
            "no_license_seller_enabled": false
        },
        {
            "id": 218,
            "name": "Medical Books",
            "description": null,
            "parent_id": 320,
            "is_primary": true,
            "is_product_listing_enabled": false,
            "no_license_seller_enabled": true
        }
    ]
}

• Default, this API list categories which used for non cross-border sellers. So if you are cross-border seller, let use param isCrossBorder=true to get cross-border categories.
• You can search categories :
  • by keyword https://api.tiki.vn/integration/v2/categories?name=book&isPrimary=true
  • travel over categories tree : https://api.tiki.vn/integration/v2/categories?parent=17166
• Until you got a primary category have "is_primary": true in response. It’s the smallest unit used to classify products at TIKI, one product belong to exactly one primary category.
• Seller can not create products on an is_product_listing_enabled=false category.
• Seller without license only can create products on categories which have no_license_seller_enabled=true

To get more detail of a category, perform the following request

GET https://api.tiki.vn/integration/v2/categories/218?includeParents=true

And receive the detail

{
  "id": 218,
  "name": "Medical",
  "description": null,
  "parents": [
    {
      "id": 2,
      "name": "Root",
      "parent_id": 1
    },
    {
      "id": 8322,
      "name": "Nhà Sách Tiki",
      "parent_id": 2
    },
    {
      "id": 320,
      "name": "English Books",
      "parent_id": 8322
    },
    {
      "id": 27,
      "name": "Non-fiction - Social sciences",
      "parent_id": 320
    },
    {
      "id": 29,
      "name": "Professions",
      "parent_id": 27
    },
    {
      "id": 218,
      "name": "Medical",
      "parent_id": 29
    }
  ],
  "parent_id": 29,
  "is_primary": true,
  "is_product_listing_enabled": false,
  "no_license_seller_enabled": false
}

2. Get attribute from primary category you chosen → map with your original attribute

Only choose a primary category to continue. Because you can only create products with primary category.

Now user needs to know which information they should provide to create a product in that category. Perform the following request:

GET https://api.tiki.vn/integration/v2/categories/218/attributes

And receive the response will describe what information is required (or optional), its data type and description:

{
  "data": [
    {
      "id": 56,
      "code": "name",
      "description": "Tên sản phẩm",
      "display_name": "Tên sản phẩm",
      "display_name_en": "Product name",
      "is_required": true,
      "default_value": "Tên sản phẩm",
      "input_type": "text",
      "data_type": "varchar",
      "description_en": null
    },
    {
      "id": 499,
      "code": "publication_date",
      "description": "Ngày - tháng - năm xuất bản.",
      "display_name": "Ngày xuất bản",
      "display_name_en": "Publication date",
      "is_required": false,
      "default_value": null,
      "input_type": "date",
      "data_type": "datetime",
      "description_en": null
    },
    {
      "id": 540,
      "code": "publisher_vn",
      "description": "Nhà xuất bản  / Công ty phát hành",
      "display_name": "Công ty phát hành",
      "display_name_en": "Publisher",
      "is_required": true,
      "default_value": null,
      "input_type": "select",
      "data_type": "int",
      "description_en": null
    },
    {
      "id": 603,
      "code": "brand",
      "description": "Name of the brand producing this product.",
      "display_name": "Thương hiệu",
      "display_name_en": "Trademark",
      "is_required": false,
      "default_value": null,
      "input_type": "select",
      "data_type": "int",
      "description_en": null
    }
  ]
}

• Note that only the primary category has the attribute to make the product request
• Each category have some required attribute like origin have "is_required": true. You have to complete this field base on our example.
• But your side don’t have anything to map to these or you still don’t have any idea about this then I can give you a small tips. It is you can complete required attribute with a dummy data like updating maybe it can bypass our automate review but I have to warn you if you abuse this TIKI content reviewer may reject your product request.
• Remember id in response as attribute_id to use later.

Some attributes might have a dynamic list of values to be selected. These attributes have "input_type": "select" or "input_type": "multiselect". To get the list the list of available values to be selected, make a call:

GET https://api.tiki.vn/integration/v2/attributes/540/values?q=phong&limit=3

This will return

{
    "data": [
        {
            "id": 4509607,
            "value": "Báo Thiếu Niên Tiền Phong",
            "position": 0,
            "attribute_code": "publisher_vn"
        },
        {
            "id": 704931,
            "value": "BÁO TIỀN PHONG",
            "position": 0,
            "attribute_code": "publisher_vn"
        },
        {
            "id": 18877,
            "value": "Cẩm Phong Books",
            "position": 0,
            "attribute_code": "publisher_vn"
        }
    ],
    "paging": {
        "total": 29,
        "per_page": 3,
        "current_page": 1,
        "last_page": 10,
        "from": 1,
        "to": 3
    }
}

• You can search values by substring with parameter q=something
• You can search pagination by using page and limit parameter. By default, the pagination is limit 20 and page 1.

3. Prepare certificate files to verify your product

Some categories or brands require legal documents. To check this, you need to query for required documents. Products that require legal documents but missing those documents will be rejected. For more detail you can read in TIKI theory

Your product has a brand

If brand attribute is required, you surely need to provide brand information and use it to query for required document. You brand attribute is optional, but you still select a brand for your product, you also need to use that brand to query for required document.

Get list of brands for attribute brand (its id 603 can be seen from previous response)

GET https://api.tiki.vn/integration/v2/attributes/603/values

This will return all brands recognized by Tiki

{
  "data": [
    {
      "id": 17827,
      "value": "Apple",
      "position": 0,
      "attribute_code": "brand"
    },
    {
      "id": 18804,
      "value": "Panasonic",
      "position": 0,
      "attribute_code": "brand"
    },
    {
      "id": 18882,
      "value": "Skullcandy",
      "position": 0,
      "attribute_code": "brand"
    }
    ...
  ]
}

You will use the brand id when querying for the required documents.

Your product has no brand (like books)

You can safely ignore the step above. And ignore the query parameter brand_listdata_id below.

Get list of required documents

Now depend on if your product has a brand or not, perform the following request (with or without brand_listdata_id query parameter).

GET https://api.tiki.vn/integration/v2/requests/requiredDocs?category_id=218&brand_listdata_id=18804

response example

{
  "category": [
    {
      "id": 1,
      "name": "Giấy tờ khác",
      "position": 1,
      "created_at": null,
      "updated_at": null
    },
    {
      "id": 18,
      "name": "Quyết định xuất bản/ phát hành sách (Nếu Nhà bán là NXB/ phát hành) HOẶC Hợp Đồng Phân Phối kèm Hóa đơn GTGT/ Bảng kê có tựa sách  \nHoặc Giấy cam kết bảo lãnh NXB/ Công ty phát hành theo đúng mẫu Tiki (Tải tại : http://bit.ly/2qNwhBJ) (Nếu là đơn vị PP)",
      "position": 0,
      "created_at": null,
      "updated_at": null
    }
  ],
  "brand_is_required": false
}

These 2 documents must be provided in the product request payload as download links and Tiki will download it for you.

4. Ask Tiki supporter for your inventory_type

inventory_type is generated automatically when you sign a contract to sell product in TIKI.

In the simplest case also the most common case ( have only 1 inventory_type ).
You don’t even need to know what is your inventory type because we will use the type in your contract as default value.

And if you still want to learn more about TIKI system , you can refer to the following definition :

• inventory_type is a selected value answer some question
  • “Where are you from?”
  • “Tiki or seller have to bring product to the customer”
  • “TIKI come seller ‘s warehouse to take product or seller bring product to TIKI ‘s warehouse?”

Notes: In the case you have only one inventory type, TIKI will choose it as default value so you can ignore this field

5. Get seller warehouse

• If product’s inventory_type is instock, you don’t need to fill in seller_warehouse
• Otherwise, you need to get seller warehouse id.

Seller warehouse is warehouse of seller, that can transfer your product to. That help TIKI know
possibles warehouses can expected the product transfer to when customers placed order. It can be only one warehouse or multiple warehouses depend on you.

You can use get seller warehouse endpoint to get list of warehouse. The valid warehouse to create product must have status = 1 and type = 1 (status active and pickup warehouse)

Go to each endpoint details to see how to use them.

6. Create a product without variants

We do this by making a POST

POST https://api.tiki.vn/integration/v2.1/requests

With request body that includes exactly 1 variant

 {
  "category_id": 21458,
  "name": "Không gia đình",
  "description": "this is description",
  "market_price": 100000,
  "attributes": {
    "bulky": 0,
    "vat": "8",
    "publisher_vn": "BÁO TIỀN PHONG",
    "po_type": "111134"
  },
  "image": "https://images-na.ssl-images-amazon.com/images/I/715uwlmCWsL.jpg",
  "images": [
    "https://images-na.ssl-images-amazon.com/images/I/6110JInm%2BBL.jpg",
    "https://images-na.ssl-images-amazon.com/images/I/41FuQMh3FUL.jpg"
  ],
  "option_attributes": [],
  "variants": [
    {
      "sku": "B0055QD0EC2",
      "min_code": 124235,
      "price": 99000,
      "inventory_type": "cross_border",
      "seller_warehouse": "1054,1233",
      "warehouse_stocks": [
        {
          "warehouseId": 1054,
          "qtyAvailable": 3
        },
        {
          "warehouseId": 1233,
          "qtyAvailable": 5
        }
      ]
    }
  ],
  "certificate_files": [
    {
      "url": "https://kenh14cdn.com/2020/7/15/legialinhmeo672472714514751590239205770621637245080975n-15948258251531626115845.jpg",
      "type": "category",
      "document_id": 1
    },
    {
      "url": "https://i.pinimg.com/236x/16/83/c3/1683c385af85d756f8fab83a93d48063.jpg",
      "type": "category",
      "document_id": 18
    }
  ],
  "meta_data": {
    "is_auto_turn_on": true
  }
}

Do you still remember these values I said you need to save before?

They are category_id , attributes, inventory_type, certificate_files

You also have to provide some more field :

• Name: the name of product that is displayed on TIKI
• Price: the sell price of a product
• Market price : the price before discount of a product
• Description: describe the information of products
• Category: the primary category that products are belong. You must choose over Tiki Information APIs carefully
• Image: the avatar of product on TIKI
• Images: the image gallery of product on TIKI
• The other attributes are based on the category of products, like RAM/CPU/Screen. That’s why you need to choose category carefully at first

There are two kinds of product at TIKI: simple product and configurable products.

• Simple products are the products that has attributes and only one instance/variant
• Configurable products are the products that has many variants.

Configurable products has many variants. Example: an iPhone has many variants differ by colors.
They are called option_attributes.

7. If you want to create a configurable product

Configurable product request body

{
    "category_id": 21458,
    "name": "Disney Women's MK2106 Mickey Mouse White Bracelet Watch with Rhinestones",
    "description": "this is description",
    "market_price": 100000,
    "attributes": {
        "bulky": 0,
        "origin": "american",
        "brand_origin": "casio",
        "product_top_features": "White bracelet watch featuring rhinestone-accented bezel and mother-of-pearl dial with sparkling Mickey Mouse designn37-mm metal case with glass dial windownQuartz movement with analog displaynMetal alloy bracelet with jewelry-clasp closurenNot water resistantn",
        "brand": "Disney",
        "case_diameter": "37 millimeters",
        "filter_case_diameter": "37 millimeters",
        "band_material": "metal-alloy",
        "filter_band_material": "metal-alloy"
    },
    "image": "https://images-na.ssl-images-amazon.com/images/I/715uwlmCWsL.jpg",
    "images": [
        "https://images-na.ssl-images-amazon.com/images/I/6110JInm%2BBL.jpg",
        "https://images-na.ssl-images-amazon.com/images/I/41FuQMh3FUL.jpg"
    ],
    "option_attributes": [
        "size",
        "color"
    ],
    "variants": [
        {
            "sku": "B0055QD0EC2",
            "min_code": 12423534,
            "price": 99000,
            "option1": "XL",
            "option2": "red",
            "inventory_type": "cross_border",
            "seller_warehouse": "1054,1233",
            "warehouse_stocks": [
                {
                    "warehouseId": 1054,
                    "qtyAvailable": 3
                },
                {
                    "warehouseId": 1233,
                    "qtyAvailable": 5
                }
            ],
            "image": "https://images-na.ssl-images-amazon.com/images/I/715uwlmCWsLBY.jpg"
        },
        {
            "sku": "B0055QD0EC3",
            "min_code": 2395828523,
            "price": 99000,
            "option1": "L",
            "option2": "red",
            "inventory_type": "cross_border",
            "seller_warehouse": "1054,1233",
            "warehouse_stocks": [
                {
                    "warehouseId": 1054,
                    "qtyAvailable": 31
                },
                {
                    "warehouseId": 1233,
                    "qtyAvailable": 15
                }
            ],
            "image": "https://images-na.ssl-images-amazon.com/images/I/715uwlmCWsLBX.jpg"
        }
    ],
      "certificate_files": [
          {
              "url": "https://i.pinimg.com/236x/16/83/c3/1683c385af85d756f8fab83a93d48063.jpg",
              "type": "brand"
          },
          {
              "url": "https://kenh14cdn.com/2020/7/15/legialinhmeo672472714514751590239205770621637245080975n-15948258251531626115845.jpg",
              "type": "category",
              "document_id": 17
          },
          {
              "url": "https://i.pinimg.com/236x/16/83/c3/1683c385af85d756f8fab83a93d48063.jpg",
              "type": "category",
              "document_id": 18
          }
      ],
      "meta_data": {
        "is_auto_turn_on": false
      }
}

With configurable products:

• A configurable product has many variants and each variant maybe has its own attribute (examples : name, color…)
• The attributes that are used to differentiate two variants, are named option attributes. Example a T Shirt differ two variants by color and size but a phone differ by RAM & screen size.

Please fill data in option_attributes and option1,option2 field.

Let call below API to get option attributes:

GET https://api.tiki.vn/integration/v2/categories/{id}/optionLabels

Tiki support up to 2 option attributes ( size, color , capacity , … )
so if you have products with more than 2, combine them or create separate products before making a product request.

Example : you are selling iPhone by

• Model : 7, 8, XS, XS max, ..
• Color : Black , White , Gold , …
• Storage : 32GB , 64GB , 128GB

You can combine 3 single attributes into 2 aggregate attributes model andcolor + storage
or split each iPhone model into 1 product containing 2 option attributes color and storage.

• option1 is the value for the first option in option_attributes ( XL for size )
• option2 is the value for the last option in option_attributes ( red for color )

Example : Product is iPhone have "option_attributes":["color","storage"] so your variant should be

• “option1” : “Black” , “option2” : “32GB”
• “option1” : “Black” , “option2” : “64GB”
• “option1” : “White” , “option2” : “32GB”
• “option1” : “White” , “option2” : “64GB”
• “option1” : “White” , “option2” : “128GB”

If you want turn on product for sale after the request approved, use "is_auto_turn_on": true in "meta_data" block. Otherwise, that value set false.

Field	Type	Mandatory	Override rule(*)	Description
sku	String	Y	No	variant ‘s sku from source side
min_code	Long	N	No	identifier from the manufactory
price	Integer	Y	No	variant ‘s sell price
market_price	Integer	N	Replace	variant ‘s market price ( price before discount )
option1	String	N	No	attribute code of the first option attribute
option2	String	N	No	attribute code of the first second attribute
inventory_type(*)	String	N	No	inventory type of this variant
quantity	Integer	Y	No	number of products available for sell
seller_warehouse(*)	String	Y	No	see detail below
name	String	N	Replace	name of this variant
description	String	N	Replace	description of this variant
attributes	List<Attribute>	N	Merge	list specific/addition attribute for this variant
image	String	N	Replace	avatar url of this variant
images	String	N	Replace	list urls of variant product gallery

*Notes:

• option1, option2 is required corresponding with the number of option attributes start from 1. The unused option value maybe null or empty or even don’t need to appear.That’s why it’s mandatory still equal “no”
• Override rule describe how transform system will treat your product request if any field is conflict between variant and parent product. By default child product will inherit all of member from its parent.
• No : Field can’t not override
• Replace : Field of variant will replace the parent one.
• Merge : attributes will merged from both side.

8. How do I know when a product request is made successfully?

Once you click send product request you will be received a response immediately

This response means that your product request has been queued for processing.
If there are not too many requests then it will probably be done right away

Then use tracking_id to track the next state of the request. Maybe you can be received an error like this, just fix your payload based on the reason, after that send a new product request. Everything will be fine

GET https://api.tiki.vn/integration/v2/tracking/{track_id} 

After all , your product request ‘s status maybe become drafted or awaiting_approve.
Note that during the testing phase we temporarily change your state to drafted to double check both sides before we actually do it.
After both TIKI and seller confirm testing completed we will set the state to automatically skip drafted and switch to awaiting_approve from then on.
awaiting_approve means that your request is pending review by the team of TIKI content.

Your job is done, normally you will receive results after 2 to 3 hours of work.
By the time the status of the product request becomes approved, your product is ready on the TIKI website

9. Some common error while create product request

• option_attributes not valid → TIKI support 2 option attributes at most so if you need more than 2 option , please merge some of them before create product
• missing required attribute → try to map attribute → fill dummy data like “updating”
• image error → TIKI support image at 500×500 px at least for the best UI/UX → so please resize your invalid image if you don’t want to miss them
• certificate file is missing -> Check to see if categories and brands require documents -> provide them as image -> add to certificate_files array