Creating a partner app
This guide will walk you through creating a partner app, step by step
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
- Login to your Partners account
- 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:
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 following link. These links will vary based on the platform, BigCommerce or Shopify. See the following table.
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
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
Updated 7 months ago