API ReferenceTheme Engine ReferenceJavaScript SDK ReferenceRecharge Help CenterContact Us

Custom customer portal tutorials

Suggest Edits

You can use Postman to create a demo customer portal using a test Recharge Environment and pre-configured test Collections. Use the following tutorials to practice using the Recharge API and create a demo customer portal.

🚧

Warning

You must use a test customer account in Recharge with at least one active subscription to complete these tutorials. A test customer account is needed because you will be editing and changing your test customer's subscription(s).

Tutorial 1 - Create your Recharge Environment and retrieve subscriptions

In this tutorial, you will set up the test Recharge Environment in Postman and retrieve your store's subscriptions using the API. This tutorial should make you comfortable using the Recharge API before creating a customer portal.

Step 1 - Set up the Recharge Environment in Postman

  1. Copy and paste the Recharge Environment Configuration and store it as a JSON file on your local device: 
    {
	"id": "afefa7fd-1f35-4eb2-af43-d455977391b1",
	"name": "Recharge Environment",
	"values": [
		{
			"key": "API token",
			"value": "",
			"type": "secret",
			"enabled": true
		},
		{
			"key": "API Version",
			"value": "2021-11",
			"enabled": true
		},
		{
			"key": "customer_id",
			"value": "",
			"type": "default",
			"enabled": true
		},
		{
			"key": "product_id",
			"value": "",
			"type": "default",
			"enabled": true
		},
		{
			"key": "address_id",
			"value": "",
			"type": "default",
			"enabled": true
		},
		{
			"key": "subscription_id",
			"value": "",
			"type": "default",
			"enabled": true
		},
		{
			"key": "hash_id",
			"value": "",
			"type": "default",
			"enabled": true
		},
		{
			"key": "charge_id",
			"value": "",
			"type": "default",
			"enabled": true
		},
		{
			"key": "bin_id",
			"value": "",
			"type": "default",
			"enabled": true
		},
		{
			"key": "webhook_id",
			"value": "",
			"enabled": true
		}
	],
	"_postman_variable_scope": "environment",
	"_postman_exported_at": "2022-06-28T17:53:00.760Z",
	"_postman_exported_using": "Postman/9.22.4"
}
  1. Copy and paste the Lab 1 Collection and store it as a JSON file on your local device:
{
	"info": {
		"_postman_id": "bdba9691-f02a-45ce-81cf-a970df1714bd",
		"name": "Recharge API: Lab 1",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
		"_exporter_id": "19669585"
	},
	"item": [
		{
			"name": "List Customers",
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "X-Recharge-Access-Token",
						"value": "{{API token}}",
						"type": "text"
					},
					{
						"key": "X-Recharge-Version",
						"value": "{{API Version}}",
						"type": "text"
					}
				],
				"url": {
					"raw": "https://api.rechargeapps.com/customers",
					"protocol": "https",
					"host": [
						"api",
						"rechargeapps",
						"com"
					],
					"path": [
						"customers"
					]
				}
			},
			"response": []
		},
		{
			"name": "List Addresses",
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "X-Recharge-Access-Token",
						"value": "{{API token}}",
						"type": "text"
					},
					{
						"key": "X-Recharge-Version",
						"value": "{{API Version}}",
						"type": "text"
					}
				],
				"url": {
					"raw": "https://api.rechargeapps.com/addresses",
					"protocol": "https",
					"host": [
						"api",
						"rechargeapps",
						"com"
					],
					"path": [
						"addresses"
					]
				}
			},
			"response": []
		},
		{
			"name": "List Orders",
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "X-Recharge-Access-Token",
						"value": "{{API token}}",
						"type": "text"
					},
					{
						"key": "X-Recharge-Version",
						"value": "{{API Version}}",
						"type": "text"
					}
				],
				"url": {
					"raw": "https://api.rechargeapps.com/orders",
					"protocol": "https",
					"host": [
						"api",
						"rechargeapps",
						"com"
					],
					"path": [
						"orders"
					]
				}
			},
			"response": []
		},
		{
			"name": "List Subscriptions",
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "X-Recharge-Access-Token",
						"value": "{{API token}}",
						"type": "text"
					},
					{
						"key": "X-Recharge-Version",
						"value": "{{API Version}}",
						"type": "text"
					}
				],
				"url": {
					"raw": "https://api.rechargeapps.com/subscriptions",
					"protocol": "https",
					"host": [
						"api",
						"rechargeapps",
						"com"
					],
					"path": [
						"subscriptions"
					]
				}
			},
			"response": []
		},
		{
			"name": "List Subscriptions with Include",
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "X-Recharge-Access-Token",
						"value": "{{API token}}",
						"type": "text"
					},
					{
						"key": "X-Recharge-Version",
						"value": "{{API Version}}",
						"type": "text"
					}
				],
				"url": {
					"raw": "https://api.rechargeapps.com/subscriptions?include=customer",
					"protocol": "https",
					"host": [
						"api",
						"rechargeapps",
						"com"
					],
					"path": [
						"subscriptions"
					],
					"query": [
						{
							"key": "include",
							"value": "customer"
						}
					]
				}
			},
			"response": []
		},
		{
			"name": "List Payment Methods",
			"protocolProfileBehavior": {
				"disableBodyPruning": true
			},
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "X-Recharge-Access-Token",
						"value": "{{API token}}",
						"type": "text"
					},
					{
						"key": "X-Recharge-Version",
						"value": "{{API Version}}",
						"type": "text"
					},
					{
						"key": "Content-Type",
						"value": "application/json",
						"type": "text"
					}
				],
				"body": {
					"mode": "raw",
					"raw": ""
				},
				"url": {
					"raw": "https://api.rechargeapps.com/payment_methods",
					"protocol": "https",
					"host": [
						"api",
						"rechargeapps",
						"com"
					],
					"path": [
						"payment_methods"
					]
				}
			},
			"response": []
		},
		{
			"name": "List Products",
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "X-Recharge-Access-Token",
						"value": "{{API token}}",
						"type": "text"
					},
					{
						"key": "X-Recharge-Version",
						"value": "2021-01",
						"type": "text"
					}
				],
				"url": {
					"raw": "https://api.rechargeapps.com/products",
					"protocol": "https",
					"host": [
						"api",
						"rechargeapps",
						"com"
					],
					"path": [
						"products"
					]
				}
			},
			"response": []
		},
		{
			"name": "List Customer by Id",
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "X-Recharge-Access-Token",
						"value": "{{API token}}",
						"type": "text"
					},
					{
						"key": "X-Recharge-Version",
						"value": "{{API Version}}",
						"type": "text"
					}
				],
				"url": {
					"raw": "https://api.rechargeapps.com/customers/{{customer_id}}",
					"protocol": "https",
					"host": [
						"api",
						"rechargeapps",
						"com"
					],
					"path": [
						"customers",
						"{{customer_id}}"
					]
				}
			},
			"response": []
		},
		{
			"name": "List Addresses by Id",
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "X-Recharge-Access-Token",
						"value": "{{API token}}",
						"type": "text"
					},
					{
						"key": "X-Recharge-Version",
						"value": "{{API Version}}",
						"type": "text"
					}
				],
				"url": {
					"raw": "https://api.rechargeapps.com/addresses/{{address_id}}",
					"protocol": "https",
					"host": [
						"api",
						"rechargeapps",
						"com"
					],
					"path": [
						"addresses",
						"{{address_id}}"
					]
				}
			},
			"response": []
		},
		{
			"name": "List Product by Id",
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "X-Recharge-Access-Token",
						"value": "{{API token}}",
						"type": "text"
					},
					{
						"key": "X-Recharge-Version",
						"value": "2021-01",
						"type": "text"
					}
				],
				"url": {
					"raw": "https://api.rechargeapps.com/products/{{product_id}}",
					"protocol": "https",
					"host": [
						"api",
						"rechargeapps",
						"com"
					],
					"path": [
						"products",
						"{{product_id}}"
					]
				}
			},
			"response": []
		}
	]
}
  1. Launch Postman and click Import.
  2. Locate and upload the Recharge Environment Configuration file you saved in Step 1.
  3. Click Import to finish uploading the Recharge Environment file.
  4. From Postman's main page, click Import again.
  5. Locate and upload the Lab 1 Collection file you saved in Step 2.
  6. Click Import to finish uploading the Lab 1 Collection.

