> ## 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.

# Activate a one-time purchase when adding a recurring product

> Opt into subscription activation with createOrderedProductV2 and use the advisory payment health result in your integration.

Use `createOrderedProductV2` with `activateSubscription: true` to activate a customer with **One-time purchase** status while adding an active recurring product. Use a project access token with subscription update permission.

The product must use the normal product behavior, rather than **Next order only** or **Already owned**. Existing product and subscription validations apply.

## Request activation and payment health

```graphql theme={null}
mutation AddProductAndActivate($subscriptionId: ID!, $productId: ID!) {
  createOrderedProductV2(input: {
    subscriptionId: $subscriptionId
    productId: $productId
    quantity: 1
    activateSubscription: true
  }) {
    subscription {
      id
      status
      updatePaymentMethodUrl
    }
    orderedProduct { id }
    paymentMethodHealthCheck {
      status
      paymentProvider
      checkedAt
      reason
    }
    errors
  }
}
```

Omitting `activateSubscription` or passing `false` adds the product without requesting activation or a payment health check. The flag is ignored for every subscription that is not a **One-time purchase**: the normal product-save permissions and response apply, and neither activation nor a payment health check occurs. Its status and activation date are preserved.

When activation occurs, Firmhouse checks the payment method before returning the response. A result for the current payment method is reused while fresh: healthy results expire after one week, and unhealthy or errored results after one day. A changed payment method requires a new check. An unsupported result is reused while it still matches the payment method.

## Handle the result

Payment health is advisory. An unhealthy, unsupported, or errored result does **not** prevent activation. If the health result cannot be stored, activation still succeeds and `paymentMethodHealthCheck` is `null` for that request.

| Status | Meaning | Integration action |
| - | - | - |
| `healthy` | The provider check found a usable payment method. | Continue your flow; this does not guarantee future payments will succeed. |
| `unhealthy` | The payment method failed the provider check, for example because no valid mandate exists. | Decide whether to ask the customer to update their payment method. |
| `errored` | The provider check could not complete. | Treat payment readiness as unknown. |
| `unsupported` | The checker cannot assess this payment setup. | Treat payment readiness as unknown. |
| `null` result | No result can be associated with the current payment method, for example because the provider or payment reference cannot be checked or matched. | Treat payment readiness as unknown. |

Your integration can send an email containing `subscription.updatePaymentMethodUrl` when follow-up is appropriate. The health check does not send this email for you.

`paymentMethodHealthCheck` returns the latest stored observation only if it matches the current payment method. When activation is skipped, any returned result is not refreshed; inspect `checkedAt` before relying on it.

## Activation scope

Activation uses the existing payment setup and shipment dates. It does not create a mandate, replay checkout, or charge an initial payment. The added product's commitments start; existing orders and plan commitments are preserved.

Validation errors roll back the product addition or quantity increase and activation together. On these failures, `subscription`, `orderedProduct`, and `paymentMethodHealthCheck` are `null`, and `errors` explains the failure. When `activateSubscription` is omitted or `false`, failed requests retain the existing response: `subscription` is returned alongside `errors`.


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