> ## Documentation Index
> Fetch the complete documentation index at: https://alguna.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Pricing Models API Reference

> Technical reference for implementing Alguna's pricing models in your API calls

This reference guide covers the technical implementation of pricing models in API calls. For conceptual information and business use cases, see our [Pricing Models Guide](/pricing/pricing-models).

## Supported Pricing Model Types

When creating prices via the API, you must specify the `type` parameter with one of these values:

| Type                   | Description                            | Model Parameter                   |
| ---------------------- | -------------------------------------- | --------------------------------- |
| `unit`                 | Simple per-unit pricing                | `unitPricingModel`                |
| `fixed`                | Fixed price regardless of usage        | `fixedPricingModel`               |
| `tiered`               | Pricing tiers based on total usage     | `tieredPricingModel`              |
| `graduated_tiered`     | Different rates for usage in each tier | `graduatedTieredPricingModel`     |
| `prepaid_tiered`       | Pre-purchased units with tier pricing  | `prepaidTieredPricingModel`       |
| `prepaid_fixed_tiered` | Pre-purchased fixed package in a tier  | `prepaidFixedTieredPricingModel`  |
| `tiered_percentage`    | Percentage rates based on tier         | `tieredPercentagePricingModel`    |
| `graduated_percentage` | Graduated percentage rates by tier     | `graduatedPercentagePricingModel` |
| `volume_percentage`    | Percentage of transaction volume       | `volumePercentagePricingModel`    |

Each pricing type requires its corresponding model parameter to be provided in your API request.

## Request Examples

Below are examples of how to structure API requests for various pricing models:

<Accordion title="Request Examples">
  <Snippet file="new-pricing-model-request-examples.mdx" />
</Accordion>

## Required and Optional Fields

Each pricing model has its own required and optional fields. The table below summarizes the base fields required for all pricing models:

| Field              | Type   | Required | Description                                                                                                                                |
| ------------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `productId`        | string | Yes      | The product ID this price applies to                                                                                                       |
| `type`             | string | Yes      | The pricing model type (see table above)                                                                                                   |
| `feeType`          | string | No       | Fee classification: `fixed` or `metered`. Defaults to the product's fee type if omitted                                                    |
| `billingDirection` | string | No       | When the charge is collected: `advance` (start of period) or `arrears` (end of period). Defaults to the product's payment terms if omitted |
| `billingInterval`  | string | Yes      | Billing interval: `monthly`, `quarterly`, or `yearly`                                                                                      |
| \[Model Parameter] | object | Yes      | The specific model parameters (varies by type)                                                                                             |

## Common Configuration Options

All pricing models support these additional configuration options:

### Trial Periods

```json theme={null}
"trialPeriodDays": 14
```

### Spending Thresholds

```json theme={null}
"maximumSpend": {
  "amount": "1000.00",
  "period": "month"
}
```

### Discounts

```json theme={null}
"discount": {
  "discountType": "percentage",
  "amount": "20.00",
  "durationType": "fixed",
  "durationValue": 3,
  "durationUnit": "months"
}
```

## Field Reference

For a complete reference of all available fields for each pricing model type:

<Snippet file="pricing-model-request-fields.mdx" />

## Using with Subscription Versions

When creating or updating subscription versions, you'll include pricing model details in your request body. See the [Create Subscription Version](/api-reference/subscriptions/createSubscriptionVersion) and [Update Subscription Version](/api-reference/subscriptions/updateSubscriptionVersion) endpoints for complete examples.