Billing Events for Envelope Sending

This document explains how DocStudio identifies the source of an envelope send action and writes billing events for different sending methods.

Overview

When an envelope is sent, DocStudio write two billing events:

• the general envelope sending event

• one source-specific event

The general event keeps existing billing logic and backward compatibility intact, while the source-specific event applies separate billing rules for QuickSend, template-based sending, or form-based sending.

Sending sources

DocStudio supports the following envelope sending sources:

Sending source	Description
QUICK	The envelope is sent through QuickSend, including POST /api/v1/envelope/quick-send and POST /api/v1/envelope/one-time-send.
TEMPLATE	The envelope is created and sent from a saved template through POST /api/v1/envelope/send.
FORM	The envelope is created and sent from a form through POST /api/v1/form/envelope/send.

The sending source must be stored in the envelope data as sending_source.

Billing events

When an envelope is sent, DocStudio writes two billing events:

1. The general event: envelope-sent

2. One source-specific event:

   • envelope-sent-q for QuickSend

   • envelope-sent-t for template-based sending

   • envelope-sent-f for form-based sending

This approach keeps existing billing behavior unchanged for accounts that use only the general envelope-sent event.

API endpoint mapping

Use this mapping to determine which source-specific billing event must be written.

Endpoint	Sending source	Billing event
POST /api/v1/envelope/quick-send	QUICK	envelope-sent-q
POST /api/v1/envelope/one-time-send	QUICK	envelope-sent-q
POST /api/v1/envelope/send	TEMPLATE	envelope-sent-t
POST /api/v1/form/envelope/send	FORM	envelope-sent-f

Limit verification

Before sending an envelope, DocStudio must check both billing limits:

1. The general limit for envelope-sent

2. The source-specific limit for one of the following events:

   • envelope-sent-q

   • envelope-sent-t

   • envelope-sent-f

If either limit is reached, DocStudio must block the send action and return a billing limit error.

Check endpoints

Use these endpoints to check whether the account can create an envelope for a specific sending source.

Sending source	Check endpoint
QuickSend	GET /api/v1/account/{accountId}/check/envelope-sent-q/create
Template-based	GET /api/v1/account/{accountId}/check/envelope-sent-t/create
Form-based	GET /api/v1/account/{accountId}/check/envelope-sent-f/create

Frontend must call the source-specific check endpoint instead of the general GET /api/v1/account/{accountId}/check/envelope-sent/create endpoint.

Frontend behavior

Use the QuickSend check endpoint in these cases:

• The user clicks the QuickSend button on the dashboard.

• The user drags and drops a file to the dashboard.

Use the template-based sending check endpoint in these cases:

• The user selects a template to create an envelope draft.

• The user clicks the Send button for an envelope created from a saved template.

Use the form-based sending check endpoint when the user sends an envelope created from a form.

If the check fails because a billing limit is reached, show the standard Billing limit reached modal window. For related error handling, read Common API Error Codes.

Analytics

DocStudio must pass the envelope sending source to analytics and reporting tools.

In the Metabase envelope table, the sending source must be available with one of the following values:

• quick-send

• template

• form

The same sending source property must also be available in the Elastic index.

Required backend changes

Backend must support the following changes:

• Add the sending_source field to the envelope.

• Support the following values for sending_source:

  • QUICK

  • TEMPLATE

  • FORM

• Write the general envelope-sent billing event for every envelope send action.

• Write one source-specific billing event for every envelope send action.

• Check the general envelope-sent limit together with the source-specific limit.

• Return a billing limit error if any required billing check fails.

• Copy the sending source to Metabase.

• Add the sending source to the Elastic index.

Required frontend changes

Frontend must replace the general billing check endpoint with source-specific endpoints.

Use:

• GET /api/v1/account/{accountId}/check/envelope-sent-q/create for QuickSend

• GET /api/v1/account/{accountId}/check/envelope-sent-t/create for template-based sending

• GET /api/v1/account/{accountId}/check/envelope-sent-f/create for form-based sending

If the billing check returns an error, show the standard Billing limit reached modal window.