Billing & Subscription Examples

Explore queries and mutations for managing subscriptions, rendering payment popups, and handling special offers.

1. Fetch Payment Popup Details

Retrieve the available subscription packages and payment configurations necessary to render a premium upgrade popup.

query GetPaymentPopupDetails {
  billing {
    paymentPopupDetails {
      paymentMethodName
      disclaimerEnabled
      disclaimerText
      popupTitle
      packages {
        id
        name
        price
        pricePerMonth
        displayMessage
        displayDescriptionItems
        isMarked
      }
    }
  }
}

2. Fetch a Special Offer Page

Retrieve a marketing landing page for a special subscription offer by its URL slug.

query GetSpecialOfferPage($url: String!) {
  billing {
    specialOfferPage(url: $url) {
      id
      title
      description
      iconTitle1
      package {
        id
        name
        price
        discountPrice
      }
    }
  }
}

Variables:

{
  "url": "summer-sale-2026"
}

3. Read the Active Membership

The plan card fields — price, billing cycle, and the trial / renewal dates — hang off me.membership, so no follow-up package lookup is required. Maintenance-mode and payment-popup flags still come from the legacy JSON:API.

query GetMembership {
  me {
    membership {
      id
      status
      name
      price
      expirationPeriodType
      expirationPeriodValue
      freeTrial
      freeTrialEndDate
      startDate
      renewalDate
      expiresAt
      freemium
      paymentMethod
      lastDiscount {
        requestedAt
        fulfilledAt
      }
    }
  }
}

price is the pre-tax amount charged per billing cycle. A lastDiscount with a requestedAt but no fulfilledAt means a retention discount is pending and applies to the next charge.

4. Cancel Membership

Permanently cancel the active membership subscription for the currently authenticated user.

mutation CancelMembership($membershipId: ID!) {
  billing {
    cancelMembership(membershipId: $membershipId)
  }
}

5. Submit Cancellation Survey

Submit a survey response when a user attempts to cancel their subscription. This is often used for retention analytics.

mutation SubmitCancellationSurvey($input: BillingSubscriptionCancellationSurveyInput!) {
  billing {
    submitSubscriptionCancellationSurvey(input: $input)
  }
}

Variables:

{
  "input": {
    "subscriptionId": "sub_12345",
    "optionId": "opt_too_expensive",
    "details": "I found another service."
  }
}

6. Create Checkout Session

Create a Stripe-hosted Checkout Session for a package. The mobile app opens the returned url in an external browser; fulfillment happens via the Stripe webhook, not the redirect.

The success and cancel redirects are configured per environment on the backend — https bridge pages that bounce to the sowl:// app scheme — and are not settable by the client, so the post-payment landing page cannot be redirected to an arbitrary host.

mutation CreateCheckoutSession($input: CreateCheckoutSessionInput!) {
  billing {
    createCheckoutSession(input: $input) {
      url
      sessionId
    }
  }
}

Variables:

{
  "input": {
    "packageId": "123"
  }
}