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

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

##### 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 {
}
```