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

# Build a paid plan switch or upgrade flow

> Let customers switch to another plan only after they accept an offer and complete an initial payment.

Use this guide when you want to offer customers an upgrade or plan switch from a headless storefront, Magento account area, Salesforce Commerce Cloud account area, or another external customer experience.

This flow is useful when the new plan should only become active after the customer pays an initial amount. A common example is upgrading from a monthly recurring plan to a prepaid 6-month plan with a lower monthly equivalent price.

<Info>
  Paid plan switch offers are currently in private beta.
</Info>

## How it works

1. You build the upgrade promotion UI in your own storefront or account area.
2. When the customer accepts the offer, your app calls `switchSubscriptionPlan`.
3. Firmhouse creates an `Offer` and returns an `acceptUrl`.
4. You redirect the customer to `acceptUrl`.
5. The customer completes payment through your configured payment provider.
6. Firmhouse records the payment, finalizes the invoice, switches the subscription to the new plan, and creates related records.
7. Firmhouse redirects the customer to your success or failure URL if you passed those URLs to the mutation.
8. You can listen for webhooks to know when the offer was accepted.

For simple plan changes that should take effect immediately and do not require payment first, use `updateSubscribedPlan` instead.

## Create the upgrade UI

Create a section in your storefront or account area that explains the upgrade and why it is useful to the customer. This can be:

* a dashboard widget
* a modal behind an **Upgrade** button
* a plan comparison screen
* a campaign landing page for logged-in customers

The call to action should trigger your backend or frontend integration code that calls `switchSubscriptionPlan`.

## Start the paid switch flow

Call `switchSubscriptionPlan` with the current subscription ID and the target plan ID.

```graphql theme={null}
mutation SwitchSubscriptionPlan {
  switchSubscriptionPlan(input: {
    subscriptionId: 1234,
    planId: 456
  }) {
    offer {
      id
      acceptUrl
    }
  }
}
```

Redirect the customer to `offer.acceptUrl`. Firmhouse opens the payment flow for the requested initial payment.

`Offer` URLs expire after 30 minutes. Create the offer when the customer explicitly starts the upgrade flow, not ahead of time.

## Redirect customers back to your site

Pass `successUrl` and `failureUrl` if you want customers to return to your own website after the payment flow.

```graphql theme={null}
mutation SwitchSubscriptionPlan {
  switchSubscriptionPlan(input: {
    subscriptionId: 1234,
    planId: 456,
    successUrl: "https://myaccount.example.com/upgrade/success",
    failureUrl: "https://myaccount.example.com/upgrade"
  }) {
    offer {
      id
      acceptUrl
    }
  }
}
```

Use:

* `successUrl` after the customer successfully pays and accepts the offer.
* `failureUrl` when the offer URL has expired or the offer cannot be accepted.

## Listen for accepted offers

When the customer accepts the offer, Firmhouse marks the offer as completed and emits an `offer_completed` webhook.

Use that webhook to update your external customer account area, analytics, CRM, or marketing automation.

## Emails

When an offer is accepted, Firmhouse can send project notifications and customer email notifications. Configure the customer-facing email in **Email Configuration** in your Firmhouse project.

## Limitations

Customers cannot enter discount codes in this paid plan switch flow yet, and the API does not support supplying a discount code for the offer.

## Related

* [Webhooks](https://developer.firmhouse.com/webhooks/overview)
* [API Reference](https://developer.firmhouse.com/graphql-api/api-reference)