Custom Event Billing: Emitting and Configuring Billable Events

1.How Custom Event Billing works

Custom Event Billing lets an app charge for specific kinds of usage, such as each call to a stored procedure, on top of the standard usage-based pricing. Setting it up takes two steps, and both must be in place before anyone is charged:

1. In the application package: write stored procedures that call SYSTEM$CREATE_BILLING_EVENT or SYSTEM$CREATE_BILLING_EVENTS, and add them to the setup script. 2. On the listing: choose a usage-based pricing plan that includes billable events.

Only one implementation pattern is supported: the app calls the system function from inside one of its stored procedures. That procedure can be written in JavaScript, Python or Java. Other ways of working out the charge are not supported, such as using the output of a table or a UDF that tracks consumer activity, or telemetry logged in an event table. You also can't test the function while you build the package, because it only runs from an app installed in a consumer account.

Sources1

2.SYSTEM$CREATE_BILLING_EVENT and its parameters

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

The class is the field that matters most. It is the name the listing uses to price the event. Class names are compared case-insensitively. base_charge is the dollar amount for this event, so your code must calculate it before calling the function.

SYSTEM$CREATE_BILLING_EVENT is limited to one event per minute. To go beyond that, use SYSTEM$CREATE_BILLING_EVENTS and pass a JSON array of events with the same fields. Batching saves time, makes it less likely you'll hit call limits, and helps keep your events set up correctly. The documentation's examples wrap the call in a helper function, createBillingEvent, whose arguments must match the system function's parameter types.

Sources21

3.Billing patterns in the setup script

Every documented pattern has the same structure. The procedure does its work, counts something, multiplies the count by a price called billing_quantity to get base_charge, and emits an event with a descriptive class. The simplest version charges a flat amount for each procedure call:

  //
  // Send a billable event when a stored procedure is called.
  //
  var event_ts = Date.now();
  var billing_quantity = 1.0;
  var base_charge = billing_quantity;
  var objects = "[ \"db_1.public.procedure_1\" ]";
  var retVal = createBillingEvent("PROCEDURE_CALL", "", event_ts, event_ts, base_charge, objects, "");

The other documented patterns change only what gets counted:

- ROWS_CONSUMED: the number of rows a query returns from a consumer table, times 2.5. - ROWS_CHANGED: rows ingested by a MERGE (rows inserted plus rows updated), times 2.5. - MONTHLY_ACTIVE_ROWS: rows inserted or updated for the first time in a calendar month, found by checking an updated_on column, times 0.02. You can adapt this pattern to count unique users or unique data load locations instead.

The event is always emitted with a start_timestamp and timestamp in Unix milliseconds, such as Date.now() in JavaScript or int(time.time() * 1000) in Python. The examples that use the shared helper add the event-emitting code in the same procedure that defines the helper.

Sources1

4.Configuring billable events on the listing

Emitting events doesn't earn anything by itself. The listing has to name each event and price it. You configure the app first so that you know every class and its billing_quantity. Then, in Provider Studio, open the draft listing, go to Pricing & Trial, choose Add, select Usage-based, and click + Billable Event once for each event:

- Class: must exactly match the class in your system function call. - Event Display Name: a readable label, for example *Row Modified*. - Billing Quantity: must match the billing_quantity variable in your code. For example, 0.01 charges $1.00 per 100 rows. - Unit Name: the unit being charged for, for example *row*.

A listing can price up to eight billable events. You also add a Description of how the app bills consumers, and a Maximum Monthly Charge. Optionally you can add a monthly fee, a per-query charge with included queries, and a trial. You are paid only for events that you add to the listing. Any other events the app emits earn nothing.

Sources3

5.Testing billable events before publishing

Test with a consumer account inside your own organization. First, release the new code: update the setup script, update the application package, and update its version and release directive. Next, create a private listing with Custom Event Billing as the pricing plan, share it with the consumer account, and install the app there through Snowsight. Then call the billing procedures from that consumer account.

Three details catch people out:

- A payment method is required, but usage within your own organization is not billed. - Running the procedures in the provider account that created the package returns an error. - The usage view has latency. Wait at least two days before you query it.

SELECT listing_global_name,
   listing_display_name,
   charge_type,
   charge
FROM SNOWFLAKE.DATA_SHARING_USAGE.MARKETPLACE_PAID_USAGE_DAILY
WHERE charge_type=' ? '
      AND PROVIDER_ACCOUNT_NAME = <account_name>
      AND PROVIDER_ORGANIZATION_NAME= <organization_name>;

Sources1

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.You can calculate billable charges from telemetry the app writes to an event table.Why is that wrong?

   The only supported approach is calling the billing system function from a stored procedure in the app. Methods based on event-table telemetry are not supported.

   Covered in How Custom Event Billing works

2. 2.The listing's Billing Quantity can be any price you choose, separate from the code.Why is that wrong?

   The listing's Class and Billing Quantity must match the class and billing_quantity used in the application code.

   Covered in Configuring billable events on the listing

3. 3.You can verify billable events by calling the procedures in the provider account that built the package.Why is that wrong?

   The system function only works from an app installed in a consumer account. Running the procedures in the provider account returns an error.

   Covered in Testing billable events before publishing

Practise it for real

Emit a PROCEDURE_CALL billable event from an app and confirm it is recorded in a consumer account in your organization.

1. 1.Add a stored procedure that defines the createBillingEvent helper and emits a PROCEDURE_CALL event with billing_quantity 1.0, then add it to the setup script.

   Why: Billable events are only supported when the system function is called from a stored procedure in the app.

   You should see: The setup script contains the billing procedure.

2. 2.Update the application package, then update its version and release directive.

   Why: Consumers only receive the new code through the release directive.

   You should see: The release directive points to the version that includes the billing procedure.

3. 3.Create a private listing with a usage-based plan, and add a billable event with Class PROCEDURE_CALL and Billing Quantity 1.0.

   Why: The listing's class and billing quantity must match the code exactly, or you are not paid.

   You should see: The draft listing shows one billable event and a Maximum Monthly Charge.

4. 4.Share the listing with a consumer account in your organization, install the app in Snowsight, and call the procedure.

   Why: The system function only works in an app installed in a consumer account.

   You should see: The procedure returns without an error.

5. 5.At least two days later, query MARKETPLACE_PAID_USAGE_DAILY in the consumer account, filtering on charge_type='MONETIZABLE_BILLING_EVENTS'.

   Why: The view has latency, and this charge type identifies Custom Event Billing charges.

   You should see: A row for your listing with a non-zero CHARGE. Usage within your organization is not billed.