# Install the Stripe Terraform provider

Set up the provider for local development.

The Stripe Terraform Provider enables you to manage Stripe resources using infrastructure as code. Configure products, prices, billing meters, and complex pricing plans with declarative Terraform syntax. Your Stripe infrastructure becomes version controlled, reproducible, and auditable. For API information, see the [Stripe API reference](https://docs.stripe.com/api.md).

## Sample Workflow

Follow this workflow to create a product with a recurring price and webhook endpoint to receive events.

Create a new Terraform file, `main.tf`:

```hcl
terraform {
  required_providers {
    stripe = {
      source = "stripe/stripe"
      version = "0.1.3"
    }
  }
}

provider "stripe" {
  # API key is read from STRIPE_API_KEY environment variable
  # Alternatively, set it explicitly (not recommended for production)
  # api_key = "sk_test_..."
}

# Define a product
resource "stripe_product" "pro_plan" {
  name        = "Pro Plan"
  description = "Professional tier with advanced features"
}

# Create a recurring price for the product
resource "stripe_price" "pro_monthly" {
  product     = stripe_product.pro_plan.id
  currency    = "usd"
  unit_amount = 2900

  recurring {
    interval = "month"
  }
}

# Set up a webhook endpoint for payment events
resource "stripe_webhook_endpoint" "payments" {
  url = "https://api.example.com/webhooks/stripe"

  enabled_events = [
    "payment_intent.succeeded",
    "payment_intent.payment_failed",
    "customer.subscription.created",
    "customer.subscription.deleted",
  ]
}

output "price_id" {
  value = stripe_price.pro_monthly.id
}
```

Set your API Key:

```bash
export STRIPE_API_KEY="<<YOUR_SECRET_KEY>>"
```

Preview and apply changes:

```bash
terraform plan
terraform apply
terraform output
```

## Supported resources

This section provides a quick reference of available resources. For detailed documentation and all configurable parameters, see [Supported resources](https://docs.stripe.com/terraform/resources.md).

### Product catalog

| Resource                      | Description                    |
| ----------------------------- | ------------------------------ |
| `stripe_product`              | Product definitions            |
| `stripe_price`                | Pricing configurations         |
| `stripe_coupon`               | Discount coupons               |
| `stripe_shipping_rate`        | Shipping rate configurations   |
| `stripe_tax_rate`             | Tax rate definitions           |
| `stripe_entitlements_feature` | Feature flags for entitlements |

### Core resources

| Resource                           | Description                      |
| ---------------------------------- | -------------------------------- |
| `stripe_customer`                  | Customer records                 |
| `stripe_webhook_endpoint`          | Webhook endpoint configurations  |
| `stripe_billing_meter`             | Usage tracking meters            |
| `stripe_v2_core_event_destination` | Event destination configurations |

### Advanced usage-based billing (Private preview)

These resources are part of the Billing v2 API and require access to the private preview.

| Resource                                   | Description                |
| ------------------------------------------ | -------------------------- |
| `stripe_v2_billing_pricing_plan`           | Pricing plan containers    |
| `stripe_v2_billing_pricing_plan_component` | Plan components            |
| `stripe_v2_billing_licensed_item`          | Licensed access items      |
| `stripe_v2_billing_license_fee`            | Subscription fees          |
| `stripe_v2_billing_metered_item`           | Usage-based billable items |
| `stripe_v2_billing_rate_card`              | Pricing containers         |
| `stripe_v2_billing_rate_card_rate`         | Individual rates           |
| `stripe_v2_billing_service_action`         | Credits and adjustments    |

### Data sources

| Data Source            | Description                     |
| ---------------------- | ------------------------------- |
| `stripe_billing_meter` | Look up existing billing meters |

## Manage multiple environments with workspaces

Terraform workspaces let you manage separate Stripe environments (sandbox versus livemode) with isolated state files. This prevents accidental changes to production resources when working in test mode.

### Set up workspaces

Create workspaces for a sandbox (test mode) and live mode:

```bash
# Create workspaces
terraform workspace new sandbox
terraform workspace new livemode

# List available workspaces
terraform workspace list
```

### Switch between environments

Each workspace maintains its own state file. Switch workspaces and set the corresponding API key:

```bash
# Work in sandbox (test mode)
terraform workspace select sandbox
export STRIPE_API_KEY=<<YOUR_SECRET_KEY>>
terraform plan
terraform apply

# Work in livemode (production)
terraform workspace select livemode
export STRIPE_API_KEY="sk_live_..."
terraform plan
terraform apply
```

## Handle rate limits

Terraform runs operations in parallel by default, which can cause rate limiting errors when managing many Stripe resources. The Stripe API allows up to [100 read operations per second in live mode and 25 in sandbox mode](https://docs.stripe.com/rate-limits.md), with individual API endpoints having their own limits.

To prevent hitting rate limits, use the `-parallelism` flag to reduce the number of concurrent operations:

```bash
terraform plan -parallelism=2
terraform apply -parallelism=2
```

For large infrastructure deployments, we recommend setting `parallelism` to between 2 and 5 to stay within the rate limits. This is important in sandbox mode, where rate limits are lower.