Custom customer portal tutorials

Use Postman to create a demo customer portal using a test Recharge Environment and pre-configured test Collections.

The following tutorials outline how to use the Recharge API and create a demo customer portal.

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 to practice updating the customer's subscription(s).

📘

Platform:

• Custom

Tutorial 1 - Create your Recharge Environment and retrieve subscriptions

This guide explains how to configure the test Recharge Environment within Postman to fetch your store's subsriptions via the API.

This walkthrough aims to familiarize you with using the Recharge API before building a custom customer portal. If you are familiar with using the Recharge API, you can skip to Tutorial 2.

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:
   JSON

   {
   	"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"
   }
   

2. 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": []
		}
	]
}

3. Launch Postman and click Import.
4. Locate and upload the Recharge Environment Configuration file you saved in Step 1.
5. Click Import to finish uploading the Recharge Environment file.
6. From Postman's main page, click Import again.
7. Locate and upload the Lab 1 Collection file you saved in Step 2.
8. Click Import to finish uploading the Lab 1 Collection.

Step 2 - Create an API token

1. From the Recharge merchant portal, click Tools & 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.

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

3. 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:
   JSON

   {
   	"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 select Customers. 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.

3. Click Send.
4. 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

3. Click Send.
4. Review the JSON response. The subscription frequency should now show as once per week.