docs_sdk_purchase-subscription.html

<!-- Docs - SDK - purchaseSubscription -->
<div class="section">
  <h2><a href="/docs/">Docs</a> : <a href="/docs/sdk/">SDK</a> : purchaseSubscription</h2>

  <p>
    <span class="font-semibold">purchaseSubscription</span> redirects your users to a <a href="https://stripe.com/docs/payments/checkout" target="_blank">Stripe Checkout</a> form, a Stripe-hosted payment page designed to reduce friction accepting payment from your users. To call this function, you must first do the following:
    <ul>
      <li>
        Include the <a href="https://stripe.com/docs/js/including" target="_blank">Stripe.js client</a> in your web app.
      </li>
      <li>
        Connect a Stripe account to your Userbase admin account in your <a href="https://v1.userbase.com/#edit-account" target="_blank">Admin panel</a>.
      </li>
      <li>
        Create a product with a recurring price in your <a href="https://dashboard.stripe.com/test/products/create" target="_blank">Stripe dashboard</a>.
      </li>
      <li>
        Take note of the price ID in the Stripe dashboard (it starts with '<span class="field">price_</span>').
      </li>
    </ul>
    And you're good to go!
  </p>

  <pre>
    <code class="language-javascript">
      userbase.purchaseSubscription({
        successUrl: 'https://example.com/success',
        cancelUrl: 'https://example.com/cancel',
        priceId: 'price_1HsI6AE3KJTop1QHR00YQXPr'
      }).then(() => {
        // user successfully redirected to Stripe Checkout form
      }).catch((e) => console.error(e))
    </code>
  </pre>

  <h3 id="params">Parameters</h3>

  <ul>
    <li>
      <span class="field">sucessUrl</span> [string] - The URL the user will be redirected to upon successful payment.
    </li>
    <li>
      <span class="field">cancelUrl</span> [string] - The URL the user will be redirected to upon canceling payment.
    </li>
    <li>
      <span class="field">priceId</span> [string] - The price ID the user will purchase. You can find this ID in your <a href="https://dashboard.stripe.com/test/products" target="_blank">Stripe dashboard</a> after creating a product with a recurring price.
    </li>
  </ul>

  <h3 id="notes">Notes</h3>

  <ul>
    <li>
      You can offer a free trial via your <a href="https://v1.userbase.com/#edit-account" target="_blank">Admin panel</a>. Users who sign up for an app with a free trial set will start out in trial mode. Users have full capabilities until the trial expires.
    </li>
    <li>
      To accept payments in production, you will need to purchase the Prod plan.
    </li>
    <li>
      Upon successful payment, the user's <span class="field">subscriptionStatus</span> will be set to 'active'. This allows the user to successfully call <a href="/docs/sdk/open-database/">openDatabase</a> on an app that requires payment.
    </li>
    <li>
      The user's credit card will be charged automatically at the start of every billing period. For example, if the user purchases a yearly subscription on May 4th, then the user will be charged on May 4th every year until they cancel.
    </li>
    <li>
      You can customize your Stripe Checkout form in your <a href="https://dashboard.stripe.com/settings/branding" target="_blank">Stripe dashboard</a>.
    </li>
  </ul>

  <h3 id="advanced">Advanced</h3>

  <ul>
    <li>You can allow promo codes at checkout. To enable promo codes:
      <ul>
        <li>Add a coupon to your Stripe account under <a href="https://dashboard.stripe.com/coupons" target="_blank">Products > Coupons</a></li>
        <li>Then add a promotion code for that coupon</li>
        <li>Finally, visit your app's Payments Portal in your <a href="https://v1.userbase.com/" target="_blank">Admin panel</a>, click "Show Advanced", and enable the option to "Allow promotion codes in Checkout"</li>
      </ul>
    </li>
    <li>You can support calculating tax at checkout. To enable automatic tax:
      <ul>
        <li>You need to activate tax collection under <a href="https://dashboard.stripe.com/settings/tax/activate" target="_blank">Settings > Tax Settings</a></li>
        <li>Set an origin address via the same link and configure tax settings</li>
        <li>Then you need to set tax behavior on a product</li>
        <li>Finally, visit your app's Payments Portal in your <a href="https://v1.userbase.com/" target="_blank">Admin panel</a>, click "Show Advanced", and enable the option to "Collect taxes in Checkout"</li>
      </ul>
    </li>
  </ul>

  <h3 id="errors">Errors</h3>

  <ul>
    <li>ParamsMustBeObject</li>
    <li>SuccessUrlMissing</li>
    <li>SuccessUrlMustBeString</li>
    <li>SuccessUrlInvalid</li>
    <li>CancelUrlMissing</li>
    <li>CancelUrlMustBeString</li>
    <li>CancelUrlInvalid</li>
    <li>StripeError</li>
    <li>StripeJsLibraryMissing</li>
    <li>SubscriptionPlanNotSet</li>
    <li>SubscriptionPlanAlreadyPurchased</li>
    <li>StripeAccountNotConnected</li>
    <li>PaymentsDisabled</li>
    <li>UserNotSignedIn</li>
    <li>TooManyRequests</li>
    <li>ServiceUnavailable</li>
  </ul>

</div>

<hr>