# Prorations Extension

Learn about the Prorations Extension and its methods.

## ID

`billing.prorations`

## Methods

### Prorate Items 

Calculates prorated amounts for subscription items when changes occur mid-billing period. The script receives the invoice items, then returns computed proration factors for each item.

|  |
| **Implementation types** | Script |
| **Optionality** | You must implement this method. |
| **Retry policy** | Stripe doesn’t retry failed requests. |

#### Parameters 

Properties of the `request` object Stripe passes to this method. Your method also receives `config` (your defined input type) and `context` (Stripe execution metadata).

| Name | Type | Nullable | **Description** |
| --- | --- | --- | --- |
| `items` | [Billing.Prorations.ProratableItem](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-billing-prorations-proratable-item)[] | No | The list of items that can have their proration factor and line item period modified. |

#### Return value 

| Name | Type | Nullable | **Description** |
| --- | --- | --- | --- |
| `items` | [Billing.Prorations.ItemWithProration](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-billing-prorations-item-with-proration)[] | No | The items with computed proration factors. |

#### Examples 

```typescript
export default class MyProrations implements Billing.Prorations<MyProrationsConfig> {
  prorateItems(
    request: Billing.Prorations.ProrateItemsInput,
    config: MyProrationsConfig,
    context: Context,
  ): Billing.Prorations.ProrateItemsResult {
    // Your implementation here
    return {
      items: {
        key: '',
        lineItemPeriod: {
          endDate: null,
          startDate: null,
        },
        prorationFactor: {},
      },
    };
  }
}
```

### Types

##### Billing.Currency 

```typescript
export type Currency = 'aed' | 'afn' | 'all' | 'amd' | 'ang' | 'aoa' | 'apt' | 'arb' | 'ars' | 'aud' | 'avax' | 'awg' | 'azn' | 'bam' | 'bbd' | 'bdt' | 'bgn' | 'bhd' | 'bif' | 'bmd' | 'bnb' | 'bnd' | 'bob' | 'bov' | 'brl' | 'bsd' | 'btc' | 'btn' | 'buidl' | 'bwp' | 'byn' | 'byr' | 'bzd' | 'cad' | 'cash' | 'cdf' | 'celo' | 'che' | 'chf' | 'chw' | 'clf' | 'clp' | 'cny' | 'cop' | 'cou' | 'crc' | 'cuc' | 'cup' | 'cve' | 'czk' | 'dai' | 'djf' | 'dkk' | 'dop' | 'dzd' | 'eek' | 'egp' | 'erd' | 'ern' | 'etb' | 'eth' | 'eur' | 'eurc' | 'fidd' | 'fjd' | 'fkp' | 'frxusd' | 'gbp' | 'gel' | 'ghc' | 'ghs' | 'gip' | 'gmd' | 'gnf' | 'gtq' | 'gyd' | 'hkd' | 'hnl' | 'hrk' | 'htg' | 'huf' | 'hype' | 'idr' | 'ils' | 'inr' | 'iqd' | 'irr' | 'isk' | 'jmd' | 'jod' | 'jpy' | 'kes' | 'kgs' | 'khr' | 'kmf' | 'kpw' | 'krw' | 'kwd' | 'kyd' | 'kzt' | 'lak' | 'lbp' | 'lkr' | 'lrd' | 'lsl' | 'ltl' | 'lvl' | 'lyd' | 'lzd' | 'm' | 'mad' | 'mdl' | 'mga' | 'mkd' | 'mmk' | 'mnt' | 'mon' | 'mop' | 'mro' | 'mru' | 'mur' | 'mvr' | 'mwk' | 'mxn' | 'mxnb' | 'mxv' | 'myr' | 'mzn' | 'nad' | 'ngn' | 'nio' | 'nok' | 'npr' | 'nzd' | 'omr' | 'open_usd' | 'ord' | 'ousd' | 'pab' | 'pen' | 'pgk' | 'php' | 'pkr' | 'pln' | 'pol' | 'pyg' | 'pyusd' | 'qar' | 'rd' | 're' | 'ron' | 'rsd' | 'rub' | 'rwf' | 'sar' | 'sbd' | 'scr' | 'sdg' | 'sek' | 'sgd' | 'shp' | 'sle' | 'sll' | 'sol' | 'sos' | 'srd' | 'ssp' | 'std' | 'stn' | 'sui' | 'svc' | 'syp' | 'szl' | 'thb' | 'tjs' | 'tmt' | 'tnd' | 'top' | 'trx' | 'try' | 'ttd' | 'twd' | 'tzs' | 'uah' | 'ugx' | 'usd' | 'usdb' | 'usdc' | 'usdg' | 'usdp' | 'usdsui' | 'usdt' | 'usn' | 'ustb' | 'uyi' | 'uyu' | 'uzs' | 'vef' | 'ves' | 'vnd' | 'vuv' | 'wst' | 'xaf' | 'xcd' | 'xcg' | 'xdc' | 'xeur' | 'xlm' | 'xof' | 'xpf' | 'xpl' | 'xusd' | 'yer' | 'zar' | 'zmk' | 'zmw' | 'zwd' | 'zwg' | 'zwl';
```

