Replace subscription products in one request

Use replaceSubscriptionProducts when several products on the same subscription need to change together—for example, replacing discontinued products with their successors.

Requirements

A project API access token with write access.
The subscription ID and the IDs of its active ordered products.
Replacement catalog product IDs from the same project.

An ordered product ID identifies a product line on a subscription. It is different from the catalog product ID.

Replace products

Send the mutation to the GraphQL API with these variables:

mutation ReplaceSubscriptionProducts(
  $subscriptionId: ID!
  $replacements: [OrderedProductReplacementInput!]!
) {
  replaceSubscriptionProducts(input: {
    subscriptionId: $subscriptionId
    replacements: $replacements
  }) {
    orderedProducts {
      id
      quantity
      product { id }
    }
    errors {
      attribute
      message
    }
  }
}

Example variables:

{
  "subscriptionId": "123456",
  "replacements": [
    { "orderedProductId": "1001", "productId": "2001" },
    { "orderedProductId": "1002", "productId": "2002" }
  ]
}

Replace these example IDs with records from your project. Each replacement retains the ordered product’s quantity, plan, and any custom price. Without a custom price, the replacement product’s price applies.

Check the shipment cadence

Stored interval settings are retained, but the effective shipment cadence can change. When an ordered product uses the default interval, it inherits the replacement product’s interval and unit. Explicit interval overrides remain effective unless the replacement product ships on the billing cycle; in that case, the subscription plan’s delivery or billing cycle determines the cadence. Check these settings before replacing products with a different shipment frequency.

Limits and results

Replace up to 100 active ordered products on one subscription per request.
Include each ordered product ID only once.
Changes are applied together. If a replacement fails validation, none of the batch is saved.
Successful changes return the updated ordered products and an empty errors list. A successful batch with changes sends the usual product-change notification once.
Replacing a product with itself makes no change; an empty replacement list also makes no change.

Check both the top-level GraphQL errors and the mutation’s errors. Invalid counts, duplicate ordered product IDs, missing records, and authorization failures can produce top-level errors. Product validation failures return orderedProducts: null and validation messages. For Shopify subscriptions, contract synchronization is scheduled after the changes are saved. A successful mutation confirms the Firmhouse changes, not completion of that background synchronization.

​Requirements

​Replace products

​Check the shipment cadence

​Limits and results

Requirements

Replace products

Check the shipment cadence

Limits and results