Subscriptions

Subscriptions represent recurring orders for one or more products on a schedule. A subscription is created during checkout for a subscription product and is then managed by the customer through their account.

The API exposes a customer’s subscriptions and a set of mutations to manage them: changing frequency, swapping products, delaying, applying retention offers and cancelling. All subscription mutations require authentication.

Availability of these fields is gated by the SUBSCRIPTIONS or SUBSCRIBE_AND_SAVE site features. Some mutations are only available when more specific features are enabled (for example SUBSCRIPTIONS_DELAY for delay actions or SUBSCRIPTIONS_CANCEL_ONLINE for self-service cancellation).

Listing a customer’s subscriptions

Subscriptions hang off the customer query. The list is paginated and can be filtered by id, status or subscription type.

query CustomerSubscriptions {
  customer {
    subscriptions(
      filter: { statuses: [ACTIVE, ON_HOLD, FAILED_PAYMENT] }
      offset: 0
      limit: 10
    ) {
      total
      hasMore
      subscriptions {
        id
        status
        createdAt
        nextBillingDate
        costPerPaymentPeriod {
          amount
          currency
          displayValue
        }
        schedule {
          dispatchFrequencyDuration {
            unit
            duration
          }
          autoRenew
          paymentType
          totalDeliveries
        }
        subscriptionItems {
          product {
            title
          }
          selectedVariant {
            sku
            title
          }
          quantity
        }
        cancellable
        cancellationRestriction {
          reason
          numberOfOrders
        }
        delayable
        productSwapAllowed
        productAddOnAllowed
        productRemovalAllowed
      }
    }
  }
}

Viewing a single subscription

To build a subscription management page you typically fetch a single subscription along with its swap and add-on options, billing details and any eligible retention offers.

query SubscriptionDetail {
  customer {
    subscriptions(filter: { id: "sub_12345" }, limit: 1) {
      subscriptions {
        id
        status
        nextBillingDate
        deliveryAddress {
          line1
          town
          postcode
          country
        }
        billingAddress {
          line1
          town
          postcode
          country
        }
        paymentCard {
          cardType
          obfuscatedCardNumber
          expiryMonth
          expiryYear
        }
        availableFrequencyChanges {
          unit
          duration
        }
        availableBillingDateChanges {
          start
          end
        }
        availableAddOnProducts {
          sku
          title
        }
        subscriptionItems {
          selectedVariant {
            sku
            title
          }
          quantity
          swappableSubscriptionVariants {
            sku
            title
          }
        }
        swappableSubscriptionPlans {
          id
          title
          planOptions {
            id
            name
            description
            isRecommended
            dispatchFrequency {
              unit
              duration
            }
            price {
              amount
              currency
              displayValue
            }
          }
        }
        eligibleRetentionSpecialOffers {
          id
          name
          description
          discountPercentage
          maxDiscountOrders
          startDate
          endDate
        }
        activeSpecialOffers {
          id
          discountPercentage
          numberOfOrdersApplicable
          specialOfferType
          specialOfferEndDate
        }
        autoRenewal {
          nextContractRenewalDate
          autoRenewalOverride {
            shouldContinueWithMonthlyRollingContractUnlessOptedIn
            optInType
          }
        }
      }
    }
  }
}

Changing frequency

Use availableFrequencyChanges on the subscription to populate the picker, then call updateSubscriptionFrequency with the chosen duration.

mutation UpdateFrequency {
  updateSubscriptionFrequency(
    subscriptionId: "sub_12345"
    newFrequency: { unit: WEEK, duration: 6 }
  )
}

Changing the next billing date

availableBillingDateChanges returns the date ranges the customer can pick from.

mutation UpdateBillingDate {
  updateSubscriptionBillingDate(
    subscriptionId: "sub_12345"
    newBillingDate: "2026-07-15"
  )
}

Updating the delivery address

The address must already exist on the customer’s account; see the address management examples for how to add one first.

mutation UpdateSubscriptionAddress {
  updateSubscriptionAddress(
    subscriptionId: "sub_12345"
    addressId: "addr_98765"
  )
}

Adding, swapping and removing products

A subscription can carry multiple items. The corresponding productAddOnAllowed, productSwapAllowed and productRemovalAllowed flags indicate which actions are available.

mutation AddSubscriptionProducts {
  addSubscriptionProducts(
    subscriptionId: "sub_12345"
    addOns: [{ newSku: 10987654, newQuantity: 1 }]
  )
}

mutation SwapSubscriptionProducts {
  swapSubscriptionProducts(
    subscriptionId: "sub_12345"
    swaps: [{ oldSku: 10000001, newSku: 10000002, newQuantity: 1 }]
  )
}

mutation RemoveSubscriptionProducts {
  removeSubscriptionProducts(
    subscriptionId: "sub_12345"
    removals: [10000001]
  )
}

Swapping plans

When a subscription has alternative plan options (different terms, frequencies or prices), swappableSubscriptionPlans lists them. Pass the chosen plan option id to swap.

mutation SwapSubscriptionPlan {
  swapSubscriptionPlans(
    subscriptionId: "sub_12345"
    newPlanOptionId: "plan_opt_456"
  )
}

Auto-renewal opt-in

For sites that ask the customer to choose between continuing on the existing contract or moving to a monthly rolling contract, set the opt-in type.

mutation UpdateAutoRenewal {
  updateSubscriptionAutoRenewalOptInType(
    subscriptionId: "sub_12345"
    optInTypeInput: { optInType: MONTHLY_ROLLING }
  )
}

Delaying a subscription

Delays push the next order out by a fixed amount (the supported delays are exposed through the SubscriptionDelay enum). The same subscription can also have a delay cancelled before it takes effect.

mutation DelaySubscription {
  delaySubscription(id: "sub_12345")
}

mutation CancelSubscriptionDelay {
  cancelSubscriptionDelay(id: "sub_12345")
}

Applying a retention offer

When the customer attempts to cancel, you can offer them a retention special offer drawn from eligibleRetentionSpecialOffers. Applying the offer keeps the subscription active under the new terms.

mutation ApplyRetentionOffer {
  applyRetentionSpecialOfferToSubscription(
    subscriptionId: "sub_12345"
    retentionSpecialOfferId: "offer_789"
  )
}

Cancelling

Before exposing a cancel button, check the cancellable flag and surface cancellationRestriction if cancellation is not allowed (for example because of an active cancellation policy or a retention offer that still has orders left to run).

mutation CancelSubscription {
  cancelSubscription(id: "sub_12345")
}