Reauthorize shops

Once you have connected one or more TikTok Shops, your client application or connector should remind sellers before their authorization expires and guide them through reauthorization so access to TikTok Shop Seller data can continue. This guide focuses on upcoming authorization expiration. It assumes you already store token and shop connection data as described in Connecting shops.

Event scope

Do not treat upcoming authorization expiration and deauthorization as the same event.

Reminder strategy

Use the webhook as the primary signal, and keep a local fallback based on refresh_token_expire_in in case webhook delivery fails. Recommended reminder timing:

If your product has low-frequency seller logins, start external reminders earlier, such as 30 or 14 days before expiration. If the seller logs in daily, in-product reminders at 14 and 7 days may be enough.

Configure the webhook

You can configure shop webhooks in Partner Center or by API. In Partner Center, open your app or service and go to the webhook or event subscription settings:

Partner Center Console
  -> App & Service
  -> Select your app or service
  -> Webhooks / Event subscriptions
  -> Add or update UPCOMING_AUTHORIZATION_EXPIRATION

Console labels may vary by Partner Center version. The important part is that the webhook topic must be UPCOMING_AUTHORIZATION_EXPIRATION and the callback URL must be your HTTPS webhook listener. To configure the same event programmatically, call Update Shop Webhook:

PUT https://open-api.tiktokglobalshop.com/event/202309/webhooks?app_key={app_key}&timestamp={timestamp}&sign={sign}&shop_cipher={shop_cipher}
Content-Type: application/json
x-tts-access-token: {access_token}

{
  "address": "https://example.com/tiktok-shop/webhooks",
  "event_type": "UPCOMING_AUTHORIZATION_EXPIRATION"
}

Use the exact endpoint reference for the latest required query parameters. For shop-scoped webhook configuration, include shop_cipher when the endpoint requires it.

Webhook payload

When your listener receives UPCOMING_AUTHORIZATION_EXPIRATION, validate the event type and map the payload to the local customer and shop connection. Example payload:

{
  "event_type": "UPCOMING_AUTHORIZATION_EXPIRATION",
  "shop_id": "7495355150342452340",
  "timestamp": 1696909648,
  "data": {
    "message": "Authorization for this TikTok Shop will expire soon.",
    "expiration_time": 1699501648
  }
}

Payload field quick reference:

Store the latest expiration reminder state against the local customer and shop connection. Do not treat data.message as the source of truth for business logic; use data.expiration_time and your stored token metadata.

Reauthorization flow

Reauthorization uses the same Seller authorization flow as the first connection. The seller must authorize your app again, your callback receives a new code, and your backend exchanges that code for a new access_token and refresh_token. Use the Seller authorization entry that matches the seller region. You can find service_id in Partner Center:

Partner Center Console
  -> App & Service
  -> Select your app or service
  -> Basic Information
  -> Service ID

Use the same authorization-link parameters as your first-time connection flow. The redirect URL is the callback URL configured for the app in Partner Center. state is strongly recommended so you can map the callback back to the local customer and shop connection; validate it before exchanging the returned code for new tokens. The reauthorization flow is:

1. Receive UPCOMING_AUTHORIZATION_EXPIRATION or detect that refresh_token_expire_in is approaching.
2. Mark the shop connection as reauthorization_required or an equivalent internal status.
3. Show the seller a clear reauthorization action.
4. Send the seller through the same Seller authorization link used by Connecting shops.
5. Receive the callback code.
6. Exchange the code for new tokens through the token endpoint.
7. Replace the stored token values and clear the reminder state for that shop connection.

Listener behavior

Your webhook listener should be idempotent. TikTok Shop may send the upcoming-expiration notification repeatedly, so receiving the same reminder more than once should update the existing reminder state instead of creating duplicate customer tasks. Recommended behavior:

Next steps

After you have implemented the upcoming authorization expiration listener, add functionality to disconnect a shop and handle seller deauthorization as a separate lifecycle event.