Skip to main content

Auth

Methods to fetch a recharge session.

info

Access to the storefront API functions require SDK to be initialized with a Recharge storefrontAccessToken - this token can be created via the merchant-admin where you manage your API tokens

Depending on the setting attached to your storefrontAccessToken PII may be obfuscated in your responses.

All API functions within the JavaScript SDK (with the exception of auth functions) require a Recharge session. The Recharge session contains an apiToken and optionally a customerId. This session is used to authenticate API calls. To obtain a Recharge session the caller must use one of the methods listed below. This method will return a session with a specific level of access. Each API function will be tagged with what scope is required to access that function. If you try to access a function without appropriate scope you will receive a 401.

Examples of the different levels of access required for a SDK method are denoted as follows:

read customerswrite subscriptions

Notes

  • The read products, read product search scopes are always returned if enabled on your Recharge Storefront Token so that Recharge Plans, and Product Search functions are available without an authenticated customer.
  • All customer portal settings from the merchant-admin are honored by the SDK & Storefront API. Example: if you don't allow subscription frequency edits via the merchant-admin then the SDK & Storefront API won't allow shipment frequency edits.
  • The Recharge session will timeout after one hour at which point a new session will need to be fetched. We are investigating allowing this session expiration to be configurable in the future.
  • Any tokens created before scopes were added have been backfilled with the previous level of auth scopes.

Example auth with scopes​

Login into Recharge without a customer​

Recharge Storefront Token with the read products, read customers, read subscriptions, and write subscriptions scopes.

Result: Recharge session with the access to read products (see notes above)

Login into Recharge without a customer​

Recharge Storefront Token with the read customers, read subscriptions, and write subscriptions scopes.

Result: Recharge session without any access

Login into Recharge with a customer​

Recharge Storefront Token with the read products, read customers, read subscriptions, and write subscriptions scopes.

Result: Recharge session with the access to read products, read customers, read subscriptions, and write subscriptions

Currently if you login with a customer that isn't in recharge you will receive an object where the apiToken would be a non-customer JWT and customerId be undefined. We recommend a merchant build the same add product workflows, but instead of "add to next order" (which appears for existing RC customers, instead provide "add to cart". Once a customer has gone through checkout, we will pick them up and all will be well.

Auth Flow

Note: All AppProxy functions require Shopify environment and the customer should already be logged into Shopify if you want to receive a session with the proper scopes/permissions associated with it.

When to use which auth function?​

Always call initRecharge before making other Auth/API calls.

Shopify Theme Storefront​

Headless Storefront/Customer Portal (e.g. Hydrogen Storefront)​

Recharge Customer Portal​

loginShopifyAppProxy v1.0.0 Types​

Get a session via the ShopifyAppProxy.

import { loginShopifyAppProxy } from '@rechargeapps/storefront-client';
const session = await loginShopifyAppProxy();

loginShopifyApi v1.0.0 Types Deprecated​

DEPRECATED: Please use loginWithShopifyStorefront instead

Get a Recharge session via Shopify Storefront Tokens.

This API also includes a message attribute in the Session response. This message will let the caller know details about the Session that was returned.

Message responses and descriptions:

  • Invalid Recharge storefront access token. - SDK was not initialized with a proper Recharge storefront token
  • No Shopify customer access token given. - No Shopify customer token was passed in
  • Customer does not exist in Recharge. - The customer is not in recharge
  • Error occurred in call to Shopify. - Shopify is giving us an error
  • Failed to validate customer with Shopify. - Shopify is saying the customer does not exist
  • Success - Everything worked and the customer is logged in
import { loginShopifyApi } from '@rechargeapps/storefront-client';
const session = await loginShopifyApi(shopifyStorefrontToken, shopifyCustomerAccessToken);

loginWithShopifyStorefront v1.17.0 Types​

Get a Recharge session via Shopify Storefront Tokens.

This API also includes a message attribute in the Session response. This message will let the caller know details about the Session that was returned.

