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:

To show this prompt, direct the user to this URL:

https://merchant.wish.com/oauth/authorize?client_id={client_id}

With {client_id} replaced by the your app's ID (without the braces). 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.

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:

POST https://merchant.wish.com/api/v2/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.

Example

Assume your client id was 55c277347770e02e65d4cd83, your client_secret was 123456789012345678901234, your redirect uri was https://example.com and your authorization code was 111222333444555666.

Example Request

> curl https://merchant.wish.com/api/v2/oauth/access_token -d "client_id=55c277347770e02e65d4cd83&client_secret=123456789012345678901234&code=111222333444555666&redirect_uri=https%3A%2F%2Fexample.com&grant_type=authorization_code"
<?php

$client_id = urlencode('55c277347770e02e65d4cd83');
$client_secret = urlencode('123456789012345678901234');
$code = urlencode('111222333444555666');
$redirect_uri = urlencode('https://example.com');

$url = sprintf(
    "https://merchant.wish.com/api/v2/oauth/access_token?&client_id=%s&client_secret=%s&code=%s&redirect_uri=%s&grant_type=authorization_code", $client_id, $client_secret, $code, $redirect_uri);

$context = stream_context_create(array(
    'http' => array(
        'method'        => 'POST',
        'ignore_errors' => true,
    ),
));

// Send the request
$response = file_get_contents($url, TRUE, $context);
echo $response;
echo "\n";
?>
<?php
require_once 'vendor/autoload.php';

use Wish\WishAuth;

$client_id = 'CLIENT_ID';
$client_secret = 'CLIENT_SECRET';
$code = 'AUTH_CODE';
$redirect_uri = 'REDIRECT_URI';

$auth = new WishAuth($client_id,$client_secret,'prod');
$response = $auth->getToken($code,$redirect_uri);

$access_token = $response->getData()->access_token;
$refresh_token = $response->getData()->refresh_token;
?>

Example Response

{
    'message' : '',
    'code' : 0,
    'data' : { 'access_token' : '1qaz2wsx3edc4rfv5tgb',
               'refresh_token' : 'mju7nhy6bgt5vfr4cde3',
               'expires_in' : 86400,
               'expiry_time' : 1438922740,
               'expiry_string': '2015-08-07 04:45:40 UTC'
             }
}

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:

POST https://merchant.wish.com/api/v2/auth_test
Parameters
access_tokenYour access token

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

Step 5: Obtaining New Access Tokens

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:

POST https://merchant.wish.com/api/v2/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.

Example

Assume your client id was 55c277347770e02e65d4cd83, your client_secret was 123456789012345678901234, and your refresh token was mju7nhy6bgt5vfr4cde3.

Example Request

> curl https://merchant.wish.com/api/v2/oauth/refresh_token -d "client_id=55c277347770e02e65d4cd83&client_secret=123456789012345678901234&refresh_token=mju7nhy6bgt5vfr4cde3&grant_type=refresh_token"
<?php

$client_id = urlencode('55c277347770e02e65d4cd83');
$client_secret = urlencode('123456789012345678901234');
$refresh_token = urlencode('mju7nhy6bgt5vfr4cde3');

$url = sprintf(
    "https://merchant.wish.com/api/v2/oauth/refresh_token?&client_id=%s&client_secret=%s&refresh_token=%s&grant_type=refresh_token",
    $client_id, $client_secret, $refresh_token);

$context = stream_context_create(array(
    'http' => array(
        'method'        => 'POST',
        'ignore_errors' => true,
    ),
));

// Send the request
$response = file_get_contents($url, TRUE, $context);
echo $response;
echo "\n";
?>
<?php
require_once 'vendor/autoload.php';

use Wish\WishAuth;

$client_id = 'CLIENT_ID';
$client_secret = 'CLIENT_SECRET';
$refresh_token = 'REFRESH_TOKEN';

$auth = new WishAuth($client_id,$client_secret,'prod');
$response = $auth->refreshToken($refresh_token);

$access_token = $response->getData()->access_token;
?>

Example Response

{
    'message' : '',
    'code' : 0,
    'data' : { 'access_token' : '1qaz2wsx3edc4rfv5tgb',
               'refresh_token' : 'mju7nhy6bgt5vfr4cde3',
               'expires_in' : 86400,
               'expiry_time' : 1438922740,
               'expiry_string': '2015-08-07 04:45:40 UTC'
             }
}

Handling Errors and Debugging

In the event of an error, the Wish API will return an error code and an error message. Some common errors are listed below.

CodeErrorExplanation
1001 Missing Parameter A required parameter was missing in your request. Please review this guide and make sure you included all the necessary parameters.
1015 Access Token Expired Access tokens expire after a period of time. To learn how to renew your access tokens, see Step 5.
1016 Access Token Revoked This means that the access token has been disabled. A common cause for this is the generation of a new access token; when a token is generated, earlier tokens will be revoked. If all tokens are revoked, the user will need to authorize your app again.
1017 Authorization Code Expired Authorization codes expire after a short period of time. When you receive your authorization code at the redirect URI, you should immediately exchange it for an access token.
1018 Access Token Redeemed This means that the authorization code has already been used to redeem a token. For security reasons, each authorization code can only be used once.
4000 Unauthorized Access This means that there was something wrong with the authorization of your request. This error will happen if your access token or authorization code are not recognized.
9000 Unknown This is an unrecognized error, and should rarely happen. Please notify Wish if you receive this error.