Schema:: BILLING

BILLING_SUBSCRIPTIONS_HISTORY view¶

The BILLING_SUBSCRIPTIONS_HISTORY view in the BILLING schema provides a current snapshot of your existing subscriptions and relevant billing information for subscription products.

The view includes:

Subscription product information.
Subscription lifecycle dates and status.
Organization and account metadata.
Subscription phase information, when applicable.
Billed or pending installments.
Subscription quantity, amount, currency, and auto-renewal information.

The view does not include:

Marketplace subscriptions.
Overage or usage charges.
Oracle BYOL products.
Invoice activity.
Subscriptions without at least one qualifying installment.

Access¶

Requirement	Detail
Database	SNOWFLAKE
Schema	BILLING
Account requirement	Must be an org-enabled account
Database role	SNOWFLAKE.ORGANIZATION_BILLING_VIEWER

Access is restricted to org-enabled accounts and requires the ORGANIZATION_BILLING_VIEWER database role on the SNOWFLAKE shared database.

Columns¶

Column Name	Data Type	Description
SUBSCRIPTION_ID	VARCHAR	Identifier of the subscription.
FEATURE	VARCHAR	Subscription product, such as `CORTEX-CODE-CLI`.
PRODUCT_TYPE	VARCHAR	Product line represented by the row.
SUBSCRIPTION_NAME	VARCHAR	Display name of the subscription.
STATUS	VARCHAR	Lifecycle status of the subscription. For the possible values, see STATUS values.
ORGANIZATION_NAME	VARCHAR	Name of the organization.
ACCOUNT_LOCATOR	VARCHAR	System-generated identifier for the account.
ACCOUNT_NAME	VARCHAR	User-defined identifier for the account.
REGION	VARCHAR	Name of the region where the account is located.
TRIAL_START_DATE	TIMESTAMP_NTZ	Start timestamp of the first Trial phase. NULL when the subscription has no configured Trial phase.
TRIAL_END_DATE	TIMESTAMP_NTZ	End timestamp (exclusive) of the first Trial phase. NULL when the subscription has no configured Trial phase or the phase is open-ended.
START_DATE	TIMESTAMP_NTZ	Subscription start timestamp.
END_DATE	TIMESTAMP_NTZ	Subscription end timestamp. NULL when the subscription is open-ended.
CANCELLATION_DATE	TIMESTAMP_NTZ	Timestamp when the cancellation takes effect. A future value means the subscription is marked for cancellation and remains in its current term until that time. NULL if the subscription is not canceled.
CANCELLATION_REASON	VARCHAR	Reason the subscription was canceled. NULL if the subscription is not canceled.
RENEWAL_DATE	DATE	Date the subscription renews. NULL if the subscription does not renew automatically.
NEXT_BILLING_DATE	DATE	Date of the next scheduled charge for the subscription. NULL when no charge is scheduled.
PHASE_NAME	VARCHAR	Name of the current phase.
IS_BILLABLE	BOOLEAN	Indicates whether the current phase is billable.
PHASE_DURATION	NUMBER	Configured duration of the current phase.
PHASE_DURATION_TYPE	VARCHAR	Unit for PHASE_DURATION, such as `DAY` or `MONTH`.
PHASE_START_DATE	TIMESTAMP_NTZ	Start timestamp of the current phase.
PHASE_END_DATE	TIMESTAMP_NTZ	End timestamp (exclusive) of the current phase.
QUANTITY	NUMBER	Number of subscribed units. The value can include a fraction.
UNIT_PRICE	NUMBER	Price of one subscribed unit on one qualifying installment, based on the most recent qualifying installment available from the source. This is not calculated as TOTAL_AMOUNT / QUANTITY and is not a lifetime average.
TOTAL_AMOUNT	NUMBER	Amount billed so far. This does not include usage or overage charges. The value is 0 if nothing has been billed.
CURRENCY	VARCHAR	Currency of the amount, represented as an ISO 4217 code. The default is USD.
INSTALLMENTS_BILLED	NUMBER	Number of subscription payments that have been billed. The value is 0 if none have been billed.
INSTALLMENTS_SCHEDULED_COUNT	NUMBER	Number of subscription payments that are still scheduled. The value is 0 if none are scheduled.
IS_AUTO_RENEW	BOOLEAN	TRUE if the subscription renews automatically.
CREATED_DATE	TIMESTAMP_NTZ	Timestamp when the subscription was created.
LAST_MODIFIED_DATE	TIMESTAMP_NTZ	Timestamp when the subscription was last updated.

STATUS values¶

The STATUS column is derived from the subscription lifecycle dates and the current subscription phase.

Value	Description
`CANCELED`	The subscription is canceled or marked for cancellation. CANCELLATION_DATE is when the termination takes effect. A CANCELLATION_DATE in the future means the subscription is marked for cancellation and remains in its current term until that timestamp. END_DATE is the subscription end and is not the cancellation effective date.
`TRIAL`	The current timestamp falls within a non-billable Trial phase interval.
`EXPIRED`	The subscription end timestamp has passed.
`ACTIVE`	The subscription is not canceled, is not currently in a Trial phase, and has not passed its end date.

For trial and phase intervals, the start timestamp is inclusive and the end timestamp is exclusive. An interval with a NULL end timestamp has no defined end.

Usage notes¶

The view is available to all customers and returns the subscriptions for your organization.
Latency for the view may be up to 4 hours.

Example queries¶

Query active and trial subscriptions¶

SELECT
    SUBSCRIPTION_ID,
    FEATURE,
    PRODUCT_TYPE,
    STATUS,
    START_DATE,
    END_DATE,
    NEXT_BILLING_DATE
  FROM SNOWFLAKE.BILLING.BILLING_SUBSCRIPTIONS_HISTORY
  WHERE STATUS IN ('ACTIVE', 'TRIAL');

Query a feature, including future-dated cancellations¶

SELECT
    SUBSCRIPTION_ID,
    FEATURE,
    STATUS,
    CANCELLATION_DATE,
    END_DATE
  FROM SNOWFLAKE.BILLING.BILLING_SUBSCRIPTIONS_HISTORY
  WHERE FEATURE = 'CORTEX-CODE-CLI'
    AND (
          STATUS IN ('ACTIVE', 'TRIAL')
          OR (
              STATUS = 'CANCELED'
              AND CANCELLATION_DATE >= CURRENT_TIMESTAMP()
          )
        );