If you are an agency or service provider, see Recharge Agency Partner Program for more information. If you are a SaaS/technology vendor, see Recharge Technology Partner Program for more information. You'll need to be accepted into one of these programs to get a partners account and build a partner application using the following steps.

If you are exploring building an integration/application using the Recharge API, you are encouraged to first manually generate an API token after you configure a test store with Recharge. Build your application using the API prior to building a partner application. This ensures you've already proven concept, found product market fit with merchants, and know what API scopes you'll need for a partner app.

Step 1. - Create an app in the Partner admin

1. Login to your Partners account
2. Navigate to Apps > Create an app

🚧

Note:

Make sure to set the correct scopes your app will require, as shops will need to set those same scopes when installing your app.

Additional parameters you will need to set when creating the app:

Upon persisting your app creation your app will be assigned the below two IDs:

Step 2. - User authorization and grant request

A customer wanting to install your app should visit the following link. These links will vary based on the platform, BigCommerce or Shopify. See the following table.

For example, if your store's URL is snowdevil.myshopify.com with the corresponding client ID d123[....]efg456, the auth link would look like this:

https://admin.rechargeapps.com/partners/app/**d123[....]efg456**/install?myshopify_domain=**snowdevil**

This URL will force the user to install Recharge if they do not already have it installed and will load your app’s permissions page, including the scopes you defined within your partner account app page.

Once you have approved the installation, we will redirect to your callback URL with the following query parameters appended to the callback link you provided during the app set up.

For example, if the callback URL was Shopify store https://www.zombo.com we will execute a GET to https://www.zombo.com?myshopify_domain=snowdevil&code=0xdeadbeef

The temporary authorization code expires after a few minutes — promptly exchange it for a permanent access token. See the next step.

Step 3. - Token exchange

Exchanging a temporary authorization code for permanent access token.

Make the below POST request to the Recharge OAuth endpoint with the following parameters:

POST tohttps://www.admin.rechargeapps.com/oauth/token

Example `POST

curl -X POST \
https://www.admin.rechargeapps.com/oauth/token 
-d "code=0xDEADBEEF&redirect_uri=https://your_domain.com&grant_type=authorization_code&client_id=your_client_id"

import requests
import json

headers = {
  "Content-Type": "application/x-www-form-urlencoded"
}
url = "https://www.admin.rechargeapps.com/oauth/token"
data = {
  "code": "0xDEADBEEF",
  "grant_type": "authorization_code",
  "redirect_uri": "https://your_domain.com",
  "client_id": "<client_id here>"
}

result = requests.post(url, data=data, headers=headers)

<?php

$request = new HttpRequest();
$request->setUrl('https://www.admin.rechargeapps.com/oauth/token');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'content-type' => 'application/x-www-form-urlencoded'
));

$request->setBody('{
  "code": "0xDEADBEEF",
  "grant_type": "authorization_code",
  "redirect_uri": "https://your_domain.com",
  "client_id": "<client_id here>"
}');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://www.admin.rechargeapps.com/oauth/token")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/x-www-form-urlencoded'
request.body = "{\n\"code\":\"0xDEADBEEF\",\n\"grant_type\":\"authorization_code\",\n\"redirect_uri\":\"https://your_domain.com\"\n,\"client_id\":\"<client_id here>\"\n}"

response = http.request(request)
puts response.read_body

Example response

{
  "access_token": "WzJ8FayZ2FrcBUpePPwmYjf1wp4Xob",
  "token_type": "Bearer",
  "refresh_token": "Vs5a5I7OUxY6P4rCmRpWVQXTckvi0S",
  "scope": "store_info read_orders"
}

Step 4. - Token refresh

Refreshing a token is very similar to the authorization code exchange.

POST to https://www.admin.rechargeapps.com/oauth/token

Example POST

curl -X POST \
https://www.admin.rechargeapps.com/oauth/token \
-d "grant_type=refresh_token&client_id=your_app_client_id_here&refresh_token=your_refresh_token_here"

import requests
import json

headers = {
  "X-Recharge-Access-Token": "your_api_token",
  "Accept": "application/json",
  "Content-Type": "application/x-www-form-urlencoded"
}
url = "https://www.admin.rechargeapps.com/oauth/token"
data = {
  "grant_type": "refresh_token",
  "client_id": "your_app_client_id_here",
  "refresh_token": "your_refresh_token_here"
}

result = requests.post(url, data=json.dumps(data), headers=headers)

<?php

$request = new HttpRequest();
$request->setUrl('https://www.admin.rechargeapps.com/oauth/token');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'content-type' => 'application/x-www-form-urlencoded',
  'x-recharge-access-token' => 'your_api_token'
));

$request->setBody('{
"grant_type": "refresh_token",
"client_id": "your_app_client_id_here",
"refresh_token": "your_refresh_token_here"
}');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://www.admin.rechargeapps.com/oauth/token")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/x-www-form-urlencoded'
request.body = "{\n\"grant_type\":\"refresh_token\",\n\"client_id\":\"your_app_client_id_here\",\n\"refresh_token\":\"your_refresh_token_here\"\n}"

response = http.request(request)
puts response.read_body

Supported scopes

The Recharge API currently supports the following scopes. Your API client must specify which scopes your app needs in the Partners dashboard. You can request tokens for any subset — or all — of the tokens your app is permitted.

State and CSRF

Due to the nature of logging in through the Shopify iframe, the state parameter used by many Oauth flows that protects against cross-site request forgery will not work. We are currently working on a mitigation strategy.

Association a store with an internal user

Many integrations require a store to be associated with an internal user. This can become problematic when the callback url lands on a page that requires authorization. We recommend storing the received authorization code in a session and recovering it once the user has registered or has logged into the integrating app’s protected environment.

OAuth Flows