# AI Insights Source: https://guide.withvayu.com/ai-insights AI insights provide intelligent analysis of your customer data, revenue patterns, and business metrics. The system automatically generates reports and recommendations based on your account activity. ## Overview AI insights analyze your Vayu data to surface meaningful patterns and trends. These insights help you understand customer behavior, identify revenue opportunities, and make data-driven decisions. ## Accessing AI insights To access AI insights, seelect **Ask Agent** from the reports dashboard. Ask Agent Improved ## Types of insights ### Customer insights AI analyzes customer data to identify: * High-value customers and growth opportunities * Customers at risk of churn * Usage patterns and trends * Revenue concentration and diversification Churn Rate ### Revenue insights The system provides analysis on: * Revenue trends and forecasting * MRR and ARR patterns * Contract renewal predictions * Pricing optimization opportunities Mrr Arr Ai Agent Question ### Usage insights AI examines usage data to surface: * Product adoption rates * Feature utilization patterns * Consumption trends * Capacity planning recommendations Customer Analysis Revenue ## Generated reports AI insights automatically generate reports that can be: * Viewed in the Vayu dashboard * Downloaded as CSV files * Scheduled for regular delivery * Customized with additional fields For more information on standard reports, see the [Enhanced Dashboard](https://guide.withvayu.com/documentation/change-log/changelog#enhanced-dashboard) section in the changelog. ## Best practices * Review AI insights regularly to stay informed about your business trends * Use insights to inform pricing and packaging decisions * Combine AI insights with custom reports for comprehensive analysis * Act on churn risk indicators proactively # Login by obtaining a new access token Source: https://guide.withvayu.com/api-reference/endpoints/auth/login-by-obtaining-a-new-access-token post /login This endpoint is designed to acquire a temporary access token. Submit the auth token in the request body to obtain a new access token. Use this new token for subsequent API calls. Token is set to expire every hour. # Create Catalog product Source: https://guide.withvayu.com/api-reference/endpoints/catalog-products/create-catalog-product post /catalogProducts Create a new Catalog product. # Delete Catalog product Source: https://guide.withvayu.com/api-reference/endpoints/catalog-products/delete-catalog-product delete /catalogProducts/{catalogProductId} Delete a Catalog product by id. # Get Catalog product Source: https://guide.withvayu.com/api-reference/endpoints/catalog-products/get-catalog-product get /catalogProducts/{catalogProductId} Get a Catalog product by id. # List Catalog products Source: https://guide.withvayu.com/api-reference/endpoints/catalog-products/list-catalog-products get /catalogProducts Get a list of Catalog products. # Update Catalog product Source: https://guide.withvayu.com/api-reference/endpoints/catalog-products/update-catalog-product put /catalogProducts/{catalogProductId} Update a Catalog product by id. # Create Contract Source: https://guide.withvayu.com/api-reference/endpoints/contracts/create-contract post /contracts Create a new Contract. # Delete Contract Source: https://guide.withvayu.com/api-reference/endpoints/contracts/delete-contract delete /contracts/{contractId} Delete a Contract by id. # Get Contract Source: https://guide.withvayu.com/api-reference/endpoints/contracts/get-contract get /contracts/{contractId} Get a Contract by id. # Get contract by integration id Source: https://guide.withvayu.com/api-reference/endpoints/contracts/get-contract-by-integration-id get /contracts/integration/{integrationType}/{integrationId} Use this endpoint to get a specific contract using its integration provider and identifier. # List contracts Source: https://guide.withvayu.com/api-reference/endpoints/contracts/list-contracts get /contracts List contracts for the account. Optionally filter by customerId or customerExternalId to retrieve contracts for a specific customer (provide at most one, not both). # Deduct credits from customer credit ledger Source: https://guide.withvayu.com/api-reference/endpoints/credits/deduct-credits-from-customer-credit-ledger post /credits/deduct This endpoint is used to deduct credits from the specified customer account. Submit the credit amount and customer ID in the request body to deduct the credits. The deducted credits will be subtracted from the customer's account. # Grant credits to a customer credit ledger Source: https://guide.withvayu.com/api-reference/endpoints/credits/grant-credits-to-a-customer-credit-ledger post /credits/grant This endpoint is used to grant credits to a customer. Submit the credit amount and customer ID in the request body to grant the credits. The granted credits will be added to the customer's account. # Retrieve credit ledger entries for customer. Source: https://guide.withvayu.com/api-reference/endpoints/credits/retrieve-credit-ledger-entries-for-customer get /credits This endpoint is used to retrieve the credit ledger entries for a specific customer. # Create Customer Source: https://guide.withvayu.com/api-reference/endpoints/customers/create-customer post /customers Create a new Customer. # Create Customer relation Source: https://guide.withvayu.com/api-reference/endpoints/customers/create-customer-relation post /customer-relations Create a new Customer relation. # Delete Customer Source: https://guide.withvayu.com/api-reference/endpoints/customers/delete-customer delete /customers/{customerId} Delete a Customer by id. # Get Customer Source: https://guide.withvayu.com/api-reference/endpoints/customers/get-customer get /customers/{customerId} Get a Customer by id. # Get customer by externalId Source: https://guide.withvayu.com/api-reference/endpoints/customers/get-customer-by-externalid get /customers/externalId/{externalId} Use this endpoint to get a specific customer using its external Id. # Get customer by integration id Source: https://guide.withvayu.com/api-reference/endpoints/customers/get-customer-by-integration-id get /customers/integration/{integrationType}/{integrationId} Use this endpoint to get a specific customer using its integration provider and identifier. # Get customer by name Source: https://guide.withvayu.com/api-reference/endpoints/customers/get-customer-by-name get /customers/name/{name} Use this endpoint to get a specific customer using its name. # Get Customer relation Source: https://guide.withvayu.com/api-reference/endpoints/customers/get-customer-relation get /customer-relations/{customerRelationId} Get a Customer relation by id. # Get products consumptions by customer alias Source: https://guide.withvayu.com/api-reference/endpoints/customers/get-products-consumptions-by-customer-alias get /customers/products-consumptions/alias/{alias} Use this endpoint to get the products consumptions by the customer alias. # Get products consumptions by customer id Source: https://guide.withvayu.com/api-reference/endpoints/customers/get-products-consumptions-by-customer-id get /customers/products-consumptions/{customerId} Use this endpoint to get the products consumptions by the customer id. # List Customers Source: https://guide.withvayu.com/api-reference/endpoints/customers/list-customers get /customers Get a list of Customers. # Update Customer Source: https://guide.withvayu.com/api-reference/endpoints/customers/update-customer put /customers/{customerId} Update a Customer by id. # Delete an event by refId Source: https://guide.withvayu.com/api-reference/endpoints/events/delete-an-event-by-refid delete /events/{refId} Use this endpoint to remove a specific event using its reference ID. # Delete events by refs Source: https://guide.withvayu.com/api-reference/endpoints/events/delete-events-by-refs post /events/delete-by-refs Delete multiple events, identified by ref, in a single request. # Get event by refId Source: https://guide.withvayu.com/api-reference/endpoints/events/get-event-by-refid get /events/{refId} Use this endpoint to get a specific event using its reference ID. # Query events by timestamp period and optional event name Source: https://guide.withvayu.com/api-reference/endpoints/events/query-events-by-timestamp-period-and-optional-event-name get /events Fetch events occurring within a specified timestamp range. An optional event name can be provided to further filter the events. # Submit a batch of events for ingestion Source: https://guide.withvayu.com/api-reference/endpoints/events/submit-a-batch-of-events-for-ingestion post /events Use this endpoint to send an array of events for processing and storage. Make sure to comply with the request schema for each event. # Submit a batch of events for testing Source: https://guide.withvayu.com/api-reference/endpoints/events/submit-a-batch-of-events-for-testing post /events/dry-run Use this endpoint to send an array of events for processing. Make sure to comply with the request schema for each event. NOTE: this is a dry run and will not result in actual storage of the events. # Get Invoice Source: https://guide.withvayu.com/api-reference/endpoints/invoices/get-invoice get /invoices/{invoiceId} Get a Invoice by id. # Get invoice payment status Source: https://guide.withvayu.com/api-reference/endpoints/invoices/get-invoice-payment-status get /invoices/{invoiceId}/payment-status Use this endpoint to retrieve payment status information for a specific invoice, including payment status, amount due, amount paid, total, due date, paid date, and invoice PDF URL. # List invoices Source: https://guide.withvayu.com/api-reference/endpoints/invoices/list-invoices get /invoices List invoices for the account. Optionally filter by customerId to retrieve invoices for a specific customer. # Create Measurement Source: https://guide.withvayu.com/api-reference/endpoints/measurements/create-measurement post /measurements Create a new Measurement. # Delete Measurement Source: https://guide.withvayu.com/api-reference/endpoints/measurements/delete-measurement delete /measurements/{measurementId} Delete a Measurement by id. # Get Measurement Source: https://guide.withvayu.com/api-reference/endpoints/measurements/get-measurement get /measurements/{measurementId} Get a Measurement by id. # List Measurements Source: https://guide.withvayu.com/api-reference/endpoints/measurements/list-measurements get /measurements Get a list of Measurements. # Delete Meter Source: https://guide.withvayu.com/api-reference/endpoints/meters/delete-meter delete /meters/{meterId} Delete a Meter by id. # Get Meter Source: https://guide.withvayu.com/api-reference/endpoints/meters/get-meter get /meters/{meterId} Get a Meter by id. # List Meters Source: https://guide.withvayu.com/api-reference/endpoints/meters/list-meters get /meters Get a list of Meters. # Update Meter Source: https://guide.withvayu.com/api-reference/endpoints/meters/update-meter put /meters/{meterId} Update a Meter by id. # Get product consumption Source: https://guide.withvayu.com/api-reference/endpoints/product-consumptions/get-product-consumption get /product-consumption/{productId} Use this action to get the consumption data for a product # Subscribe to webhooks Source: https://guide.withvayu.com/api-reference/endpoints/webhooks/subscribe-to-webhooks post /webhook Use this endpoint to subscribe to webhooks and receive event notifications. # Browsing Events Source: https://guide.withvayu.com/api-reference/pages/browsing-events Query and filter ingested events Use the events query endpoint to retrieve ingested events by time range, filter by event name or customer, and paginate through large datasets. **Endpoint:** `GET /events` ## Query parameters | Parameter | Type | Required | Description | | --------------- | ------ | -------- | ---------------------------------------------- | | `startTime` | string | Yes | Start of the time range (ISO 8601 UTC) | | `endTime` | string | Yes | End of the time range (ISO 8601 UTC) | | `eventName` | string | No | Filter to a specific event type | | `customerAlias` | string | No | Filter to events for a specific customer alias | | `limit` | number | No | Results per page (default: 10, max: 1,000) | | `cursor` | string | No | Pagination cursor from the previous response | ## Response Returns a [paginated response](/api-reference/pages/pagination) with an `events` array. ```json theme={null} { "events": [ { "name": "api_call", "ref": "4f6cf35x-2c4y-483z-a0a9-158621f77a21", "customerAlias": "customer-123", "timestamp": "2026-01-15T14:30:00Z", "data": { "endpoint": "/v1/predict", "tokens": 1500 } } ], "total": 4821, "hasMore": true, "nextCursor": "eyJpZCI6IjEyMyJ9" } ``` ## Examples ```bash curl theme={null} # Basic query by time range curl "https://connect.withvayu.com/events?startTime=2026-01-01T00:00:00Z&endTime=2026-01-31T23:59:59Z&limit=100" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "x-api-key: $VAYU_CLIENT_ID" # Filter by event name and customer curl "https://connect.withvayu.com/events?startTime=2026-01-01T00:00:00Z&endTime=2026-01-31T23:59:59Z&eventName=api_call&customerAlias=customer-123" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "x-api-key: $VAYU_CLIENT_ID" ``` ```typescript TypeScript theme={null} import VayuSDK from 'vayu-ts'; const vayu = new VayuSDK({ apiToken: process.env.VAYU_API_TOKEN }); const result = await vayu.events.query({ startTime: new Date('2026-01-01'), endTime: new Date('2026-01-31'), eventName: 'api_call', customerAlias: 'customer-123', limit: 100, }); console.log(`${result.total} total events`); for (const event of result.events) { console.log(event.name, event.customerAlias, event.timestamp); } ``` ```python Python theme={null} from vayu_client import VayuClient from datetime import datetime import os vayu = VayuClient(api_token=os.environ["VAYU_API_TOKEN"]) result = vayu.events.query( start_time=datetime(2026, 1, 1), end_time=datetime(2026, 1, 31), event_name="api_call", customer_alias="customer-123", limit=100, ) print(f"{result.total} total events") for event in result.events: print(event.name, event.customer_alias, event.timestamp) ``` ```go Go theme={null} import ( VayuSDK "github.com/weft-finance/vayu-go" "os" "time" "fmt" ) vayu := VayuSDK.NewVayu(os.Getenv("VAYU_API_TOKEN")) eventName := "api_call" limit := float32(100) result, err := vayu.Events.QueryEvents(VayuSDK.QueryEventsRequest{ StartTime: time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC), EndTime: time.Date(2026, 1, 31, 23, 59, 59, 0, time.UTC), Name: eventName, Limit: &limit, }) if err != nil { panic(err) } fmt.Printf("%d total events\n", len(result.Events)) for _, event := range result.Events { fmt.Println(event.Name, event.CustomerAlias, event.Timestamp) } ``` ## Via the UI Navigate to **Usage → Events** in the left sidebar to view the latest 100 events. You can filter by date range, event name, customer alias, or reference ID directly in the interface. # Connecting to Vayu Source: https://guide.withvayu.com/api-reference/pages/connecting-to-vayu To connect to Vayu and get your API credentials, follow these steps: 1. Log into Vayu at [http://app.withvayu.com](http://app.withvayu.com) 2. Navigate to the Integrations section 3. Click "Connect" on the Vayu card A side pane will open with two important fields: 1. **Client ID** - Identifies your organization on every request (`x-api-key` header) 2. **API Token** - A long-lived token used to obtain short-lived access tokens via the `/login` endpoint Copy the API Token immediately — it won't be shown again after you close the pane. ## How authentication works Vayu uses a two-token model: | Token | Where it comes from | Lifetime | How it's used | | ----------------------------- | ---------------------- | ---------- | --------------------------------------------------------- | | **API Token** (refresh token) | Vayu dashboard | Long-lived | Sent to `POST /login` to get an access token | | **Access token** | `POST /login` response | 1 hour | Sent as `Authorization: Bearer ` on every API call | The SDKs handle this exchange automatically — pass your API Token when initializing the client and the SDK calls `/login` and refreshes the access token as needed. ## Important Notes * You can only have one active API Token at a time * To rotate your API Token: revoke the existing one, then generate a new one from the same place ## Using Your Credentials ### With the Vayu SDK The SDKs handle the full token lifecycle — just pass your API key and start making calls. ```typescript TypeScript theme={null} import { Vayu } from 'vayu-ts'; const vayu = new Vayu(process.env.VAYU_API_KEY); // Start using the client — authentication is automatic const customers = await vayu.customers.list(); ``` ```python Python theme={null} from vayu_sdk import Vayu vayu = Vayu(api_key=os.environ["VAYU_API_KEY"]) # Start using the client — authentication is automatic customers = vayu.customers.list() ``` ```go Go theme={null} import vayu "github.com/vayucode/vayu-sdks/go" v := vayu.NewVayu(os.Getenv("VAYU_API_KEY")) // Start using the client — authentication is automatic customers, err := v.Customers.List() ``` ```bash curl theme={null} # Step 1 — Get an access token ACCESS_TOKEN=$(curl -s -X POST "https://connect.withvayu.com/login" \ -H "Content-Type: application/json" \ -H "x-api-key: $VAYU_CLIENT_ID" \ -d "{\"refreshToken\": \"$VAYU_API_TOKEN\"}" | jq -r '.accessToken') # Step 2 — Make API calls with the token curl "https://connect.withvayu.com/customers" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "x-api-key: $VAYU_CLIENT_ID" ``` For installation and more examples, see the [SDK section](/api-reference/pages/sdk). ### Direct API Usage Every request needs two headers: * `x-api-key: ` * `Authorization: Bearer ` (obtained from `POST /login`) Make sure to keep your Client ID and API Token secure and never expose them in client-side code. ## Full example — obtaining and using an access token ```bash curl theme={null} # Step 1 — Exchange your API Token for a short-lived access token ACCESS_TOKEN=$(curl -s -X POST "https://connect.withvayu.com/login" \ -H "Content-Type: application/json" \ -H "x-api-key: $VAYU_CLIENT_ID" \ -d "{\"refreshToken\": \"$VAYU_API_TOKEN\"}" | jq -r '.accessToken') # Step 2 — Use the access token on subsequent requests curl "https://connect.withvayu.com/customers" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "x-api-key: $VAYU_CLIENT_ID" ``` ```typescript TypeScript theme={null} // Without the SDK — manual token exchange with fetch const loginRes = await fetch("https://connect.withvayu.com/login", { method: "POST", headers: { "Content-Type": "application/json", "x-api-key": process.env.VAYU_CLIENT_ID, }, body: JSON.stringify({ refreshToken: process.env.VAYU_API_TOKEN }), }); const { accessToken } = await loginRes.json(); const customersRes = await fetch("https://connect.withvayu.com/customers", { headers: { "Authorization": `Bearer ${accessToken}`, "x-api-key": process.env.VAYU_CLIENT_ID, }, }); const customers = await customersRes.json(); ``` ```python Python theme={null} # Without the SDK — manual token exchange with requests import os, requests login = requests.post( "https://connect.withvayu.com/login", headers={"x-api-key": os.environ["VAYU_CLIENT_ID"]}, json={"refreshToken": os.environ["VAYU_API_TOKEN"]}, ) access_token = login.json()["accessToken"] customers = requests.get( "https://connect.withvayu.com/customers", headers={ "Authorization": f"Bearer {access_token}", "x-api-key": os.environ["VAYU_CLIENT_ID"], }, ).json() ``` ```go Go theme={null} // Without the SDK — manual token exchange with net/http loginBody, _ := json.Marshal(map[string]string{ "refreshToken": os.Getenv("VAYU_API_TOKEN"), }) req, _ := http.NewRequest("POST", "https://connect.withvayu.com/login", bytes.NewBuffer(loginBody)) req.Header.Set("Content-Type", "application/json") req.Header.Set("x-api-key", os.Getenv("VAYU_CLIENT_ID")) resp, _ := http.DefaultClient.Do(req) var loginRes struct{ AccessToken string `json:"accessToken"` } json.NewDecoder(resp.Body).Decode(&loginRes) req, _ = http.NewRequest("GET", "https://connect.withvayu.com/customers", nil) req.Header.Set("Authorization", "Bearer "+loginRes.AccessToken) req.Header.Set("x-api-key", os.Getenv("VAYU_CLIENT_ID")) resp, _ = http.DefaultClient.Do(req) ``` Access tokens expire after **1 hour**. If using a raw HTTP client, re-call `/login` when you receive a `401` response. The SDKs handle this automatically. ## Scopes An API Token carries a set of scopes, and any access token you obtain from `POST /login` inherits them. Every endpoint requires a scope, and a request is only authorized if your token's scopes cover it. ### Scope grammar A scope takes one of four forms: | Form | Grants | | --------------------- | ------------------------------------------ | | `vayu..read` | Read access to one domain | | `vayu..write` | Write access to one domain | | `vayu..*` | Both read and write access to one domain | | `vayu.*` | Full access — every domain, read and write | Matching is strict. `vayu.*` covers every request. `vayu..*` covers both read and write on that domain. `vayu..read` covers only read operations on that domain, and `vayu..write` covers only write operations — a `write` scope does **not** imply `read`. Scopes are independent grants, so an ingest-only token can carry `vayu.events.write` alone, with no read access at all. In the Vayu dashboard, you either leave the "Full access" switch on — the default — or turn it off and tick Read and/or Write per domain: for a single domain, for a whole group (Billing, Catalog, Usage, Other), or for all domains at once. Read and Write are independent ticks and at least one must be ticked; a domain with both ticked is stored as `vayu..*`. `vayu.*` (full access) is what a token gets when the "Full access" switch is on. Every API Token created before scopes existed also behaves as full access. ### Scope domains | Scope domain | Covers | Group | | ------------------------ | ------------------------------------------------------------------------------------------ | ------- | | `customers` | Customer records, lookups by external id, name or integration, and customer relations | Billing | | `contracts` | Contract creation, listing, lookup, termination, credit refresh, and lookup by integration | Billing | | `invoices` | Invoice lookup, listing, and payment status | Billing | | `credits` | Credit ledger entries, grants, deductions, and top-ups | Billing | | `credit-products` | Listing of credit purchase products | Billing | | `plans` | Plan listing, lookup, and deletion | Catalog | | `catalog-products` | Catalog product creation, listing, lookup, update, and deletion | Catalog | | `custom-fields` | Custom field definition creation, listing, lookup, update, and deletion | Catalog | | `events` | Event ingestion and querying, including aggregation and dry-run validation | Usage | | `measurements` | Measurement creation, listing, lookup, and deletion | Usage | | `meters` | Meter listing, lookup, update, and deletion | Usage | | `product-consumptions` | Product consumption lookup by product id | Usage | | `cloud-usage-submission` | Submission of cloud marketplace usage records | Usage | | `webhooks` | Webhook subscription management | Other | ### Which scope an endpoint needs As a rule, `GET` endpoints need `.read` and every other method (`POST`, `PATCH`, `PUT`, `DELETE`) needs `.write`. The one exception is `POST /v2/events/aggregation`, which needs `vayu.events.read` since it only queries data. If you generate clients from Vayu's OpenAPI specification, each operation carries an `x-required-scope` extension naming the exact scope it needs. ### Denied requests A request whose token lacks the required scope is rejected with a `403` and a `permission_error`: ```json theme={null} { "type": "permission_error", "code": "insufficient_scope", "message": "Token lacks required scope vayu.invoices.write", "requiredScope": "vayu.invoices.write" } ``` See [Errors](/api-reference/pages/errors) for the full error response format. ### Changing scopes Scopes are fixed at creation and can't be edited on an existing token. To change them, create a new API Token in the Vayu dashboard with the scopes you want, then revoke the old one. # Errors Source: https://guide.withvayu.com/api-reference/pages/errors HTTP error codes and error response format All Vayu API errors return a JSON body with a consistent structure. Use `type` for broad SDK-level handling and `code` for specific programmatic logic. ## Error response format ```json theme={null} { "type": "invalid_request_error", "code": "resource_not_found", "message": "Customer with id cust_123 not found" } ``` | Field | Type | Description | | --------- | ------ | ------------------------------------ | | `type` | string | Error category — for broad handling | | `code` | string | Specific machine-readable error code | | `message` | string | Human-readable explanation | ## Error types | `type` | Meaning | | ----------------------- | ---------------------------------------------------------------- | | `invalid_request_error` | Problem with the request itself (bad input, not found, conflict) | | `authentication_error` | Missing or invalid access token | | `permission_error` | Token doesn't carry the scope the endpoint requires | | `rate_limit_error` | Too many requests | | `api_error` | Unexpected server-side error | ## Error codes | `code` | HTTP status | `type` | Description | | ------------------------- | ----------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `parameter_missing` | 400 | `invalid_request_error` | A single required field is missing | | `parameter_invalid` | 400 | `invalid_request_error` | A single field failed validation | | `validation_failed` | 400 | `invalid_request_error` | Multiple fields failed validation | | `bad_request` | 400 | `invalid_request_error` | Malformed JSON or other request-level error | | `authentication_failed` | 401 | `authentication_error` | Missing or expired access token | | `insufficient_scope` | 403 | `permission_error` | Token doesn't carry the scope the endpoint requires — the response includes an extra `requiredScope` field naming the missing scope | | `resource_not_found` | 404 | `invalid_request_error` | Requested resource does not exist | | `resource_already_exists` | 409 | `invalid_request_error` | Duplicate — e.g. customer with this `externalId` already exists | | `request_too_large` | 413 | `invalid_request_error` | Payload exceeds the 256 KB limit | | `rate_limit_exceeded` | 429 | `rate_limit_error` | Rate limit exceeded — see [Rate Limits](/api-reference/pages/rate-limits) | | `internal_error` | 500 | `api_error` | Unexpected server error — contact support if this persists | ## Validation errors Validation errors come in two shapes depending on how many fields failed. ### Single field ```json theme={null} { "type": "invalid_request_error", "code": "parameter_missing", "message": "Missing required parameter: customerAlias", "param": "customerAlias" } ``` `code` is `parameter_missing` if the field is absent, or `parameter_invalid` if it's present but invalid. ### Multiple fields ```json theme={null} { "type": "invalid_request_error", "code": "validation_failed", "message": "2 validation errors in request", "errors": [ { "param": "customFields[0].integrationEntityType", "message": "Invalid enum value. Expected 'Account' | 'Invoice' | ..." }, { "param": "customFields[1].integrationEntityType", "message": "Invalid enum value. Expected 'Account' | 'Invoice' | ..." } ] } ``` | Field | Type | Description | | -------- | ------ | ------------------------------------------------------------------- | | `param` | string | Present on single-field errors — the parameter that failed | | `errors` | array | Present on multi-field errors — each item has `param` and `message` | ## Handling errors in code ```typescript TypeScript theme={null} import { VayuClient } from 'vayu-ts'; const vayu = new VayuClient({ apiToken: process.env.VAYU_API_TOKEN }); try { const customer = await vayu.customers.create({ name: 'Acme Corp' }); } catch (error) { if (error.code === 'resource_already_exists') { console.log('Customer already exists'); } else if (error.code === 'validation_failed') { error.errors.forEach(e => console.log(`${e.param}: ${e.message}`)); } else if (error.code === 'parameter_missing' || error.code === 'parameter_invalid') { console.log(`${error.param}: ${error.message}`); } else { throw error; } } ``` ```python Python theme={null} from vayu_client import VayuClient from vayu_client.exceptions import VayuAPIError vayu = VayuClient(api_token=os.environ["VAYU_API_TOKEN"]) try: customer = vayu.customers.create(name="Acme Corp") except VayuAPIError as e: if e.code == "resource_already_exists": print("Customer already exists") elif e.code == "validation_failed": for err in e.errors: print(f"{err['param']}: {err['message']}") elif e.code in ("parameter_missing", "parameter_invalid"): print(f"{e.param}: {e.message}") else: raise ``` ```go Go theme={null} import ( VayuSDK "github.com/weft-finance/vayu-go" "os" "fmt" ) vayu := VayuSDK.NewVayu(os.Getenv("VAYU_API_TOKEN")) _, err := vayu.Customers.CreateCustomer(VayuSDK.CreateCustomerRequest{Name: "Acme Corp"}) if err != nil { if vayuErr, ok := err.(*VayuSDK.VayuError); ok { fmt.Println("API error:", vayuErr.Body) } panic(err) } ``` # Idempotency Source: https://guide.withvayu.com/api-reference/pages/idempotency Safely retry API requests without creating duplicates ## Overview Vayu event ingestion supports idempotency via the `ref` field on each event. If you send the same event twice with the same `ref`, Vayu processes it only once — the second submission is a no-op and returns the original result. This is critical for reliable integrations: if a network timeout leaves you uncertain whether a request was received, you can safely retry without double-counting usage. ## How to use `ref` Include a unique `ref` value on every event. Use a stable identifier from your own system — a database row ID, a transaction ID, or a UUID you generate and store before sending. ```json theme={null} { "events": [ { "name": "api_call", "ref": "txn_a1b2c3d4e5f6", "customerAlias": "customer-123", "timestamp": "2026-01-15T14:30:00Z", "data": { "endpoint": "/v1/predict", "tokens": 1500 } } ] } ``` ## Rules * `ref` must be unique per event name within your account * `ref` values are stored permanently — a `ref` used for a deleted event cannot be reused * If you omit `ref`, no idempotency protection applies to that event * The idempotency window is permanent (not time-bounded) ## Duplicate detection in the response Duplicate `ref` values are returned in the `invalidEvents` array: ```json theme={null} { "validEvents": [], "invalidEvents": [ { "event": { "ref": "txn_a1b2c3d4e5f6" }, "error": "Event with ref txn_a1b2c3d4e5f6 already exists" } ] } ``` ## Best practice: generate `ref` before sending Always generate and persist your `ref` before the API call. If the call fails before a response arrives, retry with the same `ref` safely. ```typescript theme={null} const ref = `txn_${uuid()}`; await db.pendingEvents.insert({ ref, ...eventData }); await vayu.events.ingest([{ ref, ...eventData }]); await db.pendingEvents.markSent(ref); ``` # Dry Run Ingestion Source: https://guide.withvayu.com/api-reference/pages/ingestion Test event processing without storing data The dry run endpoint processes your events exactly as the live ingestion pipeline would — validating, matching customers, and evaluating meters — but **does not store any data**. Use it to verify your event schema, check customer matching, and preview meter values before going live. **Endpoint:** `POST /events/dry-run` ## Request Same schema as live ingestion: 1–1,000 events per request, max 256 KB payload. ```json theme={null} { "events": [ { "name": "api_call", "ref": "test-ref-001", "customerAlias": "customer-123", "timestamp": "2026-01-15T14:30:00Z", "data": { "endpoint": "/v1/predict", "tokens": 1500 } } ] } ``` | Field | Type | Required | Description | | --------------- | ------ | -------- | ------------------------------------------------------------------- | | `name` | string | Yes | Event type identifier — must match a configured meter's `eventName` | | `ref` | string | Yes | Unique idempotency key for this event | | `customerAlias` | string | Yes | Identifier used to match the event to a customer | | `timestamp` | string | Yes | ISO 8601 UTC timestamp of when the event occurred | | `data` | object | No | Arbitrary key-value payload used by meter filters and aggregations | ## Response Returns one result object per submitted event. ```json theme={null} { "events": [ { "event": { "name": "api_call", "ref": "test-ref-001", "customerAlias": "customer-123", "timestamp": "2026-01-15T14:30:00Z", "data": { "tokens": 1500 } }, "matchedCustomer": "cust_abc123", "meterWithValues": [ { "name": "API Calls Meter", "eventName": "api_call", "aggregationMethod": "COUNT", "value": 1, "instanceValue": null } ] } ] } ``` | Field | Type | Description | | --------------------------------- | -------------- | -------------------------------------------------------------- | | `event` | object | The submitted event as it would be ingested | | `matchedCustomer` | string \| null | The customer ID the event matched, or `null` if no match found | | `meterWithValues` | array | Meters this event would be counted against | | `meterWithValues[].value` | number \| null | Contribution to the meter's aggregated value | | `meterWithValues[].instanceValue` | any | For instance-based meters: the instance identifier | If `matchedCustomer` is `null`, the event would create an anonymous customer in live ingestion. Check your `customerAlias` value. ## Examples ```bash curl theme={null} curl -X POST "https://connect.withvayu.com/events/dry-run" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "x-api-key: $VAYU_CLIENT_ID" \ -d '{ "events": [ { "name": "api_call", "ref": "test-ref-001", "customerAlias": "customer-123", "timestamp": "2026-01-15T14:30:00Z", "data": { "tokens": 1500 } } ] }' ``` ```typescript TypeScript theme={null} import VayuSDK from 'vayu-ts'; const vayu = new VayuSDK({ apiToken: process.env.VAYU_API_TOKEN }); const result = await vayu.events.dryRun([{ name: 'api_call', ref: 'test-ref-001', customerAlias: 'customer-123', timestamp: new Date().toISOString(), data: { tokens: 1500 } }]); for (const { event, matchedCustomer, meterWithValues } of result.events) { console.log('Event:', event.name); console.log('Matched customer:', matchedCustomer ?? 'NO MATCH'); console.log('Meter values:', meterWithValues.map(m => `${m.name}: ${m.value}`)); } ``` ```python Python theme={null} from vayu_client import VayuClient from datetime import datetime, timezone import os vayu = VayuClient(api_token=os.environ["VAYU_API_TOKEN"]) result = vayu.events.dry_run([{ "name": "api_call", "ref": "test-ref-001", "customer_alias": "customer-123", "timestamp": datetime.now(timezone.utc).isoformat(), "data": {"tokens": 1500} }]) for item in result.events: print("Event:", item.event.name) print("Matched customer:", item.matched_customer or "NO MATCH") for meter in item.meter_with_values: print(f" {meter.name}: {meter.value}") ``` ```go Go theme={null} import ( VayuSDK "github.com/weft-finance/vayu-go" "os" "time" "fmt" ) vayu := VayuSDK.NewVayu(os.Getenv("VAYU_API_TOKEN")) result, err := vayu.Events.SendEventsDryRun([]VayuSDK.Event{{ Name: "api_call", Ref: "test-ref-001", CustomerAlias: "customer-123", Timestamp: time.Now().UTC(), Data: map[string]interface{}{"tokens": 1500}, }}) if err != nil { panic(err) } for _, item := range result.Events { fmt.Printf("Event: %s\n", item.Event.Name) if item.MatchedCustomer != nil { fmt.Printf("Matched customer: %s\n", *item.MatchedCustomer) } else { fmt.Println("Matched customer: NO MATCH") } for _, m := range item.MeterWithValues { fmt.Printf(" %s: %v\n", m.Name, m.Value) } } ``` ## Common dry run results | Scenario | What you'll see | | --------------------------- | ------------------------------------------------------------------------------- | | Event matches a customer | `matchedCustomer` is populated with the customer ID | | No customer match | `matchedCustomer` is `null` — live ingestion would create an anonymous customer | | Event matches a meter | `meterWithValues` contains the meter with a non-null `value` | | Event name not in any meter | `meterWithValues` is empty | | Invalid event schema | Event appears in the `invalidEvents` array with an error message | # Vayu API Source: https://guide.withvayu.com/api-reference/pages/introduction Full API reference for the Vayu billing platform ## Overview The Vayu API gives you programmatic access to your billing operations — create and manage customers, contracts, catalog products, events, invoices, credits, measurements, and webhooks. All resources are accessible via RESTful HTTP endpoints and are supported by official SDKs in TypeScript, Python, and Go. **Base URL:** `https://connect.withvayu.com` **OpenAPI Spec:** [Download vy-openapi.yml](https://raw.githubusercontent.com/vayucode/docs/main/config/vy-openapi.yml) Get your credentials and make your first authenticated request Official client libraries for TypeScript, Python, and Go Receive real-time event notifications ## Key concepts * **Pagination** — All list endpoints use cursor-based pagination. See [Pagination](/api-reference/pages/pagination). * **Idempotency** — Events support an idempotency key via the `ref` field. See [Idempotency](/api-reference/pages/idempotency). * **Batch ingestion** — Send 1–1,000 events per request (256 KB max). See [Sending Events](/api-reference/pages/sending-events). * **Error handling** — All errors return structured JSON with a machine-readable code. See [Errors](/api-reference/pages/errors). * **Rate limits** — See [Rate Limits](/api-reference/pages/rate-limits). # Pagination Source: https://guide.withvayu.com/api-reference/pages/pagination How to work with paginated list responses All list endpoints return a consistent paginated response shape. ## Response format ```json theme={null} { "customers": [...], "total": 2783, "hasMore": true, "nextCursor": "eyJpZCI6IjEyMyJ9" } ``` | Field | Type | Description | | ------------ | ------- | --------------------------------------------------------------------- | | `[resource]` | array | The list of items (e.g. `customers`, `events`, `invoices`) | | `total` | number | Total count of items in the collection — unaffected by `limit` | | `hasMore` | boolean | `true` if more results exist beyond this page | | `nextCursor` | string | Cursor to pass in the next request — absent when `hasMore` is `false` | ## Request parameters | Parameter | Default | Max | Description | | --------- | ------- | ----- | -------------------------------------------------------- | | `limit` | 10 | 1,000 | Number of items to return | | `cursor` | — | — | Cursor from the previous response to fetch the next page | ## Iterating all pages ```typescript TypeScript theme={null} async function fetchAll( fetchPage: (cursor?: string) => Promise<{ data: T[]; hasMore: boolean; nextCursor?: string }> ): Promise { const results: T[] = []; let cursor: string | undefined; do { const page = await fetchPage(cursor); results.push(...page.data); cursor = page.nextCursor; } while (page.hasMore); return results; } ``` ```python Python theme={null} def fetch_all(fetch_page): results = [] cursor = None while True: page = fetch_page(cursor=cursor) results.extend(page.data) if not page.has_more: break cursor = page.next_cursor return results ``` ```go Go theme={null} import VayuSDK "github.com/weft-finance/vayu-go" vayu := VayuSDK.NewVayu(os.Getenv("VAYU_API_TOKEN")) var cursor *string for { resp, err := vayu.Customers.ListCustomers(nil, cursor) if err != nil { panic(err) } for _, c := range resp.Customers { fmt.Println(c.Id) } if !resp.HasMore { break } cursor = &resp.NextCursor } ``` # Product Structure Source: https://guide.withvayu.com/api-reference/pages/product-structure How to define products in contracts Products are the line items inside a contract. Each product defines what is being charged, how it is scheduled, and what pricing model applies. ## Base fields | Field | Type | Required | Description | | ------------------- | ------- | -------- | ----------------------------------------------------------------- | | `displayName` | string | Yes | Label shown on invoices | | `scheduling` | object | Yes | When and how often the product bills | | `pricing` | object | Yes | The pricing model | | `catalogProductId` | string | No | Links to a catalog product — required for all usage-based pricing | | `description` | string | No | Internal description | | `paymentTerm` | string | No | `prepayment` or `postpayment` — defaults based on pricing type | | `isCalendarAligned` | boolean | No | Align invoice periods to calendar months (default: `false`) | | `commitment` | object | No | Minimum committed units — see [Commitment](#commitment) | | `productErpId` | string | No | ERP identifier for accounting sync | ## Scheduling ```json theme={null} { "scheduling": { "billingDay": 1, "duration": { "unit": "MONTH", "value": 1 } } } ``` | Field | Type | Description | | ---------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- | | `billingDay` | integer (1–31) | Day of month the billing period starts. Defaults to `1`. Should match the contract start date to avoid proration. | | `duration.unit` | string | `DAY`, `WEEK`, `MONTH`, or `YEAR` | | `duration.value` | integer (0–1000) | Number of units per billing period | ## Pricing models ### ONE\_TIME A single charge billed when the contract starts. Duration must be 1 day. ```json theme={null} { "pricing": { "type": "ONE_TIME", "price": 500.00 } } ``` ### SUBSCRIPTION Recurring fixed fee. The `subscriptionCadence` controls how often the charge accumulates within the billing period. ```json theme={null} { "pricing": { "type": "SUBSCRIPTION", "price": 99.00, "subscriptionCadence": { "unit": "MONTH", "value": 1 } } } ``` A product with a 3-month `duration` and monthly `subscriptionCadence` bills 3× $99 = $297 per invoice. ### CONTRACT\_TERMS A total contract fee, optionally split into installments at specific dates. ```json theme={null} { "pricing": { "type": "CONTRACT_TERMS", "price": 12000.00, "installments": [ { "installmentDate": "2026-01-01T00:00:00Z", "amount": 6000.00 }, { "installmentDate": "2026-07-01T00:00:00Z", "amount": 6000.00 } ] } } ``` ### PER\_UNIT Pay-as-you-go. Requires `catalogProductId`. ```json theme={null} { "pricing": { "type": "PER_UNIT", "price": 0.002, "chunkSize": 1000, "baseAmount": 500, "usageReset": 1 } } ``` | Field | Type | Description | | ------------ | ------ | ---------------------------------------------------------------------------- | | `price` | number | Price per unit (or per chunk if `chunkSize` is set) | | `chunkSize` | number | Billing granularity — usage is rounded up to the nearest chunk | | `baseAmount` | number | Free units included before metered charges begin | | `usageReset` | number | Reset accumulated usage every N months — must be `1`, `2`, `3`, `6`, or `12` | ### TIERED Volume-based pricing with different rates or flat fees per tier. Requires `catalogProductId`. ```json theme={null} { "pricing": { "type": "TIERED", "tiers": [ { "fromInclusive": 0, "toExclusive": 1000, "rate": 0.10 }, { "fromInclusive": 1000, "toExclusive": 10000, "rate": 0.07 }, { "fromInclusive": 10000, "rate": 0.04 } ], "subscriptionCadence": { "unit": "MONTH", "value": 1 }, "autoUpgrade": false, "prorate": false, "baseAmount": 0, "usageReset": 1 } } ``` | Tier field | Type | Description | | --------------- | -------------- | --------------------------------------------------------------------- | | `fromInclusive` | number | Lower bound of the tier (inclusive) | | `toExclusive` | number \| null | Upper bound (exclusive). Omit or `null` for the final open-ended tier | | `rate` | number | Per-unit rate in this tier | | `flatFee` | number | Flat fee charged when usage enters this tier | | `packageSize` | number | Units grouped into a package for billing | | Tiered option | Type | Description | | --------------------- | ------- | ------------------------------------------------------------------------ | | `subscriptionCadence` | object | Makes tiered pricing subscription-based (charges flat fees on a cadence) | | `autoUpgrade` | boolean | Automatically move to the next tier in the following billing period | | `prorate` | boolean | Prorate flat fees based on when the tier was entered mid-period | | `isRevShare` | boolean | Revenue share mode — `rate` is treated as a percentage | | `baseAmount` | number | Free units before tiered charges apply | | `usageReset` | number | Reset usage every N months: `1`, `2`, `3`, `6`, or `12` | ## Commitment Attach a minimum committed usage to any usage-based product. ```json theme={null} { "commitment": { "units": 10000, "price": 500.00, "overageStrategy": "IGNORE" } } ``` | Field | Type | Description | | ----------------- | ------ | ------------------------------------------------------------------- | | `units` | number | Committed usage units | | `price` | number | Price charged for the committed amount | | `overageStrategy` | string | What happens when usage exceeds the commitment — `IGNORE` (default) | | `scheduling` | object | For recurring commitments — same shape as product scheduling | ## Product groups Products can be grouped to share ERP settings, commitments, and a combined line item on invoices. ```json theme={null} { "productGroups": [ { "displayName": "Platform Bundle", "products": [ { "displayName": "Base Subscription", "scheduling": { "billingDay": 1, "duration": { "unit": "MONTH", "value": 1 } }, "pricing": { "type": "SUBSCRIPTION", "price": 500.00, "subscriptionCadence": { "unit": "MONTH", "value": 1 } } }, { "displayName": "API Usage", "scheduling": { "billingDay": 1, "duration": { "unit": "MONTH", "value": 1 } }, "pricing": { "type": "PER_UNIT", "price": 0.001, "chunkSize": 100 }, "catalogProductId": "cat_abc123" } ] } ] } ``` Products inside a `productGroup` cannot use `isCalendarAligned`. Group-level settings like `commitment` and ERP fields apply to all products in the group. # Rate Limits Source: https://guide.withvayu.com/api-reference/pages/rate-limits API rate limits and how to handle them The Vayu API enforces rate limits via AWS API Gateway to ensure reliability and fair usage across all customers. ## Limits | | Value | | ----------- | ------------------- | | Rate limit | 500 requests/second | | Burst limit | 100 requests | Need higher limits? Contact [help@withvayu.com](mailto:help@withvayu.com) to discuss increases. ## Handling 429 responses When you exceed the rate limit, the API returns HTTP `429` with the standard error format: ```json theme={null} { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests" } ``` ```typescript TypeScript theme={null} async function withRetry(fn: () => Promise, retries = 3): Promise { for (let i = 0; i < retries; i++) { try { return await fn(); } catch (error) { if (error.type === 'rate_limit_error' && i < retries - 1) { await new Promise(resolve => setTimeout(resolve, 1000)); } else { throw error; } } } } ``` ```python Python theme={null} import time def with_retry(fn, retries=3): for i in range(retries): try: return fn() except VayuAPIError as e: if e.type == 'rate_limit_error' and i < retries - 1: time.sleep(1) else: raise ``` ```go Go theme={null} import "time" func withRetry(fn func() error, retries int) error { for i := 0; i < retries; i++ { err := fn() if err == nil { return nil } if i < retries-1 { time.Sleep(time.Second) continue } return err } return nil } ``` # SDK Source: https://guide.withvayu.com/api-reference/pages/sdk Vayu client packages The Vayu client packages are available in multiple languages. These packages are open source and can be used to integrate with Vayu. } href="https://www.npmjs.com/package/vayu-ts"> Install the [typescript package](https://www.npmjs.com/package/vayu-ts) } href="https://pypi.org/project/vayu-client"> Install the [python package](https://pypi.org/project/vayu-client) } href="https://github.com/vayucode/vayu-sdks/tree/main/go"> Install the [golang package](https://github.com/vayucode/vayu-sdks/tree/main/go) # Sending events Source: https://guide.withvayu.com/api-reference/pages/sending-events Sending events to Vayu Vayu processes events in batches. If some events in a batch are invalid, only those are discarded — valid events are still ingested. ## Event structure Each event requires four fields: | Field | Type | Description | | --------------- | ----------------- | ---------------------------------------------- | | `name` | string | Event label (e.g. `api_call`, `storage_used`) | | `timestamp` | ISO 8601 datetime | When the event occurred (UTC) | | `customerAlias` | string | Identifies the customer (external ID or alias) | | `ref` | string | Unique reference for idempotency | | `data` | object (optional) | Arbitrary key-value metadata | ## Batch limits * **Minimum events:** 1 * **Maximum events:** 1,000 * **Total payload size:** 256 KB ## Example ```typescript TypeScript theme={null} import { Vayu } from 'vayu-ts'; const vayu = new Vayu(process.env.VAYU_API_KEY); const result = await vayu.events.send([ { name: 'api_call', timestamp: new Date(), customerAlias: 'customer-123', ref: 'evt_abc123', data: { endpoint: '/users', method: 'GET' }, }, ]); console.log('Valid:', result.validEvents.length); console.log('Invalid:', result.invalidEvents.length); ``` ```python Python theme={null} from vayu_sdk import Vayu from datetime import datetime, timezone import os vayu = Vayu(api_key=os.environ["VAYU_API_KEY"]) result = vayu.events.send(events=[ { "name": "api_call", "timestamp": datetime.now(timezone.utc), "customerAlias": "customer-123", "ref": "evt_abc123", "data": {"endpoint": "/users", "method": "GET"}, }, ]) print("Valid:", len(result.valid_events)) print("Invalid:", len(result.invalid_events)) ``` ```go Go theme={null} import vayu "github.com/vayucode/vayu-sdks/go" v := vayu.NewVayu(os.Getenv("VAYU_API_KEY")) result, err := v.Events.SendEvents([]vayu.Event{ { Name: "api_call", Timestamp: time.Now().UTC(), CustomerAlias: "customer-123", Ref: "evt_abc123", Data: map[string]interface{}{ "endpoint": "/users", "method": "GET", }, }, }) fmt.Println("Valid:", len(result.ValidEvents)) fmt.Println("Invalid:", len(result.InvalidEvents)) ``` ```bash curl theme={null} curl -X PUT "https://connect.withvayu.com/events" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "x-api-key: $VAYU_CLIENT_ID" \ -d '{ "events": [ { "name": "api_call", "timestamp": "2026-04-14T12:00:00Z", "customerAlias": "customer-123", "ref": "evt_abc123", "data": { "endpoint": "/users", "method": "GET" } } ] }' ``` ## Response structure The response includes two arrays: * **`validEvents`** — events that were successfully ingested * **`invalidEvents`** — events that failed validation, each with an error message ```json theme={null} { "validEvents": [ { "name": "api_call", "ref": "evt_abc123", ... } ], "invalidEvents": [] } ``` ## Immediate availability Events are available in the API and UI immediately after ingestion. Invalid events **do not** cause the entire request to fail. They are returned in the `invalidEvents` array while valid events are still processed. # Webhooks Source: https://guide.withvayu.com/api-reference/pages/webhooks Receive real-time event notifications from Vayu Webhooks let Vayu push notifications to your server when billing events occur. You subscribe per event type with a callback URL, and Vayu sends a signed POST request whenever that event fires. ## Subscribing **Endpoint:** `POST /webhook` ```json theme={null} { "callbackUrl": "https://your-server.com/webhooks/vayu", "eventType": "Overage" } ``` ```bash curl theme={null} curl -X POST "https://connect.withvayu.com/webhook" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "x-api-key: $VAYU_CLIENT_ID" \ -d '{ "callbackUrl": "https://your-server.com/webhooks/vayu", "eventType": "Overage" }' ``` ```typescript TypeScript theme={null} import { Vayu } from 'vayu-ts'; const vayu = new Vayu(process.env.VAYU_API_KEY); await vayu.webhooks.subscribe({ callbackUrl: 'https://your-server.com/webhooks/vayu', eventType: 'Overage', }); ``` ```python Python theme={null} from vayu_sdk import Vayu import os vayu = Vayu(api_key=os.environ["VAYU_API_KEY"]) vayu.webhooks.subscribe( callback_url="https://your-server.com/webhooks/vayu", event_type="Overage", ) ``` ```go Go theme={null} import vayu "github.com/vayucode/vayu-sdks/go" v := vayu.NewVayu(os.Getenv("VAYU_API_KEY")) err := v.Webhooks.Subscribe(vayu.WebhookSubscribeRequest{ CallbackUrl: "https://your-server.com/webhooks/vayu", EventType: "Overage", }) ``` ## Available event types | Event type | Description | | ----------------------------- | ----------------------------------------------------------------------------- | | `Overage` | Customer exceeds their provisioned amount for a product | | `AnonymousCustomer` | Event received for an unrecognized customer alias — auto-created as anonymous | | `UpcomingRenewal` | Customer contract is approaching its renewal date | | `InvoiceApproved` | An invoice has been approved and is ready to send | | `UnchargedEvents` | Events exist that have not been counted against any meter | | `TierCrossed` | Customer usage has crossed into a new pricing tier | | `CommitmentCrossed` | Customer has crossed their committed usage threshold | | `FinalTierExceeded` | Customer usage has exceeded the final pricing tier | | `InvoicePaymentStatusChanged` | An invoice payment status has changed (e.g. paid, failed, overdue) | ## Webhook payloads ### Overage ```json theme={null} { "type": "Overage", "productId": "prod_123456789", "productName": "API Calls", "provisionedAmount": 1000, "consumedAmount": 1200, "usagePercentage": 120, "hasAccess": false, "remainingAmount": 0, "exceededAmount": 200 } ``` ### AnonymousCustomer ```json theme={null} { "type": "AnonymousCustomer", "id": "cust_123456789", "externalId": "ext_987654321", "aliases": ["ext_987654321"], "name": "Anonymous Customer" } ``` ### UpcomingRenewal ```json theme={null} { "type": "UpcomingRenewal", "customerId": "cust_123456789", "customerName": "Acme Corp", "contractId": "contract_abc123", "renewalDate": "2026-02-01T00:00:00Z" } ``` ### InvoiceApproved ```json theme={null} { "type": "InvoiceApproved", "invoiceId": "inv_123456789", "customerId": "cust_123456789", "customerName": "Acme Corp", "amount": 1500.00, "currency": "USD", "dueDate": "2026-02-15T00:00:00Z" } ``` ### InvoicePaymentStatusChanged ```json theme={null} { "type": "InvoicePaymentStatusChanged", "invoiceId": "inv_123456789", "customerId": "cust_123456789", "previousStatus": "PENDING", "currentStatus": "PAID", "amount": 1500.00, "currency": "USD" } ``` ### TierCrossed ```json theme={null} { "type": "TierCrossed", "customerId": "cust_123456789", "productId": "prod_123456789", "productName": "API Calls", "previousTier": 1, "currentTier": 2, "currentUsage": 10001, "tierThreshold": 10000 } ``` ### CommitmentCrossed ```json theme={null} { "type": "CommitmentCrossed", "customerId": "cust_123456789", "contractId": "contract_abc123", "committedAmount": 50000, "currentUsage": 50001 } ``` ### FinalTierExceeded ```json theme={null} { "type": "FinalTierExceeded", "customerId": "cust_123456789", "productId": "prod_123456789", "productName": "API Calls", "finalTierThreshold": 100000, "currentUsage": 100500 } ``` ### UnchargedEvents ```json theme={null} { "type": "UnchargedEvents", "customerId": "cust_123456789", "eventCount": 42, "earliestEventTimestamp": "2026-01-10T08:00:00Z" } ``` ## Handling webhook events A minimal server that receives Vayu webhooks, routes by event type, and reads the payload: ```typescript TypeScript (Express) theme={null} import express from 'express'; import { Vayu } from 'vayu-ts'; const vayu = new Vayu(process.env.VAYU_API_KEY); const app = express(); app.use(express.json()); // Register the webhook (run once) // await vayu.webhooks.subscribe({ // callbackUrl: 'https://your-server.com/webhooks/vayu', // eventType: 'Overage', // }); app.post('/webhooks/vayu', (req, res) => { const event = req.body; switch (event.type) { case 'Overage': console.log( `${event.productName}: ${event.consumedAmount}/${event.provisionedAmount} used ` + `(${event.exceededAmount} over limit)` ); break; case 'InvoiceApproved': console.log(`Invoice ${event.invoiceId} for ${event.customerName}: $${event.amount} ${event.currency}`); break; case 'TierCrossed': console.log(`${event.productName}: customer moved from tier ${event.previousTier} → ${event.currentTier}`); break; case 'AnonymousCustomer': console.log(`New anonymous customer created: ${event.externalId}`); break; default: console.log(`Unhandled event: ${event.type}`); } res.sendStatus(200); }); app.listen(3000, () => console.log('Listening on :3000')); ``` ```python Python (Flask) theme={null} from flask import Flask, request from vayu_sdk import Vayu import os vayu = Vayu(api_key=os.environ["VAYU_API_KEY"]) app = Flask(__name__) # Register the webhook (run once) # vayu.webhooks.subscribe( # callback_url="https://your-server.com/webhooks/vayu", # event_type="Overage", # ) @app.route('/webhooks/vayu', methods=['POST']) def handle_webhook(): event = request.get_json() if event['type'] == 'Overage': print( f"{event['productName']}: {event['consumedAmount']}/{event['provisionedAmount']} used " f"({event['exceededAmount']} over limit)" ) elif event['type'] == 'InvoiceApproved': print(f"Invoice {event['invoiceId']} for {event['customerName']}: ${event['amount']} {event['currency']}") elif event['type'] == 'TierCrossed': print(f"{event['productName']}: customer moved from tier {event['previousTier']} → {event['currentTier']}") elif event['type'] == 'AnonymousCustomer': print(f"New anonymous customer created: {event['externalId']}") else: print(f"Unhandled event: {event['type']}") return '', 200 if __name__ == '__main__': app.run(port=3000) ``` ```go Go (net/http) theme={null} package main import ( "encoding/json" "fmt" "io" "net/http" vayu "github.com/vayucode/vayu-sdks/go" ) // Register the webhook (run once) // v := vayu.NewVayu(os.Getenv("VAYU_API_KEY")) // v.Webhooks.Subscribe(vayu.WebhookSubscribeRequest{ // CallbackUrl: "https://your-server.com/webhooks/vayu", // EventType: "Overage", // }) func main() { http.HandleFunc("/webhooks/vayu", func(w http.ResponseWriter, r *http.Request) { body, _ := io.ReadAll(r.Body) var event map[string]interface{} json.Unmarshal(body, &event) switch event["type"] { case "Overage": fmt.Printf("%s: %.0f/%.0f used (%.0f over limit)\n", event["productName"], event["consumedAmount"], event["provisionedAmount"], event["exceededAmount"]) case "InvoiceApproved": fmt.Printf("Invoice %s for %s: $%.2f %s\n", event["invoiceId"], event["customerName"], event["amount"], event["currency"]) case "TierCrossed": fmt.Printf("%s: customer moved from tier %.0f → %.0f\n", event["productName"], event["previousTier"], event["currentTier"]) case "AnonymousCustomer": fmt.Printf("New anonymous customer created: %s\n", event["externalId"]) default: fmt.Printf("Unhandled event: %s\n", event["type"]) } w.WriteHeader(http.StatusOK) }) fmt.Println("Listening on :3000") http.ListenAndServe(":3000", nil) } ``` In production, always [verify the webhook signature](#verifying-signatures) before processing the payload. ## Webhook security All Vayu webhook requests include headers for signature verification: | Header | Description | | --------------------- | ---------------------------------------------------------------- | | `X-Timestamp` | Unix timestamp (seconds) of when the request was sent | | `X-Signature` | Base64-encoded RSA-SHA256 signature of `timestamp.JSON(payload)` | | `X-Signature-Version` | Signature scheme version (currently `v1`) | The signed message is: `${timestamp}.${JSON.stringify(payload)}` Only HTTPS callback URLs are supported. ### Verifying signatures The TypeScript SDK provides a built-in helper. Built-in verification for the Python and Go SDKs is coming soon — in the meantime, verify manually using Vayu's public key. ```typescript TypeScript (SDK) theme={null} import { Vayu } from 'vayu-ts'; const vayu = new Vayu(process.env.VAYU_API_KEY); app.post('/webhooks', async (req, res) => { const payload = JSON.stringify(req.body); const timestamp = Number(req.headers['x-timestamp']); const signature = String(req.headers['x-signature']); const isValid = vayu.webhooks.verifyWebhookSignature({ payload, timestamp, signature, tolerance: 300, // optional — reject if older than 5 minutes (default) }); if (!isValid) { return res.sendStatus(401); } const event = req.body; console.log('Received webhook:', event.type); res.sendStatus(200); }); ``` ```python Python (manual) theme={null} import json, time, base64, math from cryptography.hazmat.primitives import hashes, serialization from cryptography.hazmat.primitives.asymmetric import padding from flask import Flask, request # Load Vayu's public key (provided during onboarding) with open("vayu-public.pem", "rb") as f: public_key = serialization.load_pem_public_key(f.read()) TOLERANCE = 300 # 5 minutes app = Flask(__name__) @app.route('/webhooks', methods=['POST']) def webhooks(): payload = request.get_data(as_text=True) timestamp = int(request.headers.get('X-Timestamp', '0')) signature = request.headers.get('X-Signature', '') # Reject stale webhooks if abs(time.time() - timestamp) > TOLERANCE: return '', 401 # Reconstruct the signed message message = f"{timestamp}.{json.dumps(json.loads(payload))}" try: public_key.verify( base64.b64decode(signature), message.encode(), padding.PKCS1v15(), hashes.SHA256(), ) except Exception: return '', 401 event = json.loads(payload) print('Received webhook:', event['type']) return '', 200 ``` ```go Go (manual) theme={null} import ( "crypto" "crypto/rsa" "crypto/sha256" "crypto/x509" "encoding/base64" "encoding/json" "encoding/pem" "fmt" "io" "math" "net/http" "os" "strconv" "time" ) // Load Vayu's public key (provided during onboarding) var publicKey *rsa.PublicKey func init() { keyData, _ := os.ReadFile("vayu-public.pem") block, _ := pem.Decode(keyData) pub, _ := x509.ParsePKIXPublicKey(block.Bytes) publicKey = pub.(*rsa.PublicKey) } const tolerance = 300 // 5 minutes func webhookHandler(w http.ResponseWriter, r *http.Request) { body, _ := io.ReadAll(r.Body) timestamp, _ := strconv.ParseInt(r.Header.Get("X-Timestamp"), 10, 64) signature := r.Header.Get("X-Signature") // Reject stale webhooks if math.Abs(float64(time.Now().Unix()-timestamp)) > tolerance { http.Error(w, "stale webhook", http.StatusUnauthorized) return } // Reconstruct the signed message message := fmt.Sprintf("%d.%s", timestamp, string(body)) hash := sha256.Sum256([]byte(message)) sigBytes, _ := base64.StdEncoding.DecodeString(signature) err := rsa.VerifyPKCS1v15(publicKey, crypto.SHA256, hash[:], sigBytes) if err != nil { http.Error(w, "invalid signature", http.StatusUnauthorized) return } var event map[string]interface{} json.Unmarshal(body, &event) fmt.Println("Received webhook:", event["type"]) w.WriteHeader(http.StatusOK) } ``` # Change Log Source: https://guide.withvayu.com/documentation/change-log/changelog New features and updates to Vayu # Change Log # Stripe - Partial Payments When credits are applied to an invoice in Vayu, or when a partial payment is recorded, that information now syncs back to Stripe for synced invoices. **What this means for customers:** * Stripe-hosted invoices now show a more accurate remaining balance * Customers and finance teams see less mismatch between Vayu and Stripe * If an invoice is fully settled through credits and payments, Stripe can reflect that correctly as well This is especially helpful for teams that rely on Stripe-hosted invoice links as part of their billing workflow. # Payments Page – Custom Fields Customer and contract custom fields can now be added as optional columns on the Payments page. What this means for customers: * Teams can personalize the Payments view with the fields most relevant to them * Payment records can be reviewed with more business context directly in the table * Users can reduce manual lookup by seeing customer or contract metadata alongside payment activity This improves reporting, reconciliation, and day-to-day operational workflows for teams managing high payment volume. # Reporting Upgrades New Reports Changelog We have launched the new [NRR/GRR](/accounting-reports) and Customer Master Reports. The ARR/MRR Report also comes with added AI analysis support, custom field integration, and flat export capabilities. You’ll see a general UI upgrade as well as enhancements to the XLSX exports, column picker, Ask Agent toggle, and chart legend. # Inflationary Uplift We’ve introduced automatic phase creation for [Inflationary Uplift](https://guide.withvayu.com/documentation/guides/plans-and-pricing/phases#inflationary-uplift), ensuring pricing updates are applied seamlessly and on schedule. This reduces manual effort and improves billing accuracy by automatically reflecting uplift changes in contracts. # Customer UI Updates We’ve introduced a faster, clearer customer experience with a redesigned interface, smoother navigation, and improved visibility across contracts and invoices. This includes patchwork pricing, manual phase control, and reliability upgrades across billing, integrations, and performance. # Vayu Insights Agent Image Added a new Vayu Insights Agent to help users explore and understand revenue data through natural language queries. # Revenue Waterfall Report Image We have introduced a redesigned revenue waterfall experience with improved navigation, clearer hierarchy, and more accurate revenue breakdowns across time. # Scheduling Snowflake, ERP Imports & Export Image We have introduced the ability to set unique, ongoing schedules for Snowflake and ERP import and export sync jobs, giving you more flexible and controlled data synchronization.1 # Extract From makes PDF data uploads easy Image Extract From allows you to upload a contract PDF and automatically extract structured contract data into Vayu. The system parses the uploaded document and prepares the extracted information for use within the contract workflow. To use this feature: Click Extract from PDF in the upper-right corner. In the modal window, drag and drop your contract PDF or click "Upload file." Upload the document to begin extraction. # Anrok Integration Live + New Invoice Features Vayu’s new integration with [Anrok](/documentation/guides/integrations/anrok) is live. This will allow you to manage taxes from inside Vayu. Anrok Integration By connecting Anrok, tax is calculated automatically on invoices based on product type and customer location, removing the need for manual tax handling and reducing the risk of compliance errors. This integration is designed to keep tax calculation accurate, consistent, and fully embedded in the invoicing workflow, without adding operational overhead. # Dynamic Invoice Highlights Dynamic Invoice Highlights introduce status chips such as Overdue, In Review, and Pending, all of which are clickable for filtering. Additionally, invoice data now recalculates as you change filters like Issue Date (for example, if you add a month). # Sync Invoices as Sales Orders in NetSuite You can now sync your Vayu invoices as Sales Orders in [NetSuite](/documentation/guides/integrations/netsuite), including data such as the PO number. Sync As Sales Order Netsuite This includes a sync status display to follow the process. Simply hit the Ellipse menu (●●●), then select **Sync**. On the Sync submenu, select **Sync Invoice as Sales Order**. # Invoice Filtering We’ve updated our invoice filtering to allow parsing by separate months. This makes for easy selection of months outside of one specific range, as seen in the example below. Invoice Filtering You can scroll by year and select individual months.  # ARR/MRR Visualization This update has many feature additions for reporting recurring revenue. First, there is a new ARR graph on your homepage dashboard, reporting real-time revenue updates. Image We have enhanced the recurring revenue endpoint to be more accurate on ARR/MRR metrics at both the customer and account levels. Additional features include contract phases in MRR calculation and custom fields for MRR reports. ## Other Notable Updates * **Billing Engine:** We have just implemented automatic rounding of line items and invoice revenues to pre-configured decimal precision, which you can define in your account settings. This will be consistent across the platform. * **Cloning Contracts:** Users can now duplicate previous contracts with pre-filled fields, including the customer and required start date. This will speed up new contract creation. # Tier Usage Notification We have updated Vayu to send an in-app alert when usage passes the last tier. This will let users know to follow up and adjust settings later. Image ## Other Notable Updates * We have added settings to control whether or not invoice numbers from your integrations should override Vayu invoice numbers after a sync. * A "Select All" option was added to product dropdowns for improved selected item display. * Aggregated invoices will default to "In Review." # **MRR Report** Vayu has improved its recurring revenue reporting. These reports are viewable in the app, can be downloaded in CSV form and are available by account or customer level. \ \ Navigate to **Reports** on the left-side menu, then go to the menu on the right and select **Recurring Revenue Reports >**.\ \ The reports allow for custom fields (which appear by additional column), support contract phases, and can be viewed along with past reports' MRR data in the Vayu UI. Rrr Gi # **Additional Improvements** You will now see better customer-to-contact linking and data consistency in the Vayu UI. This release focused heavily on invoice management, especially currencies and line item editing. Bug fixes and feature enhancements also included a focus on accurate PDF generation. # **Currencies: Contract and Invoice-Level** Approved invoices will maintain their original currency and *not auto-switch* when customer currency settings are changed. For example, if you charged a customer USD in the past, but switched your default to EUR later, that previous invoice will remain in USD. Currencies Pn Additional currency-related updates include: * **Data Migration:** We added an overridingCurrency field as well as new migration settings for invoice currencies. * **Dynamic Editing:** Improved line item editing and dynamic currency fields for invoices (UI and API) # **Editable Usage Line Items** Users can now edit usage product line items the same as they can for fixed fee line items. Usageline Gi Additional UI enhancements include: * Undo function for modified prices * Line item editing in the API # **Contract Management** The Contract Page also got a few enhancements, namely the ability to manage custom configurations or restrictions for editing contracts. Additionally, contract pages now show both the ERP ID and the product name. This makes it easy to check that integrations are working properly. # **Additional Features** * **Monitoring:** Vayu now has more enhanced audit logging and better logging for invoice calculations. # **Multi-Currency Contract Management** Vayu customers can now have multiple contracts with different currencies. This means you can set a specific currency other than default for each contract. Currencies Pn # **External API** We have added a schema with dynamic paths for catalog products, including create, get, lists, and update. # **Hubspot Integration** You can now link products to Hubspot, including support for contract creation, plan creation, revision, and deleting. Hubspot Gi # **Important Changes** * Clearly labeled Refund operations, changed from "**Invoice**" # **Contract Overview Page** This creates a navigable hub for managing contracts. New design now includes easy to access metrics, and places actionable contract lifecycle actions in the front: * Billing Tab * Phases Tab * Products Tab Contract Overview Gi # **Introducing Phases** Phases Gi Vayu now lets you create phased contract agreements, where the terms of payment change throughout the life of the contract. Simply go to **Customers**, then the **Contract** page, and finally press the gray **+ Add Phase** button to the right of the page. From there, a window will open letting you define the start date of the new phase. Add a label, then hit the dark blue button **Go to plan builder >**. Check out the video below for a short, full tutorial: [https://www.linkedin.com/feed/update/urn:li:activity:7382059848361738240/](https://www.linkedin.com/feed/update/urn:li:activity:7382059848361738240/) # **NetSuite Integration** Netsuite Integration1 Gi Vayu introduces its new NetSuite integration that includes automatic class assignment, class synchronization, and easy maintainability. # **Invoice Management** Changes for invoice management include: * Contract status visibility and improvements to the invoice history * Sync status * Additional fields for currency, customer, period, issue date, and due date # **Plan Template** The UI for plan creation is more intuitive than it was before, with additional guidance to walk you through the steps. image.png # **Enhanced Dashboard** Dashboard Pn Vayu has upgraded its reports dashboard to display more comprehensive data. This also includes suggested reports. * Additional `useInvoicesSummary` hook for comprehensive reporting * Revenue chart data * Suggested reports list includes new report sections, including Customer section # **Notifications** Vayu has created or enhanced notification options, including a new option for Slack and improved email alerts. # Sales Order Flow Users will benefit from our updated sales order sync, validations, and status capture. You should see better focus handling and clearer status display. # **Customer Overview Page** The **Customer Overview Page** provides a consolidated view of a customer's **financial status, revenue insights, and key metrics**, streamlining workflows for tracking billing, managing contracts, and analyzing revenue # **NetSuite Invoice Synching** Vayu now lets you sync invoices with many of your resources. Our improved NetSuite integration gives you the capability to sync invoices with different items. * Credit information * Discounts * Manual changes # Email Notifications We have added improved email alerts for tier crossing and commitments. # **Security** Vayu has added granular role-based access control (RBAC) to Catalog Products. # Introduction Source: https://guide.withvayu.com/documentation/get-started/introduction Billing with Vayu With Vayu, companies can streamline and optimize their billing processes, regardless of the complexity of their pricing models or how dispersed their billing data is across various platforms. Modern businesses offer a wide variety of pricing options including [usage-based pricing](/documentation/guides/plans-and-pricing/usage-based-fees), [fixed fees](/documentation/guides/plans-and-pricing/fixed-fees), [subscription costs](/documentation/guides/plans-and-pricing/pricing-new-overview), tiered pricing, discounts, promotions, and more. Companies aim to provide pricing that suits their customers' needs, aligns with the products being used, and is sensitive to variations across geographies or subsidiaries. Vayu's vision is to make embracing total pricing flexibility fast, easy, accurate, and hassle-free, and Vayu provides just that. Integrating with Vayu is straightforward and takes just a few hours through a simple RESTful [API integration](/api-reference/pages/connecting-to-vayu). Once integrated, Vayu's platform can receive events of all kinds from your BI, CRM, and ERP systems. Any event, from any source, can be a billable event. How it's billed is entirely up to you and can be configured using Vayu's intuitive low-code/no-code interface, ensuring that commercial terms from diverse platforms are accurately reflected in your invoices. Setting up pricing plans, templates, and contracts for specific customers can be done quickly and easily using the manual option within the Vayu platform. Alternatively, you can simply pull this data from your existing systems. Once a billing plan is set up, all invoices are generated automatically at the designated times. You'll gain real-time insights into customer usage and its effect on billing, with the flexibility to make adjustments at any time. ### Architecture Principles Vayu is designed to provide companies with complete autonomy over their pricing and billing. Developer or data resources are only required for the initial integration. After that, product and sales teams can freely manage pricing models, while finance teams have the ability to bill customers accurately and effortlessly, regardless of the complexity of the data or pricing model. ### What Developers Need to Know The Vayu API is focused and direct: it is for logging in and for sending events. It takes two lines of code for your company to start being able to bill for metered events at scale. Event data can be from any source and can be unstructured. Events can be sent in real-time or in batches. Vayu is built for scale, no matter how many events or how many different types of events you want to send and use for billing. The platform can digest and process millions of events per day. Working with the event data (creating customers, subsidiaries, pricing models, invoices, etc.) can all be done by finance teams with absolutely no need for developer involvement. Vayu's platform is built for high visibility and transparency, making auditing as easy as possible. To review how easy integration with Vayu really is, take a look at our API reference documentation. ### What Finance Professionals Need to Know Vayu's platform is designed to require minimal developer involvement. After just a few hours of work from your engineers or data team, you'll be up and running. From there, the finance team will have complete control and flexibility over billing. **Intuitive** \ Vayu's platform is intuitive and easy for everyone to use - no coding necessary. You can create customers, subsidiaries, pricing templates, contracts, invoices and more with ease. **Customizable** \ No matter how many different pricing models you need, you can easily manage them all and effectively bill your customers. Whether you need to combine tiered pricing with fixed fees, or a subscription base with usage-based pricing, Vayu makes it simple. Managing multiple subsidiaries with varying pricing and billing needs is effortless. \\ **Automated** \ Once it's set up, you're good to go. Billing and invoicing will no longer be a headache, but rather a seamless and automated process. All that's left for you to do is review and approve. \\ **Flexible** \ With Vayu, it's easy to renew contracts with new terms or update 'live' contracts with new products or discounts. Your billing can seamlessly adapt to your customers and their needs. \\ **Accurate** \ Vayu leverages data from wherever you have it stored, to ensure that your billing always accurately reflects your customers' usage. You can review their usage and its impact on billing at any time. To see how easy it is to set up a pricing plan with Vayu, take a look at our platform guide. # Quickstart Source: https://guide.withvayu.com/documentation/get-started/quickstart The best way to get a sense of how easy Vayu is to use is to explore the platform's user guide. You'll find that everything — from setting up and creating pricing plans to reviewing [invoices](/documentation/guides/invoices/invoices-overview), [monitoring customer usage](/usage-and-data-reports), and [managing data metering](/file) — is straightforward and intuitive. If you have any questions, or would like to inquire about additional features, please reach out to us. We'd love to hear from you: [help@withvayu.com](mailto:help@withvayu.com) ### Get Started Getting started with Vayu could not be simpler. Check out the steps you’ll need to take: #### 1. [Create a Pricing Plan](/documentation/guides/plans-and-pricing/create-plan) You can create pricing plans for specific customers or subsidiaries as well as create generic pricing plans to use as templates that can be customized as necessary. Any plan can combine whichever types of pricing you need, whether it’s usage-based, commitment fees, tiered pricing, etc. You can also choose the currency you need for each plan. Furthermore, you get to define the start date, duration, and the frequency at which invoices are created and at what intervals. #### 2. [Explore Invoices](/documentation/guides/invoices/invoices-overview) You’ll have real-time insight into your customers’ consumption at any given time, as well as what that means for their billing. Invoices are generated automatically and accurately according to your specifications. Once they’re ready, you can review, modify if desired, and send. #### 3. [Review Customers](/documentation/guides/customers/customer-overview) You can add customers directly from data in a CSV file, from syncing via a Salesforce or Hubspot integration, or manually using the quick and simple process in the Vayu platform. You can establish subsidiaries and related entities with ease. Once a customer is set up, you can view their current billing and usage status, balance overview, issued and overdue invoices, and more at any time. #### 4. [Data Metering](/documentation/guides/data-metering/events) The Vayu platform gives you visibility into your events and data metering. You’ll be able to view all the events that have been digested and counted by the platform, download consumption reports, and define products to meter. ## API Quickstart If you're integrating programmatically, here's the fastest path to your first working API call: Log into Vayu → Integrations → click **Connect** on the Vayu card. Copy your **Client ID** and **API Token**. See [Connecting to Vayu](/api-reference/pages/connecting-to-vayu) for details. ```bash npm theme={null} npm install vayu-ts ``` ```bash pip theme={null} pip install vayu-client ``` ```bash go theme={null} go get github.com/weft-finance/vayu-go ``` ```typescript TypeScript theme={null} import { VayuClient } from 'vayu-ts'; // Pass your API Token — the SDK handles login/token refresh automatically const vayu = new VayuClient({ apiToken: process.env.VAYU_API_TOKEN }); const result = await vayu.events.ingest([{ name: 'api_call', ref: 'my-unique-ref-001', customerAlias: 'your-customer-id', timestamp: new Date().toISOString(), data: { tokens: 1500 } }]); console.log('Valid events:', result.validEvents.length); ``` ```python Python theme={null} from vayu_client import VayuClient import os vayu = VayuClient(api_token=os.environ["VAYU_API_TOKEN"]) result = vayu.events.ingest([{ "name": "api_call", "ref": "my-unique-ref-001", "customer_alias": "your-customer-id", "timestamp": datetime.utcnow().isoformat() + "Z", "data": {"tokens": 1500} }]) print("Valid events:", len(result.valid_events)) ``` ```go Go theme={null} import ( VayuSDK "github.com/weft-finance/vayu-go" "os" "time" "fmt" ) vayu := VayuSDK.NewVayu(os.Getenv("VAYU_API_TOKEN")) result, err := vayu.Events.SendEvents([]VayuSDK.Event{{ Name: "api_call", Ref: "my-unique-ref-001", CustomerAlias: "your-customer-id", Timestamp: time.Now().UTC(), Data: map[string]interface{}{"tokens": 1500}, }}) if err != nil { panic(err) } fmt.Printf("Valid events: %d\n", len(result.ValidEvents)) ``` Not sure if events will match your customers and meters? Use the [dry-run endpoint](/api-reference/pages/ingestion) to test without storing data. # Accounting Reports Source: https://guide.withvayu.com/documentation/guides/accounting-reports Accounting reports are designed to support financial reporting and reconciliation workflows. * **ARR/MRR Report\* -** This reviews recurring revenue and trends over different periods of time, whether monthly (MRR), quarterly (QRR), or annually (ARR). \*This merges the previous Month-End Report with the previous Recurring Revenue Report. * **NRR/GRR Report -** Measure customer revenue retention performance for two things: 1) Net Revenue Retention (NRR) and Gross Revenue Retention (GRR) * **Revenue Analysis Report -** Analyze recognized revenue across customers and time periods. Accounting reports are designed to support financial reporting and reconciliation workflows. These reports provide the data needed to close books, recognize revenue, and maintain compliance with accounting standards. ## ARR / MRR Report The ARR / MRR Report tracks recurring revenue trends over time across customers, contracts, products, and billing periods. This report calculates MRR (Monthly Recurring Revenue), QRR (Quarterly Recurring Revenue), and ARR (Annual Recurring Revenue) using active recurring contract data and displays both current revenue values and historical changes. It includes the following metrics: * Current MRR values by customer and contract * Historical MRR, QRR, and ARR trends across selected time periods * Revenue waterfall movements, including: * New revenue * Expansion revenue * Reactivation revenue * Contraction revenue * Churned revenue * Contract start and end dates * Contract status information * Revenue grouped by customer, contract, or product * Original currency values and exchange rate conversions * Custom fields and metadata for segmentation * Monthly, quarterly, and annual reporting views Recurring revenue is calculated using active recurring contract charges and billing schedules. The report includes recurring subscription and fixed-fee revenue while excluding one-time charges and non-recurring invoice items. Contract phase changes, renewals, expirations, uplifts, and pricing adjustments are reflected automatically in the calculation logic. The chart view provides a recurring revenue waterfall visualization that highlights revenue movement between reporting periods. Revenue categories such as New, Expansion, Reactivation, Contraction, and Churn are displayed alongside total MRR trends to help explain period-over-period changes. The report supports configurable dimensions and column selection, allowing users to customize views using customer attributes, labels, subsidiaries, contract metadata, currencies, and other available business fields. ### Export/Download You can download the report as a CSV for financial reporting, board reporting, forecasting, and revenue operations analysis. ### Ask AI Agent The ARR / MRR Report includes the Ask AI Agent, which allows users to analyze recurring revenue trends using natural-language questions. Users can quickly investigate churn, expansion, MRR waterfalls, product-level revenue breakdowns, and projected ARR without manually building filters or reports. Arr Mrr New May72026 ## NRR / GRR Report The NRR / GRR Report measures customer revenue retention over time by analyzing recurring revenue changes across existing customer accounts. This report calculates NRR (Net Revenue Retention) and GRR (Gross Revenue Retention) using recurring revenue activity such as expansions, contractions, and churn. The report displays the following metrics: * Starting MRR for each reporting period * Expansion MRR from upgrades and account growth * Contraction MRR from downgrades or reduced spend * Churn MRR from fully lost recurring revenue * NRR percentages by reporting period * GRR percentages by reporting period * Historical monthly retention trends * Retention performance across selected date ranges NRR calculations include expansion revenue, contraction revenue, and churned revenue to measure overall retained and expanded recurring revenue from existing customers. GRR calculations exclude expansion revenue and measure only retained recurring revenue after accounting for contraction and churn. Nrr Grr Report 7may2026 Retention calculations are based on recurring contract revenue and active customer billing activity during each reporting period. One-time charges and non-recurring invoice items are excluded from retention calculations. Switch Between Nrr Grr The report supports both chart and table views for analyzing retention performance at a high level or reviewing detailed monthly retention metrics. The chart view visualizes retention trends over time and compares NRR and GRR performance across reporting periods. This makes it easier to identify periods of strong expansion, elevated churn, or declining customer retention. ### Export/Download You can download the report as a CSV for board reporting, investor reporting, revenue operations analysis, and customer retention monitoring. ### Ask AI Agent The NRR / GRR Report includes the Ask AI Agent for conversational retention analysis. Users can ask questions about NRR and GRR performance, identify customer contractions or expansions, and review retention trends across reporting periods directly from the report interface. ## Revenue Waterfall Report The Revenue Waterfall Report provides visibility into recognized, deferred, and unbilled revenue across customers, contracts, and adjustable reporting periods. This report shows finance and revenue teams how billed and unbilled revenue changes over time, monitor deferred balances, and recognize trends. The report combines chart and table views to support both high-level financial analysis and detailed customer-level revenue review. It displays the following metrics: * Recognized revenue by reporting period * Deferred revenue balances over time * Unbilled revenue amounts * Revenue by customer and contract * Monthly, quarterly, and annual revenue trends * Remaining deferred balances by customer * Historical revenue recognition activity * Revenue totals across selected date ranges The table view can be adjusted to give even more granular detail by adjusting metrics that appear on the table. It provides customer-level revenue detail, including monthly recognized revenue values, cumulative recognized totals, and remaining balances associated with active contracts and schedules. Revenue Analysis New Filters Revenue calculations are based on active billing schedules, invoice timing, contract structures, and revenue recognition rules configured within the platform. Recognized revenue reflects revenue earned during each reporting period, while deferred revenue represents billed revenue that has not yet been recognized. Unbilled revenue represents earned or scheduled revenue that has not yet been invoiced. The chart view visualizes recognized, deferred, and unbilled revenue trends across adjustable time periods, making it easier to identify revenue timing shifts or changes in billing patterns. ### Export/Download You can download the report as a CSV for accounting review, financial reporting, revenue reconciliation, audit preparation, and operational analysis. ### Ask AI Agent The Revenue Analysis Report includes the Ask AI Agent for interactive revenue analysis and financial insights. Users can generate revenue summaries, identify concentration risks, analyze customer revenue distribution, and break down recognized revenue trends using natural-language queries. Revenue Analysis Ai # Billing Reports Source: https://guide.withvayu.com/documentation/guides/billing-reports Billing reports provide visibility into invoices, payment status, and customer financial health. These reports help you monitor upcoming charges, track collections, and identify issues before they impact cash flow. * **Billing forecast report -** View upcoming invoices and expected charges before they are issued. This helps anticipate revenue and identify anomalies early. * **AR Health -** Track overdue invoices and identify customers who may require follow-up. Useful for managing collections and cash flow. * **Email exception report -** Monitor email delivery issues related to billing communications, such as failed invoice sends. * **Customers -** Access a list of all customers, including their billing status and account details. ### **Billing Forecast Reports** Image The Billing forecast report shows upcoming invoices and expected charges before they are issued. This report pulls data from active contracts, scheduled billing cycles, and metered usage to project what will be invoiced in the next period. Use this report to anticipate revenue, identify potential billing anomalies, and communicate expected charges to customers before invoices are finalized. The forecast includes both recurring charges and usage-based fees, calculated according to each contract's pricing structure and billing schedule. Billing Forecast Report 20260421 144132 The report displays: * Customer name and contract details * Expected invoice date and billing period * Projected subtotal, tax, and total amount * Breakdown by product or pricing component * Usage estimates for metered products Forecasts are generated automatically based on contract terms and recent usage patterns. For usage-based products, the system projects charges using historical consumption data and any defined commitments or base amounts. ### AR Health The AR Health report tracks overdue invoices and identifies customers who may require follow-up. This report is designed to support collections workflows and help you maintain healthy cash flow. Ar Health Report Plus Chart Filters 20260421 143157 The report shows: * Customer name and outstanding balance * Invoice aging buckets (current, 30 days, 60 days, 90+ days) * Payment status and due dates * Days past due for each overdue invoice * Contact information for billing follow-up Use this report to prioritize collection efforts, identify customers with recurring payment issues, and monitor overall accounts receivable health. The report updates in real-time as payments are recorded and invoices are issued. Invoices are marked as overdue automatically when they pass their due date without payment. Payment status updates flow back from integrated payment providers ([Stripe](/documentation/guides/integrations/stripe)) and ERP systems ([NetSuite](/documentation/guides/integrations/netsuite), [QuickBooks](/documentation/guides/integrations/quickbooks2)) to ensure the report reflects current payment state. ### Email Exception Report The Email exception report monitors email delivery issues related to billing communications. This report surfaces failed invoice sends, bounced emails, and other delivery problems that could prevent customers from receiving billing notifications. Email Exception Report Vayu Email Exception Report Vayu The report displays: * Customer name and billing contact * Email address that failed * Type of failure (bounce, rejection, invalid address) * Date and time of failure * Invoice or communication that failed to deliver Use this report to identify and resolve email delivery issues before they impact payment timelines. Common issues include outdated contact information, spam filters, or invalid email addresses. When an email failure is detected, you can update the customer's billing contact information and resend the invoice manually. The report helps ensure that all customers receive their invoices on time, reducing payment delays caused by communication failures. ### Customers The Customers report provides a comprehensive list of all customers in your account, including their billing status and account details. This report serves as a central reference for customer information and billing configuration. Customers Report 20260421 132443 The report shows: * Customer name and legal name * Active contracts and billing status * Currency and payment terms * Billing contacts and email addresses * Outstanding balance and payment history * Custom fields and account attributes Use this report to review customer account details, verify billing configuration, and identify customers by specific attributes. The report supports filtering and search to help you quickly locate specific customers or groups. Customer data syncs with integrated CRM and ERP systems to ensure consistency across platforms. Updates to customer information in [NetSuite](/documentation/guides/integrations/netsuite), [Salesforce](/documentation/guides/integrations/salesforce), or [QuickBooks](/documentation/guides/integrations/quickbooks2) flow back into Vayu and appear in this report. # Adding a Customer Source: https://guide.withvayu.com/documentation/guides/customers/adding-a-customer Customers can be added in one of three ways: 1. Imported via CSV file 2. Salesforce or Hubspot integration 3. Adding manually - as described below Click **+ Customer** to create a new customer profile. Screenshot 2026 05 07 At 15 37 36 The Add Customer page is divided into structured configuration sections. Each section captures a different category of account information. ## **Company Details** ### **General Information** The General Information section captures the legal and identifying information of the customer, including Name, Legal Name, and Tax ID. These fields define how the customer is referenced throughout the system and on billing documents. ### **Address** The Address section stores geographic and mailing information, including Country or Region, State, City, Street Address, and Postal Code. This information may affect taxation, invoice formatting, and reporting. ## **Contacts** The Contacts section allows you to associate one or more contacts with the customer account. Each contact record includes identifying and communication details such as Contact Name, Title, Phone Number, and Email. You may designate whether the contact should receive invoices by selecting the **Send Invoice** option. Additional actions allow you to add new contacts, manage existing ones, or remove contact records. ## **Configuration** The Configuration section defines system identifiers and billing-related behaviors. ### **External & Integration Identifiers** Fields such as External ID, CRM ID, NS Customer ID, and QB ERP ID are used to synchronize customer records with external systems and accounting platforms. These identifiers allow mapping between Vayu and integrated systems. ### **Account Configuration** Within this section, you assign the customer to a **Subsidiary**, define the default **Overage behavior**, and select a **Customer Type**. These values influence how billing and contracts are applied to the account. ## Invoices Screenshot 2026 05 07 At 15 40 17 The Invoices section controls billing configuration. Here, you define the account Currency, Tax rate method, Invoice Due Date terms, and whether invoices require **Manual Review** before issuance. These settings directly affect invoice generation and approval workflows. ## Payments The Payments section determines how customer payments are handled. You can configure a Primary and Secondary Payment Provider, associate a Wallet if applicable, and enable or disable **Automatically charge payment**. This toggle determines whether invoices are automatically collected based on stored payment methods. ## Aliases Aliases allow you to define alternate names or references for the customer. These may be used for searchability, integrations, or reporting consistency. # Customer Overview Source: https://guide.withvayu.com/documentation/guides/customers/customer-overview The **Customers** page organizes all customer profiles in one place and provides a consolidated operational view of customer status, billing configuration, and account metadata. From this page, you can search, filter, review, and manage customer accounts across your environment. Customer Overview ## **Customer Status Overview** At the top of the page, a status summary bar displays the number of customers in each state: **Active**, **Inactive**, **Churned**, and **Trial**. This summary reflects the current distribution of accounts and updates dynamically based on applied filters. It provides a high-level operational snapshot without needing to inspect individual records. ## **Search and Actions** The control bar allows you to quickly locate and manage customers. The **Global Search** field lets you search by name, email, or other indexed fields. Results update automatically based on matching records. The **Filters** button opens the structured filter builder, allowing more granular control over the displayed results. The **Settings (gear icon)** controls table configuration, while the **Export / Download** option allows you to export customer data. To create a new customer, click **+ Customer**. ## **Filtering Customers** You can filter customer data in a few different ways. That includes using multiple filters or combining conditions. You can define conditions using a structured rule format with fields, operators or values. You can set the operators to "contains," "equals," or "is any of" and relate it to a dropdown will let you select from number of fields: The available filter fields include: * Status * Parent Customer * Address * Country * State * City * Postal Code * Manual Review * Subsidiary Multiple filter conditions can be combined to narrow the result set. Filters can be removed individually or cleared entirely. ## **Customers Table** Below the filter controls, the main customer table displays all customer records that match the current filter state. Each row represents a single customer profile and includes operational and billing metadata. ### **Table Columns** The table includes fields such as Status, Customer name, Legal Name, number of Contracts, Subsidiary, Created Date, Address details, Invoice Due configuration, Manual Review state, and Parent Customer relationships. A contextual action menu is available at the end of each row for additional operations. ### **Table Behavior** Columns can be sorted to reorganize the dataset. The table supports horizontal scrolling when additional columns are displayed. Pagination controls appear at the bottom of the table, where you can define the number of rows per page and navigate between result sets. The current record range (for example, 1–50 of 222) is displayed for reference. ### **Custom Fields** Use custom fields to capture additional information about your customers beyond the standard fields. Custom fields allow you to store business-specific data such as account manager names, customer segments, contract IDs, or any other metadata relevant to your organization. You can define custom fields through the **Settings** section and then populate them on individual customer records. These fields appear on the customer detail page and can be used for filtering, reporting, and segmentation across your customer base. Custom field values can be set manually through the UI or programmatically via the API when creating or updating customer records. This flexibility ensures your customer data structure adapts to your unique business requirements. # Exporting Customer Data Source: https://guide.withvayu.com/documentation/guides/customers/export To export customer information: 1. Navigate to **Customers** 2. Use the **Filters** button to narrow down the customer list if needed 3. Click the **Export / Download** button in the control bar 4. Select the fields you want to include in the export 5. Download the CSV file Filtered Customers Download ### **What's included in customer exports** Customer exports include: * Customer name and legal name * Email and contact information * Status (Active, Inactive, Churned, Trial) * Address details (country, state, city, postal code) * Subsidiary information * Parent customer relationships * Number of contracts * Created date * Invoice due configuration * Manual review status * Any custom fields you've configured You can customize which columns appear in the export by using the **Settings (gear icon)** to select specific fields before exporting. # Managing Customers Source: https://guide.withvayu.com/documentation/guides/customers/managing-customers Create, update, and delete customer records through the UI and API ## Overview Vayu provides multiple ways to manage customer records, including creating new customers, updating existing profiles, and removing customer data when needed. ## Creating customers ### Through the UI To create a new customer: Add Customer 1. Navigate to **Customers** 2. Click **+ Customer** in the control bar 3. Fill in the customer details: * Name and legal name * Contact information * Billing address * Tax ID * Currency * Payment terms (due days) * Custom fields 4. Save the customer profile ### Through the API Use the `POST /customers` endpoint to create customers programmatically: ```json theme={null} { "name": "Acme Corporation", "legalName": "Acme Corp Inc.", "contacts": [ { "name": "John Smith", "email": "jsmith@example.com", "title": "CFO", "receiveInvoiceEmail": true } ], "address": { "country": "United States", "city": "San Francisco", "state": "CA", "postalCode": "94105", "addressText": "123 Main Street" }, "currency": "USD", "dueDays": "NET_30" } ``` ## **Updating customers** ### **Through the UI** To create a new customer: 1. Navigate to **Customers** 2. Click **+ Customer** in the control bar 3. Fill in the customer details: * Name and legal name * Contact information * Billing address * Tax ID * Currency * Payment terms (due days) * Custom fields 4. Save the customer profile ### Through the API Use the `POST /customers` endpoint to create customers programmatically: ```json theme={null} { "name": "Acme Corporation", "legalName": "Acme Corp Inc.", "contacts": [ { "name": "John Smith", "email": "jsmith@example.com", "title": "CFO", "receiveInvoiceEmail": true } ], "address": { "country": "United States", "city": "San Francisco", "state": "CA", "postalCode": "94105", "addressText": "123 Main Street" }, "currency": "USD", "dueDays": "NET_30" } ``` ## **Updating customers** ### **Through the UI** Image To update an existing customer: 1. Navigate to **Customers** 2. Select the customer from the table 3. Go to the **Settings** tab 4. Modify the fields you need to update 5. Save your changes ### **Through the API** Use the `PUT /customers/{customerId}` endpoint to update customer records: ```text theme={null} { "name": "Updated Company Name", "dueDays": "NET_45" } ``` ## **Deleting customers** ### **Through the API** Use the `DELETE /customers/{customerId}` endpoint to remove a customer: ```text theme={null} DELETE /customers/{customerId} ``` ### **Important considerations** When deleting a customer: * The deletion is permanent and cannot be undone * All associated data (contracts, invoices, usage) will be affected * Consider the impact on historical reporting and audit trails * Ensure compliance with data retention policies ## **Searching and filtering** The **Customers** page provides powerful search and filter capabilities: ### **Global search** Use the search field to find customers by: * Customer name * Email address * Other indexed fields Results update automatically as you type. ### **Advanced filtering** Click **Filters** to build complex queries using: * **Status** - Active, Inactive, Churned, Trial * **Parent Customer** - Filter by hierarchy relationships * **Address fields** - Country, State, City, Postal Code * **Subsidiary** - Filter by subsidiary assignment * **Manual Review** - Flag status Multiple conditions can be combined to narrow results. ## **Exporting customer data** To export customer information: Image 1. Apply any desired filters 2. Click the **Export / Download** button *next* to the **+ Create Customer** button 3. Download the file ## **API reference** For complete API documentation, see: * [Create Customer](https://guide.withvayu.com/api-reference/endpoints/customers/create-customer) * [Get Customer](https://guide.withvayu.com/api-reference/endpoints/customers/get-customer) * [List Customers](https://guide.withvayu.com/api-reference/endpoints/customers/list-customers) * [Update Customer](https://guide.withvayu.com/api-reference/endpoints/customers/update-customer) * [Delete Customer](https://guide.withvayu.com/api-reference/endpoints/customers/delete-customer) To update an existing customer: 1. Navigate to **Customers** 2. Select the customer from the table 3. Go to the **Settings** tab 4. Modify the fields you need to update 5. Save your changes ### **Through the API** Use the `PUT /customers/{customerId}` endpoint to update customer records: ```text theme={null} { "name": "Updated Company Name", "dueDays": "NET_45" } ``` ## **Deleting customers** ### **Through the API** Use the `DELETE /customers/{customerId}` endpoint to remove a customer: ```text theme={null} DELETE /customers/{customerId} ``` ### **Important considerations** When deleting a customer: * The deletion is permanent and cannot be undone * All associated data (contracts, invoices, usage) will be affected * Consider the impact on historical reporting and audit trails * Ensure compliance with data retention policies ## **Searching and filtering** The **Customers** page provides powerful search and filter capabilities: ### **Global search** Use the search field to find customers by: * Customer name * Email address * Other indexed fields Results update automatically as you type. ### **Advanced filtering** Click **Filters** to build complex queries using: * **Status** - Active, Inactive, Churned, Trial * **Parent Customer** - Filter by hierarchy relationships * **Address fields** - Country, State, City, Postal Code * **Subsidiary** - Filter by subsidiary assignment * **Manual Review** - Flag status Multiple conditions can be combined to narrow results. ## **Exporting customer data** To export customer information: Image 1. Apply any desired filters 2. Click the **Export / Download** button *next* to the **+ Create Customer** button 3. Download the file # Customer Portal Source: https://guide.withvayu.com/documentation/guides/customers/port Provide customers secure access to view and download their invoices The customer portal provides a secure and streamlined way for customers to access their invoices in one place. Instead of managing multiple emails or logins, customers receive a single-use, one-time access key that grants them entry to their personalized portal. ## What customers can do Within the portal, customers can view and download all issued invoices associated with their account, including the following details: invoice status (paid, pending, or overdue) and due dates. ## Enabling the customer portal To include a customer portal link in invoices: 1. Navigate to **Settings** > **Invoice Preferences** 2. Check off "Include customer portal link in invoice email and PDF" When enabled, customers will receive a portal access link with each invoice, allowing them to check invoice status and view related usage information. ## How it works When a customer receives an invoice with a portal link: 1. They click the unique, one-time access link 2. The portal authenticates them automatically without requiring a password 3. They land on their personalized invoice dashboard 4. They can view all invoices, check statuses, and download PDFs ## Security The customer portal uses single-use access keys for security: * Each link is unique and time-limited * No passwords or account creation required * Access is automatically scoped to the customer's invoices only * Links expire after use or after a set time period # Related Entities Source: https://guide.withvayu.com/documentation/guides/customers/subsidiaries-and-related-entities Create a hierarchy between entities and associate child entities It is possible to create a hierarchy between entities and associate "child" entities with a parent account. This provides a high level of customization, allowing you to either issue invoices to each entity separately, or aggregate the charges to the main parent account. * In the main menu bar, click **Customers** and select the customer (parent) you wish to edit * Go to the **Settings** tab and scroll down to find the **Advanced** section * Click the **+ Add related entity** in the bottom corner of the section. A window will appear. Once there, select the customer you wish to add. (You can add an **unlimited number of entities**). Addrelatedentity Addrelatedentity2 Once done, make sure to **Confirm**. # Events Source: https://guide.withvayu.com/documentation/guides/data-metering/events The **Data Metering — Events** section provides visibility into the raw event data for usage tracking, metering, and downstream billing calculations within Vayu. It gives teams a window to review incoming event activity, validate ingestion workflows, and monitor the underlying data that powers usage-based pricing models. Events represent incoming activity before aggregation or billing calculations are applied. They act as the foundational data layer for usage calculations across the platform for an array of use cases like ingesting product telemetry, validating customer activity, or troubleshooting metering discrepancies. At the top of the page, you’ll find tools for filtering and reviewing events by customer, source, product, or ingestion status. Below that, event records are displayed in a searchable operational view designed to support both metering workflows and billing validation processes. ## **Filters** You can filter events by: * **Date Range** * **Events** – Filter by event name or type. * **Ref** – Search by event reference. * **Customer Alias** – Locate events associated with a specific customer. These filters help isolate individual events or investigate activity patterns. ## Overview Use event search to query and filter usage events recorded in Vayu. This allows you to analyze customer activity, verify metered usage, and troubleshoot billing discrepancies. Events List And Filter View 20260421 133034 Events Dashboard *** ## Search Events Use event search to query and filter usage events recorded in Vayu. This allows you to analyze customer activity, verify metered usage, and troubleshoot billing discrepancies. ### Searching events through the UI To view events in the Vayu interface: 1. Navigate to **Usage** in the left-hand navigation 2. Click **Events** 3. View the latest 100 events recorded in the system Search Events The events list displays: * Event name * Timestamp * Customer alias * Event reference ID * Event data and properties ### Searching events through the API For more advanced filtering and larger result sets, use the API to query events. #### Query events endpoint ````text theme={null} GET /events ### Query parameters Filter events using these parameters: - `startTime` - Beginning of timestamp range (ISO 8601 format) - `endTime` - End of timestamp range (ISO 8601 format) - `eventName` - Filter by specific event name (optional) - `limit` - Maximum number of results to return (default: 10) - `cursor` - Pagination cursor for retrieving additional results ### Example request ```bash GET /events?startTime=2023-11-01T00:00:00Z&endTime=2023-11-30T23:59:59Z&eventName=api_call&limit=100 ```` #### **Example response** ```text theme={null} { "events": [ { "name": "api_call", "timestamp": "2023-09-13T18:25:43.511Z", "customerAlias": "customer_12345", "ref": "4f6cf35x-2c4y-483z-a0a9-158621f77a21", "data": { "key1": "processing_duration", "key2": "api_url" }, "id": "", "createdAt": "2023-11-07T05:31:56Z", "updatedAt": "2023-11-07T05:31:56Z" } ] } ``` ## **Common search scenarios** ### **Find events for a specific customer** Query events by customer alias and time period to see all activity for that customer: `GET /events?startTime=2023-11-01T00:00:00Z&endTime=2023-11-30T23:59:59Z&customerAlias=customer_12345` ### **Verify usage for billing period** Search events within a billing period to verify metered usage before invoice generation: `GET /events?startTime=2023-10-01T00:00:00Z&endTime=2023-10-31T23:59:59Z&eventName=compute_hours` ### **Troubleshoot missing charges** Query events by event name to identify if usage was recorded but not billed: `GET /events?eventName=storage_gb&startTime=2023-11-01T00:00:00Z&endTime=2023-11-30T23:59:59Z` ### **Analyze usage patterns** Retrieve large datasets to analyze usage trends and patterns: `GET /events?startTime=2023-01-01T00:00:00Z&endTime=2023-12-31T23:59:59Z&limit=1000` ### **Event availability** Events are immediately available after submission: * **Real-time visibility** - Events appear instantly in both UI and API * **No processing delay** - Query events as soon as they're recorded * **Immediate analysis** - Monitor and act on incoming data in real-time ### **Pagination** For large result sets, use cursor-based pagination: 1. Make initial request with `limit` parameter 2. Response includes a `cursor` value 3. Use cursor in next request to retrieve additional results 4. Continue until no more results are returned ### **Best practices** * **Use time ranges** - Always specify startTime and endTime to limit result sets * **Filter by event name** - Narrow results to specific event types when possible * **Set appropriate limits** - Balance between result size and number of API calls * **Store cursors** - Save pagination cursors to resume queries * **Monitor in real-time** - Use event search for live monitoring and alerting ## Pricing Events Pricing events, also called measurements, are the raw usage data points you send to Vayu to power usage-based billing. Each event represents a billable action or consumption that occurred in your product. Pricing events are individual records of customer usage that include: * **Event name** - The type of usage being measured (e.g., "api\_call", "storage\_gb", "seats") * **Customer identifier** - Links the event to a specific customer * **Timestamp** - When the usage occurred * **Quantity** - The amount of usage (e.g., 1 API call, 50 GB storage) * **Metadata** - Additional context like region, product tier, or feature flags You can ingest pricing events through multiple methods: ### Ingestion #### **API ingestion** Send events directly to Vayu's ingestion API: ```json theme={null} POST /events { "eventName": "api_call", "customerId": "customer_123", "timestamp": "2024-03-17T10:00:00Z", "quantity": 1, "metadata": { "endpoint": "/users", "method": "GET" } } ``` #### **Batch ingestion** For high-volume scenarios, send events in batches to reduce API overhead. #### **Data warehouse integration** Connect your data warehouse to automatically sync usage data to Vayu on a scheduled basis. ### **Event processing** Once ingested, pricing events flow through Vayu's processing pipeline: 1. **Validation** - Events are checked for required fields and data integrity 2. **Enrichment** - Customer and product data is attached to each event 3. **Aggregation** - Events are grouped and summed according to your pricing configuration 4. **Rating** - Aggregated usage is converted to billable amounts based on pricing tiers 5. **Invoicing** - Rated usage appears on customer invoices #### **Event requirements** Each pricing event must include: * **Unique event ID** - Prevents duplicate processing (idempotency) * **Customer identifier** - Maps to a customer in Vayu * **Event name** - Matches a configured pricing metric * **Timestamp** - Must be within the acceptable time window * **Quantity** - Numeric value representing the usage amount **Best Practices** When sending pricing events: * **Send events in real-time** - Minimize delay between usage and event ingestion * **Use idempotency keys** - Prevent duplicate charges from retry logic * **Include rich metadata** - Enable detailed usage analysis and debugging * **Batch when appropriate** - Balance real-time visibility with API efficiency * **Monitor ingestion** - Track event delivery and processing errors * **Test thoroughly** - Verify events are correctly mapped to pricing metrics ### **Viewing Pricing Events** You can view ingested pricing events in the Vayu dashboard: 1. Navigate to **Usage Data** 2. Select **Events** or **Measurements** 3. Filter by customer, date range, or event type 4. Review event details and processing status This visibility helps you troubleshoot billing issues and verify usage data accuracy. # Usage Source: https://guide.withvayu.com/documentation/guides/data-metering/usage The **Data Metering — Usage** section provides visibility into the consumption data that powers usage-based billing, metering workflows, and operational reporting within Vayu. From here, teams can monitor tracked usage activity, validate incoming data, and review how usage is connected to pricing or invoicing workflows. Usage data acts as a core input for billing calculations and revenue operations across the platform. This section brings usage information to the surface in a structured operational format. Use cases cover tracking customer consumption against contractual commitments, reviewing billable activity, or validating imported usage records before invoicing At the top of the page, you’ll find filtering and monitoring tools for reviewing usage activity across customers, products, and billing periods. Each record represents usage attributed to a specific product for a specific customer on a given day. Below that, usage records and related data are organized to support both real-time operational review and long-term billing analysis. ## **Filters** You can filter usage data using: * **Date Range** – Limit results to a specific billing period. * **Customers** – View usage for one or more customers. * **Product** – Isolate usage for a specific product. Usage Reports Scroll 20260421 142739 Filters allow you to focus on a particular contract period, customer account, or product line when validating billing data. ## **Usage Table** Usage Reports 20260421 142635 The table includes: * **Day** – The date the usage was recorded. * **Customer ID** – Internal identifier for the customer. * **Customer** – Customer name. * **Product** – The product associated with the usage. * **Sub Product** – A more granular classification of the product, if applicable. * **Quantity** – The number of billable units recorded. * **Price** – The price applied to the usage record. At the bottom of the page, you can see: * **Total usage (units)** for the filtered results. * Pagination controls and rows-per-page selection. Usage Filter 20260421 142840 ## **Exporting Usage Data** Click **Download** to export usage data based on the currently applied filters. This is useful for reconciliation, reporting, or auditing. # Anrok Source: https://guide.withvayu.com/documentation/guides/integrations/anrok Vayu–Anrok Integration Vayu Anrok Vayu integrates with Anrok to support sales tax calculation and compliance for usage-based billing. Invoice and transaction data generated in Vayu are made available to Anrok to enable tax calculation, nexus tracking, reporting, and filing workflows, while compliance execution remains within Anrok. By connecting Anrok, tax is calculated automatically on invoices and line items based on product type and customer location, removing the need for manual tax handling and reducing the risk of compliance errors. This integration is designed to keep tax calculation accurate, consistent, and fully embedded in the invoicing workflow, without adding operational overhead. ## Prerequisites Here is a list of what you will need for the Vayu-Anrok integration to work: * Active Anrok account * Anrok API key created in Anrok * At least one pre-configured Anrok product with an assigned tax category * The Anrok product’s external *product ID* available for configuration ## How the Integration Works Once Anrok is connected, tax calculation becomes part of the standard invoice lifecycle in Vayu.  Anrok Integration Connected Vayu integrates with Anrok to support sales tax calculation and compliance for usage-based billing. Invoice and transaction data generated in Vayu are made available to Anrok to enable tax calculation, nexus tracking, reporting, and filing workflows, while compliance execution remains within Anrok. By connecting Anrok, tax is calculated automatically on invoices and line items based on product type and customer location, removing the need for manual tax handling and reducing the risk of compliance errors. This integration is designed to keep tax calculation accurate, consistent, and fully embedded in the invoicing workflow, without adding operational overhead. ## Tax Rate Options in Vayu Vayu supports both manual and automated tax rate methods.  Invoices are created as usual, and tax is calculated automatically before they are finalized. When an invoice is approved, it is sent to Anrok as a transaction, ensuring the tax amount is properly recorded for compliance purposes. This process happens seamlessly in the background, allowing teams to focus on billing and revenue operations while tax logic is handled automatically. ## Tax Rate Options in Vayu Vayu supports both manual and automated tax rate methods.  Vayu Tax Rate Options ### Automated Tax Rate With the automated tax rate option, Vayu sends invoice data to Anrok, which calculates the correct tax dynamically. This method automatically adjusts as conditions change, such as customer location or product classification, and is the recommended approach when using the Anrok integration. With the automated tax rate option, Vayu sends invoice data to Anrok, which calculates the correct tax dynamically. This method automatically adjusts as conditions change, such as customer location or product classification, and is the recommended approach when using the Anrok integration. ### Manual Tax Rate With a manual tax rate, a fixed tax percentage is applied. Even when the Anrok integration is connected, the automatic tax calculation can be overridden with the manual tax rate option. ## Invoice Approval and Compliance Tax is calculated while invoices are in draft; tax calculated through Anrok is finalized at the *moment an invoice is approved*. Once approved, the invoice is recorded in Anrok and treated as a filed transaction. At this point, the invoice is locked in Vayu and cannot be modified. This approval-based locking ensures consistency between billing records and tax filings, helping maintain compliance across systems. ## Downstream Billing and Sync After tax is added, invoices can continue through existing workflows. Tax-inclusive invoices may be sent directly to customers and synced to connected ERP systems, depending on the organization’s setup. # HubSpot Source: https://guide.withvayu.com/documentation/guides/integrations/hubspot Vayu–HubSpot Integration Vayu Hubspot Vayu pulls closed HubSpot customers & deals (including line items, amounts, and selected custom fields), associates them with the HubSpot company and contacts, and recreates them in Vayu as contracts that can be reviewed, activated, and invoiced. ## **Connection and Setup** Connecting your HubSpot account to Vayu is extremely easy. Go to the Integrations tab and select the HubSpot panel. Click the blue Connect button. Connectto Hubspot Connectto Hubspot In the connection window, choose the HubSpot account that you want and Authorize the connection. ## **Configuration** Hubspot Zoomin Hubspot Zoomin In Vayu, there are two settings in the main integration configuration window to manage. First, choose whether or not to automatically import customers: * Automatically import customers from HubSpot (recommended) * Do not import automatically Second, choose whether or not to automatically import contracts: * Automatically import contracts from HubSpot (recommended) * Do not import automatically ## **Workflow** Once you have **closed** a deal in HubSpot, it will automatically be pulled to Vayu as a new contract that is available for review.  To see this information, go to the individual customer’s profile. Note that you will be able to see the origin of a customer (and if it originates from a HubSpot sync). ### **Activation Flow** When the contract enters Vayu, it is by default in an *inactive* state. Once you 1) review and 2) activate the contract, it then creates invoices. Hubspot Activate Contract Hubspot Activate Contract When you click into the contract itself under **Contracts**, you can see the **Integrations** section (next to **Billing**). This shows everything that happened with the specific integration for this particular contract, plus displays any and all custom fields for that deal. Shows Hubspot Synced Shows Hubspot Synced Under the **Settings** tab for the Customer, you can also see the **CRM ID** information. # NetSuite Source: https://guide.withvayu.com/documentation/guides/integrations/netsuite Vayu–NetSuite Integration Vayu Netsuite Vayu specializes in unifying contract and event data into a single revenue management platform. Oracle’s NetSuite platform offers a powerful way for businesses to handle key financial and operational tasks, including accounting and financial management. Integrating the two platforms ensures that your billing and revenue information is fully up to date and aligned at all times, no matter where you’re accessing it.  Vayu integrates smoothly and swiftly with Netsuite, offering robust two-way synchronization for your billing and revenue workflows. Not only do you achieve data consistency across platforms, you can also seamlessly automate critical finance operations. ### **What’s Synced** Vayu enables you to sync customers, sales orders, and invoices **to NetSuite**: * **Customers** - Create and update customer records in NetSuite from Vayu or ingest existing customer records from NetSuite into Vayu. (The sync respects key NetSuite attributes like subsidiary and account configuration.) * **Sales Orders\*** - Automatically generate Sales Orders in NetSuite based on usage, subscriptions, or events tracked in Vayu. This pulls Sales Orders from NetSuite for reconciliation and reporting in Vayu. * **Invoices** - Push invoice data from Vayu and pull from NetSuite: * Push invoices from Vayu to NetSuite as part of your billing cycle. * Pull invoice data from NetSuite for reporting or reconciliation in Vayu. You can now sync Vayu invoices as Sales Orders in NetSuite, including data such as the PO number. This includes a sync status display to follow the process. Go up to the Ellipse menu (●●●), then select **Sync**. On the Sync submenu, select **Sync Invoice as Sales Order**. Sync As Sales Order Netsuite 1 ### **NetSuite Attributes & Setup** To enable precise syncing, Vayu uses NetSuite attributes defined at the **client/account level**, including subsidiaries, accounts receivable, and product ERP mappings. * **Subsidiaries** – Ensures transactions are correctly tagged to the appropriate legal entity in NetSuite. * **Accounts Receivable** - Sync aligns with the customer’s receivable account setup in NetSuite, ensuring accurate GL posting. * **Product ERP Mappings** - Products and pricing in Vayu are matched to NetSuite items using ERP codes, classifications, and other identifiers. ### **Configuration Notes** * Vayu supports both **push and pull** mechanisms via secure API. * Attribute mapping and field-level rules are configurable based on your NetSuite implementation. * Sync can be scheduled or triggered in real-time, depending on your workflow needs. ## Capabilities To enable precise syncing, Vayu uses NetSuite attributes defined at the client/account level, including: * **Subsidiaries**- Ensures transactions are correctly tagged to the appropriate legal entity in NetSuite. * **Accounts Receivable** - Sync aligns with the customer’s receivable account setup in NetSuite, ensuring accurate GL posting. * **Product ERP Mappings** - Products and pricing in Vayu are matched to NetSuite items using ERP codes, classifications, and other identifiers. In other words, the Vayu configurations will precisely match and mirror your NetSuite setup, ensuring the smooth flow of data between Vayu and NetSuite and providing the framework for reliable reporting and insights. ### Operations Overall, these are the operations that Vayu’s NetSuite integration supports: * **Push/Pull** — Across several categories and their attributes, data can be pushed from Vayu to NetSuite, or pulled from NetSuite to Vayu * **Create/Update** — Users can create new records in Vayu that will be pushed to NetSuite * **Reconciliation** —Mismatches are noted and displayed to be fixed * **Scheduled Sync** — Attributes are periodically updated from Vayu ## Prerequisites & Permissions You will need the following to get started: 1. NetSuite account 2. Vayu account 3. Permissions and Admin support ## Connection & Setup To launch initial setup and integrations, please contact the Vayu support team. ## Configurations Set up configurations by clicking on NetSuite on the integration page. A panel with various settings will open to the right side of the page: Netsuite Zoom In ### Products Choose from a dropdown which product you are configuring. For each product, you will be able to configure attributes separately. ### Customers Here, choose if you want your customer lists to automatically export to your NetSuite account, or if you want to maintain full control and go with manual matching. We recommend turning on automatic export by selecting ⦿ **Export customers automatically (recommended)**. ### Invoices There are two configurations for invoices. First, decide if you want automatic syncing once invoices are approved. Upon integration, Vayu aggregates metered events and applies pricing rules (fixed, usage-based, or hybrid). The platform generates draft invoices automatically, visible under the customer’s [**Invoices**](https://guide.withvayu.com/documentation/guides/invoices/real-time-invoice) tab: ### Invoicesfrom Net Suite Pn After approval, invoices are pushed to NetSuite where they inherit all GL and subsidiary attributes from Vayu. NetSuite handles downstream accounting and payment status updates, which Vayu can read back for reconciliation. *Secondly*, choose which invoice number you want to use as your primary, either the auto-generated NetSuite number or override that number with Vayu's invoice number. To allow Vayu to override the NetSuite number, enter your NetSuite settings. Go to **Setup**, then Company, then **Auto-Generated Numbers**, then **Document Numbers**. Go to the Invoice row and check **Allow Override**, then hit **Save**. > > Image > > > While [NetSuite warns](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/bridgehead_4340447524.html) that its next automatic number generation will then follow the higher of the number it generated or the one manually entered, this should not be an issue as the Allow Override setting will let Vayu automatically input its own numbers. ### Credit Memos Finally, choose whether or not you want to automatically sync credit memos when you create a new credit ledger. ## Field Mappings & Attribution ### How Contracts Sync When a deal is marked *Closed–Won* in a CRM (e.g., Salesforce or HubSpot), Vayu automatically creates the customer and contract record. Contract details—start/end dates, product mix, payment provider, and pricing tiers—are created in Vayu for finance team to review and activate. The integration ensures that each contract’s commercial terms are reflected in NetSuite sales orders and invoices. ### Approval Workflows Every invoice has an approval stage before it is synced to NetSuite. Users with proper permissions can modify line items, discounts, quantities, and approve/reject invoices. Once approved, invoices are automatically pushed to NetSuite, updating the **Invoice Activity Log** with timestamps for: * “Written to NetSuite” * “Approved” * “Paid” ## Reconciliation ### How Data Flows Back into ERP/CRM NetSuite updates (payment status, AR changes, credit memos) are pulled into Vayu for real-time visibility. These updates refresh dashboards, contract summaries, and invoice activity views. ### Logs and Activity Tracking Each integration maintains an **Activity Log** showing: * When an invoice or order was created, synced, or modified. * When payments or credits were applied in NetSuite. * Any sync or validation errors encountered. * The log is searchable and filterable by customer, object type, or date. ## Troubleshooting ### Common Issues and Fixes | Issue | Common Reason | Common Fix | | ------------------------------------------------ | ---------------------------------------------------- | --------------------------------------------------------------- | | Invoice or Sales Order not appearing in NetSuite | Missing or incorrect Customer or ERP product mapping | Verify product codes under *Integration → Manage → ERP Mapping* | | Duplicate customer records | Customer existed in both systems before sync | Merge duplicate records in NetSuite; refresh in Vayu | | Sync failed with “Permission Denied” | NetSuite role lacks API access | Update NetSuite user role to include API + transaction rights | | Discrepancy in invoice totals | Currency or rounding mismatch | Confirm both systems use same currency and rounding precision | ## **NetSuite Tax Handling** When connected to NetSuite, Vayu supports flexible tax handling that aligns with NetSuite’s configuration and reporting requirements. You can control how tax is calculated and synced between systems: * **NetSuite-managed tax:** Use NetSuite as the source of truth for tax rates, codes, and jurisdiction logic. Vayu aligns invoice data with NetSuite’s configuration during sync. * **Vayu-applied tax:** Apply tax within Vayu at the invoice or line-item level, then sync finalized invoices to NetSuite. * **Aligned tax syncing:** Maintain consistency between systems by ensuring tax structure, rates, and mappings match NetSuite expectations. Vayu adapts to NetSuite’s tax model by supporting both line-item and invoice-level tax, depending on how your products and tax settings are configured. # QuickBooks Source: https://guide.withvayu.com/documentation/guides/integrations/quickbooks2 Vayu–QuickBooks Integration Vayu Quickbooks Vayu specializes in unifying contract commercials and usage data into a single revenue management platform. QuickBooks offers a powerful way for businesses to handle key financial and operational tasks, including accounting and financial management. Integrating the two platforms ensures that your billing and revenue information is fully up to date and aligned at all times, no matter where you’re accessing it.  Vayu integrates smoothly and swiftly with QuickBooks, offering robust two-way synchronization for your billing and revenue workflows. Not only do you achieve data consistency across platforms, you can also seamlessly automate critical finance operations. ## **Overview** The Vayu-QuickBooks integration supports two-way syncs, with data syncing from Vayu and other information from QuickBooks. You are given multiple options for syncing with the integration.  You can opt for Manual Sync on a per-invoice basis, Bulk Sync for multiple-invoice approval in a single batch, and two different options for Auto Sync. You can implement *Auto Sync by Invoice Issue Date* or *Auto Sync on Approval*. ### **From Vayu → QuickBooks** * **Invoice Issuance**: Syncs fixed, usage, or hybrid invoices for prepaid, post-paid, or mixed periods. Metadata includes period start/end, product lines, discounts, taxes, Vayu invoice# * **Credit Notes:** For cancellations, refunds, overages, then reconciled/mapped to original invoice * **Payments**: Pushes payment status (paid, partial, failed, etc.); reconciles invoices with payment records * **Refunds**: Triggers refund issuance and sync refund metadata (amount, date, reason). * **Customer & Contract Sync**: Links invoices to QuickBooks customers, optionally mapping Vayu contracts to Quickbooks projects, jobs, or contracts. Also syncs customer details (name, address, email, external IDs). * **Products / Items** * Sync Vayu products to ERP catalog for revenue mapping. * Include metadata: product ID, SKU, revenue category, tax class. * **GL Account Mapping**: Enables per-line or per-product mapping to QuickBooks chart of accounts (income, AR, tax). * **Custom Metadata**: Syncs custom fields like Class, Department, and Tags for financial reporting or segmentation. ### **From QuickBooks → Vayu** * **Invoice Status Updates**: Retrieves updated status (Paid, Overdue, Voided) from QuickBook to sync back into Vayu. * **Customer Metadata**: Pulls updates to customers * **Product Metadata**: Pulls updates to product definitions (e.g., class assignments, GL mappings). ## **Prerequisites & Permissions** You’ll need the following to get started: 1. QuickBooks account 2. Vayu account 3. Permissions and Admin support ## **Connection & Setup** To launch initial setup and integrations, please contact the Vayu support team. From Vayu, click **Connect to QuickBooks**. Image2 Next, sign in with your QuickBooks admin or accountant account. Finally, authorize Vayu to access the required accounting data. Once connected, Vayu will begin pulling customer and product metadata and will allow invoice syncs according to your settings. ## **Configurations** Image6 Set up configurations by clicking on QuickBooks on the integration page. A panel with various settings will open to the right side of the page: ### **Invoices** You have two configurations to consider for invoices with QuickBooks and Vayu. First, choose which invoice number to use: * ⦾ Use Vayu invoice number  * ⦾ Generate invoice numbers in Vayu and sync to QuickBooks * ⦾ Use QuickBooks invoice numbers and override Vayu numbers Second, choose whether or not to include bank details: * ⦾ Include * ⦾ Don’t include ## **Capabilities** The main capabilities of the integration include: 1. Syncing Vayu invoices into QuickBooks 2. Syncing Vayu invoices as sales orders into QuickBooks 3. Syncing invoice status 1. From Vayu to QuickBooks 2. From QuickBooks to Vayu 4. Mapping Vayu customers to QuickBooks customers 5. Mapping Vayu products to QuickBooks products To make sure that all info is up-to-date, select the three dots symbol, then select **Sync**, then **Sync to QuickBooks**. Image1 Under **QB sync**, you can view: 1. Integration status  2. When data was last synced 3. the original invoice by clicking **Open on QuickBooks**. Image4 To map your Vayu customer to a QuickBooks customer, go to the customer profile in Vayu and select **Settings**.  Go to **QB ERP ID** and select the customer available from your QuickBooks sync, as seen here: Image3 A similar process works for syncing products. Under **Products**, select **+ Create New**. Fill in the product information, then select from the **QB Products** dropdown: Image5 ## **Reconciliation** The Vayu-QuickBooks integration tracks failed syncs, catalogs errors, and monitors retries. On top of this, there is duplication prevention when it comes to retries, matching records by unique IDs to avoid conflicts. ### **Field Mappings & Attribution** * **ItemRef:** Identifies the QuickBooks product/service * **AccountRef:** Income or AR account * **ClassRef:** Optional segmentation fields * **CustomerRef:** Mapped QuickBooks customer ### **Logs and Activity Tracking** Vayu ensures proper versioning and reconciliation by logging all synced records with timestamps for audits.  To do this, be sure to enable syncing on validation reports.  All sync activity is tracked inside Vayu: * Success and failure logs for failed syncs * Retry attempts * IDs of created QuickBooks transactions * Timestamped event history * Error reasoning/details with user-friendly explanations These logs help finance teams quickly diagnose and correct issues. ## **Troubleshooting** ### **Common Issues and Fixes** | **Issue** | **Explanation** | **Fix** | | :------------------ | :----------------------------------------------------------- | :---------------------------------------------------------------------- | | Missing ItemRef | A Vayu product is not mapped to a QuickBooks Product/Service | Add mapping in Vayu → retry sync | | Permission error | QuickBooks user lacks access to invoices or items | Reconnect using a QuickBooks admin | | Rate limit exceeded | QuickBooks Online throttles at 500 req/min | Vayu automatically retries; try bulk sync during lower activity periods | | Invalid GL mapping | The referenced account is inactive or restricted | Update mapping to an active income or AR account | | Token expired | OAuth token revoked or expired | Reconnect QuickBooks in Vayu | ## **QuickBooks Online** The integration is managed by token and OAuth 2.0 authentication. The Vayu QuickBooks integration can handle up to 500 requests/minute (including retries). It also comes replete with rich support for Chart of Accounts (COA, mapping Vayu products to QuickBook accounts) and segmentation by classes and location.  Additionally, QuickBooks accountants use the same API under the accountant role, but with multi-client and permission nuances.  ### **Refunds** Refunds are handled by Credit Memo and Payment reversal. ## **Quickbooks Accounting User as client** QuickBooks accountants use the same API under the accountant role, but with multi-client and permission nuances.  Similarly, this is managed by token access and OAuth 2.0 authentication. ## **QuickBooks Tax Handling** When integrated with QuickBooks, Vayu supports tax handling that aligns with QuickBooks’ native tax engine and reporting structure. You can control how tax is applied and synced: * **QuickBooks-managed tax:** Allow QuickBooks to calculate and apply tax based on its configured rates, jurisdictions, and customer settings. * **Vayu-applied tax:** Calculate and include tax in Vayu before syncing invoices to QuickBooks. * **Consistent tax alignment:** Ensure invoice structure and tax fields match QuickBooks expectations to reduce reconciliation issues. Vayu supports both automatic tax calculation in QuickBooks and explicit tax values passed during sync, depending on your workflow. # Rillet Source: https://guide.withvayu.com/documentation/guides/integrations/rillet Vayu–Rillet Integration Vayu integrates with Rillet to support automated accounting workflows for usage-based billing. Approved invoices and customer data from Vayu syncs to Rillet, enabling accurate revenue recognition, reporting, and month-end close processes without manual re-entry. Vayu Rillet Vayu Rillet *Get in touch with our team to learn more about integrating with Vayu and Rillet* See more about connecting with the [Vayu API](https://guide.withvayu.com/api-reference/pages/connecting-to-vayu). # Salesforce Source: https://guide.withvayu.com/documentation/guides/integrations/salesforce Vayu–Salesforce Integration Vayu Salesforce Vayu Salesforce The Salesforce integration connects Salesforce CRM data with Vayu’s revenue and billing workflows. It enables Vayu to ingest customer and deal context from Salesforce and use that data to drive pricing, invoicing, and revenue execution. Salesforce remains the system of record for CRM entities such as accounts and opportunities. Vayu serves as the system of record for monetization, billing logic, and revenue workflows. This integration is designed for teams that manage customers and commercial agreements in Salesforce and require a consistent, auditable path from closed deals to billing activity. ## **Synced Data and System Ownership** Vayu syncs account and deal-related data from Salesforce and associates it with customers, products, and pricing logic inside Vayu. Salesforce is authoritative for account identity, opportunity structure, and CRM-managed fields. Vayu does not write back to Salesforce and does not attempt to replicate CRM functionality. Only data required to support revenue workflows is ingested, and Salesforce record identifiers are preserved for traceability. ## **Installation** ### **Prerequisites** * User must have **Salesforce admin-level access:** 1. Managed package installation 2. Permission grants Installation is via the Salesforce managed package, done through a direct link that you will get during onboarding (and is not individualized). First, open the install link (you have the option to use a custom domain). Choose the scope of the installation, as in installing for a general user or an admin. ## **Setup and Authentication** The integration is configured from within the Vayu platform. The Salesforce integration is enabled by installing a Salesforce managed package and completing initial configuration in Vayu.  Authentication is handled natively within Salesforce and *does not* require OAuth credentials. Unlike other integrations in Vayu, setup is done through the Salesforce sign-in screen and a Custom Domain. Image1 1 Admins can get this custom domain by logging into Salesforce, then clicking on **Settings**. Search for “domain,” then navigate down to **Company Settings** and select “My Domain.” Once there, copy the **Current My Domain URL**, as seen above. Next, navigate to the Salesforce login screen. Once there, choose to log in via Use Custom Domain in the bottom right corner of the window. Then, paste your Custom Domain URL from Salesforce. Hit **Continue**. Next, you will decide the level of access you want to provide from three choices: * Install for Admins Only * Install for All Users * Install for Specific Profiles Choose the appropriate option and check the box to acknowledge you are installing a “Non-Salesforce Application.” Press **Install**,. Next, a final **Approve Third-Party Access** box will appear. There, you will have the *option* to select **SSL Encryption**. Finally, select the checkbox next to “**Yes, grant access to these third-party websites**” and press **Continue**. Image2 You will be able to see Vayu included on a list of installed packages. An administrator connects a Salesforce account and grants access to the Salesforce objects required for account and deal ingestion. Authentication establishes a secure connection between Salesforce and Vayu. Once authentication is complete, Vayu immediately begins ingesting eligible records. # Slack Source: https://guide.withvayu.com/documentation/guides/integrations/slack Slack Int Vayu supports a native Slack integration that allows customers to connect their Slack workspace, configure notification delivery, and interact with selected workflows directly from Slack. ## Overview The Slack integration is used to connect a customer’s Slack workspace to Vayu so that Vayu can: * send direct messages for approval workflows * send direct notifications for specific events * send automated notifications to a configured Slack channel * receive and process interactive Slack actions This integration is OAuth-based and requires a workspace admin or authorized user to connect Slack to Vayu. ## Capabilities Once connected, the Slack integration supports the following capabilities: * **Workspace connection via OAuth**: Users can authorize Vayu to access their Slack workspace through the Slack OAuth flow. * **Channel configuration for notifications**: Users can select and save a Slack channel where automated notifications should be delivered. Slack Channel Config * **User and channel discovery**: Vayu can retrieve Slack users and channels from the connected workspace to support configuration and notification flows. * **Interactive approvals**\ Vayu can send interactive approval messages in Slack, including an **Approve** action for invoices. * **Operational notifications**\ Vayu can send direct notifications such as credit note updates, as well as automated channel notifications. ## How it works The Slack integration consists of several parts across the Vayu platform: * **API integration endpoints**\ The API exposes endpoints to initiate the Slack connection, handle the OAuth callback, retrieve users and channels, receive Slack events, and trigger Slack notifications. * **Slack client**\ Vayu uses a dedicated Slack client built on `@slack/web-api` to communicate with Slack using the stored OAuth token. * **Frontend integration settings**\ The Vayu frontend includes Slack integration settings that allow users to connect Slack, configure a destination channel, and disconnect the integration. * **Notification delivery pipeline**\ Automated Slack notifications are queued through SNS and delivered by the communications service. ## Supported flows The Slack integration currently supports the following flows: 1. **Connect Slack workspace**\ A user starts the OAuth flow from the Vayu integrations UI. 2. **Authorize and store credentials**\ Slack redirects back to Vayu, which processes the callback and stores the workspace authentication details. 3. **Configure notification channel**\ A user selects a Slack channel to receive automated notifications. This channel ID is stored in the integration configuration. 4. **Send direct or channel notifications**\ Vayu sends Slack messages either to users directly or to the configured workspace channel, depending on the workflow. 5. **Handle interactive actions**\ When a user clicks an interactive action in Slack, Vayu receives the callback and processes the corresponding business action. ## Interactive actions The current Slack interaction handling is focused on `block_actions`. At present, the primary implemented interactive action is: * `approve_invoice` When a user selects this action in Slack: * Vayu updates the invoice status to **Approved** * the original Slack message is updated to reflect the completed action ## Configuration requirements The Slack integration depends on the following configuration: * `API_URL`\ Used to construct the Slack OAuth callback URL. * `SLACK_SECRETS_ID`\ Used to retrieve the Slack OAuth application secrets. The configured secret is expected to contain values such as: * `CLIENT_ID` * `CLIENT_SECRET` * `SCOPES` ## Important behavior and limitations * Automated Slack channel notifications require a saved `channelId` in the integration configuration. * If no `channelId` is configured, channel-based notification delivery will fail. * Slack users and channels are only retrieved when the integration is active. * Current interactive support appears to be limited to specific implemented actions, primarily invoice approval. ## Relevant components Key implementation areas include: * `apps/api/src/modules/integrations/integrations.controller.ts` * `apps/api/src/modules/integrations/integrations-apps/slack/` * `libs/integration-client/src/slack-client/slack-client.ts` * `apps/communications/src/apps/slack/slack-emitter/` # Snowflake Source: https://guide.withvayu.com/documentation/guides/integrations/snowflake Vayu–Snowflake Integration Vayu Snowflake The Snowflake integration lets Vayu ingest usage data from Snowflake so that usage-based billing can be calculated inside Vayu. In this setup, Snowflake acts as the system where usage events are stored, while Vayu acts as the billing layer that reads, accepts, and processes that usage data. This integration replaces the legacy ERP Imports workflow. In practical terms, the integration is designed for teams that already collect usage data in a Snowflake data warehouse and want to use that data for billing and revenue operations. Rather than forcing teams to move their operational usage data into a separate system first, Vayu works with Snowflake as the source of truth and supports multiple ingestion paths depending on how much control the customer wants over timing, transformation, and delivery. This page explains how the Snowflake integration works, what data Vayu expects, and how to prepare a Snowflake environment for ingestion. It is useful both for teams that want Vayu to pull usage from Snowflake directly and for teams that prefer to push usage records into Vayu through the API. ## How The Snowflake Integration Works Snowflake is commonly used to store structured operational and analytical data, including product usage events, transaction logs, and billing-related measurements. The Snowflake integration allows Vayu to use that data as the basis for billing calculations without requiring Snowflake to stop serving as the customer’s warehouse of record. Vayu supports two ingestion models for Snowflake data. In the pull model, Vayu connects to Snowflake and reads usage records from a configured table or view. In the push model, the customer sends usage records from Snowflake to Vayu by calling the Usage Ingestion API. ## Pull Model In the pull model, usage events remain in Snowflake and Vayu connects using configured credentials. Vayu reads from a designated table or view at scheduled intervals and processes the data for billing. This model works best when Snowflake already serves as the central warehouse for metering data and a stable dataset is available for ingestion. To set it up, identify the table or view that should act as the billing source. Ensure the dataset contains one row per usage record and that column names and data types remain consistent over time. Then create or assign a Snowflake user or service account for Vayu. Grant USAGE on the relevant database and schema, and SELECT on the target table or view. Limit permissions to only what the integration requires. ## Push Model In the push model, the customer sends usage records from Snowflake to Vayu through the Usage Ingestion API. This typically runs through scheduled jobs, pipelines, or other orchestration layers. It is useful when you need control over when data is sent, how it is transformed, or how records are grouped before delivery. To set it up, extract the required usage records from Snowflake, transform them into the expected format if needed, and send them to Vayu’s ingestion endpoint. Monitor the pipeline to catch failed submissions, schema mismatches, or missing fields. ## Data Requirements For either ingestion model, Snowflake must contain structured usage records that match the schema Vayu expects. The exact source can be a table or a view, but the data should be stable, consistently typed, and suitable for repeated ingestion. At a minimum, each usage record should identify the customer or account, identify the metric or event being measured, include the usage quantity, and include a timestamp. Depending on the billing model, customers may also include related entity identifiers, contract references, or custom metadata that help enrich the billing context. Because Vayu uses this data for billing calculations, consistency matters as much as completeness. A table or view with inconsistent data types, missing identifiers, or irregular timestamp formats may ingest unpredictably or require additional transformation before it can be used safely. ## Prepare The Snowflake Source Before enabling the integration, prepare a Snowflake table or view for billing ingestion. A dedicated view is often preferred, as it allows you to normalize source data and expose only the fields required for billing. Each row should represent a single usage record, with stable column names and consistent data types. If your upstream pipeline produces multiple datasets or complex transformations, consolidate that logic before ingestion so Vayu reads from a clean, predictable source. Start by identifying or creating the table or view that will act as the usage source. Confirm that required billing fields are present and that records follow a consistent structure. If needed, create a dedicated view to handle transformation and field mapping within Snowflake rather than during ingestion. ## Grant Access For The Pull Model If you plan to use the pull model, Vayu must be able to connect to Snowflake and read from the selected source. This requires a Snowflake identity with the correct access to the target database, schema, and table or view. In most cases, a service account is the safest approach because it gives the integration a dedicated identity that can be managed separately from individual user accounts. That also makes auditing and permission control easier over time. Create or assign the Snowflake user or service account that Vayu will use. Grant `USAGE` on the target database and schema. Grant `SELECT` on the usage table or view. Review the permissions once they are in place and remove anything that is broader than the integration actually needs. ## Next Steps Once the Snowflake source is prepared, the next step is to configure the integration in Vayu according to the ingestion model you plan to use. For pull-based setups, connect Vayu to Snowflake and point it to the correct table or view. For push-based setups, prepare the process that sends usage records to the Usage Ingestion API. After the connection and source setup are complete, validate the ingestion flow with sample usage data before relying on it for production billing. This makes it easier to catch schema mismatches, missing fields, or permission issues before they affect invoices or revenue reporting. # Stripe Source: https://guide.withvayu.com/documentation/guides/integrations/stripe Vayu–Stripe Integration Vayu Stripe Vayu integrates with **Stripe** to handle invoice payments, payment status updates, and customer billing workflows. Stripe can function as a customer’s **primary payment provider**, enabling automatic invoice synchronization and real-time payment status updates from strip to Vayu. The integration supports customers who are **already using Stripe** as well as customers who are **new to Stripe**, with onboarding handled either directly in Stripe or, in future iterations, via Vayu-assisted flows. It includes a payment link in the invoice itself, as well as an auto-collect feature you can toggle. ## How the Stripe Integration Works Once Stripe is connected for a customer, Vayu remains the source of truth for **customer**, **contract management,** and **invoicing**. Stripe will be used solely for **payments**. After a contract is active, invoices are generated in Vayu. Upon approval, invoices can be synced to Stripe automatically or manually, depending on configuration. Invoices can also be auto-collected. Set Stripe as the payment provider by going to a **Customer** profile, then selecting **Settings**. Scroll to **Configurations** and choose Stripe as your **Primary** **Payment Provider**. Set Payment Method Stripe You can also elect to add auto-collect by toggling “Automatically charge payment”: Auto Collectpayment Stripe ### **Invoice Synchronization Flow** When an invoice is approved in Vayu, one of two sync paths applies: * **Automatic sync (default):**\ Approved invoices are immediately pushed from Vayu to Stripe without manual action. * **Manual sync (optional):**\ Users can manually trigger invoice sync if auto-sync is disabled. This sync ensures that the Stripe invoice reflects the exact totals, line items, and billing details generated in Vayu. Sync Stripe ### **From Vayu invoice to Stripe invoice** Once synced, each invoice in Vayu includes a **clickable reference** that opens the corresponding Stripe invoice. This allows finance teams to move seamlessly from operational billing (Vayu) to payment execution (Stripe). ### **Payment methods and customer experience** Stripe supports multiple payment methods, including: * Credit cards * ACH / wire transfers * Direct online payment links From the customer’s perspective, invoices received via Stripe include a **Pay Online** option. This link is embedded directly in the invoice PDF and routes the customer to Stripe’s hosted checkout. Set Payment Method Stripe You can also elect to add auto-collect by toggling “Automatically charge payment”: Auto Collectpayment Stripe ### **Invoice Synchronization Flow** When an invoice is approved in Vayu, one of two sync paths applies: * **Automatic sync (default):**\ Approved invoices are immediately pushed from Vayu to Stripe without manual action. * **Manual sync (optional):**\ Users can manually trigger invoice sync if auto-sync is disabled. This sync ensures that the Stripe invoice reflects the exact totals, line items, and billing details generated in Vayu. Sync Stripe ### **From Vayu invoice to Stripe invoice** Once synced, each invoice in Vayu includes a **clickable reference** that opens the corresponding Stripe invoice. This allows finance teams to move seamlessly from operational billing (Vayu) to payment execution (Stripe). ### **Payment methods and customer experience** Stripe supports multiple payment methods, including: * Credit cards * ACH / wire transfers * Direct online payment links From the customer’s perspective, invoices received via Stripe include a **Pay Online** option. This link is embedded directly in the invoice PDF and routes the customer to Stripe’s hosted checkout. Payfrom Invoice Stripe ### **Payment status updates back to Vayu** After a payment attempt: * Stripe updates the **payment intent status** (success or failure). * Vayu retrieves this status and updates the invoice accordingly. * Successful payments automatically update the invoice status to **Paid** in Vayu. * Failed payments surface as part of Vayu’s **outstanding balances (OOS)** and AR workflows. This ensures billing, finance, and operations teams always see the **current payment state** without switching systems. Future iterations may allow parts of this onboarding to be initiated or guided directly from Vayu. ## Configuring the Stripe Integration Go to your Stripe and get an API key for your Stripe account. Back in Vayu, go to **Integrations** and go to the **Stripe** panel. Click on **Manage**. Once there, you will have three things to configure. First, paste your API key in the text bar (which you can modify later). Stripe Getstarted Configure Stripe Integration Next, choose how you would like to sync your customer list from these three options: * Sync customers from Stripe to Vayu * Sync customers from Vayu to Stripe * Do not sync automatically Finally, choose how to sync approved invoices: * Automatically sync invoices upon approval (recommended) * Do not sync automatically ### **Payment status updates back to Vayu** After a payment attempt: * Stripe updates the **payment intent status** (success or failure). * Vayu retrieves this status and updates the invoice accordingly. * Successful payments automatically update the invoice status to **Paid** in Vayu. * Failed payments surface as part of Vayu’s **outstanding balances (OOS)** and AR workflows. This ensures billing, finance, and operations teams always see the **current payment state** without switching systems. Future iterations may allow parts of this onboarding to be initiated or guided directly from Vayu. ## Configuring the Stripe Integration Go to your Stripe and get an API key for your Stripe account. Back in Vayu, go to **Integrations** and go to the **Stripe** panel. Click on **Manage**. Once there, you will have three things to configure. First, paste your API key in the text bar (which you can modify later). Stripe Getstarted Configure Stripe Integration Next, choose how you would like to sync your customer list from these three options: * Sync customers from Stripe to Vayu * Sync customers from Vayu to Stripe * Do not sync automatically Finally, choose how to sync approved invoices: * Automatically sync invoices upon approval (recommended) * Do not sync automatically # Xero Source: https://guide.withvayu.com/documentation/guides/integrations/xero Vayu–Xero Integration Vayu Xero Vayu supports a full integration with Xero, including: exporting approved invoices, allowing usage-based and fixed charges to appear as structured invoice line items. Customers and products map to their Xero equivalents, enabling teams to complete billing and accounting workflows directly in Xero. Vayu centralizes contract, usage, and pricing data into a single billing system. Xero provides the accounting layer where financial records are stored, categorized, and reported. When connected, Vayu sends finalized invoices directly to Xero. Each invoice is exported with its full structure, including usage-based and fixed charges as separate line items. This allows finance teams to review, reconcile, and report on revenue inside Xero without needing to reconstruct how an invoice was calculated. ## **What’s Synced** Vayu syncs billing data to Xero as part of the invoicing workflow. Customers are created or matched in Xero so invoices are always associated with a valid contact. Approved invoices are exported with all line items preserved, including quantities, descriptions, and totals. Products defined in Vayu can be mapped to Xero items so invoice lines are categorized correctly for reporting. ## **Xero Attributes & Setup** Accurate syncing depends on how records are structured in Xero. Each invoice must be associated with a contact, so customer records in Vayu are either linked to existing contacts or created during sync. Products can be mapped to Xero items, which determines how invoice line items are categorized. These mappings ensure that revenue is grouped correctly and remains consistent across reports. Because invoices are created with full detail, the way products and accounts are configured in Xero will directly affect how financial data appears after sync. ## **Configuration Notes** Invoice sync is triggered after approval in Vayu. Draft invoices are not exported. When a record has already been synced, subsequent syncs update the existing record based on its current state rather than creating duplicates. Product and customer mappings determine how data is represented in Xero, so these should be reviewed before syncing at scale. ## **Capabilities** The integration supports creating and updating customers, invoices, and products in Xero through Vayu. Sync operations are initiated from within Vayu, and each action is tracked so you can confirm whether it completed successfully. Because billing logic is handled in Vayu, Xero reflects the results of that process rather than driving it. ## **Prerequisites & Permissions** To get started, you need access to a Xero organization and permission to authorize integrations. In Vayu, you’ll need the ability to manage integrations and access billing data. Before connecting, make sure your core data is already defined. Customers, products, and invoices should exist in Vayu so they can be synced and mapped correctly. ## **Connection & Setup** To connect Xero, open the integrations page in Vayu and select Xero. Start the connection flow and complete authentication in Xero, then return to Vayu once authorization is complete. After the connection is established, Vayu links to your Xero organization and enables syncing. ## **Configurations** After connecting, review the integration settings to ensure that data flows into Xero as expected. ### **Products** Products in Vayu can be mapped to items in Xero. This mapping determines how invoice line items are categorized and is important for reporting. ### **Customers** Customer syncing ensures that invoices are tied to the correct contact. Records can be created automatically in Xero or matched to existing contacts to prevent duplication. ### **Invoices** Invoices are generated in Vayu based on usage, subscriptions, and pricing rules. Once approved, they are synced to Xero with all line items preserved. Each component of pricing appears as its own line item, allowing full visibility into how the invoice total was calculated. ## **Field Mappings & Attribution** When data is synced, Vayu maps billing records into Xero’s invoice structure. Customers become contacts, and mapped products are used when creating line items. This ensures that invoice data in Xero reflects the same structure defined in Vayu, including the breakdown of usage-based and fixed charges. ## **Reconciliation** ### **How data is used in Xero** Once invoices are synced, they can be managed directly in Xero for payment tracking and reporting. Finance teams can rely on Xero for downstream accounting workflows while using Vayu to generate and structure billing data. ### **Logs and activity tracking** Vayu tracks sync activity for each record. You can review whether a sync succeeded, when it occurred, and any details returned during the process. ## **Next steps** After connecting Xero, sync a small set of customers and invoices and review how they appear in Xero. Confirm that mappings, line item structure, and totals behave as expected before relying on the integration more broadly. ## **Xero Tax Handling** When connected to Xero, Vayu supports tax handling that aligns with Xero’s predefined tax rates and codes. You can control how tax is managed across systems: * **Xero-managed tax:** Use Xero as the source of truth for tax rates and rules, with Vayu aligning invoice data during sync. * **Vayu-applied tax:** Apply tax within Vayu and send finalized invoice values to Xero. * **Synced tax consistency:** Maintain alignment between systems by matching tax rates, codes, and product mappings. Vayu supports line-item tax and Xero-compatible tax codes, ensuring invoices sync correctly with Xero’s tax model. # Alerts and Notifications Source: https://guide.withvayu.com/documentation/guides/invoices/alerts-and-notifications Configure alerts to stay informed about important billing events and customer activity ## Overview Use alerts and notifications to monitor critical billing events, usage thresholds, and customer activity. Vayu provides multiple notification channels including email, Slack, and in-app alerts to keep your team informed. ## Notification channels ### Email notifications Receive email alerts for important billing events: * **Tier crossing** - Get notified when a customer's usage crosses into a new pricing tier * **Commitment thresholds** - Alerts when customers approach or exceed their commitment amounts * **Invoice events** - Notifications for invoice generation, approval, and payment status * **Usage anomalies** - Alerts for unusual usage patterns or spikes ### Slack notifications Connect [Vayu to your Slack workspace](https://guide.withvayu.com/documentation/guides/integrations/slack) to receive real-time alerts in designated channels. Slack notifications provide: * Instant visibility for time-sensitive events * Team collaboration on billing issues * Centralized notification management * Customizable channel routing ### In-app alerts View notifications directly within the Vayu platform by clicking on the bell icon in the upper right. Notification Center Sample You will see alerts such as: * **Tier usage alerts** - When usage passes the last configured tier, prompting you to adjust settings * **Action required** - Notifications for invoices pending approval or sync issues * **System updates** - Important platform changes or maintenance notifications * **Recent downloads** - Including successful and failed downloads ## Configuring alerts To set up notifications: 1. Navigate to **Settings** 2. Go to **Notifications** 3. Select your preferred notification channels 4. Configure alert types and thresholds 5. Add recipient email addresses or Slack channels 6. Save your notification preferences ## Alert types ### Usage-based alerts Monitor customer consumption patterns: * **Tier crossing** - Customer moves to a different pricing tier * **Usage threshold** - Consumption reaches a specified percentage of commitment * **Overage detection** - Usage exceeds contracted amounts * **Last tier exceeded** - Usage surpasses the highest configured tier ### Billing alerts Stay informed about billing cycle events: * **Invoice generated** - New invoice created for a customer * **Invoice approved** - Invoice ready for sync to ERP * **Payment received** - Customer payment processed * **Payment overdue** - Invoice past due date ### System alerts Operational notifications: * **Sync failures** - Issues syncing data to ERP systems * **Integration errors** - Problems with connected systems * **Data quality issues** - Missing or inconsistent billing data ## Managing notifications ### Notification preferences Customize which events trigger notifications and who receives them. You can: * Enable or disable specific alert types * Set different recipients for different alert categories * Configure notification frequency (immediate, daily digest, weekly summary) * Define custom thresholds for usage-based alerts ### Notification history View past notifications to track: * When alerts were sent * Which events triggered notifications * Who received the alerts * Actions taken in response ## Best practices * **Set appropriate thresholds** - Configure alerts that provide actionable information without overwhelming your team * **Route strategically** - Send different alert types to the appropriate teams (billing, customer success, finance) * **Test notifications** - Verify alerts are working correctly before relying on them for critical events * **Review regularly** - Periodically assess which alerts are valuable and adjust accordingly * **Document responses** - Create runbooks for common alert scenarios to ensure consistent handling # Credits Source: https://guide.withvayu.com/documentation/guides/invoices/credits Manage customer credit balances and apply them to invoices ## Overview Credits allow you to maintain a running balance for each customer that can be applied to reduce invoice amounts. Instead of issuing refunds or adjusting invoices directly, you can grant credits to a customer’s account and let those credits be applied over time. This approach provides flexibility for handling prepayments, refunds, promotional offers, and billing adjustments, while keeping a clear and auditable record of all changes through the customer’s credit ledger. ## How credits work Each customer has a credit ledger that tracks every credit-related transaction. When credits are granted, deducted, or applied to invoices, those actions are recorded as entries in the ledger, along with the resulting balance. The ledger includes: * **Grant entries** – Credits added to the customer’s account * **Deduction entries** – Credits removed from the customer’s account * **Application entries** – Credits applied to specific invoices * **Running balance** – The available credit balance after each transaction This structure ensures that every change to a customer’s balance is traceable and tied to a specific action or invoice. ## Granting credits You can grant credits to a customer either through the Vayu interface or programmatically through the API. ### Through the UI Navigate to **Customers**, select the relevant customer, and open the **Credits** tab. From there, click **Grant Credits**, enter the amount, and optionally include a note explaining the reason for the credit. Once confirmed, the credits are added to the customer’s balance and recorded in the ledger. ### Through the API Use the `POST /credits/grant` endpoint to add credits programmatically: ```json theme={null} { "creditAmount": 500, "customerId": "customer_123" } ``` ## Credit Ledger The credit ledger provides a complete audit trail of all credit activity for a customer. It records every grant, deduction, and application of credits, maintaining a running balance that shows the customer's available credit at any point in time. ### Accessing the credit ledger To view a customer's credit ledger: 1. Navigate to **Customers** 2. Select the customer 3. Go to the **Credits** tab The ledger displays all credit transactions in chronological order, showing the most recent activity first. ### Transaction types The credit ledger tracks three types of transactions: #### Grant transactions Credits added to the customer's account. These can come from: * Manual grants through the UI * API-based credit grants * Promotional credits * Service credits for issue resolution #### Deduction transactions Credits removed from the customer's account. These include: * Manual deductions through the API * Administrative adjustments * Expired credits (if applicable) #### Application transactions Credits applied to reduce invoice amounts. These show: * The invoice that received the credit * The amount applied * The remaining balance after application ### Ledger information Each ledger entry includes: * **Transaction type** - Grant, deduct, or application * **Amount** - The credit value for this transaction * **Running balance** - Available credit after this transaction * **Timestamp** - When the transaction occurred * **Associated invoice** - For application transactions, which invoice was credited * **Notes** - Optional description or reason for the transaction * **Created by** - User or system that initiated the transaction ### Viewing credit history via API You can retrieve a customer's credit ledger programmatically using the `/credits` endpoint: ```bash theme={null} GET /credits?customerId=customer_123 ``` The API returns the complete transaction history with all ledger details. ### **Auditing and compliance** The credit ledger serves as an immutable audit trail for: * **Financial reconciliation** - Match credit activity to accounting records * **Customer inquiries** - Provide transparent history of credit usage * **Dispute resolution** - Reference exact dates and amounts of credit transactions * **Compliance reporting** - Track promotional credits or service level agreements ### **Filtering and search** Use the ledger interface to: * Filter by transaction type (grants, deductions, applications) * Search by date range * View transactions for specific invoices * Export ledger data for reporting ### **Balance calculation** The running balance updates with each transaction: * **Grants** increase the balance * **Deductions** decrease the balance * **Applications** decrease the balance and link to an invoice The current balance represents the total credits available for the customer to use on future invoices. # Dunning and Payment Reminders Source: https://guide.withvayu.com/documentation/guides/invoices/dunning Automate payment reminders and manage collections for overdue invoices ## Overview Dunning and payment reminders allow you to automate how your system follows up on unpaid invoices. Instead of relying on manual outreach, Vayu tracks invoice status and sends timely reminders to customers as payments become due or overdue. This automation helps maintain consistent communication, improves collection rates, and reduces the operational burden on your team. At the same time, it gives you control over how and when reminders are sent, how messaging escalates, and how payment collection is handled for overdue accounts. ## How Dunning Works Dunning is the communication layer of your collections process. It monitors invoice status and triggers reminders based on timing and payment state. As invoices move through their lifecycle: 1. An invoice approaches its due date or becomes overdue 2. The system sends reminders based on your configured schedule 3. Reminder frequency and tone escalate over time 4. The process continues until the invoice is paid or reaches a final state This ensures that customers are consistently notified without requiring manual follow-up. ## Configuring Reminder Schedules To configure your reminder workflow, navigate to **Settings** and open your billing preferences. From there, define when reminders should be sent across the invoice lifecycle. A complete schedule typically includes: * **Pre-due reminders** – Notifications sent before the invoice due date * **Due date reminders** – Sent on the day payment is expected * **Overdue reminders** – Sent at intervals after the due date (for example, 7, 14, or 30 days overdue) You can adjust the timing and number of reminders to match your billing policies and customer expectations. ## Reminder Stages and Tone Beyond timing, dunning workflows are typically structured around stages that reflect increasing urgency. A common progression includes: ### Friendly Reminder Sent shortly before or after the due date. The tone is polite and assumes the customer may have overlooked the payment. ### Follow-up Reminder Sent if payment is still outstanding. The message becomes more direct while remaining professional. ### Final Notice Sent as a last attempt before escalation. Clearly communicates urgency and potential consequences of non-payment. ### Escalation Actions taken after all reminders fail, such as restricting access, applying penalties, or escalating internally. This staged approach helps maintain good customer relationships while still enforcing payment expectations. ## Customizing Reminder Emails Each stage in your reminder workflow can be customized to reflect your messaging and brand. Reminder emails typically include: * Invoice details such as amount due, invoice number, and due date * Clear payment instructions or a link to pay * Contact information for billing questions * Messaging tone appropriate to the stage of escalation * Branding elements such as your company name and visual identity Customizing these templates ensures that communication remains consistent and aligned with your business. ## Excluding Customers From Dunning In some cases, automated reminders are not appropriate. You can exclude specific customers from dunning to handle them manually. To do this, open the customer profile, navigate to their settings, and enable **Exclude from dunning**. This is commonly used for customers with special payment arrangements, accounts under dispute, or high-value relationships that require personalized handling. ## Payment Collection and Automation Dunning focuses on communication, but payment collection determines how invoices are actually paid. If customers have a payment method on file, you can enable automatic payment collection. When enabled, the system attempts to charge the stored payment method when invoices are issued or become due. You can also configure retry behavior for failed payments, allowing the system to automatically attempt collection again before escalating through the dunning workflow. This reduces the need for reminders in many cases and can significantly improve collection efficiency. ## Monitoring Overdue Invoices and Performance To track how your dunning strategy is performing, you can monitor overdue invoices and collection metrics across the system. Common approaches include: * Viewing overdue invoices directly in the invoice dashboard * Reviewing customer-level balances and aging information * Generating reports on accounts receivable aging * Tracking metrics such as days sales outstanding (DSO) and collection success rates These insights help you refine reminder timing, messaging, and escalation policies over time. ## Integration With Payment Providers Dunning and payment collection workflows integrate with your connected payment systems. For example: * Payment providers such as Stripe can automatically attempt to charge stored payment methods and update invoice status * Accounting systems can reflect payment status changes such as Paid or Overdue * Customer-facing portals allow customers to view invoices and complete payments directly These integrations ensure that reminders, payments, and financial records stay in sync across systems. ## Best Practices A well-designed dunning workflow balances persistence with professionalism. * Start with friendly, helpful reminders before escalating tone * Keep messaging clear and include direct payment options * Escalate gradually based on how overdue the invoice is * Apply rules consistently while allowing for exceptions when needed * Monitor results and adjust timing or messaging based on effectiveness A consistent and thoughtful approach improves both collection rates and customer experience. ## Service Restrictions and Escalation For severely overdue invoices, you can define escalation actions that go beyond reminders. These may include restricting access to services, preventing additional usage, or requiring payment before reactivation. If you use these measures, clearly communicate them in your final reminder so customers understand the consequences in advance # Invoice PDF Source: https://guide.withvayu.com/documentation/guides/invoices/invoice-pdf Generate, customize, and share PDF invoices with customers ## Overview Invoice PDFs provide a finalized, shareable format for customer invoices. Unlike the dynamic view that shows detailed usage calculations, the PDF represents the official invoice document for sharing, sending, and record keeping. ## Dynamic view vs. PDF view Vayu provides two ways to view invoices: ### Dynamic view The dynamic view displays: * How the invoice was calculated * Usage consumption for each product over the invoice period * Usage accumulation throughout the billing period * Detailed charge breakdowns * Usage growth patterns and spikes Use the dynamic view to understand billing calculations and analyze customer consumption patterns. ### PDF view Image The PDF view provides: * Finalized invoice format for official records * Clean, professional layout for customer sharing * Printable and archivable document * Optional clickable links (such as "Pay Now" buttons) * Simplified line item display options Use the PDF view for customer communication, payment collection, and accounting records. ## Generating invoice PDFs Invoice PDFs are automatically generated when an invoice is finalized. You can: 1. Navigate to **Invoices** 2. Select an invoice 3. Select **Show Invoice** 4. Click **View PDF** or **Download PDF** 5. Share the PDF directly with customers or download for your records ## Customizing PDF appearance Configure PDF formatting in **Invoice Preferences**: 1. **Line Item Visibility** — Decide whether or not to **Show zero-value line items** (displaying all line items, even those with zero totals), or **Hide zero-value line items** (removing items with no charges). Hiding zero-value items reduces visual clutter and makes invoices easier to scan. 2. **Line Item Detail Level** — Choose the level of detail for each line item, either with a **Full breakdown** (quantity, unit price, and total for each item), or **Total only** (only the total amount for each line item). 3. **Branding and Formatting** — Customize the PDF to match your brand's logo, info, color scheme, styling, custom footer text, instructions, and payment terms. ## Accessing PDFs via API Retrieve invoice PDFs programmatically using the API: ```bash theme={null} GET /invoices/{invoiceId}/payment-status ``` The response includes an `invoicePdfUrl` field with a direct link to the PDF: ```json theme={null} { "invoiceId": "inv_123", "billingStatus": "Paid", "amountDue": 0, "amountPaid": 5000, "total": 5000, "dueDate": "2024-01-31T00:00:00Z", "paidAt": "2024-01-28T15:30:00Z", "invoicePdfUrl": "https://example.com/invoices/inv_123.pdf" } ``` ## **Interactive PDF features** Digital PDFs can include clickable elements: * **Pay Now links** - Direct customers to payment portals * **Contact information** - Clickable email addresses and phone numbers * **Support links** - Quick access to help resources * **Customer portal** - Link to view invoice details online These interactive elements improve the customer payment experience while maintaining a professional invoice format. ## **PDF storage and retrieval** Invoice PDFs are: * **Automatically stored** - Generated and saved when invoices are finalized * **Permanently accessible** - Available for historical invoices * **Version controlled** - Original PDFs preserved even if invoice data changes * **Securely hosted** - Protected with authentication and access controls ## **Sharing invoice PDFs** Send PDFs to customers through: * **Email** - Attach PDF to invoice notification emails * **Customer portal** - Make PDFs available for customer download * **Direct download** - Generate download links for specific invoices * **ERP sync** - Include PDF URLs when syncing to accounting systems ## **Best practices** * **Review before sending** - Always preview the PDF to ensure accuracy before sharing with customers * **Customize appropriately** - Balance detail with clarity based on your customer needs * **Maintain consistency** - Use the same PDF format across all invoices for professional appearance * **Archive systematically** - Store PDFs according to your record retention policies * **Test interactive elements** - Verify that clickable links work correctly in the PDF # Invoices Overview Source: https://guide.withvayu.com/documentation/guides/invoices/invoices-overview The Invoices section provides a centralized view of generated invoices across your customers, contracts, and billing cycles. It shows finance and operations teams all invoice activity, track billing status, and manage invoice workflows in a single location. Invoices are designed to reflect the output of your configured pricing, subscriptions, and usage data. This section helps surface the relevant billing information in a structured and operationally focused format. This applies for reviewing draft invoices before finalization, validating billed usage, or tracking invoice history for a customer account. At the top of the page, you’ll find summary information and filtering tools that help narrow invoice data by customer, status, billing period, or related contract activity. Below that, invoices are displayed in a searchable table designed to support both day-to-day billing operations and financial review workflows. ## **Invoice Overview** The Invoices section allows you to view and manage invoices generated for your customers and serves as the primary workspace for reviewing billing activity. From this view, you can see invoices across customers and contracts and filter them. Prior to approving each invoice, you can also apply changes to individual invoices then approve, send & sync each invoice or multiple invoices at once . ### **Invoice Filters and Presets** Invoices can be filtered to help you focus on specific subsets of data. Invoices Report 20260421 132550 Filtering allows you to narrow down invoices by status, customer, contract, or time period. You can also apply preset filter combinations to quickly switch between different invoice views without rebuilding filters each time. Presets help standardize common workflows, such as review queues or approval batches. ### **Working With Multiple Invoices** From the invoice list view, you can take actions on multiple invoices simultaneously, allowing for: * Reviewing groups of invoices * Applying bulk actions where relevant (such as status changes or multiple approvals) * Navigating efficiently across large invoice sets This can be especially useful for high-volume billing operations. Image ### **Zen Mode** Zen Mode provides a focused way to review invoices one at a time. Think of it as a soothing, meditative approach to invoice management without being overwhelmed by an entire table of options.  When Zen Mode is enabled, invoices are presented **individually**, then reviewed/approved in sequence, one at a time. The interface minimizes distractions from surrounding data. Image ### **Dynamic View vs. PDF View** Each invoice includes a dynamic view that displays how the invoice was calculated as well as the usage consumption for each product over the invoice period. From this view, you can see usage accumulation over the invoice period and how charges are broken down within the invoice. Within an invoice, usage is displayed as it accumulates across the billing period. This allows you to see how usage grows or spikes during the invoice timeframe and to make changes for consumption in later billing periods. Each invoice can also be viewed as a PDF, represents the finalized invoice format and allows for standard sharing, sending, and record keeping. The PDF can also include clickable links in its digital form, such as a ‘Pay Now’ link. Dynamic And Pdf Invoice View 20260421 124925 # Invoices Portal Source: https://guide.withvayu.com/documentation/guides/invoices/invoices-portal Share invoices with customers easily The Customer Portal provides a secure and streamlined way for customers to access their invoices in one place. Instead of managing multiple emails or logins, customers receive a single-use, one-time access key that grants them entry to their personalized portal. Within the portal, customers can: * View all issued invoices associated with their account. * Check invoice status, including paid, pending, or overdue. * See due dates to stay informed about upcoming payments. * View and download invoices in a structured, easy-to-access format. # One-Off Invoices Source: https://guide.withvayu.com/documentation/guides/invoices/one-off-invoices Create standalone invoices outside of regular billing cycles for ad-hoc charges, adjustments, or special circumstances One-Off Invoices allow you to bill customers for charges that fall outside of your regular billing cycles. These standalone invoices are useful for ad-hoc services, manual adjustments, implementation fees, or any other charges that don't fit into your standard contract-based billing. Unlike contract-based invoices, One-Off Invoices are manually created and are not tied to usage data or metered events. Charges are entered directly, allowing you to invoice immediately without waiting for billing cycle closure. ## When to use One-Off Invoices Use One-Off Invoices for: * **Ad-hoc services** – One-time professional services, consulting, or support charges * **Manual adjustments** – Billing corrections or credits that need to be issued separately * **Implementation fees** – Setup or onboarding charges billed independently from the main contract * **Special circumstances** – Custom charges that don't align with your regular billing schedule * **Out-of-cycle charges** – Charges that need to be billed immediately rather than waiting for the next billing period * **Mid-cycle adjustments** – Usage overages or added resources that need to be billed before the next cycle * **Refunds or credits** – Adjustments to previously issued invoices handled outside the standard billing flow One-Off Invoices are separate from One-Time Fees within contracts. One-Time Fees are part of a contract's pricing structure, while One-Off Invoices are standalone billing documents created outside of any contract. ## One-Off Invoices vs. One-Time Fees Understanding the difference between these two concepts is important: | Feature | One-Off Invoices | One-Time Fee | | ------------------------ | -------------------------------- | ------------------------------------- | | **Scope** | Standalone invoice | Part of a contract | | **Timing** | Created manually as needed | Scheduled within contract terms | | **Use case** | Ad-hoc charges outside contracts | Planned fees like setup or onboarding | | **Billing cycle** | Independent of billing cycles | Follows contract billing schedule | | **Contract requirement** | No contract needed | Requires an active contract | ## Creating a One-Off Invoices To create a One-Off Invoices: You can create a One-Off Invoices from either the global invoice view or directly from a specific customer. **Option 1: From the Home page** 1. Navigate to **Home** from the main menu 2. Click **Create Invoice** in the upper menu 3. Select the customer you want to bill 4. Add line items with descriptions and amounts 5. Set the invoice due date 6. Review and approve the invoice by clicking **Save Settings & Continue** 7. Send or sync the invoice to your ERP system **Option 2: From the Customer page** 1. Navigate to **Customers** 2. Select the relevant customer 3. Open the **Invoices** tab 4. Click **Create One-Off Invoices** 5. Add line items and complete the invoice details 6. Review, approve, and send ### Line item configuration When adding line items to a One-Off Invoices, you can specify: * **Description** – Clear explanation of what the charge is for * **Amount** – The charge amount in the customer's currency * **Quantity** – Number of units (if applicable) * **Tax** – Tax rate to apply to this line item * **Discount** – Fixed amount or percentage discount ### Invoice settings Configure these settings for your One-Off Invoices: * **Currency** – Defaults to the customer's currency but can be overridden * **Due date** – When payment is expected (defaults to customer's payment terms) * **Invoice date** – The date the invoice is issued * **Tax treatment** – How tax should be calculated and applied * **Payment terms** – Net 30, Net 60, or custom terms ## Approving and sending One-Off Invoices Once you've created a One-Off Invoices: 1. **Review** – Verify all line items, amounts, and customer details are correct 2. **Approve** – Click **Approve** to finalize the invoice (this locks it from further editing) 3. **Send** – Email the invoice directly to the customer or download the PDF 4. **Sync** – Push the invoice to your connected ERP system (Stripe, NetSuite, QuickBooks, etc.) Invoices can be shared with customers through direct email or made available via the customer portal, and can be viewed in both dynamic and PDF formats. Once approved, One-Off Invoices cannot be edited. If you need to make changes, you'll need to void the invoice and create a new one. ## Managing One-Off Invoices ### Viewing One-Off Invoices One-Off Invoices appear in your main invoice list alongside contract-based invoices. You can filter to show only One-Off Invoices: 1. Go to **Invoices** 2. Click **Filters** 3. Select **Invoice Type: One-Off** ### Tracking payment status Monitor payment status for One-Off Invoices: * **Draft** – Invoice created but not yet approved * **Pending** – Invoice approved and sent, awaiting payment * **Paid** – Payment received and recorded * **Overdue** – Payment not received by due date * **Void** – Invoice cancelled ### Voiding a One-Off Invoices If you need to cancel a One-Off Invoices: 1. Open the invoice from the invoice list 2. Click **Actions** → **Void Invoice** 3. Add a reason for voiding (optional but recommended) 4. Confirm the action Voided invoices remain in your records but are marked as cancelled and won't be included in revenue calculations. ## Integration with ERP systems One-Off Invoices sync to your connected ERP systems just like contract-based invoices: ### Stripe One-Off Invoices are created as [Stripe](https://guide.withvayu.com/documentation/guides/integrations/stripe) invoices with all line items, tax, and payment terms preserved. The invoice includes a clickable reference linking back to Vayu. ### NetSuite One-Off Invoices inherit GL codes and subsidiary attributes from the customer configuration. They appear as standard invoices in [NetSuite](https://guide.withvayu.com/documentation/guides/integrations/netsuite) with all line items and tax details. ### QuickBooks One-Off Invoices sync to [QuickBooks](https://guide.withvayu.com/documentation/guides/integrations/quickbooksx) with your configured invoice numbering scheme and include all line items, tax calculations, and payment terms. ### Xero One-Off Invoices are created in [Xero](https://guide.withvayu.com/documentation/guides/integrations/xero) with proper account codes and tax rates based on your integration settings. ## API access You can create and manage One-Off Invoices programmatically using the Vayu API. See the [API Reference](https://guide.withvayu.com/api-reference/endpoints/invoices/list-invoices) for details on invoice endpoints. **Best Practices** * **Clear descriptions** – Use detailed line item descriptions so customers understand what they're being charged for * **Consistent naming** – Develop a naming convention for One-Off Invoices (e.g., "Professional Services - \[Date]") * **Document reasons** – Keep internal notes about why each One-Off Invoices was created * **Review before approval** – Double-check all amounts and details since approved invoices cannot be edited * **Track separately** – Use filters and reports to monitor One-Off Invoices revenue separately from contract-based revenue * **Set proper due dates** – Ensure due dates align with your payment terms and customer agreements # Payments Source: https://guide.withvayu.com/documentation/guides/invoices/payments Manually update invoice payment status when payments are received outside of integrated payment systems ## Overview Use the mark as paid feature to manually update an invoice's payment status when you receive payment through channels not integrated with Vayu, such as wire transfers, checks, or external payment processors. ## When to mark invoices as paid Mark invoices as paid manually when: * **Wire transfers** - Customer pays via bank transfer outside of Stripe or other integrated payment systems * **Check payments** - Customer sends a physical check * **External payment processors** - Payment is processed through a system not connected to Vayu * **Cash payments** - Customer pays in cash (less common for B2B) * **Payment reconciliation** - Correcting payment status after manual verification ## Marking an invoice as paid ### Through the UI 1. Navigate to **Invoices** 2. Locate the invoice you want to mark as paid 3. Click on the invoice to open the detail view 4. Click **Mark as Paid** 5. Confirm the action The invoice status will update to **Paid** and the paid date will be recorded. ### Through the API Use the payment status endpoint to retrieve and verify invoice payment information: GET /invoices//payment-status `The response includes: - billingStatus - Current payment status - amountDue - Outstanding amount - amountPaid - Amount already paid - total - Total invoice amount - dueDate - Payment due date - paidAt - Date payment was received - invoicePdfUrl - Link to invoice PDF ## Automatic payment status updates When using integrated payment systems like Stripe, payment status updates automatically: - **Successful payments** - Invoice status updates to Paid in Vayu automatically - **Failed payments** - Surface in outstanding balances and AR workflows - **No manual intervention needed** - Billing and finance teams see current payment state in real-time This eliminates the need to manually mark invoices as paid when using integrated payment processors. ## Payment tracking Once marked as paid: - The invoice appears in paid invoice filters - The paid date is recorded for reporting - Outstanding balance calculations exclude the invoice - AR aging reports reflect the payment - The invoice is locked from further editing ## Best practices - **Verify payment receipt** - Confirm funds are received before marking as paid - **Document payment method** - Add notes about how payment was received - **Reconcile regularly** - Match marked payments against bank deposits - **Use integrations when possible** - Automated payment tracking reduces manual work and errors` # Assign Plan to Customer Source: https://guide.withvayu.com/documentation/guides/plans-and-pricing/assign-plan-to-customer Once a contract template has been created, it can be assigned at any point to a new customer. * Go to the **Plans & Pricing** page * Click on the three-dot menu on the line of the plan you wish to assign and select **Assign customer** * Define the starting date according to the customer's contractual terms and click '**Finish**'. It is also possible to assign a contract directly by selecting **Assign and save as a contract** from within the plan editor by using the **Save** dropdown menu. # Base Amount and Commitment Source: https://guide.withvayu.com/documentation/guides/plans-and-pricing/base-amount-and-commitment #### Configuration of Base Amount > Base amounts allow you to set a minimum amount to be charged in cases of zero consumption. This is only applicable for metered or usage-based products. The base amount is set on the product line item, so you must start with a product line item. * Go to **Plans & Pricing** → **New plan** → **Add pricing & products** → **Tiered Pricing** * Add by clicking on **+ Set Base Amount** * Enter the **amount to be charged** in case of no usage metered * **Delete** or **edit** by hovering with your mouse **Please Note** \ Base amounts are only applicable for usage products (otherwise it's easier to go for "fixed recurring" pricing). \ Base amount charges will be added to the customer's invoice according to the plan's billing interval. All amounts are calculated in USD. *** #### Configuration of Commitment > Commitment is the minimum quantity a customer has committed to purchase during the plan lifetime. The commitment is set on the product line item, so you must start by creating a product. * **Go to Plans & Prcing** --> New plan--> Add pricing & products --> select **Tiered Pricing** * Add by clicking on **+ Set Commitment** * Enter the number of units you want to set as your commitment * **Delete** or **edit** by hovering with your mouse **Please Note** Commitment can be used for usage products with tiered-based pricing. Commitments are counted in units and calculated based on the price per unit (the defined tier). # Contract Lifecycle Source: https://guide.withvayu.com/documentation/guides/plans-and-pricing/contract-lifecycle The Contract Processing section defines how Vayu evaluates contracts, pricing structures, subscriptions, and usage data to generate billable outputs across the platform. It provides visibility into the processing logic that connects customer agreements to invoicing, revenue workflows, and downstream financial operations. Contract processing supports a wide range of billing models, including fixed fees, usage-based pricing, phased contracts, minimum commitments, and pricing adjustments over time. Whether you are validating billing behavior, reviewing how pricing rules are applied, or troubleshooting contract-related calculations, this section helps surface the operational flow behind how contract data is processed throughout the billing lifecycle. #### Contract Status * **Active / Inactive** An active contract refers to a contract that is live and operational. The platform's automated billing cycle generates invoices based on the contract's defined terms and billing period. Invoices for active contracts will appear in the **Invoices** section. You also have the option to deactivate a contract, which will suspend billing automation, and no further invoices will be issued. Contracts with future start dates are labeled as "Inactive" and will automatically transition to active status once the start date is reached. * **Terminated** The contract will conclude on the specified end date. Upon termination, no additional invoices will be issued. Terminated contracts cannot be duplicated or turned into Active again. #### Contract Edit Use edit for contract that only started and no invoice had been approved. **When to use:** when there is a mistake or some wrong pricing definition and no invoices has been approved or issued to customers **What to expect** The system will delete and replace the contract and the invoices with new ones from the given start date. #### Contract Revision Revision allows you to edit the commercial terms of a contract and is applicable for the following use cases: **Renewal with new terms** Renewal of contract for a new period with updated pricing terms. **Update** **of the current contract** Update contract terms and commercial details, including additional products, pricing, and discounts. You can modify the contract terms *retroactively* or schedule updates for a *future* date. Invoices will be issued based on the updated terms. **When to use update contract terms** when the contract is process ‘live’ and ‘active’ however, there are new pricing / products that needs to be updated and added to the current contract. **What to expect** 1. System will Terminate the old contract immediately and will start a new version based on the initial start date but with the new terms. 2. System will re-generate invoices for the selected period. Invoices which are on ‘**Draft**’ and ‘**In** **review**’ will be deleted and **re generated** according to the updated terms. 3. Invoices that had already been **approved** under the old contract **will remain as is** - in cases of duplication or irrelevant invoice can be either deleted or tag as ‘Cancelled’ #### Delete a Contract This will allow you to delete a contract and its related invoices all together. This function is immediate and final - once deleted, a contract or invoice cannot be restored. **When to use** When the contract is false and the commercial terms are outdated. Delete the contract and create a new one instead. **What to expect** 1. System will delete the contract and remove it from the platform 2. The deleted contract cannot be restored 3. All related invoices will be deleted and cannot be restored ## Overview Use contract phases to create agreements where the terms of payment change throughout the life of the contract. This allows you to structure contracts with different pricing, products, or billing terms across multiple time periods. ## Creating a phase To add a phase to a contract: 1. Navigate to **Customers** 2. Select the customer and go to the **Contract** page 3. Click the **+ Add Phase** button on the right side of the page 4. In the phase creation window: * Define the **start date** for the new phase * Add a **label** to identify the phase 5. Click **Go to plan builder >** to configure the phase's pricing and products ## Use cases Contract phases are useful for: * **Tiered pricing rollouts** - Start with introductory pricing and transition to standard rates * **Pilot to production** - Begin with a limited pilot phase before full deployment * **Seasonal pricing** - Adjust pricing based on seasonal demand or usage patterns * **Graduated commitments** - Increase minimum commitments as the customer relationship matures * **Product expansion** - Add new products or services at specific milestones ## Managing phases Each phase operates as a distinct pricing period within the same contract. When a phase's start date is reached, the system automatically applies the new terms and generates invoices according to the phase's configuration. You can view and manage all phases from the **Phases** tab on the contract overview page. ## Video tutorial For a complete walkthrough of creating contract phases, see this tutorial velow: