Preview Upcoming Subscription Invoice

Returns a non-persisted preview of the invoice the next renewal will generate (Stripe-style invoice.upcoming). Returns `invoice: null` when the subscription is set to cancel at period end. Rejects incomplete, canceled, and unpaid subscriptions (no future cycle exists to preview). For past_due subscriptions, the preview reflects the cycle AFTER the current retry, not the in-flight unpaid invoice itself. To inspect the current cycle's open invoice, use `list_invoices` with `subscriptionId` and `status: payment_failed`.

Authorization

AuthorizationRequiredBearer <token>

API key as Bearer token

In: header

Path Parameters

idRequiredstring

Subscription id, discoverable via list_subscriptions

GET/v1/subscriptions/{id}/upcoming

curl -X GET "https://api.3common.com/v1/subscriptions/string/upcoming" \
  -H "Authorization: Bearer <token>"

Default Response

Response

{
  "data": {
    "invoice": {
      "customerId": "string",
      "subscriptionId": "string",
      "currency": "string",
      "lineItems": [
        {
          "description": "string",
          "quantity": 1,
          "unitAmount": 9007199254740991,
          "productId": "string",
          "priceId": "string"
        }
      ],
      "subtotal": 9007199254740991,
      "total": 9007199254740991,
      "periodStart": "2019-08-24T14:15:22Z",
      "periodEnd": "2019-08-24T14:15:22Z"
    }
  }
}

TypeScript

export interface Response {
  data: {
    invoice: {
      customerId: string;
      subscriptionId: string;
      currency: string;
      lineItems: {
        description: string;
        quantity: number;
        /**
         * Per-unit amount in minor units (cents)
         */
        unitAmount: number;
        productId?: string;
        priceId?: string;
      }[];
      /**
       * Sum of line-item amounts in minor units
       */
      subtotal: number;
      /**
       * Final amount the next renewal will bill, in minor units
       */
      total: number;
      periodStart: string;
      periodEnd: string;
    } | null;
  };
}