Overview

Your app cannot access Wish data without authenticating itself first. Wish uses the OAuth 2.0 specification to identify which apps are allowed access to resources. This guide will walk you through the authentication process.

Terminology

Here's a list of terms you should be familiar with while reading this guide.

  • App

    The app, or the client, is any application that would like to access a merchant's data on Wish.

  • User

    The user is someone with a merchant account on Wish. This is the person giving permission to the app to access their data.

  • Access Token

    The access token is the app's password that it uses to access users' data.

Step 1: Asking for Permission

The first step is to get permission from the user. This is done by displaying the following prompt:

There are two ways for merchants to receive this prompt:

  1. The merchant finds your app in the Wish App Store and clicks the "Add app" button.
  2. The merchant is linked to the following URL:
    https://china-merchant.wish.com/v3/oauth/authorize?client_id={client_id}

    With {client_id} replaced by your app's ID (without the braces). client_id is a required parameter. This will open up the page on the user's dashboard. The user must be logged in to their merchant account on Wish to see this prompt.

Step 2: Receiving the Authorization Code

After the user grants permission to your app, Wish will redirect the user to the redirect URI specified when the app was created. One of the parameters of this request is the Authorization Code (without the braces).

https://example.redirect.uri.com?code={authorization_code}

This authorization code can now be exchanged for an access token. Keep in mind, some merchants may not be logged in or have an account with your service. Make sure to handle this case by prompting the merchant to log in or sign up first, and then use the authorization_code to continue with the OAuth process.

Please note the authorization code will expire after 5 minutes and can only be used once.

Step 3: Obtaining the Access Token

To obtain an access token, your app must make the following request:

GET https://china-merchant.wish.com/api/v3/oauth/access_token
Parameters
client_idYour app's client ID
client_secretYour app's client secret
codeThe authorization code you received
grant_typeThe string 'authorization_code'
redirect_uriYour app's redirect uri that you specified when you created the app

Wish will respond with an access token and a refresh token. Your app should store both these tokens somewhere. The access token is used to make authorized requests, and the refresh token is used to obtain new access tokens. Wish will also respond with a merchant user ID, which uniquely identifies the user that authorized your client.

For security, our access tokens are temporary, and will expire after 30 days. To obtain a new access token, see Step 5 of this guide.

Step 4: Making Authorized Requests

To make an authorized request, add the following to the request header:

Authorization: Bearer {access_token}

Alternatively, you can also add the access token as a parameter in the body of a request. For example, you can use the following endpoint to test your access token:

GET https://china-merchant.wish.com/api/v3/oauth/test
Parameters
access_tokenYour access token

For a full guide to our API endpoints, click here.

Step 5: Refreshing Access Token

Access tokens expire after a certain period of time. In order to obtain a new access token without going through the full oAuth process again, your app can make the following request:

GET https://china-merchant.wish.com/api/v3/oauth/refresh_token
Parameters
client_idYour app's client ID
client_secretYour app's client secret
refresh_tokenYour refresh token
grant_typeThe string 'refresh_token'

Please note that your existing access token will be revoked.