Pass client_reference_id to prevent double subscriptions

[remorses]

From Claude:

In stripe.checkout.sessions.create, client_reference_id serves several important purposes:

1. Session Identification:

const session = await stripe.checkout.sessions.create({
  client_reference_id: 'order_123', // Your internal reference
  line_items: [...],
  mode: 'payment'
});

2. Idempotency Control:

• Prevents duplicate checkout sessions for the same order
• If you try to create another session with the same client_reference_id, it will return the existing session

3. Webhook Event Linking:

// In your webhook handler
app.post('/webhook', (req, res) => {
  const event = req.body;
  
  if (event.type === 'checkout.session.completed') {
    const session = event.data.object;
    const clientReferenceId = session.client_reference_id;
    // Use clientReferenceId to update your order status
  }
});

4. Session Retrieval:

// Find sessions by client_reference_id
const sessions = await stripe.checkout.sessions.list({
  client_reference_id: 'order_123'
});

5. Order Tracking:

// Create session with order details
const session = await stripe.checkout.sessions.create({
  client_reference_id: `order_${orderId}`,
  metadata: {
    order_id: orderId
  },
  line_items: [...],
  mode: 'payment'
});

// Later retrieve order details
const order = await findOrderById(session.client_reference_id);

Important Notes:

• It's optional but highly recommended
• Should be unique per order/transaction
• Doesn't affect customer creation or subscription limits
• Useful for your internal record keeping
• Helps with payment reconciliation
• Maximum length is 255 characters

Best Practices:

// Good example
const session = await stripe.checkout.sessions.create({
  client_reference_id: `order_${orderId}_${timestamp}`,
  customer_email: customerEmail,
  line_items: [...],
  mode: 'payment',
  success_url: `${YOUR_DOMAIN}/success?session_id={CHECKOUT_SESSION_ID}`,
  cancel_url: `${YOUR_DOMAIN}/cancel`
});

// Include in error handling
try {
  const session = await stripe.checkout.sessions.create({
    client_reference_id: orderId,
    // ... other options
  });
} catch (error) {
  console.log(`Failed to create session for order ${orderId}`);
  throw error;
}

[santiagopuentep]

In my testing the client_reference_id doesn't prevent other sessions to created. I can have multiple sessions with the same client_reference_id if I want to. What I do is to manually close all other sessions before creating a new one. I also have active the Stripe setting to only allow one subscription per user (see Theo's video), which makes the checkout page show a message if they try to checkout with a subscription active.