##### Billing.Prorations.CustomPricingUnitOverageRate 

| Name | Type | Nullable | **Description** |
| --- | --- | --- | --- |
| `customPricingUnit` | `string` | No |  |
| `id` | `string` | No |  |
| `metadata` | `Record<string, string>` | No |  |
| `rateCard` | [Billing.Prorations.RateCard](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-billing-prorations-rate-card) | No |  |
| `unitAmount` | [Decimal](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-decimal) | No |  |

##### Billing.Prorations.ItemType 

```typescript
type ItemType = 'credit' | 'debit';
```

##### Billing.Prorations.ItemWithProration 

An item with a computed proration factor.

| Name | Type | Nullable | **Description** |
| --- | --- | --- | --- |
| `key` | `string` | No | The unique identifier of the item, matching a key from the input. |
| `lineItemPeriod` | [Billing.TimeRange](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-billing-time-range) | No | The displayed period for the invoice line item. |
| `prorationFactor` | [Decimal](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-decimal) | No | The computed proration factor. Positive for charges, negative for credits. |

##### Billing.Prorations.LicenseFee 

| Name | Type | Nullable | **Description** |
| --- | --- | --- | --- |
| `currency` | [Billing.Currency](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-billing-currency) | No |  |
| `id` | `string` | No |  |
| `lookupKey` | `string` | Yes |  |
| `metadata` | `Record<string, string>` | No |  |
| `serviceInterval` | [Billing.Prorations.RecurringPriceInterval](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-billing-prorations-recurring-price-interval) | No |  |
| `serviceIntervalCount` | `number` | No |  |
| `tieringMode` | [Billing.Prorations.PricingTierMode](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-billing-prorations-pricing-tier-mode) | Yes |  |
| `tiers` | [Billing.Prorations.LicenseFeeTier](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-billing-prorations-license-fee-tier)[] | No |  |
| `unitAmount` | [Decimal](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-decimal) | Yes |  |

##### Billing.Prorations.LicenseFeeTier 

| Name | Type | Nullable | **Description** |
| --- | --- | --- | --- |
| `flatAmount` | [Decimal](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-decimal) | Yes |  |
| `unitAmount` | [Decimal](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-decimal) | Yes |  |
| `upTo` | [Decimal](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-decimal) | Yes |  |

##### Billing.Prorations.PreviousDebit 

Information about a previous debit that a credit item offsets.

| Name | Type | Nullable | **Description** |
| --- | --- | --- | --- |
| `servicePeriod` | [Billing.TimeRange](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-billing-time-range) | No | The service period of the corresponding debit. |

##### Billing.Prorations.Price 

| Name | Type | Nullable | **Description** |
| --- | --- | --- | --- |
| `billingScheme` | [Billing.Prorations.PricingScheme](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-billing-prorations-pricing-scheme) | No |  |
| `currency` | [Billing.Currency](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-billing-currency) | No |  |
| `id` | `string` | No |  |
| `metadata` | `Record<string, string>` | No |  |
| `product` | [Billing.Prorations.Product](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-billing-prorations-product) | No |  |
| `recurring` | [Billing.Prorations.RecurringPrice](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-billing-prorations-recurring-price) | Yes |  |
| `tiers` | [Billing.Prorations.PriceTier](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-billing-prorations-price-tier)[] | No |  |
| `tiersMode` | [Billing.Prorations.PricingTierMode](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-billing-prorations-pricing-tier-mode) | Yes |  |
| `type` | [Billing.Prorations.PriceType](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-billing-prorations-price-type) | No |  |
| `unitAmount` | [Decimal](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-decimal) | Yes |  |

