Categories:

System Functions (System Control)

SYSTEM$CREATE_BILLING_EVENT

Creates a billable event that tracks consumer usage of an installed monetized application. This system function can only be called from an application installed in a consumer account.

Syntax

SYSTEM$CREATE_BILLING_EVENT(
  <class>,
  <subclass>,
  <start_timestamp>,
  <timestamp>,
  <base_charge>,
  <objects>,
  <additional_info>)
Copy

Arguments

Required:

class

Identifier for the custom event class.

Type: String

The identifier has the following requirements:

  • Must start with a letter (A-Z) or an underscore (“_”).

  • Must contain only letters, underscores, decimal digits (0-9), and dollar signs (“$”).

  • Length cannot exceed 64 characters.

  • Must not start with SNOWFLAKE_. SNOWFLAKE_ is reserved for internal identifiers.

The class name is stored and resolved as uppercase characters. Class name comparisons are case-insensitive.

timestamp

Specifies the timestamp (UTC) when the event was created as a Unix timestamp in milliseconds.

Type: Integer

base_charge

Specifies the amount in US dollars to be charged for the billable event. The value must be greater than 0, less than 999.99, and must not exceed 2 decimal places of precision. For example, 1.00 or 0.07.

Type: Double

Optional:

subclass

Identifier for the custom event subclass. This field is only used by the provider.

Type: String

The identifier has the same naming requirements as the class argument.

start_timestamp

Specifies the start time of the event as a Unix timestamp in milliseconds.

Type: Integer

Use to set the start time in cases where providers want to emit an event based on a time range; otherwise set to the same value used for the TIMESTAMP argument.

objects

A JSON string array containing fully qualified object names that apply to this event.

Type: String

The maximum size is 4 KB.

additional_info

A JSON string of key-value pairs the provider can use to send additional info.

Type: String

The maximum size is 4 KB.

Returns

This function returns the following status messages:

Status Message

Description

Type of Value Returned

Success

Indicates that the billable event was successfully created.

Invalid parameter: <PARAM_NAME>.

Indicates that an unsupported parameter was passed to the function.

Only callable from within an application.

Indicates that the function was called from outside an application.

Payload length exceeds the limit of 9000 characters.

Indicates that the call to the function exceeds the character limit.

Number of events exceeds the limit of 100.

Indicates that the maximum number of billable events has been reached for the application.

Too many calls. At most 1 call is allowed per 1 second window.

Indicates that an application made too many calls to this system function within a specific timeframe.

Usage Notes

This system function can only be called from within a stored procedure in the setup script of an application created using the Snowflake Native App Framework.

Examples

See Billable event examples.

Language: English