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:

Name	Type	Example
response_type	String	code
client_id	String	<client id from Open API oauth application>
redirect_uri	String	<self defined redirect uri>
scope	String	shop

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:

Name	Type	Example
grant_type	String	authorization_code
code	String	<authorization code retrieved from /oauth/authorize>
redirect_uri	String	<same redirect_uri as /oauth/authorize>
client_id	String	<client id from Open API oauth application>
client_secret	String	<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." }