> For the complete documentation index, see [llms.txt](https://docs.humblytics.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.humblytics.com/how-to-track-purchase-events/stripe/stripe-api.md).

# 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 API Key** (see below for recommended setup)
6. Save your configuration

### Recommended: Use a Restricted API Key

For better security, we recommend using a **restricted API key** with read-only permissions instead of your full secret key:

1. Go to your [Stripe Dashboard → Developers → API keys](https://dashboard.stripe.com/settings/applications)
2. Click **Create restricted key**
3. Give it a name like "Humblytics Revenue Attribution"
4. Grant **Read** permissions for:
   * Payment Intents
   * Invoices
   * Subscriptions
   * Customers
   * Charges
   * Account
5. Click **Create key** and copy it to Humblytics

Your API key is encrypted and stored securely. Restricted keys starting with `rk_` are accepted and recommended for enhanced security. Full secret keys starting with `sk_` also work but provide broader access than necessary.

<figure><img src="/files/NZ9LLvfUPBkG3QEuJA4I" 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="/files/LMg5TVRvTnqaABjajcln" 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="/files/QtSszJYYXHQwYi1d0rYc" 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>.