Preview subscription

Previews the pricing impact of creating or updating a subscription without making changes. Returns estimated costs, taxes, and proration details.

POST /api/v1/subscriptions/preview

JavaScript

JavaScript

import Stigg from '@stigg/typescript';

const client = new Stigg({
  apiKey: process.env['STIGG_API_KEY'], // This is the default and can be omitted
});

const response = await client.v1.subscriptions.preview({
  customerId: 'customerId',
  planId: 'planId',
});

console.log(response.data);

201

{
  "data": {
    "immediateInvoice": {
      "total": 123,
      "subTotal": 123,
      "discount": 123,
      "tax": 123,
      "currency": "<string>",
      "billingPeriodRange": {
        "start": "2023-11-07T05:31:56Z",
        "end": "2023-11-07T05:31:56Z"
      },
      "lines": [
        {
          "description": "<string>",
          "unitPrice": 123,
          "subTotal": 123,
          "currency": "<string>",
          "quantity": 123
        }
      ],
      "discounts": [
        {
          "description": "<string>",
          "amount": 123,
          "currency": "<string>"
        }
      ],
      "discountDetails": {
        "code": "<string>",
        "percentage": 123,
        "fixedAmount": 123
      }
    },
    "recurringInvoice": {
      "total": 123,
      "subTotal": 123,
      "discount": 123,
      "tax": 123,
      "currency": "<string>",
      "billingPeriodRange": {
        "start": "2023-11-07T05:31:56Z",
        "end": "2023-11-07T05:31:56Z"
      },
      "lines": [
        {
          "description": "<string>",
          "unitPrice": 123,
          "subTotal": 123,
          "currency": "<string>",
          "quantity": 123
        }
      ],
      "discounts": [
        {
          "description": "<string>",
          "amount": 123,
          "currency": "<string>"
        }
      ],
      "discountDetails": {
        "code": "<string>",
        "percentage": 123,
        "fixedAmount": 123
      }
    },
    "billingPeriodRange": {
      "start": "2023-11-07T05:31:56Z",
      "end": "2023-11-07T05:31:56Z"
    },
    "isPlanDowngrade": true,
    "hasScheduledUpdates": true,
    "freeItems": [
      {
        "id": "<string>",
        "quantity": 1
      }
    ]
  }
}

Authorizations

X-API-KEY · string · header · required

Server API Key

Headers

X-ACCOUNT-ID · string

Account ID — optional when authenticating with a user JWT (Bearer token); falls back to the user's first membership. Ignored for API-key auth.

X-ENVIRONMENT-ID · string

Environment ID — required when authenticating with a user JWT (Bearer token) on environment-scoped endpoints. Ignored for API-key auth (env is intrinsic to the key).

Body

application/json

Preview subscription pricing and invoice details before provisioning. Returns calculated totals, line items, taxes, and discounts based on the provided subscription configuration.

customerId · string · required

Customer ID

Required string length: 1 - 255

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.@-]*$

planId · string · required

Plan ID

Required string length: 1 - 255

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$

payingCustomerId · string

Paying customer ID for delegated billing

Required string length: 1 - 255

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.@-]*$

resourceId · string

Resource ID for multi-instance subscriptions

Required string length: 1 - 255

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$

billingPeriod · enum<string>

Billing period (MONTHLY or ANNUALLY)

Available options: MONTHLY, ANNUALLY

billingCountryCode · string

ISO 3166-1 country code for localization

Maximum string length: 255

unitQuantity · integer

Unit quantity for per-unit pricing. Minimum is 0 (zero is allowed).

Required range: x >= 0

billableFeatures · BillableFeature · object[]

Billable features with quantities

Show child attributes

charges · SubscriptionCharge · object[]

One-time or recurring charges

Show child attributes

addons · SubscriptionAddon · object[]

Addons to include

Show child attributes

startDate · string<date-time>

Subscription start date

billingInformation · SubscriptionBillingInfo · object

Billing and tax configuration

Show child attributes

scheduleStrategy · enum<string>

When to apply subscription changes

Available options: END_OF_BILLING_PERIOD, END_OF_BILLING_MONTH, IMMEDIATE

appliedCoupon · SubscriptionCoupon · object

Coupon or discount to apply

Show child attributes

trialOverrideConfiguration · TrialOverrideConfiguration · object

Trial period override settings

Show child attributes

billingCycleAnchor · enum<string>

Billing cycle anchor behavior for the subscription

Available options: UNCHANGED, NOW

Response

201

application/json

The subscription preview with pricing breakdown.

Response object

data · SubscriptionPreview · object · required

Pricing preview with invoices

Show child attributes