Use the Recharge API to build a custom customer portal
Allow customers to manage their subscriptions, update billing information, and see their purchase history with a custom-built portal.
Leverage the Recharge API and build a custom customer portal that provides customers complete control over their subscriptions.
Platform
- Custom
Overview
Utilize the Recharge API to build a custom customer portal for more flexibility, or to integrate subscription actions into your platform's existing customer portal. With these options, you can pull in all subscription data and perform actions allowing customers to manage their subscriptions.
Custom customer portal architecture
A custom customer portal uses both backend architecture and frontend architecture.
- The backend architecture is responsible for sending API calls and receiving responses
- The frontend architecture is the user interface that the customer interacts with
Backend architecture
The backend architecture of a custom customer portal is compromised of the following:
- Customer Portal Application
- Middleware
- The Recharge API
In this example, the Customer Portal Application reaches out to middleware hosted on a merchant's domain. The middleware handles the API calls to the Recharge API and passes along the appropriate API responses to the domain's frontend.
Middleware is necessary for creating a custom customer portal because the Recharge API does not support CORS, so connecting to the API from another domain is not possible. Middleware also provides secure storage of Recharge API keys on the backend.
This architecture allows a single API call result in multiple responses. For example, when a customer adds a one-time product to a shipment, a single API call can add the one-time product to the customer's subscription while also updating metafields on a customer object to track that customer's order history for a loyalty program.
Frontend architecture
The frontend architecture receives API responses and acts as the user interface that customers use when managing their subscriptions. The general frontend architecture of a custom customer portal is compromised of the following:
- Customer
- Subscriptions
- Delivery Schedule
- Purchase History
- Addresses
- Payment Methods
It is not required to structure a custom customer portal using the same frontend architecture, however, this example provides a general overview of how to configure a custom customer portal.
Decide what actions a customer can perform under each component of the frontend architecture. For example, under the Subscriptions component it's possible to offer the following actions to your customers:
- Change the charge date
- Change the frequency
- Skip order
- Swap product
- Cancel subscription
- Add one-time product
Step 1 - Retrieve the customer hash
The customer_hash is used when a customer accesses their customer portal in a Recharge-hosted customer portal. The customer_hash authenticates the user and maps the user to the correct customer_id. The customer_id is then used to locate the correct customer details.
For custom customer portals, use the customer_hash or customer's email address during login to map the user to the correct customer_id. After retrieving the customer_id build the different features and their corresponding actions for the custom customer portal.
Use the following directions to retrieve a list of customers' customer hashes:
- From the merchant portal, click Data and select Exports.
- Click Create export.
- From the Export type menu, select Customers and add your email address to the export.
- Open the Export and view the file.
- Retrieve the
customer_hashfrom thehashcolumn.
Step 2 - Create actions in the customer portal
There are several different features of the customer portal that you can build. Each feature has specific corresponding actions a customer can take in the customer portal. In the following tables, each feature and its corresponding action shows the API requests needed to build the customer portal.
Note:
The following request actions use API version 2021-11.
View Subscriptions
View Subscriptions features typically live under the Subscriptions section of the customer portal. The recommended actions for this feature allow a customer to view their subscriptions and add a subscription directly from the customer portal.
| Action | Request | API Reference link |
|---|---|---|
| View current subscriptions and subscription details | GET /subscriptions?customer_id=<customer_id> | List subscriptions |
| View single subscription and subscription details | GET /subscriptions/<subscription_id> | Retrieve a subscription |
| Add a subscription | POST /subscriptions | Create a subscription |
Edit Subscriptions
Edit Subscriptions features typically live under the Subscriptions section of the customer portal. The recommended actions for this feature allow a customer to edit and manage their subscriptions, add a one-time item, or cancel their subscription.
| Action | Request | API Reference Link |
|---|---|---|
| Change charge date/next shipment of product | POST /subscriptions/<subscription_id>/set_next_charge_date | Change a subscription charge date |
| Order now/Process charge | POST /charges/<charge_id>/process | Process a charge |
| Skip shipment/Skip charge | POST /charges/<charge_id>/skip | Skip a charge |
| Unskip a shipment/Unskip charge | POST /charges/<charge_id>/unskip | Unskip a charge |
| Add discount code to a single charge | POST /charges/<charge_id>/appy_discount | Apply a discount |
| Add discount code to an Address ID/Add discount code to all subscriptions under a customer's Address ID | PUT /addresses/<address_id> | Update an address |
| Update subscription | PUT /subscriptions/<subscription_id> | Update a subscription |
| Swap out subscription product | PUT /subscriptions/<subscription_id> | Update a subscription |
| Add one-time product to next shipment | POST /onetimesNotes: Use the add_to_next_charge boolean if there is a known queued charge to add to so it ships out with the next subscription shipment.If there is no queued charge, set the date for the one-time to be processed with next_charge_scheduled_at. | Create a onetime |
| Change delivery schedule | PUT /subscriptions/<subscription_id>Notes: This request updates the subscription and changes the order_interval_frequency and order_interval_unit.The charge_interval_frequency must also be updated to align the new schedule. | Update a subscription |
| Cancel subscription | POST /subscriptions/<subscription_id>/cancel | Cancel a subscription |
Delivery Schedule
Delivery Schedule features typically live under the Subscriptions or Delivery Schedule sections of the customer portal. The recommended actions for this feature allow a customer to see upcoming charges and skip or unskip a shipment.
| Action | Request | API Reference link |
|---|---|---|
| See upcoming shipments/charges | GET /customers/<customer_id>/delivery_schedule | Retrieve a customer delivery schedule |
| Skip charge/shipment | POST /charges/<charge_id>/skip | Skip a charge |
| Unskip charge/shipment | POST /charges/<charge_id>/unskip | Unskip a charge |
Purchase History
Purchase History features typically live under the Subscriptions or Purchase History sections of the customer portal. The recommended actions for this feature allow a customer to see past charges, charge statuses, and order details.
| Action | Request | API Reference link |
|---|---|---|
| See past charges | GET /charges?customer_id=<customer_id> | List charges |
| Show charge status (error, success, pending, etc.) | GET /charges?customer_id=<customer_id>&status=queued, refunded, partially_refunded, success, error | List charges |
| View order details | GET /orders/<order_id> | Retrieve an order |
Shipping Addresses and Payment Methods
Shipping Address and Payment Method features typically live under separate sections of the customer portal, but these features rely on one other to store data. Payment Methods are stored under Shipping Addresses (Address IDs). The recommended actions for these features allow a customer to manage their shipping addresses and payment methods.
| Action | Request | API Reference link |
|---|---|---|
| Shipping Addresses | GET /payment_methods?customer_id=<customer_id>Notes: Each Address ID for a customer has its own Payment Method and each Payment Method has its own Billing Address. | List payment methods |
| The customer object has an email attribute for this data. | The customer object | |
| Data for card(s) on file | GET /payment_methods?customer_id=<customer_id> | List payment methods |
| View all addresses | GET /addresses?customer_id=<customer_id> | List addresses |
| Update Shipping address | POST /subscriptions/<subscription_id>/change_addressNotes: If there are multiple subscriptions that need updated, the request must be made multiple times. | Change a subscription address |
| Update Billing Address | PUT /payment_methods/<payment_method_id>Notes: Each Payment Method has its own Billing Address data that can be updated. | Update a payment method |
| Add additional addresses | POST /addressesNotes: Any additional Addresses need a Payment Method attached to it for charges to process under that Payment Method. | Create an address |
| Add new payment method | POST /payment_methodsNotes: Card data will need to be tokenized separately from Recharge API. New Payment Method will need to be set to a specific Address ID for charges under that Address to be processed. | Create a payment method Update an address |
| Update card for payment | POST /payment_methodsNotes: Card data will need to be tokenized separately from Recharge API. Update Address ID with the ID of the new payment method under payment_method_id on the Address object. | Create a payment method Update an address |
Create a demo customer portal using the Recharge API
Use Postman to create a demo customer portal using a test Recharge Environment and pre-configured test Collections. To create a demo customer portal, use the Custom customer portal tutorials.
Updated 6 months ago