Message responses and descriptions:

  • Invalid Recharge storefront access token. - SDK was not initialized with a proper Recharge storefront token
  • No Shopify customer access token given. - No Shopify customer token was passed in
  • Customer does not exist in Recharge. - The customer is not in recharge
  • Error occurred in call to Shopify. - Shopify is giving us an error
  • Failed to validate customer with Shopify. - Shopify is saying the customer does not exist
  • Success - Everything worked and the customer is logged in
import { loginWithShopifyStorefront } from '@rechargeapps/storefront-client';
const session = await loginWithShopifyStorefront(shopifyStorefrontToken, shopifyCustomerAccessToken);

loginWithShopifyCustomerAccount v1.17.0 Types​

Get a Recharge session via Shopify Customer Account Token.

This API also includes a message attribute in the Session response. This message will let the caller know details about the Session that was returned.

Message responses and descriptions:

  • Invalid Recharge storefront access token. - SDK was not initialized with a proper Recharge storefront token
  • No Shopify customer access token given. - No Shopify customer token was passed in
  • Customer does not exist in Recharge. - The customer is not in recharge
  • Error occurred in call to Shopify. - Shopify is giving us an error
  • Failed to validate customer with Shopify. - Shopify is saying the customer does not exist
  • Success - Everything worked and the customer is logged in
import { loginWithShopifyCustomerAccount } from '@rechargeapps/storefront-client';
const session = await loginWithShopifyCustomerAccount(shopifyCustomerAccessToken);

sendPasswordlessCode v1.0.0 Types​

Start a passwordless flow via Recharge API. This API returns a session_token when successful, which must be used in the validate step.

This function is recommended for logging in customers who do not have Shopify accounts and for merchants using the SDK from outside a hosted Shopify storefront.

Second argument is optional. Defines whether you want to send code via email and/or SMS(if enabled for you store). Default is to send to email and not to SMS.

SMS code will be sent to the phone number listed on the customer.

requires init with Recharge storefrontAccessToken

import { sendPasswordlessCode } from '@rechargeapps/storefront-client';
const session = await sendPasswordlessCode('asdf@email.com', { send_email: true, send_sms: true });

sendPasswordlessCodeAppProxy v1.0.0 Types​

Start a passwordless flow via Shopify App Proxy. This API returns a session_token when successful, which must be used in the validate step.

This function is recommended for logging in customers who do not have Shopify accounts and for merchants using the SDK from a hosted Shopify Storefront.

Second argument is optional. Defines whether you want to send code via email and/or SMS(if enabled for you store). Default is to send to email and not to SMS.

SMS code will be sent to the phone number listed on the customer.

requires init with Recharge storefrontAccessToken

import { sendPasswordlessCodeAppProxy } from '@rechargeapps/storefront-client';
const session = await sendPasswordlessCodeAppProxy('asdf@email.com', { send_email: true, send_sms: true });

validatePasswordlessCode v1.0.0 Types​

Finish a passwordless flow via Recharge API. This API returns a Recharge session when successful.

This function is recommended for logging in customers who do not have Shopify accounts and for merchants using the SDK from outside a hosted Shopify storefront.

requires init with Recharge storefrontAccessToken

args:

  • email - email of user
  • session_token - token returned from first step
  • code - code sent to user via email
import { validatePasswordlessCode } from '@rechargeapps/storefront-client';
const session = await validatePasswordlessCode('asdf@email.com', 'session_token', 'code');

validatePasswordlessCodeAppProxy v1.0.0 Types​

Finish a passwordless flow via Shopify App Proxy. This API returns a Recharge session when successful.

This function is recommended for logging in customers who do not have Shopify accounts and for merchants using the SDK from a hosted Shopify Storefront.

requires init with Recharge storefrontAccessToken

args:

  • email - email of user
  • session_token - token returned from first step
  • code - code sent to user via email
import { validatePasswordlessCodeAppProxy } from '@rechargeapps/storefront-client';
const session = await validatePasswordlessCodeAppProxy('asdf@email.com', 'session_token', 'code');

loginCustomerPortal v1.6.0 Types​

Get a session when in the context of the Recharge Customer Portal. If you are not within the context of a Recharge Customer Portal this call will throw an error.

import { loginCustomerPortal } from '@rechargeapps/storefront-client';
const session = await loginCustomerPortal();