Guides
Start typing to search…

Token Exchange

To get Customer Access Token, you need to first obtain an authorization code, then use this authorization code to exchange token.

1. Get authorization code

To begin the process, we call GET /oauth/authorize to obtain an authorization code. After the user grants permission, the authorization server redirects to your redirect_uri with an authorization code.

Request Method: GET

Request Host: shop host (e.g. https://{{handle}}.shoplineapp.com)

Request Endpoint: /oauth/authorize

Request Body: N/A

Request Parameter:

NameTypeExample
response_typeStringcode
client_idString<client id from Open API oauth application>
redirect_uriString<self defined redirect uri>
scopeStringshop

Request URL example:

GET {{shop_host}}/oauth/authorize?response_type=code&client_id={{client_id}}&redirect_uri={{redirect_uri}}&scope=shop

Redirect URI example:

{{redirect_uri}}?code={{authorization_code}}

Save the authorization code of the query string from redirect uri for later step.

📘

Authorization code is one-time use only

The authorization code is by specification one-time use only.

You need to generate another new authorization code to exchange for a new access token.

2. Exchange token with authorization code

Once you receive the authorization code, call POST /oauth/token to exchange it for a Customer Access Token.

Request Method: POST

Request Host: shop host (e.g. https://{{handle}}.shoplineapp.com)

Request Endpoint: /oauth/token

Request Body:

NameTypeExample
grant_typeStringauthorization_code
codeString<authorization code retrieved from /oauth/authorize>
redirect_uriString<same redirect_uri as /oauth/authorize>
client_idString<client id from Open API oauth application>
client_secretString<client secret from Open API oauth application>

Request URL example:

POST {{shop_host}}/oauth/token

Example Response:

Status Code

Example Response Body

200 OK

The request was successful, and the access_token, refresh_token is returned as customer access token and customer refresh token.

{  
    "access_token": "xxx",  
    "token_type": "Bearer",  
    "expires_in": 15778476,  
    "refresh_token": "xxx",  
    "scope": "shop",  
    "created_at": 1742791521,  
    "merchant": {  
        "\_id": "6270afa09ece2a273289d796",  
        "email": "[email protected]",  
        "handle": "mary581",  
        "name": "Mary's Store"  
    },  
    "user": {  
        "\_id": "63292fb4cff523028659b38c",  
        "email": "[email protected]",  
        "locale_code": "en",  
        "name": "Mary"  
    }  
}

400 Bad Request

Invalid or missing parameters, such as grant_type, code, redirect_uri, client_id, or client_secret.

{  
    "error": "invalid_grant",  
    "error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client."  
}

401 Unauthorized

Invalid client id or client secret

{  
    "error": "invalid_client",  
    "error_description": "Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method."  
}

Updated 2 days ago