Subscription Mutations

WooGraphQL Pro provides mutations for complete subscription lifecycle management and subscription product CRUD.

Marks an active subscription for cancellation. The subscription will be cancelled at the end of the current billing period.

Returns the updated Subscription object.

mutation CancelSubscription($id: Int!) {
  cancelSubscription(input: { id: $id }) {
    subscription {
      id
      databaseId
      status
      cancelledDate
      endDate
    }
  }
}

Variables:

{
  "id": 123
}

Response:

{
  "data": {
    "cancelSubscription": {
      "subscription": {
        "id": "c3Vic2NyaXB0aW9uOjEyMw==",
        "databaseId": 123,
        "status": "PENDING_CANCEL",
        "cancelledDate": "2024-01-15T10:30:00+00:00",
        "endDate": "2024-02-15T10:30:00+00:00"
      }
    }
  }
}

• Changes status to PENDING_CANCEL
• Subscription remains active until the current period ends
• Customer retains access until endDate

---

Restores a cancelled or pending-cancel subscription to active status.

Returns the updated Subscription object.

mutation ReactivateSubscription($id: Int!) {
  reactivateSubscription(input: { id: $id }) {
    subscription {
      id
      status
      nextPaymentDate
    }
  }
}

Variables:

{
  "id": 123
}

Response:

{
  "data": {
    "reactivateSubscription": {
      "subscription": {
        "id": "c3Vic2NyaXB0aW9uOjEyMw==",
        "status": "ACTIVE",
        "nextPaymentDate": "2024-02-15T10:30:00+00:00"
      }
    }
  }
}

• Changes status back to ACTIVE
• Clears cancellation date
• Recalculates next payment date

---

Switches a subscription to a different product, with automatic proration calculation.

Returns the Cart with the switch item and proration details.

mutation SwitchSubscription(
  $subscriptionId: Int!
  $lineItemId: Int!
  $productId: Int!
) {
  switchSubscription(
    input: {
      subscriptionId: $subscriptionId
      lineItemId: $lineItemId
      productId: $productId
    }
  ) {
    cart {
      contents {
        nodes {
          key
          product {
            node {
              name
            }
          }
          quantity
          total
          extraData {
            key
            value
          }
        }
      }
      total
    }
    cartItem {
      key
      extraData {
        key
        value
      }
    }
  }
}

Variables:

{
  "subscriptionId": 123,
  "lineItemId": 456,
  "productId": 789
}

The cart item's extraData contains switch metadata:

The switch calculates prorated amounts based on:

• Time remaining in current period
• Price difference between products
• Subscription settings for upgrades/downgrades

• Adds switch item to cart (requires checkout to complete)
• Supports both upgrades and downgrades
• Respects WooCommerce Subscriptions proration settings

---

Updates subscription details including billing address.

Returns the updated Subscription object.

mutation UpdateSubscription($id: Int!, $billing: CustomerAddressInput) {
  updateSubscription(input: { id: $id, billing: $billing }) {
    subscription {
      id
      billing {
        firstName
        lastName
        address1
        city
        state
        postcode
        country
        email
        phone
      }
    }
  }
}

Variables:

{
  "id": 123,
  "billing": {
    "firstName": "Jane",
    "lastName": "Smith",
    "address1": "456 New Street",
    "city": "New City",
    "state": "CA",
    "postcode": "90210",
    "country": "US",
    "email": "[email protected]",
    "phone": "555-0123"
  }
}

---

Sets a subscription's recurring payment method to one of the customer's saved payment tokens. The token must already exist (added via the customer's account / add-payment-method flow) and belong to the subscription's customer.

mutation ChangePaymentMethod($id: ID!, $paymentTokenId: Int!) {
  changePaymentMethod(input: { id: $id, paymentTokenId: $paymentTokenId }) {
    subscription {
      id
      paymentMethod
      paymentMethodTitle
    }
  }
}

• The mutation is gateway-agnostic. It hands the new token to WCS_Payment_Tokens::update_subscription_token(), which swaps only the single gateway meta key whose value matches the subscription's current source (resolved via the woocommerce_subscription_payment_meta filter). Account-scoped meta such as a gateway customer id is left untouched, and no gateway-specific keys cross the wire.
• The subscription's active source is often not a saved, reusable token (e.g. the off-session source captured at signup). In that case the mutation synthesizes a stand-in from the stored source value — identified generically as the meta value sharing the new token's id prefix (e.g. pm_) — so the correct key can still be located and swapped.
• If the new token belongs to a different gateway than the subscription's current one, the subscription's payment method is repointed to the new gateway.
• The subscription must have a current source on its gateway to replace. If none can be resolved, the mutation errors rather than writing partial meta.
• To use a brand-new card, add it through the customer's add-payment-method flow first, then call this mutation with the resulting token id.

---

Resubscribes to a cancelled or expired subscription by adding its items to the cart for checkout (mirrors the WCS_Cart_Resubscribe flow). The current cart is emptied first.

Returns the cart populated with the resubscription items.

mutation Resubscribe($id: ID!) {
  resubscribe(input: { id: $id }) {
    cart {
      contents {
        nodes {
          key
          product {
            node {
              name
            }
          }
          quantity
        }
      }
      total
    }
  }
}

• Only allowed when wcs_can_user_resubscribe_to passes — the subscription is cancelled/expired, has previous payments, and all products are still available.
• Each cart item carries subscription_resubscribe extra data linking it to the original subscription and line item.
• Complete the flow with the standard checkout mutation against the populated cart.

See the Mutations Reference for the full specification.

---

All subscription mutations require:

• User must be authenticated
• User must own the subscription OR be an admin

Common errors:

Creates a new subscription product with recurring billing fields. See the Mutations Reference for full input/output details.

mutation CreateSubscriptionProduct($input: CreateSubscriptionProductInput!) {
  createSubscriptionProduct(input: $input) {
    product {
      databaseId
      name
      ... on SubscriptionProduct {
        price
        subscriptionPeriod
        subscriptionPeriodInterval
        subscriptionLength
        trialPeriod
        trialLength
        signUpFee
      }
    }
  }
}

Variables:

{
  "input": {
    "name": "Monthly Pro Plan",
    "subscriptionPrice": 29.99,
    "subscriptionPeriod": "MONTH",
    "subscriptionPeriodInterval": 1,
    "subscriptionLength": 0,
    "signUpFee": 9.99,
    "trialPeriod": "WEEK",
    "trialLength": 1
  }
}

Updates an existing subscription product.

mutation UpdateSubscriptionProduct($input: UpdateSubscriptionProductInput!) {
  updateSubscriptionProduct(input: $input) {
    product {
      databaseId
      ... on SubscriptionProduct {
        subscriptionPrice
        subscriptionPeriod
      }
    }
  }
}

Subscription product mutations also accept addons and excludeGlobalAddons fields. See Per-Product Addon Fields.

• Querying Subscriptions - Query subscription data
• Subscription Products - Product types
• API Mutations Reference - Complete mutation specifications