Activate a one-time purchase when adding a recurring product

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

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.

​Request activation and payment health

​Handle the result

​Activation scope

Request activation and payment health

Handle the result

Activation scope