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

# Overview

[Stripe](https://stripe.com/billing) is the fastest way for your business to bill customers with subscriptions or invoices, and accept recurring payments globally.

Stigg's native integration with Stripe enables:

1. Automatic propagation of changes from the Stigg platform to Stripe, including: changes to the product catalog (product, plans and add-ons, coupons), customers, subscriptions and their usage.
2. Automatic propagation of changes from Stripe to Stigg, including: subscription cancellations in Stigg when they're cancelled in Stripe.
3. Ability to leverage Stripe's hosted checkout page for customer checkout process, without needing to perform any additional integration with Stripe.
4. Ability to leverage Stripe's hosted billing portal to allow customers to update their billing details and payment method, as well as view past invoices, without needing to perform any additional integration with Stripe.

## Entity mapping

Stigg entities are mapped to Stripe entities as follows:

| Stigg Entity | Stripe Entity | Stripe Entity Name Format                                       | Notes                                                                                              |
| ------------ | ------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Feature      | N/A           |                                                                 |                                                                                                    |
| Product      | N/A           |                                                                 |                                                                                                    |
| Plan         | Product       | `<STIGG-PRODUCT> <PLAN-NAME> Plan` e.g. Acme Basic Plan         | Each plan maps to a Stripe product. Charges are mapped to separate products. Prices are versioned. |
| Add-on       | Product       | `<STIGG-PRODUCT> <ADDON-NAME> Add-on` e.g. Acme 10 Seats Add-on | Each add-on maps to a Stripe product. Prices are versioned.                                        |
| Coupon       | Coupon        |                                                                 | Archived coupons in Stigg are deleted in Stripe. Existing applied coupons remain active.           |
| Customer     | Customer      |                                                                 | Customer name/email synced to Stripe. You can override the name for invoice purposes.              |
| Subscription | Subscription  |                                                                 | Includes line items per charge and add-on. Max 500 active subscriptions per Stripe customer.       |

<img src="https://mintcdn.com/stigg/uDKRUM0nhFFFMP5M/images/stripe1.png?fit=max&auto=format&n=uDKRUM0nhFFFMP5M&q=85&s=61d69bc3156a30e8198a7c022d9ea9f4" alt="" width="2024" height="1244" data-path="images/stripe1.png" />

### Entities that are not synced to Stripe

| Entity       | Not synced to Stripe when...                                          |
| :----------- | :-------------------------------------------------------------------- |
| Customer     | Customer doesn't have any subscription                                |
|              | Customer only has subscriptions to free plans                         |
|              | Customer only has trial subscriptions                                 |
|              | Customer only has subscriptions to plans with a custom price          |
|              | Customer's billing information is not sent to Stigg                   |
|              | Customer doesn't have a payment method define in the billing solution |
|              | Syncing of customers is disabled in the environment                   |
| Subscription | Subscription is for a free plan                                       |
|              | Subscription is for a trial plan                                      |
|              | Subscription is for a plan with a custom price                        |
|              | Syncing of subscriptions is disabled in the environment               |

### Syncing customer usage to Stripe

When customers are subscribed to plans with [pay-as-you-go usage-based charges](/documentation/modeling-your-pricing-in-stigg/plans#pay-as-you-go), Stigg automatically syncs their data (usage and total amount) to Stripe **upon invoice generation**.

<Warning>
  Stigg requires at least a 1 hour invoice finalization grace period to be [configured in Stripe](https://docs.stripe.com/billing/subscriptions/usage-based/recording-usage#configurable-grace-period), which is also Stripe's default configuration.
</Warning>

## Setting up the integration

In the [Stigg app](https://app.stigg.io), under the **Settings > Integrations > Apps** section, select the Stripe connector.

### 1. Choose the Stripe environment

Select the environment that matches your use case:

| Environment           | When to use                                                                                    |
| --------------------- | ---------------------------------------------------------------------------------------------- |
| **Sandbox**           | Evaluating Stigg. Uses a shared Stripe sandbox environment — no real money, no real customers. |
| **Test mode**         | Active development. Uses your own Stripe account in test mode.                                 |
| **Live (Production)** | Ready to bill real customers with live Stripe data.                                            |

Click **Continue to Stripe connection**.

### 2. Authorize in Stripe

You'll be redirected to Stripe. Sign in, select the Stripe account you want to link, review the permissions Stigg requests, and click **Install app**.

<Note>
  The Stripe account mode must match the environment you selected in Stigg. Sandbox installs only work with a Stripe Sandbox account, Test mode only with a Stripe test account, and Live only with a live Stripe account.

  If you created a new Stripe account recently, it may default to Sandbox mode. Switch to the correct mode using the account dropdown in the top-right corner of the Stripe Dashboard before installing.
</Note>

### 3. Connection confirmed

After authorizing, you'll be redirected back to Stigg. The integration status will show as **Active**, along with your Stripe account name, account ID, and integration ID.

<Note>
  If you connected Stripe before this update, your existing connection continues to work with no action required.
</Note>

## Permissions requested

During install, Stripe shows a consent screen listing the access Stigg requires. These permissions cover the full sync between Stigg and Stripe — catalog, customers, subscriptions, billing, and webhooks.

| Permission                               | Access         |
| ---------------------------------------- | -------------- |
| Account and user information             | Read-only      |
| Accounts                                 | Read-only      |
| Charges and Refunds                      | Read-only      |
| Checkout Sessions                        | Read and write |
| Coupons                                  | Read and write |
| Customers                                | Read and write |
| Elements                                 | Read and write |
| Events                                   | Read-only      |
| Invoices                                 | Read and write |
| Payment Intents                          | Read-only      |
| Payment Methods                          | Read and write |
| Prices                                   | Read and write |
| Products                                 | Read and write |
| Promotion Codes                          | Read-only      |
| Setup Intents                            | Read and write |
| Sources                                  | Read-only      |
| Subscriptions                            | Read and write |
| Tax Rates                                | Read and write |
| Test clocks                              | Read-only      |
| Tokens                                   | Read-only      |
| Usage Records                            | Read and write |
| Webhook Endpoints and Event Destinations | Read-only      |
| External access                          | Data sharing   |

## Indication for synced entities

Entities that are synced from Stigg to Stripe have a clickable "billing ID" property with a Stripe logo next to it and indication of their sync status (successful, failed, [will not be synced](#entities-that-are-not-synced-to-stripe)).

<img src="https://mintcdn.com/stigg/uDKRUM0nhFFFMP5M/images/stripe3.png?fit=max&auto=format&n=uDKRUM0nhFFFMP5M&q=85&s=85279de2116092b9f0596075fa86c6f4" alt="" width="3800" height="1102" data-path="images/stripe3.png" />

## Accessing Stripe entities from Stigg

In the Stigg app, clicking on the link of the "billing ID" property will open the relevant entity in Stripe.

<img src="https://mintcdn.com/stigg/uDKRUM0nhFFFMP5M/images/stripe4.png?fit=max&auto=format&n=uDKRUM0nhFFFMP5M&q=85&s=f65dab7f957c6d24456aeb1d575a00bc" alt="" width="3800" height="1102" data-path="images/stripe4.png" />

## Accessing Stigg entities from Stripe

In Stripe, under the "Metadata" section of the relevant entity, click on the link that appears under the "stiggEntityUrl" field.

<img src="https://mintcdn.com/stigg/uDKRUM0nhFFFMP5M/images/stripe5.png?fit=max&auto=format&n=uDKRUM0nhFFFMP5M&q=85&s=208e30a83eba8688ed0d264b0c973b2e" alt="" width="3016" height="1054" data-path="images/stripe5.png" />

## Integration with Stripe Billing Portal

When Stigg is integrated with Stripe and using [Stigg's Customer Portal widget](/api-and-sdks/integration/frontend/react#rendering-a-customer-portal), customers can update their billing information and view previous invoices directly from [Stripe's Billing Portal](https://stripe.com/docs/customer-management/get-started) (when it's enabled).

To ensure that the functionality of Stigg's Customer Portal doesn't collide with that of Stripe's Billing Portal, it's recommended to [configure Stripe's Billing Portal](https://dashboard.stripe.com/settings/billing/portal) as follows:

1. Launch customer portal with a link - **enabled**
2. Invoices
   1. Invoice history - **enabled**
3. Customer information - **enabled**
   1. Name - **unchecked**
   2. Email address - **unchecked**
   3. Billing address - **checked**
   4. Phone number - optional
   5. Tax ID - optional
4. Payment methods
   1. Payment method - **enabled**
5. Cancelations
   1. Cancel subscriptions - **disabled**
   2. Pause subscriptions - **disabled**
6. Subscriptions
   1. Switch plans - **disabled**
   2. Update quantities - **disabled**

## Integration with Stripe Tax

Stigg can be integrated with <a href="https://stripe.com/tax">Stripe</a> Tax to automatically calculate customer tax rates during checkout sessions, provisioning and updating of subscriptions.

Before the integration can be enabled, please make sure to <a href="https://stripe.com/docs/tax/set-up">set up Stripe Tax</a>.

To enable the integration, simply toggle on the configuration in the Stripe integration details:

<img src="https://mintcdn.com/stigg/uDKRUM0nhFFFMP5M/images/stripe6.png?fit=max&auto=format&n=uDKRUM0nhFFFMP5M&q=85&s=b1ae4b52c88007d7f0c5e846149c3845" alt="" width="1492" height="348" data-path="images/stripe6.png" />

## Removing the integration

To remove the integration, click on the dotted menu icon and select the "Remove" action.

Confirm the action by clicking on the "Remove" button in the opened modal.