# 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="/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>.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.humblytics.com/how-to-track-purchase-events/stripe/stripe-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.