Connecting shops

A core scenario for TikTok Shop API developers is to create, manage, and disconnect a persistent connection between a local customer account in your system and that customer's TikTok Shop seller account.

Seller authorization only: This guide applies to Seller authorization, where a customer authorizes your app to access TikTok Shop Seller and shop data. Creator authorization and partner authorization use different entry points and may authorize different data owners. See Creator authorization guide and Partner authorization guide if your app needs creator-owned or partner-owned data.

Authorization entry points and API endpoints

Use different domains for authorization, token exchange, and Open API calls. Do not use an authorization entry domain as the Open API request host.

Authorization types are not interchangeable:

Manage TikTok Shop connections

A basic requirement for this use case is indexing your local customer data to TikTok Shop data. This allows you to look up the credentials and shop identifiers needed to call TikTok Shop APIs on a customer's behalf. You must securely store your customer's TikTok Shop access and refresh tokens and associate them with your own local customer identifier. An access_token is the credential used to access customer data, but it does not contain enough shop-identifying information by itself. Store the token response and authorized shop data together so you can retrieve the correct token and shop identifiers when making API calls. You must also store token expiration timestamps so your system can refresh tokens before access expires and reauthorize the app when refresh access expires.

If you serve customers with cross-border shops in China, also store the shop_cipher associated with each TikTok Shop. shop_cipher is required by many shop-scoped endpoints for cross-border shops in China. It is optional for local shops in the US, UK, and SEA markets unless an endpoint reference explicitly requires it.

Finally, we recommend storing all TikTok Shop metadata returned by Get Authorized Shops, because it does not change frequently. Also provide a way for customers to refresh their TikTok Shop data from your application or connector, because customers are most likely to know when their shop details have changed. Image Text alternative for the diagram: the customer authorizes your app, TikTok Shop redirects to your callback URL with a one-time code, your backend exchanges that code for tokens, and your backend stores the token response against your local customer record. Later, your backend uses the stored access_token and x-tts-access-token header to call TikTok Shop Open APIs. The call flow is:

1. Your customer authorizes your TikTok Shop App to access their TikTok Shop Seller data. If your app is published in the TikTok Shop App Store, the customer authorizes it by clicking the Install button. Otherwise, provide a Seller authorization link so the customer can sign in with their TikTok Shop Seller account and authorize your app.
2. After authorization, TikTok Shop calls your configured callback URL with URL parameters, including code. This code is a short-lived, one-time authorization code. Do not store it as a reusable credential.
3. Exchange the code for an access token and refresh token by calling the token endpoint from your backend:

GET https://auth.tiktok-shops.com/api/v2/token/get?app_key={app_key}&app_secret={app_secret}&auth_code={code}&grant_type=authorized_code

Required query parameters:

Example successful token response:

{
  "code": 0,
  "message": "success",
  "data": {
    "access_token": "TTP_example_access_token",
    "access_token_expire_in": 1660556783,
    "refresh_token": "TTP_example_refresh_token",
    "refresh_token_expire_in": 1691487031,
    "open_id": "7010736057180325637",
    "seller_name": "Example Shop",
    "seller_base_region": "ID",
    "user_type": 0,
    "granted_scopes": [
      "seller.affiliate_collaboration.read",
      "seller.affiliate_collaboration.write"
    ]
  },
  "request_id": "2022080809462301024509910319695C45"
}

Token field quick reference:

Connecting a single shop

Use this model if each local customer account can connect to only one TikTok Shop and you do not plan to support multiple TikTok Shops for the same customer. In your local data store, CustomerID can be unique in the shop connection table because each customer maps to only one shop connection. Image Text alternative for the diagram: one local customer record maps to one TikTok Shop row. The row stores the customer identifier, token metadata, and the shop data returned by Get Authorized Shops.

Connecting multiple shops

Use this model if a customer can have more than one TikTok Shop associated with their TikTok Seller account, or if you may support this in the future. In your local data store, CustomerID cannot be the unique key in the shop connection table because one customer may have multiple shop rows. Use a composite key such as CustomerID + shop_cipher or CustomerID + shop_id, depending on the identifiers required by your endpoints and internal data model. Image Text alternative for the diagram: one local customer record maps to multiple TikTok Shop rows. Each row stores the same local customer identifier and a different TikTok Shop identifier, shop cipher, and shop metadata.

Single-shop and multiple-shop comparison

Both connection models use the same token exchange and Get Authorized Shops API. The key difference is how you model the local customer-to-shop relationship.

To retrieve authorized shop data in either model:

• Retrieve the stored access_token for the local customer.
• Call Get Authorized Shops:

GET https://open-api.tiktokglobalshop.com/authorization/202309/shops?app_key={app_key}&timestamp={timestamp}&sign={sign}
Content-Type: application/json
x-tts-access-token: {access_token}

• Read the returned data.shops array. Each object represents a TikTok Shop authorized by the Seller token.
• Store the returned shop fields, especially identifiers such as cipher, id, code, name, region, and seller_type, against your local customer record.

Example response shape:

{
  "code": 0,
  "data": {
    "shops": [
      {
        "cipher": "ROW_xkMbgAAAeVAQra0eZWebFQq5aIK",
        "code": "123456789",
        "id": "7495355150342452340",
        "name": "Example TikTok Shop",
        "region": "US",
        "seller_type": "LOCAL"
      }
    ]
  },
  "message": "Success",
  "request_id": "20230901000000000000000000000000"
}

Next steps

Once you have connected one or more TikTok Shops, implement an authorization expiration webhook listener and add functionality to disconnect a shop. Use the reauthorization flow for authorization-expiration or deauthorization events so customers can reconnect their shop when access is still required.