Step 2 - Create an API token

  1. From the Recharge merchant portal, click Apps and select API tokens.
  2. Click Create an API token.
  3. Name the token Test for Postman, provide your email address, and set the scopes for all permissions to Read and Write, if available, or Read if not available.
  4. Agree to Recharge's API Terms of Service and click Save.
  5. Click Yes, grant access and copy the API token to your clipboard.

Step 3 - Update the Postman Environment

  1. In Postman, click on the Environment drop-down menu and select Recharge Environment.

  1. Click on the Environment quick look icon and click Edit.

  1. Paste your Recharge API token under Current Value and click Save.

Step 4 - Use GET to retrieve subscriptions

  1. Open the Lab 1 Collection and click List Subscriptions.
  2. Click Headers and review the API Token and API Version. Ensure your API Token is correct and the API Version is set to 2021-11.
  3. Click Send and verify the GET call was successful.
  4. Open the Lab 1 Collection and click List Subscriptions with include.
  5. Click Send.
  6. Compare your results to the first GET call. The second call should include customer information.
  7. Continue executing other API calls in this Collection for more practice or move on to the next tutorial.

Tutorial 2 - Create a customer portal using the Recharge API

In this tutorial, you will use a pre-configured test Collection and test customer account to create a customer portal using the Recharge API. After completing this tutorial, you should understand the basics of creating a custom customer portal.

