Preview Subscription

Previews the pricing impact of creating or updating a subscription without making changes. When a customer already has an active subscription, Stigg automatically detects it and calculates proration — no subscriptionId is needed.

Mutation

Mutation

mutation PreviewSubscription($input: PreviewSubscriptionInput!) {
  previewSubscription(input: $input) {
    immediateInvoice {
      subtotal {
        amount
        currency
      }
      discount {
        amount
        currency
      }
      tax {
        amount
        currency
      }
      total {
        amount
        currency
      }
      lineItems {
        description
        quantity
        unitPrice {
          amount
          currency
        }
        total {
          amount
          currency
        }
      }
    }
    recurringInvoice {
      subtotal {
        amount
        currency
      }
      total {
        amount
        currency
      }
    }
    credits {
      amount
      currency
    }
    proration {
      amount
      currency
    }
  }
}

{
  "input": {
    "customerId": "customer-123",
    "planId": "plan-enterprise",
    "billingPeriod": "ANNUAL",
    "addons": [
      { "addonId": "addon-seats", "quantity": 10 }
    ]
  }
}

{
  "data": {
    "previewSubscription": {
      "immediateInvoice": {
        "subtotal": {
          "amount": 3990,
          "currency": "USD"
        },
        "discount": {
          "amount": 0,
          "currency": "USD"
        },
        "tax": {
          "amount": 319.2,
          "currency": "USD"
        },
        "total": {
          "amount": 4309.2,
          "currency": "USD"
        },
        "lineItems": [
          {
            "description": "Enterprise Plan (Annual)",
            "quantity": 1,
            "unitPrice": {
              "amount": 2990,
              "currency": "USD"
            },
            "total": {
              "amount": 2990,
              "currency": "USD"
            }
          },
          {
            "description": "Extra Seats x 10",
            "quantity": 10,
            "unitPrice": {
              "amount": 100,
              "currency": "USD"
            },
            "total": {
              "amount": 1000,
              "currency": "USD"
            }
          }
        ]
      },
      "recurringInvoice": {
        "subtotal": {
          "amount": 3990,
          "currency": "USD"
        },
        "total": {
          "amount": 4309.2,
          "currency": "USD"
        }
      },
      "credits": null,
      "proration": null
    }
  }
}

Parameters

input · PreviewSubscriptionInput · required

Input for previewing subscription

Show properties

customerId · String · required

Customer reference ID

planId · String · required

Plan reference ID

billingPeriod · BillingPeriod

Billing period

addons · [SubscriptionAddonInput]

Addons to include

couponId · String

Coupon to apply

resourceId · String

Resource ID

environmentId · UUID

Environment ID

Return Type

Returns a SubscriptionPreviewV2 with:

Field	Type	Description
immediateInvoice	InvoicePreview	Charges due immediately
recurringInvoice	InvoicePreview	Future recurring charges
credits	Money	Credits to be applied
proration	Money	Proration amount

InvoicePreview Fields

Field	Type	Description
subtotal	Money	Before tax/discount
discount	Money	Discount amount
tax	Money	Tax amount
total	Money	Final amount
lineItems	[LineItem]	Itemized charges

Examples

Preview New Subscription

{
  "input": {
    "customerId": "customer-123",
    "planId": "plan-pro",
    "billingPeriod": "MONTHLY"
  }
}

Preview Upgrade

Pass the customer’s ID and the target planId. The backend automatically detects the customer’s active subscription and calculates proration.

{
  "input": {
    "customerId": "customer-123",
    "planId": "plan-enterprise"
  }
}

Preview with Coupon

{
  "input": {
    "customerId": "customer-123",
    "planId": "plan-pro",
    "couponId": "SAVE20"
  }
}

Common Use Cases

Checkout preview

Show pricing before customer confirms purchase.

Upgrade preview

Show pricing impact of upgrading to a higher plan.

Coupon validation

Show discount amount before applying coupon.

Related Operations

• Provision Subscription - Create subscription
• Update Subscription - Modify subscription