> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stigg.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CodeGroup>
  ```graphql Mutation theme={null}
  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
      }
    }
  }
  ```

  ```json Variables theme={null}
  {
    "input": {
      "customerId": "customer-123",
      "planId": "plan-enterprise",
      "billingPeriod": "ANNUAL",
      "addons": [
        { "addonId": "addon-seats", "quantity": 10 }
      ]
    }
  }
  ```

  ```json Response theme={null}
  {
    "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
      }
    }
  }
  ```
</CodeGroup>

## Parameters

<ParamField body="input" type="PreviewSubscriptionInput" required>
  Input for previewing subscription

  <Expandable title="properties">
    <ParamField body="customerId" type="String" required>
      Customer reference ID
    </ParamField>

    <ParamField body="planId" type="String" required>
      Plan reference ID
    </ParamField>

    <ParamField body="billingPeriod" type="BillingPeriod">
      Billing period
    </ParamField>

    <ParamField body="addons" type="[SubscriptionAddonInput]">
      Addons to include
    </ParamField>

    <ParamField body="couponId" type="String">
      Coupon to apply
    </ParamField>

    <ParamField body="resourceId" type="String">
      Resource ID
    </ParamField>

    <ParamField body="environmentId" type="UUID">
      Environment ID
    </ParamField>
  </Expandable>
</ParamField>

## 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

```json theme={null}
{
  "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.

```json theme={null}
{
  "input": {
    "customerId": "customer-123",
    "planId": "plan-enterprise"
  }
}
```

### Preview with Coupon

```json theme={null}
{
  "input": {
    "customerId": "customer-123",
    "planId": "plan-pro",
    "couponId": "SAVE20"
  }
}
```

## Common Use Cases

<AccordionGroup>
  <Accordion title="Checkout preview">
    Show pricing before customer confirms purchase.
  </Accordion>

  <Accordion title="Upgrade preview">
    Show pricing impact of upgrading to a higher plan.
  </Accordion>

  <Accordion title="Coupon validation">
    Show discount amount before applying coupon.
  </Accordion>
</AccordionGroup>

## Related Operations

* [Provision Subscription](/api-and-sdks/api-reference/mutations/provision-subscription) - Create subscription
* [Update Subscription](/api-and-sdks/api-reference/mutations/update-subscription) - Modify subscription