Documentation: Stripe Integration Setup

Prerequisites

• Stripe account with products/pricing configured
• TrackTags business account created

Step 1: Configure Stripe Products (CRITICAL)

For each product in your Stripe Dashboard that customers will subscribe to:

1. Go to Products → Select your product → Edit product
2. Scroll to Product metadata section
3. Click Add metadata
4. Add the following key-value pair:
   • Key: customer_id
   • Value: {{CHECKOUT_SESSION_CLIENT_REFERENCE_ID}}

This tells Stripe to automatically populate the customer_id metadata with the value passed from the pricing table’s client-reference-id attribute.

Step 2: Configure TrackTags Integration Keys

In the TrackTags dashboard, go to Stripe Setup and configure:

1. Pricing Table ID - From Stripe Dashboard → Pricing Tables
2. Publishable Key - From Stripe Dashboard → Developers → API Keys
3. Secret Key - From Stripe Dashboard → Developers → API Keys
4. Webhook Secret - From Stripe Dashboard → Developers → Webhooks

Step 3: Configure Stripe Webhook

1. Go to Stripe Dashboard → Developers → Webhooks
2. Click Add endpoint
3. Set endpoint URL to your TrackTags business webhook (found in your TrackTags dashboard Stripe Setup page)
   • Format: https://your-tracktags-domain.com/api/v1/webhooks/stripe/{your-business-id}
4. Select events to listen for:
   • customer.subscription.created
   • customer.subscription.updated
   • customer.subscription.deleted
   • invoice.payment_succeeded
   • invoice.payment_failed
   • invoice.finalized
5. Copy the Webhook signing secret and paste it in TrackTags Stripe Setup (Step 2 above)

Step 4: Configure Product Metadata in Stripe

When creating or editing products in Stripe that customers will subscribe to, you MUST add metadata to link subscriptions to TrackTags customers:

1. In Stripe Dashboard, go to Products
2. Select the product (or create a new one)
3. Click Edit product
4. Scroll to Metadata section
5. Add metadata:
   • Key: customer_id
   • Value: {{CHECKOUT_SESSION_CLIENT_REFERENCE_ID}}

Important: This step is required for EVERY product that customers can subscribe to. Without this metadata configuration, TrackTags cannot link Stripe subscriptions to your customers.

How It Works

When a customer completes checkout:

1. The Stripe Pricing Table passes client-reference-id containing the TrackTags customer_id
2. Stripe copies this to the subscription’s customer_id metadata (via the product metadata configuration)
3. Webhook fires to your business endpoint with customer_id in the subscription metadata
4. TrackTags automatically links the Stripe subscription to the correct customer
5. Customer’s plan is updated in real-time

Important Notes

• You MUST configure the product metadata with {{CHECKOUT_SESSION_CLIENT_REFERENCE_ID}} or customer subscriptions will not be linked
• The metadata configuration is per-product - configure ALL products that customers can subscribe to
• If you add new products later, remember to add the metadata configuration
• Your webhook URL is unique to your business and shown in the TrackTags Stripe Setup page

Troubleshooting

Problem: Customer subscribes but plan doesn’t update in TrackTags

Checklist:

1. ✅ Verify product has customer_id metadata configured with {{CHECKOUT_SESSION_CLIENT_REFERENCE_ID}}
2. ✅ Check webhook is pointing to the correct business URL (includes your business_id)
3. ✅ Verify webhook secret is correctly configured in TrackTags
4. ✅ Check webhook logs in Stripe Dashboard → Developers → Webhooks for delivery errors
5. ✅ Check TrackTags logs for webhook processing errors

Problem: Webhook receives events but returns errors

Common causes:

• Webhook secret mismatch (recopy the signing secret from Stripe)
• Product metadata not configured (add customer_id metadata to products)
• Business webhook endpoint not configured (verify URL includes your business_id)

Problem: “Missing customer_id in metadata” error

Solution: The product metadata is not configured. Go to your Stripe product and add:

• Key: customer_id
• Value: {{CHECKOUT_SESSION_CLIENT_REFERENCE_ID}}