Handle User Association

This guide explains how to link subscriptions to users in your application and manage subscription ownership.

Link During Checkout

The simplest way to associate a user is during checkout:

await iaptic.createStripeCheckout({
  offerId: 'stripe:prod_xyz#price_xyz',
  applicationUsername: 'user123', // Your user identifier
  successUrl: 'https://example.com/success',
  cancelUrl: 'https://example.com/cancel'
});

The applicationUsername will be stored in the subscription's metadata.

Update Existing Subscription

You can change the user association of an existing subscription:

// Using Stripe Dashboard
// Edit subscription metadata:
{
  "application_username": "newuser123"
}

// Or using Stripe API
await stripe.subscriptions.update('sub_xyz', {
  metadata: {
    application_username: 'newuser123'
  }
});

Track Ownership Changes

When ownership for a subscription changes, Iaptic will send a purchase.updated webhook event for both the old and new owner.

// In your webhook handler
if (event.type === 'purchase.updated') {
  const { applicationUsername, collection } = event;
  const oldUserCollection = db.getCollection(applicationUsername);
  // check if oldUserCollection contains a product that not in it's new collection
  // check if the new collection contains a product that is not in the oldUserCollection
}

See Setting Application Username for details and best practices.