Step 1 - Recharge Environment configuration

  1. Copy and paste the Lab 2 Collection and store it as a JSON file on your local device: 
    {
	"info": {
		"_postman_id": "3719f16e-dce4-4f5d-b337-ee46678726ae",
		"name": "Recharge API: Lab 2",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
		"_exporter_id": "19669585"
	},
	"item": [
		{
			"name": "List Customer by hash",
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "X-Recharge-Access-Token",
						"value": "{{API token}}",
						"type": "text"
					},
					{
						"key": "X-Recharge-Version",
						"value": "{{API Version}}",
						"type": "text"
					}
				],
				"url": {
					"raw": "https://api.rechargeapps.com/customers?hash={{hash_id}}",
					"protocol": "https",
					"host": [
						"api",
						"rechargeapps",
						"com"
					],
					"path": [
						"customers"
					],
					"query": [
						{
							"key": "hash",
							"value": "{{hash_id}}"
						}
					]
				}
			},
			"response": []
		},
		{
			"name": "List Customer by Id",
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "X-Recharge-Access-Token",
						"value": "{{API token}}",
						"type": "text"
					},
					{
						"key": "X-Recharge-Version",
						"value": "{{API Version}}",
						"type": "text"
					}
				],
				"url": {
					"raw": "https://api.rechargeapps.com/customers/{{customer_id}}",
					"protocol": "https",
					"host": [
						"api",
						"rechargeapps",
						"com"
					],
					"path": [
						"customers",
						"{{customer_id}}"
					]
				}
			},
			"response": []
		},
		{
			"name": "List Customer Delivery Schedule",
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "X-Recharge-Access-Token",
						"value": "{{API token}}",
						"type": "text"
					},
					{
						"key": "X-Recharge-Version",
						"value": "{{API Version}}",
						"type": "text"
					}
				],
				"url": {
					"raw": "https://api.rechargeapps.com/customers/{{customer_id}}/delivery_schedule",
					"protocol": "https",
					"host": [
						"api",
						"rechargeapps",
						"com"
					],
					"path": [
						"customers",
						"{{customer_id}}",
						"delivery_schedule"
					]
				}
			},
			"response": []
		},
		{
			"name": "List Subscriptions by Customer",
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "X-Recharge-Access-Token",
						"value": "{{API token}}",
						"type": "text"
					},
					{
						"key": "X-Recharge-Version",
						"value": "{{API Version}}",
						"type": "text"
					}
				],
				"url": {
					"raw": "https://api.rechargeapps.com/subscriptions?customer_id={{customer_id}}",
					"protocol": "https",
					"host": [
						"api",
						"rechargeapps",
						"com"
					],
					"path": [
						"subscriptions"
					],
					"query": [
						{
							"key": "customer_id",
							"value": "{{customer_id}}"
						}
					]
				}
			},
			"response": []
		},
		{
			"name": "List Subscriptions by Id",
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "X-Recharge-Access-Token",
						"value": "{{API token}}",
						"type": "text"
					},
					{
						"key": "X-Recharge-Version",
						"value": "{{API Version}}",
						"type": "text"
					}
				],
				"url": {
					"raw": "https://api.rechargeapps.com/subscriptions/{{subscription_id}}",
					"protocol": "https",
					"host": [
						"api",
						"rechargeapps",
						"com"
					],
					"path": [
						"subscriptions",
						"{{subscription_id}}"
					]
				}
			},
			"response": []
		},
		{
			"name": "List Addresses by customer",
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "X-Recharge-Access-Token",
						"value": "{{API token}}",
						"type": "text"
					},
					{
						"key": "X-Recharge-Version",
						"value": "{{API Version}}",
						"type": "text"
					}
				],
				"url": {
					"raw": "https://api.rechargeapps.com/addresses?customer_id={{customer_id}}",
					"protocol": "https",
					"host": [
						"api",
						"rechargeapps",
						"com"
					],
					"path": [
						"addresses"
					],
					"query": [
						{
							"key": "customer_id",
							"value": "{{customer_id}}"
						}
					]
				}
			},
			"response": []
		},
		{
			"name": "List payment methods by customer",
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "X-Recharge-Access-Token",
						"value": "{{API token}}",
						"type": "text"
					},
					{
						"key": "X-Recharge-Version",
						"value": "{{API Version}}",
						"type": "text"
					}
				],
				"url": {
					"raw": "https://api.rechargeapps.com/payment_methods?customer_id={{customer_id}}",
					"protocol": "https",
					"host": [
						"api",
						"rechargeapps",
						"com"
					],
					"path": [
						"payment_methods"
					],
					"query": [
						{
							"key": "customer_id",
							"value": "{{customer_id}}"
						}
					]
				}
			},
			"response": []
		},
		{
			"name": "Update Subscription frequency",
			"request": {
				"method": "PUT",
				"header": [
					{
						"key": "X-Recharge-Access-Token",
						"value": "{{API token}}",
						"type": "text"
					},
					{
						"key": "X-Recharge-Version",
						"value": "{{API Version}}",
						"type": "text"
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\n    \"order_interval_unit\": \"month\",\n    \"order_interval_frequency\": 2,\n    \"charge_interval_frequency\": 2\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "https://api.rechargeapps.com/subscriptions/{{subscription_id}}",
					"protocol": "https",
					"host": [
						"api",
						"rechargeapps",
						"com"
					],
					"path": [
						"subscriptions",
						"{{subscription_id}}"
					]
				}
			},
			"response": []
		},
		{
			"name": "Subscriptions: Set next charge date",
			"request": {
				"method": "POST",
				"header": [
					{
						"key": "X-Recharge-Access-Token",
						"value": "{{API token}}",
						"type": "text"
					},
					{
						"key": "X-Recharge-Version",
						"value": "{{API Version}}",
						"type": "text"
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\n    \"date\": \"2022-07-07\"\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "https://api.rechargeapps.com/subscriptions/{{subscription_id}}/set_next_charge_date",
					"protocol": "https",
					"host": [
						"api",
						"rechargeapps",
						"com"
					],
					"path": [
						"subscriptions",
						"{{subscription_id}}",
						"set_next_charge_date"
					]
				}
			},
			"response": []
		},
		{
			"name": "Skip Upcoming order",
			"request": {
				"method": "POST",
				"header": [
					{
						"key": "X-Recharge-Access-Token",
						"value": "{{API token}}",
						"type": "text"
					},
					{
						"key": "X-Recharge-Version",
						"value": "{{API Version}}",
						"type": "text"
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\n    \"purchase_item_ids\": [{{subscription_id}}]\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "https://api.rechargeapps.com/charges/{{charge_id}}/skip",
					"protocol": "https",
					"host": [
						"api",
						"rechargeapps",
						"com"
					],
					"path": [
						"charges",
						"{{charge_id}}",
						"skip"
					]
				}
			},
			"response": []
		},
		{
			"name": "List past charges",
			"protocolProfileBehavior": {
				"disableBodyPruning": true
			},
			"request": {
				"method": "GET",
				"header": [
					{
						"key": "X-Recharge-Access-Token",
						"value": "{{API token}}",
						"type": "text"
					},
					{
						"key": "X-Recharge-Version",
						"value": "{{API Version}}",
						"type": "text"
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\n    \"subscription_ids\": [{{subscription_id}}]\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "https://api.rechargeapps.com/charges?customer_id={{customer_id}}&status=success",
					"protocol": "https",
					"host": [
						"api",
						"rechargeapps",
						"com"
					],
					"path": [
						"charges"
					],
					"query": [
						{
							"key": "customer_id",
							"value": "{{customer_id}}"
						},
						{
							"key": "status",
							"value": "success"
						}
					]
				}
			},
			"response": []
		}
	]
}
  2. Launch Postman and click Import.
  3. Locate and upload the Lab 2 Collection file you created in Step 1.
  4. Click Import to finish uploading the Recharge Environment file.

Step 2 - Retrieve customer by hash

  1. From the Recharge merchant portal, click Customers and open a test customer's account.
  2. From the test customer's profile, click Customer portal links and copy the Subscriptions link.
  3. Paste the URL in a text file or notepad.
  4. Locate the customer_hash. The customer_hash is located between portal/ and /subscriptions/ in the URL.
  5. Copy the customer_hash value.
  6. Launch Postman and from the Environment drop-down choose Recharge Environment.
  7. Click on the Environment quick look icon and click Edit.
  8. Locate the hash_id variable and paste the customer_hash value under Current Value.
  9. Click Save.
  10. Open the Lab 2 Collection and click List Customer by hash.
  11. Click Send.
  12. Verify the GET call was successful.
  13. Locate and highlight the id in the response body.
  14. Right-click the highlighted id and click Set: Recharge Environment > customer_id.
  15. You have now retrieved the customer_id and set the customer_id variable by using the customer_hash.

Step 3 - Retrieve customer subscriptions by customer_id

  1. From the Lab 2 Collection, click List Subscriptions by Customer.
  2. Click Send.
  3. Review the JSON response. All the subscriptions for the customer should be listed.
  4. Locate and highlight the id in the response body.
  5. Right-click the highlighted id and click Set: Recharge Environment > subscription_id.

Step 4 - Retrieve customer delivery schedule

  1. From the Lab 2 Collection, click List Customer Delivery Schedule.
  2. Click Send.
  3. Review the JSON response. The delivery schedule for the customer's subscriptions should be listed.
  4. Locate and highlight the charge_id in the response body.
  5. Right-click the highlighted charge_id and click Set: Recharge Environment > charge_id.

Step 5 - Add a filter to customer delivery schedule

  1. From the Lab 2 Collection, click List Customer Delivery Schedule.
  2. Edit the GET line in Postman and add the ?future_interval=10 filter. This will return all scheduled deliveries for the next 10 days.

  1. Click Send.
  2. Review the JSON response. You can add additional filters that you might find useful in a customer portal. Refer to the Recharge API Reference for an explanation of these attributes.

Step 6 - Skip next order

  1. From the Lab 2 Collection, click Skip upcoming order.
  2. Click Send.
  3. Review the JSON response. You should see that you skipped the next order for this subscription. To verify this, check the customer's account from the Recharge merchant portal.

Step 7 - Update frequency

  1. From the Lab 2 Collection, click Update Subscription Frequency.
  2. Click Body and set the following:
  • order_interval_unit: "week"
  • order_interval_frequency: 1
  • charge_interval_frequency: 1
  1. Click Send.
  2. Review the JSON response. You should have changed this subscription's frequency to once per week.

Updated 5 months ago

Suggested Article

Need Help? Contact Us