> ## Documentation Index
> Fetch the complete documentation index at: https://docs.haloagents.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Stripe

> Sync customers, subscriptions, and payments. Power renewal data and let agents request refunds, cancellations, and credits through a human approval queue.

## What Stripe adds to Halo

Stripe powers two important things in Halo:

| Mode | What it does |
| - | - |
| **Ingest** | Customers, subscriptions, and payments sync into the `stripe_customers` table. Used in AI prompts, segments, renewal data, and health scores. |
| **Actions** | Agents can submit billing requests (refund, cancel, credit, extend trial) to a human approval queue. |

Stripe data also feeds:

* **Renewal status** auto-rules ("Set to cancel" when subscription is scheduled to cancel)
* **Health scores** payment signal
* **Audience filters** in segments and broadcasts (subscription status, MRR, lifetime value)

Connect at **Integrations > Stripe**.

## Setup

### Connecting

Click **Connect Stripe**. You'll be redirected to Stripe's prebuilt Apps install link with a CSRF state. After approval, Halo:

* Exchanges the OAuth code for tokens
* Stores encrypted tokens and `stripe_user_id`
* Triggers a full customer sync via `stripe/sync.requested`
* Sets up to receive webhooks

### Webhooks

Webhook endpoint: `https://app.haloagents.ai/api/integrations/stripe/webhook`

Halo registers the endpoint automatically and verifies signatures with the integration's webhook secret. Events processed:

* `customer.created`, `customer.updated`, `customer.deleted`
* `charge.succeeded`, `charge.refunded`
* `payment_intent.succeeded`
* `customer.subscription.created`, `.updated`, `.deleted`
* `invoice.paid`, `invoice.payment_failed`

## Ingest mode

When ingest is on:

* **Initial sync** pulls all customers (paginated, full historical backfill)
* **Webhooks** keep records fresh in real time

Customers are matched to Halo `companies` by `customer_id_field` mapping (configurable on the integration page). When a Stripe customer matches an existing Halo company, the company gets:

* Stripe customer ID
* Subscription status, plan, MRR
* Lifetime value
* Last payment date

Stripe `cronSync` is **off** — there's no hourly cron, since webhooks keep things fresh.

### Configuration

Editable on the integration page:

| Field | Purpose |
| - | - |
| **`customer_id_field`** | Which field on Halo's company record to match against Stripe customer email/ID |
| **`mrr_mode`** | How to compute MRR: `stripe_subscription` (sum of active subscriptions), `previous_month_charges`, or `manual` (use the `mrr` trait) |
| **`display_fields`** | Which Stripe fields to show on company detail pages |

## Billing actions

Stripe's single action is `billing` — but it covers five different request types submitted to a human approval queue:

| Request | What it asks for |
| - | - |
| **Refund** | Refund a charge (full or partial) |
| **Cancel at period end** | Cancel subscription at the end of the current period |
| **Cancel immediately** | Cancel subscription immediately, with optional refund |
| **Apply credit** | Add account credit |
| **Extend trial** | Extend the trial by N days |

The AI never executes billing actions directly. Instead, it submits requests with:

* The action type
* A reason (why the customer is asking)
* A summary of the conversation
* Optional amount, subscription ID, days

These appear in your inbox under **Agent Requests**. A teammate reviews and approves or denies. Approved requests then execute against Stripe.

This human-in-the-loop design protects against AI mistakes for high-stakes actions.

### Configuration

The Billing action card lets you configure:

* **Default action agent** — which agent reviews billing requests (usually the support agent)
* **Default approver** — auto-assign requests to a teammate
* **Approval thresholds** — auto-approve below certain dollar amounts (advanced)

## Notifications

Stripe doesn't have a separate notifications mode — instead, when **Slack** is connected and the `stripe_event` notification type is enabled, Halo posts to Slack on:

* Customer created
* Subscription created or deleted
* Charge succeeded or refunded
* Invoice payment failed

Each event is labeled with a human-readable description and links back to Stripe.

## Renewals from Stripe

Renewal status, dates, and contract terms can be auto-derived from Stripe subscription data:

* **`renewal_status: set_to_cancel`** when the subscription is scheduled to cancel at period end
* **`renewal_date`** from `current_period_end`
* **`contract_term`** inferred from billing interval

Configure renewal data sources at **Settings > Renewals**. See [Renewals](https://docs.haloagents.ai/contacts/renewals.md).

## Health scores from Stripe

Stripe data powers the **payment signal** in health scores. By default, only customers with an **active** (paying) subscription are scored. You can add other statuses such as `trialing` or `past_due` in [Health Scores](https://docs.haloagents.ai/contacts/health-scores.md) settings if you want them included.

## Where to go next

> **[Agent Actions](https://docs.haloagents.ai/agents/actions.md)**
>
> Enable billing requests per agent.

> **[Renewals](https://docs.haloagents.ai/contacts/renewals.md)**
>
> How Stripe data powers renewal tracking.

> **[Health Scores](https://docs.haloagents.ai/contacts/health-scores.md)**
>
> Stripe is the payment signal.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.