ID market: "Tokopedia & Shop" Open API Integration One Pager

• Tokopedia & Shop - ISV & Seller developer onboarding guide
• Tokopedia & Shop - Migration rehearsal guide

<span style="background-color: rgb(255, 245, 235)">As we proceed with the Tokopedia & Shop seller integration project, we want to clearly communicate the following principles to ensure alignment across all partners.</span> <span style="background-color: rgb(255, 245, 235)">In accordance with Indonesia's laws and regulations, we hereby state that the use of </span><span style="background-color: rgb(255, 245, 235)"><strong>"TikTok"</strong></span><span style="background-color: rgb(255, 245, 235)"> branding or logo is not allowed and must be replaced by </span><span style="background-color: rgb(255, 245, 235)"><strong>"Tokopedia & Shop"</strong></span><span style="background-color: rgb(255, 245, 235)"> in all third-party partner services or features, such as custom shipping labels, custom invoices, and platform interfaces.</span> <span style="background-color: rgb(255, 245, 235)">Specifically for custom shipping labels, </span><span style="background-color: rgb(255, 245, 235)"><strong>we recommend avoiding additional logos and aligning with the branding generated by the e-commerce platform</strong></span><span style="background-color: rgb(255, 245, 235)">.</span>

<span style="background-color: rgb(255, 245, 235)">You can obtain the "Tokopedia & Shop" logo </span>here<span style="background-color: rgb(255, 245, 235)">.</span> <span style="background-color: rgb(255, 245, 235)">We appreciate your cooperation in following the applicable rules.</span>

---

Existing Independent Software Vendors (ISVs) or app developers that are providing services to the Indonesian market. <span style="background-color: rgb(255, 245, 235)">📌 </span><span style="background-color: rgb(255, 245, 235)"><strong>Note</strong></span><span style="background-color: rgb(255, 245, 235)">: New App developers should refer to </span>Tokopedia & Shop - ISV & Seller Developer Onboarding Guideline<span style="background-color: rgb(255, 245, 235)"> for detailed instructions on how to get started.</span>

This one-pager is designed to help existing developers understand which are the appropriate APIs to use with Tokopedia & Shop, and what are the differences compared with previous APIs.

In the Indonesian market, Tokopedia and TikTok Shop are currently undergoing a business merger. After the merger, the platform will update its brand to "Tokopedia & Shop". The merchants are expected to start migration in December 2024. After the merger:

• Only one merchant portal (Tokopedia & Shop Seller Center) and one set of Open APIs (TikTok Shop APIs) will be available
• Both user Apps — TikTok and Tokopedia — will remain available

Merchants can choose to sell products on one of these apps or both simultaneously. ISVs must use the TikTok Shop APIs to manage merchant operations on both apps. Once the merchant migration is complete, all newly generated data can only be accessed through the TikTok Shop APIs. Some historical data (such as merchant data) will be migrated to TikTok Shop, while other historical data (such as orders and bills) will remain in Tokopedia.

This document will explain in detail the key changes and processes following the merger:

1. Data access via APIs: What APIs to use to access new data and integrate historical data of merchants migrating from Tokopedia to "Tokopedia & Shop"?
2. Changes to TikTok Shop APIs: What changes are made in TikTok Shop APIs to suit the Indonesian market?
3. Mapping of shops and products: How will the new shops and products from "Tokopedia & Shop" be mapped to those from Tokopedia?

What APIs to use to access data for "Shop| Tokopedia"?

<span style="background-color: rgb(255, 245, 235)">📌 </span><span style="background-color: rgb(255, 245, 235)"><strong>Note</strong></span><span style="background-color: rgb(255, 245, 235)">: This one-pager is based on TikTok Shop API </span>version 202309 or later<span style="background-color: rgb(255, 245, 235)">. Please always use the latest API version to get the full capabilities of "Tokopedia & Shop". All existing APIs in the </span>online API reference list<span style="background-color: rgb(255, 245, 235)"> will be available in the Indonesian market, unless otherwise specified.</span>

Changes required for the "Tokopedia & Shop" merger will be developed and iterated based on the latest version of TikTok Shop APIs. All developers serving the Indonesian market, regardless of the type of merchant your are servicing (e.g. operating solely on TikTok Shop, migrating from Tokopedia, or new to "Tokopedia & Shop"), must integrate with this API upgrade.

The APIs that you will use moving forward vary based on your merchant type:

• Solely on TikTok Shop: The merchant has always operated solely on TikTok Shop.
• Access and manage all new and historical data through TikTok Shop APIs.
• Migration completed: The merchant has a Tokopedia store and has completed the migration to "Tokopedia & Shop".
• Access and manage all new data through TikTok Shop APIs.
• For historical data:
• Product data:
• Access and publish product information through TikTok Shop APIs since all types of product information will be automatically synchronized to "Tokopedia & Shop".
• Obtain information about the mapping between new and old products through Tokopedia's Get Product Info by Shop ID endpoint.
• Other data: Access all other Tokopedia data related to historical orders, fulfillment, return and refunds, promotion, finance, and customer service through Tokopedia OpenAPI.
• Pending migration: The merchant has a Tokopedia store but has not completed the migration to "Tokopedia & Shop".
• Continue to use Tokopedia OpenAPI for data access and business operations.

Products

Orders

Fulfillment

Logistics

Return and refund

Customer service

Affiliate

<span style="background-color: rgb(255, 245, 235)">📌 </span><span style="background-color: rgb(255, 245, 235)"><strong>Note</strong></span><span style="background-color: rgb(255, 245, 235)">: As of Oct 28, 2024, all the API changes mentioned in this document are released. You can view them in the online </span>API reference<span style="background-color: rgb(255, 245, 235)"> documentation.</span> The following content is only a preview of the API changes for "Tokopedia & Shop". Always refer to the online API reference documentation when designing your app features.

Create Products, Edit Products, Check Product Listing

Request (sample)

{
  ......
  "sku": {
      "pre_sale": {
          "type": "PRE_ORDER",
          "fulfillment_type" : {
              "handling_duration_days": 24
              "release_date": 1619611761
          }
      }
  }
  "listing_platform": ["TIKTOK_SHOP", "TOKOPEDIA"],
  "shipping_insurance_requirement": "MANDATORY",
  "is_pre_owned": false,
  "minimum_order_quantity": 4
}

Response (sample)

"data": {
    "errors":[ 
        {
            "code": 36002005,
            "message": "Error message here.",            
            "detail": {
                "listing_platform":"TIKTOK_SHOP"
            }
        }
    ],
    ......
}

Partial Edit Products

Request (sample)

{
  ......
  "listing_platform": ["TIKTOK_SHOP", "TOKOPEDIA"],
}

Response (sample)

"data": {
    "errors":[ 
        {
            "code": 36002005,
            "message": "Error message here.",            
            "detail": {
                "listing_platform":"TIKTOK_SHOP"
            }
        }
    ],
    ......
}

Search Products

Request (sample)

{
  ......
  "listing_platform": ["TIKTOK_SHOP", "TOKOPEDIA"],
}

Response (sample)

{
  ......
  "data": {
    "products": [
      {
        "integrated_platform_statuses": [{            
            "platform":"TOKOPEDIA",
            "status":"PLATFORM_DEACTIVATED"       
        }]
     }]
  }
} 

Get Product

Request (sample)

No changes

Response (sample)

{
  ......
  "data": {
    "audit_failed_reasons": [
      {
        "listing_platform": "TOKOPEDIA", 
        "position": "product",
        "reasons": [
          "violate listing rules"
        ],
        "suggestions": [
          "The product violates TikTok Shopping listing rules, please check and resubmit."
        ]
      }
    ]
    ......
    "skus": [
      {
        ......
      "pre_sale": {
          "type": "PRE_ORDER",
          "fulfillment_type" : {
              "handling_duration_days": 24
              "release_date": 1619611761
              }
          }
      }]
    "integrated_platform_statuses": [{            
      "platform":"TOKOPEDIA",
      "status":"PLATFORM_DEACTIVATED"       
    }]
    "shipping_insurance_requirement": "MANDATORY",
    "is_pre_owned": false,
    "minimum_order_quantity": 4  
  }
}

Activate Product

Request (sample)

{
  ......
  "listing_platform": ["TIKTOK_SHOP", "TOKOPEDIA"],
}

Response (sample)

