Getting started

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:

Argument

Description

callback URL

This is the location where we will direct all shops and Oauth flow traffic.

app image

Link to an icon for your app

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

Argument

Description

Client ID

The client_id is a public identifier for apps.

Client Secret

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

Argument

Description

CLIENT_ID

The client_id is the public identifier for your app which you have

YOUR_STORE_NAME_HERE

The 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.

Parameter

Description

code=WHAT_YOU_RECEIVE_ON_CALLBACK_URL

After you visit the link above, log in and click install, you should check your callback URL for this code.

Platform

Parameter

Description

Shopify

myshopify_domain=YOUR_STORE_NAME_HERE

The store name prefix of your store URL (i.e., snowdevil.myshopify.com)

BigCommerce

mybigcommerce_domain=YOUR_STORE_NAME_HERE

The store name prefix of your store URL (i.e., 956coffee.mybigcommerce.com)

All

shop_domain=YOUR_STORE_NAME_HERE

You 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

Argument

Description

code=YOUR_CODE_HERE

This code can be found in your callback URL after step 2.

grant_type=authorization_code

Value for this should always be “authorization_code” in order for our OAuth flow to work

redirect_uri

Your 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

Argument

Description

grant_type=refresh_token

Value for this should always be “refresh-token”.

refresh_token

Refresh token is the refresh_token value you received when you got this given token.

client_id

The 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.

Object

Read

Write

Orders

read_orders

write_orders

Discounts

read_discounts

write_discounts

Webhooks

read_webhooks

write_webhooks

Subscriptions

read_subscriptions

write_subscriptions

Customers

read_customers

write_customers

Payments

read_payments

write_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

95259525

Need Help? Contact Us