Initiate subscription

Learn how your user can select a plan and initiate a subscription request with a payment method.

There are two main ways that you can initiate a subscription for your user. If the user is new and you do not have their payment method, then it is ideal to use Stripe checkout using Tier to both capture the subscription and their payment method.

You can initiate a direct subscription call with Tier without the need to invoke Stripe checkout if you already have the payment method of your customer.

Before getting started

To get the most out of this quick-start guide, you’ll need:

Stripe secret key
Select your pricing model & sync with Stripe
Basic auth implementation with auth guards

You will never have to sync any Tier or pricing-specific details to your DB, Tier will ensure that you get the most updated pricing and usage data, except user data.

SDK Object definition


CheckoutResponse	This object is returned with a Stripe checkout URL, this is usually used when you do not have the customer’s payment method.
PaymentMethodsResponse	This object will contain all the saved payment methods of the customer.

1. Initialize Tier SDK

Initialize the Tier SDK, ideally in a singleton design pattern, with both TIER_BASE_URL and TIER_API_KEY environment variables set with the prescribed values.

// To make use of Tier Cloud Alpha you need to
// points base URL to the Tier API server
TIER_BASE_URL = "https://api.tier.run"
// and set Tier API Key as your Stripe secret key
TIER_API_KEY = "sk_test_51..."

Initialize Tier

import tier from "tier"

2. Check for saved payment methods

When the customer clicks on a plan in your pricing table, the very first thing to do will be to check for any existing payment method for the customer. If the customer already has a payment method then it is ideal to just use subscribe() to upgrade or downgrade their plan and if they do not have any payment method we should initiate a stripe checkout using checkout().

Check saved payment methods

const paymentDetails = await tier.lookupPaymentMethods(
  "org:customer-id-from-your-db" // This is a concatenation of 'org' and your 'customerId' from your DB
)

if (!paymentMethod.methods[0] === undefined) {
  // initiate Checkout
} else {
  // Subscribe
}

3. Initiate a Stripe checkout

If your customer has to be subscribed to a default plan of your pricing model then, you should subscribe them to it right after registering them in Tier.

Register your customer

await tier.updateOrg(`org:customer-id-from-your-db`, {
  email: "customer@email.com", // Email of your customer
  name: "Customer name", // Full name of your customer
  description: "description", // Optional: Based on your use case add a description
  phone: "+11 1111 1111", //Optional: Phone number of your customer
  invoiceSettings: {
    defaultPaymentMethod: "payment-method-id", // Optional: update customer default payment method if needed
  },
  metadata: {}, // Optional: You can add additional data about the customer using metadata
})

Get checkout URL to subscribe

const checkoutResponse = await tier.checkout('org:customer-id-from-your-db',
		"https://success-path.com", // Redirect url for your customer on success
		{
    		cancelUrl: "https://cancel-path.com", // Redirect your customer on cancellation
    		features: 'plan:plan-id@version' // Plan ID or it can be an array of feature-ids,
			requireBillingAddress: true, // Optional: If you want to save the address
			trialDays: 30 // Optional: If you your customers to have a product trial
		}
);

const checkoutUrl = checkoutResponse.url;

4. Initiate Tier subscription flow

If you have saved customer payment details, as per step 2, then you can initiate a subscription flow using subscribe().

Start subscription call

await tier.subscribe('org:customer-id-from-your-db',
	'plan:plan-id@version' // or it can be an array of feature-ids,
	{
		effective: new Date("Sun May 12, 2023"), // Optional: Provide effective data of subscription
		paymentMethodID: 'payment-method-id', //Optional: provide if your customer wants to use something different from the default
		trialDays: 30 // Optional: If you your customers to have a product trial
		info: {
			// Optional: Update the organization/customer information if required,
			// and provide all details even if you want to change just one field
			name: 'Customer name', // Optional: update customer name if needed
			email: 'customer@email.com', // Optional: update customer email if needed
			phone: '+11 1111 1111', // Optional: update customer email if needed
			metadata: {}, // Optional: add any additional details as metadata
			description: 'description', // Optional: update customer description if needed
			invoiceSettings: {
				defaultPaymentMethod: 'payment-method-id', // Optional: update customer default payment method if needed
			},
		},
});

This quickstart will give you an idea of how to register your customer in Tier. You can also refer to our SDK references to understand more about subscribe() and checkout().

Check our SDK references for more details on these topics.