Product Catalog

The Product Catalog in Vayu is a centralized list of reusable product definitions. Catalog products are primarily used to standardize product metadata, such as name, description, and external IDs, and to support usage-based billing in contracts.

Overview

Catalog products let you define reusable product records that can be referenced from contracts. This helps keep product definitions consistent across customers and supports integrations with external systems.

Key Concepts

It is important to distinguish between catalog products and products defined inside contracts.

Catalog products are reusable product definitions stored in the Product Catalog. They contain product metadata, such as name, description, and externalId.

Contract products are billing line items defined inside a contract. They specify how a customer is charged, including scheduling, pricing, and invoice behavior.

A contract product can reference a catalog product using catalogProductId.

When catalogProductId Is Required

In Vayu, catalogProductId is optional for some contract products, but it is required for usage-based pricing models, including PER_UNIT and TIERED.

This is because usage metering is anchored to a catalog product.

Usage-Based Pricing

Catalog products are especially important for usage-based billing.

PER_UNIT pricing supports fields such as price, chunkSize, baseAmount, and usageReset.

TIERED pricing supports tier definitions and options such as tiers, subscriptionCadence, autoUpgrade, prorate, isRevShare, baseAmount, and usageReset.

Both PER_UNIT and TIERED require catalogProductId.

Integrations

Catalog products support integration workflows by storing an optional externalId. This can be used to map Vayu products to records in external systems.

Use a consistent externalId format when your team integrates with ERP, CRM, or accounting systems so product mappings stay predictable.

Best Practices

Use clear product names that are easy to recognize in contracts and downstream systems.

Example

These names are specific enough to identify later in billing and reporting workflows.

API Calls - Standard Tier
Cloud Storage - Per GB
Professional Services - Hourly

Avoid vague names such as Product 1 or SKU-12345, which can be difficult to identify later.

Create catalog products before creating usage-based contract products. For any usage-based billing model, create the catalog product first so it can be referenced by catalogProductId.

Common Use Cases

Example

This catalog product can be used for metered API billing.

{
  "name": "API Requests",
  "description": "Pay-per-request API access",
  "externalId": "api-requests"
}

Example

This catalog product can be used for usage-based storage billing.

{
  "name": "Storage GB",
  "description": "Usage-based storage billing by gigabyte",
  "externalId": "storage-gb"
}

Example

This catalog product can be used as a reusable internal product definition for services contracts.

{
  "name": "Implementation Services",
  "description": "Internal reference product for services contracts",
  "externalId": "services-implementation"
}