API ReferenceTheme Engine ReferenceJavaScript SDK ReferenceRecharge Help CenterContact Us

Getting started

Suggest Edits

This guide will walk you through creating a partner app, step by step.

Step 1. - Create an app in the Partner admin

🚧

Scopes

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:

ArgumentDescription
callback URLThis is the location where we will direct all shops and Oauth flow traffic.
app imageLink to an icon for your app

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

ArgumentDescription
Client IDThe client_id is a public identifier for apps.
Client SecretThe client_secret is a secret known only to the application and the authorization server.

Step 2. - User authorization and grant request

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

Authorization URL
https://admin.rechargeapps.com/partners/app/**CLIENT_ID**/install?myshopify_domain=**YOUR_STORE_NAME_HERE**

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**

ArgumentDescription
CLIENT_IDThe client_id is the public identifier for your app which you have
YOUR_STORE_NAME_HEREThe client ID that preceds the platform domain i.e., YOUR-STORE-NAME.myshopify.com or YOUR-STORE-NAME.mybigcommerce.com when you view the URL in your admin or control panel.

Important: Do not enter the .myshopify.com extension, only the store name.

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.

ParameterDescription
code=WHAT_YOU_RECEIVE_ON_CALLBACK_URLAfter you visit the link above, log in and click install, you should check your callback URL for this code.
PlatformParameterDescription
Shopifymyshopify_domain=YOUR_STORE_NAME_HEREThe store name prefix of your store URL (i.e., snowdevil.myshopify.com)
BigCommercemybigcommerce_domain=YOUR_STORE_NAME_HEREThe store name prefix of your store URL (i.e., 956coffee.mybigcommerce.com)
Allshop_domain=YOUR_STORE_NAME_HEREYou can use shop_domain regardless of platform.

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

ArgumentDescription
code=YOUR_CODE_HEREThis code can be found in your callback URL after step 2.
grant_type=authorization_codeValue for this should always be “authorization_code” in order for our OAuth flow to work
redirect_uriYour Redirect URI (this needs to be the same URI like the one in your App settings) aka callback url
client_id You application client ID, as in Step 2. It can also be found in your app settings.

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

ArgumentDescription
grant_type=refresh_tokenValue for this should always be “refresh-token”.
refresh_tokenRefresh token is the refresh_token value you received when you got this given token.
client_idThe client_id is a public identifier for your app.

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

Integration notes

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.

ObjectReadWrite
Ordersread_orderswrite_orders
Discountsread_discountswrite_discounts
Webhooksread_webhookswrite_webhooks
Subscriptionsread_subscriptionswrite_subscriptions
Customersread_customerswrite_customers
Paymentsread_paymentswrite_payments

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

9525

Updated 5 months ago

Need Help? Contact Us