Frequently Asked Questions

Common questions about integrating and using StackBE.

How do I test locally?

StackBE works out of the box for local development. Set the devCallbackUrl in your SDK config or app settings to redirect magic links to localhost:

typescript
const stackbe = new StackBE({
  apiKey: process.env.STACKBE_API_KEY!,
  appId: process.env.STACKBE_APP_ID!,
  devCallbackUrl: 'http://localhost:3000/auth/callback',
});

Can I use my own Stripe account?

Yes! StackBE uses Stripe Connect, which means you connect your own Stripe account. All payments go directly to you. StackBE never holds your funds or customer payment information.

What happens when a customer clicks a magic link?

The magic link contains a secure, time-limited token. When clicked, the user is redirected to your callback URL with the token as a query parameter. Your app verifies the token with StackBE and receives a session containing the customer info and their entitlements.

How do entitlements work?

Entitlements are key-value pairs attached to plans. When you check a customer's entitlements, StackBE returns the values from their current plan. Use them to gate features, set limits, or customize the experience per plan.

typescript
// Plan entitlements: { "plan": "pro", "apiCalls": 10000 }

const { hasAccess, value } = await stackbe.entitlements.check(
  customerId,
  'apiCalls'
);
// hasAccess: true, value: 10000

What's the difference between customers and users?

A customer is someone who can subscribe to your app. For apps with organizations enabled, multiple users can belong to one organization that shares a single subscription. "Subscriptions" count billing entities (customers or orgs), while "Users" count individual people with access.

Can customers belong to multiple organizations?

Yes! A customer can be a member of multiple organizations with different roles (owner, admin, member) in each. When they log in, they can switch organization context to access different subscriptions and entitlements.

How do I handle subscription changes?

You can query the current subscription status anytime using the SDK. For real-time updates, set up webhooks to receive events when subscriptions are created, updated, or cancelled.

typescript
// Check subscription status
const sub = await stackbe.subscriptions.get(customerId);
console.log(sub.status); // 'active', 'trialing', 'canceled', etc.

What if a customer's subscription expires?

When a subscription expires or is cancelled, the customer's entitlements reflect their new state (typically a free plan or no access). Your app should check entitlements before granting access to premium features.

How do I create a free trial?

Create a plan with a trial period in Stripe. When customers subscribe via StackBE checkout, they'll start in the 'trialing' status. You can check this status or the trial end date to show trial-specific UI.

Can I migrate existing customers to StackBE?

Yes. You can create customers via the API with their existing email addresses. If they have existing Stripe subscriptions, you can link them by providing the Stripe subscription ID when creating the StackBE subscription.

Is there a sandbox/test mode?

Yes! Use Stripe's test mode during development. Connect your Stripe test mode account in the StackBE dashboard, and all transactions will use Stripe's test environment. Use Stripe's test card numbers (4242 4242 4242 4242) for testing.

How do I handle failed payments?

Stripe handles payment retries automatically based on your Stripe settings. StackBE updates the subscription status accordingly (e.g., 'past_due'). You can check the status and show appropriate UI, or set up webhooks for payment_failed events.

Still Have Questions?