# Stripe API

## Step 1: Connect Stripe to Humblytics

Before Humblytics can track your revenue, connect your Stripe account:

1. Go to your Humblytics dashboard and open **Site Settings**
2. Click the **Revenue** tab
3. Select **Stripe** as your payment provider
4. Choose **Stripe API** as the integration method
5. Enter your **Stripe Secret Key** (available in your [Stripe Dashboard](https://dashboard.stripe.com/apikeys))
6. Save your configuration

Your Stripe Secret Key is encrypted and stored securely. Never share it publicly.

<figure><img src="https://1281224403-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqZMBn2D7F1lV2hgGTS2X%2Fuploads%2Fgit-blob-787e379b8a8381efb15d69dd9e6de857b572c4b9%2FFyvV9cH0-15%402x.png?alt=media" alt=""><figcaption></figcaption></figure>

## Step 2: Add the `humblytics_view_id` Metadata

Tag your Stripe objects with a `humblytics_view_id` to link payments back to the visitor session. Humblytics looks for the first `humblytics_view_id` across these Stripe objects:

| Stripe Object   | When to Use                                       |
| --------------- | ------------------------------------------------- |
| `PaymentIntent` | One-time payments or custom payment flows         |
| `Invoice`       | Payments generated from invoices                  |
| `Subscription`  | Recurring payments and renewals                   |
| `Checkout`      | Hosted checkout flows using Stripe Checkout       |
| `Customer`      | Apply the ID globally to future invoices/payments |

💡 If you store the ID on a `Subscription` or `Customer`, Humblytics automatically applies it to future invoices and payments for that customer.

### Frontend: capture the view ID

```javascript
// Get the current Humblytics view ID on the client
const viewId = window.Humblytics.viewId;

// Send it to your backend along with the payload you already collect
await fetch("/api/create-payment", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    amount: 5000,
    currency: "usd",
    humblytics_view_id: viewId,
    // ...any other fields you need to pass along
  }),
});
```

### Backend examples

Attach the `humblytics_view_id` inside your server-side Stripe calls. Pick the object that matches your flow.

```javascript
// One-time payment using PaymentIntents
const { amount, currency, humblytics_view_id } = payload;

const paymentIntent = await stripe.paymentIntents.create({
  amount,
  currency,
  metadata: {
    humblytics_view_id,
  },
});
```

```javascript
// Subscription signup
const { customerId, priceId, humblytics_view_id } = payload;

const subscription = await stripe.subscriptions.create({
  customer: customerId,
  items: [{ price: priceId }],
  metadata: {
    humblytics_view_id,
  },
});
```

```javascript
// Stripe Checkout Session
const { line_items, humblytics_view_id } = payload;

const session = await stripe.checkout.sessions.create({
  line_items,
  mode: "payment",
  metadata: {
    humblytics_view_id,
  },
});
```

```javascript
// Apply globally to a Customer record
const { customerId, humblytics_view_id } = payload;

await stripe.customers.update(customerId, {
  metadata: {
    humblytics_view_id,
  },
});
```

## Step 3: View Attributed Revenue

After a payment succeeds, Humblytics automatically attributes the revenue to the correct visitor session—no webhooks or extra setup required. Review the revenue metrics (referrer, country, browser, etc.) in your Humblytics dashboard.

<figure><img src="https://1281224403-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqZMBn2D7F1lV2hgGTS2X%2Fuploads%2Fgit-blob-e86484af08c64b8d405d424db66640486da427c4%2Frevenue-attribution-card%20(5).png?alt=media" alt=""><figcaption></figcaption></figure>

## Key Benefits

| Benefit               | Detail                                                   |
| --------------------- | -------------------------------------------------------- |
| Automatic attribution | Revenue linked to visitor and campaign data              |
| Flexible integration  | Works with Checkout, PaymentIntents, Subscriptions, etc. |
| No webhooks needed    | Metadata-based tracking keeps setup simple               |
| Privacy-compliant     | Cookie-free tracking, no consent banners                 |
| Split test ready      | Use revenue as a goal in your Humblytics A/B tests       |

## Setting Up Split Tests with Revenue Goals

1. Create a split test on your main website
2. Choose **Revenue** as your goal type
3. Set a target revenue or select **Any Revenue**
4. Launch the test - revenue is tracked automatically

<figure><img src="https://1281224403-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqZMBn2D7F1lV2hgGTS2X%2Fuploads%2Fgit-blob-03fecd05b7f04beb97bc4db8b0cd83737d35eae1%2FSplit-test-revenue%20(1).png?alt=media" alt=""><figcaption></figcaption></figure>

## Troubleshooting

* **No revenue data appearing?** Confirm your Stripe account is connected to Humblytics.
* **Missing attribution?** Ensure a `humblytics_view_id` metadata field is set on at least one supported Stripe object.
* **Need help?** Reach us at <support@humblytics.com>.