##### Billing.Prorations.PriceTier 

| Name | Type | Nullable | **Description** |
| --- | --- | --- | --- |
| `flatAmount` | [Decimal](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-decimal) | Yes |  |
| `unitAmount` | [Decimal](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-decimal) | Yes |  |
| `upTo` | `number` | Yes |  |

##### Billing.Prorations.PriceType 

```typescript
type PriceType = 'one_time' | 'recurring';
```

##### Billing.Prorations.PricingScheme 

```typescript
type PricingScheme = 'per_unit' | 'tiered';
```

##### Billing.Prorations.PricingTierMode 

```typescript
type PricingTierMode = 'graduated' | 'volume';
```

##### Billing.Prorations.Product 

| Name | Type | Nullable | **Description** |
| --- | --- | --- | --- |
| `id` | `string` | No |  |
| `metadata` | `Record<string, string>` | No |  |
| `name` | `string` | No |  |

##### Billing.Prorations.ProratableItem 

```typescript
type ProratableItem = ({
        customPricingUnitOverageRate: CustomPricingUnitOverageRate;
        priceKind: 'customPricingUnitOverageRate';
    } | {
        licenseFee: LicenseFee;
        priceKind: 'licenseFee';
    } | {
        otherPriceKind: string;
        priceKind: 'other';
    } | {
        price: Price;
        priceKind: 'price';
    } | {
        priceKind: 'rateCardRate';
        rateCardRate: RateCardRate;
    } | { priceKind?: never }) & {
        correspondingDebit?: PreviousDebit;
        currentProrationFactor: Decimal;
        isProration: boolean;
        key: string;
        priceIntervalDuration: number;
        servicePeriod: TimeRange;
        type: ItemType;
    };
```

##### Billing.Prorations.RateCard 

| Name | Type | Nullable | **Description** |
| --- | --- | --- | --- |
| `currency` | [Billing.Currency](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-billing-currency) | No |  |
| `id` | `string` | No |  |

##### Billing.Prorations.RateCardRate 

| Name | Type | Nullable | **Description** |
| --- | --- | --- | --- |
| `id` | `string` | No |  |
| `metadata` | `Record<string, string>` | No |  |
| `rateCard` | [Billing.Prorations.RateCard](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-billing-prorations-rate-card) | No |  |
| `tieringMode` | [Billing.Prorations.PricingTierMode](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-billing-prorations-pricing-tier-mode) | Yes |  |
| `tiers` | [Billing.Prorations.RateCardRateTier](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-billing-prorations-rate-card-rate-tier)[] | No |  |
| `unitAmount` | [Decimal](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-decimal) | Yes |  |

##### Billing.Prorations.RateCardRateTier 

| Name | Type | Nullable | **Description** |
| --- | --- | --- | --- |
| `flatAmount` | [Decimal](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-decimal) | Yes |  |
| `unitAmount` | [Decimal](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-decimal) | Yes |  |
| `upTo` | [Decimal](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-decimal) | Yes |  |

##### Billing.Prorations.RecurringPrice 

| Name | Type | Nullable | **Description** |
| --- | --- | --- | --- |
| `interval` | [Billing.Prorations.RecurringPriceInterval](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-billing-prorations-recurring-price-interval) | No |  |
| `intervalCount` | `number` | No |  |
| `meter` | `string` | Yes |  |
| `usageType` | [Billing.Prorations.UsageType](https://docs.stripe.com/extensions/prorations-extension.md#prorate_items-billing-prorations-usage-type) | Yes |  |

##### Billing.Prorations.RecurringPriceInterval 

```typescript
type RecurringPriceInterval = 'day' | 'month' | 'week' | 'year';
```

##### Billing.Prorations.UsageType 

```typescript
type UsageType = 'licensed' | 'metered';
```

##### Billing.TimeRange 

Represents a time period with start and end dates.

| Name | Type | Nullable | **Description** |
| --- | --- | --- | --- |
| `endDate` | `Date` | No | The ending date of the range. |
| `startDate` | `Date` | No | The beginning date of the range. |

##### Decimal 

Arbitrary-precision decimal type for billing calculations.

```typescript
export interface Decimal {
}
```