{
  "code": 0,
  "data": {
    "errors": [
      {
        "code": 12052990,
        "detail": {
          "extra_errors": [
            {
              "code": 12052003,
              "message": "The current product status can not be activated"
            }
          ],
          "product_id": "1729382588639839583",
          "listing_platform": "TIKTOK_SHOP"
        },
        "message": "Batch activate business error."
      }
    ],
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}

Deactivate Product

Request (sample)

{
  ......
  "listing_platform": ["TIKTOK_SHOP", "TOKOPEDIA"],
}

Response (sample)

No changes

Recommend Category, Get Categories

Request (sample)

{
  ......
  "listing_platform": ["TOKOPEDIA"],
}

Response (sample)

{
  "code": 0,
  "data": {
    "categories": [
      {
        "id": "605254",
        "is_leaf": true,
        "level": 1,
        "name": "Teas",
        "permission_statuses": "[INVITE_ONLY]",
      }
    ],
    "leaf_category_id": "605254"
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}

Get Order Detail, Get Order List

Request (sample)

No changes

Response (sample)

{
  "data": {
    "orders": [
      ......
      "payment": {
        ......
        "shipping_insurance": "5000",
        "item_insurance": "5000",
      },
      "recipient_address": {
        ......
      },
      "commerce_platform": "TOKOPEDIA",
    ]
  ....
}

Get Warehouse List

Request (sample)

No changes

Response (sample)

{
  "code": 0,
  "data" : {
    ......
    "geolocation": {
      "latitude": "45.41634",
      "longitude": "-75.6868"
    }
  }
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}

Ship Package, Batch Ship Package

Request (sample)

No changes

Response (sample)

No major changes, only added error codes

• 11021035: Fail to ship package because shipments can only be made within the collection time
• 11021036: No available shipping services for this request, because there is no collection time. Please contact platform customer service

Get Warehouse Delivery Options

Request (sample)

No changes

Response (sample)

{
    "code": 0,
    "data": {
        "delivery_options":[
            {
                "id": "7129437321920775979",
                "name": "LSV-TTS-STD",
                "type":"STANDARD",
                "platform":["TOKOPEDIA","TTS_SHOP"]
                "description":"LSV-TTS-STD S"
                "item_dimension_limit": {
                    "height": 5,
                    "length": 5,
                    "width": 5,
                    "unit":"INCH"
                },
                "item_weight_limit": {
                    "max_weight": 10,
                    "min_weight": 0,
                    "unit":"GRAM"
                }
            }
         ]
    }
}

Search Returns

Request (sample)

No changes

Response (sample)

{
  ......
  "data": {
    ......
    "return_warehouse_address": {
      "full_address": "full_address",
      "address_line1": "address_line1",
      "address_line2": "address_line2",
      "address_line3": "address_line3",
      "address_detail": "address_detail"
    }
  }
}

Get Conversations

Request (sample)

No changes

Response (sample)

{
  ......
  "data": {
    ......
    "participants" [
      {
        ......
        "buyer_platform": "TOKOPEDIA"
      }
    ]
  }
}

Generate Affiliate Sharing Link

Request (sample)

{
    "material": {
        "material_id": "1729624807198591373",
        "type": 1
    },
    "channel": "Shopback",
    "tags": [
        "111-WA-ABC",
        "222-CC-DD"
    ]
}

Response (sample)

{
    "code": 0,
    "data": {
        "affiliate_sharing_links": [
            {
                "tag": "111-bbb",
                "affiliate_sharing_link": "www.tiktok.com/asdsfe1c"
            },
            {
                "tag": "121-ccc",
                "affiliate_sharing_link": "www.tiktok.com/afasdasd"
            }
        ],
        "errors": [
            {
                "code": 16661001,
                "msg": "tag invalid",
                "detail": {
                    "tag": "222-ccc",
                    "fail_reason": "tag exceed limit"
                }
            }
        ]
    },
    "message": "Success",
    "request_id": "202203070749000101890810281E8C70B7"
}

Product mapping

You can utilize the Get Product Info endpoint from the Tokopedia API by providing either the product ID or shop ID from TikTok Shop or Tokopedia as parameters.

Using product ID

1. Endpoint: /inventory/v1/fs/:fs_id/product/info?product={{product_id}
2. Replace {product_id} with your specific product ID from either TikTok Shop or Tokopedia.
3. Parameters:
4. shop_id: Optional, but providing this helps narrow down the search.
5. product_id: The specific product ID from either TikTok Shop or Tokopedia.
6. Example request:

GET /inventory/v1/fs/:fs_id/product/info?product=123456?shop_id=78910
Authorization: Bearer {access_token}

Replace 123456 with the actual product ID and 78910 with the shop ID.

JSON Response Example:

{
  "status": "success",
  "data": {
    "product_id": "123456",
    "product_name": "Sample Product",
    "shop_id": "78910",
    "tts_product_id": "4324578910", 
    "price": 100000,
    "stock": 50,
    "category": "Fashion",
    "brand": "Brand A"
  }
}

In this response:

• product_id: Represents the Tokopedia product ID.
• tts_product_id: Represents the mapped TikTok Shop product ID.
• Other relevant details like product_name, price, and stock are also included.

Shop mapping

For shop mapping, you can either use the [Get Shop Info] endpoint from the Tokopedia API or manually check the relationship through TikTok Shop Partner Center (TTSPC).

Using Tokopedia Get Shop Info endpoint

1. Endpoint: /v1/shops/{shop_id}
2. Replace {shop_id} with your specific Tokopedia shop ID.
3. Parameters:
4. shop_id: The unique identifier for the shop from either TikTok Shop or Tokopedia.
5. Example request:

GET /v1/shop/fs/:fs_id/shop-info
Authorization: Bearer {access_token}

Replace 78910 with the actual shop ID.

JSON response example:

{
  "status": "success",
  "data": {
    "shop_id": "78910",
    "shop_name": "Sample Shop",
    "tts_shop_id": "TTS123456",
    "location": "Jakarta",
    "owner_name": "Pungky",
    "products_count": 150
  }
}

In this response:

• shop_id: Represents the Tokopedia shop ID.
• tts_shop_id: Represents the mapped TikTok shop ID.

Manually checking via TikTok Shop Partner Center (TTSPC):

You can log in to the TTSPC dashboard to check the mapping relationship between TikTok Shop and Tokopedia shops. This is useful for verifying or cross-referencing the mapping data obtained from the APIs.

To ensure your shops are successfully migrated, Tokopedia provides two options for checking the migration status: Get Shop Info API and Webhook Migration Status. Both options will be available by the end of November 2024.

Using the Get Shop Info API

Get Shop Info API allows you to retrieve the migration status for the shops you manage. Steps:

1. Call the Get Shop Info API using the relevant shop identifier (e.g., shop_id or user_id).
2. Check the response payload for the tts_integration_completed field.

API Response Example:

{
  "shop_id": 11111,
  "user_id": 1111,
  "shop_name": "shop",
  ...
  "tts_integration_completed": {
    "toko_shop_id": 11111,
    "tts_seller_id": 111111,
    "completed_time": 11111111
  }
}

Key Indicators:

• toko_shop_id: Indicates the Tokopedia shop ID.
• tts_seller_id: Confirms the TikTok Shop seller ID.
• completed_time: The timestamp of the migration completion.

Action:

If tts_integration_completed is present, the migration is complete. Otherwise, the shop has not yet been migrated.

<span style="background-color: rgb(255, 245, 235)">📌 </span><span style="background-color: rgb(255, 245, 235)"><strong>Note</strong></span><span style="background-color: rgb(255, 245, 235)">: To avoid exceeding rate limits and ensure efficient server utilization, implement a </span><span style="background-color: rgb(255, 245, 235)"><strong>5-minute interval</strong></span><span style="background-color: rgb(255, 245, 235)"> for API calls.</span>

Using the Webhook Migration Status

Webhook Migration Status notifies you of real-time updates on shop migration activities.

Webhook Payload Example:

{
    "status": "merge",
    "tts_seller_id": "123456",
    "toko_shop_id": "654321",
    "timestamp": 1697678931
}

Payload Fields:

• status: Indicates whether the shop has completed migration (merge) or is separate (unmerge).
• tts_seller_id: The TikTok Shop seller ID.
• toko_shop_id: The Tokopedia shop ID.
• timestamp: The time of the status update.

To effectively monitor shop migration statuses, it's essential to register a webhook with Tokopedia. This setup ensures you receive real-time notifications about any changes.

Registering a Webhook with Tokopedia

Tokopedia provides an API endpoint to register your webhook URL, enabling you to receive event notifications. API Endpoint: POST /v1/fs/{FSID}/register Request Headers:

• Authorization: Bearer token for authentication
• Content-Type: application/json

Example Request:

curl --location 'https://fs.tokopedia.net/v1/fs/{FSID}/register' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer c:{Authorization bearer token}' \
--data '{
    "fs_id": {FSID},
    "shop_merge_notification_url": "https://webhook.test.com/callback/message/tokopedia/pushMessageCallback"
}'

Shop mirroring is a process that automatically syncs TikTok Shop listings to the Tokopedia storefront, effectively creating a virtual store on the Tokopedia marketplace for sellers originating from TikTok Shop. This process requires listing all items on the Tokopedia storefront and establishing a mapping relationship between the two platforms.

This feature is only available for selected sellers. TikTok Shop sellers that are whitelisted to use the shop mirroring feature can use the shop mirroring webhook to get notifications on changes in the mirroring status.