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