> For the complete documentation index, see [llms.txt](https://developers.docstudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.docstudio.com/api-documentation/envelope/billing-events-for-envelope-sending.md).

# Billing Events for Envelope Sending

### 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:

<table><thead><tr><th width="105">Sending source</th><th>Description</th></tr></thead><tbody><tr><td><code>QUICK</code></td><td>The envelope is sent through <strong>QuickSend</strong>, including<br> <code>POST /api/v1/envelope/quick-send</code> and <code>POST /api/v1/envelope/one-time-send</code>.</td></tr><tr><td><code>TEMPLATE</code></td><td>The envelope is created and sent from a saved template through<br><code>POST /api/v1/envelope/send</code>.</td></tr><tr><td><code>FORM</code></td><td>The envelope is created and sent from a form through<br><code>POST /api/v1/form/envelope/send</code>.</td></tr></tbody></table>

{% hint style="info" %}
The sending source must be stored in the envelope data as `sending_source`.
{% endhint %}

### 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.

<table><thead><tr><th width="326">Endpoint</th><th>Sending source</th><th>Billing event</th></tr></thead><tbody><tr><td><code>POST /api/v1/envelope/quick-send</code></td><td><code>QUICK</code></td><td><code>envelope-sent-q</code></td></tr><tr><td><code>POST /api/v1/envelope/one-time-send</code></td><td><code>QUICK</code></td><td><code>envelope-sent-q</code></td></tr><tr><td><code>POST /api/v1/envelope/send</code></td><td><code>TEMPLATE</code></td><td><code>envelope-sent-t</code></td></tr><tr><td><code>POST /api/v1/form/envelope/send</code></td><td><code>FORM</code></td><td><code>envelope-sent-f</code></td></tr></tbody></table>

### 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.

<table><thead><tr><th width="185">Sending source</th><th>Check endpoint</th></tr></thead><tbody><tr><td>QuickSend</td><td><code>GET /api/v1/account/{accountId}/check/envelope-sent-q/create</code></td></tr><tr><td>Template-based</td><td><code>GET /api/v1/account/{accountId}/check/envelope-sent-t/create</code></td></tr><tr><td>Form-based</td><td><code>GET /api/v1/account/{accountId}/check/envelope-sent-f/create</code></td></tr></tbody></table>

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](/api-documentation/common-api-error-codes.md).

### 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.