# Recurring Billing Item Handling Extension

Learn about the Recurring Billing Item Handling Extension and its methods.

## ID

`billing.recurring_billing_item_handling`

## Methods

### Before Item Creation 

Runs before invoice items are created. Decides whether each item should be created or skipped.

|  |
| **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.RecurringBillingItemHandling.Item`](https://docs.stripe.com/extensions/recurring-billing-item-handling-extension.md#before_item_creation-billing-recurring-billing-item-handling-item) | No | The list of items to evaluate for creation. |

#### Return value 

| Name | Type | Nullable | **Description** |
| --- | --- | --- | --- |
| `items` | [`Billing.RecurringBillingItemHandling.ItemWithCreationStrategy`](https://docs.stripe.com/extensions/recurring-billing-item-handling-extension.md#before_item_creation-billing-recurring-billing-item-handling-item-with-creation-strategy) | No | The items with their creation strategies. |

#### Examples 

```typescript
export default class MyRecurringBillingItemHandling implements Billing.RecurringBillingItemHandling<MyRecurringBillingItemHandlingConfig> {
  beforeItemCreation(
    request: Billing.RecurringBillingItemHandling.BeforeItemCreationInput,
    config: MyRecurringBillingItemHandlingConfig,
    context: Context,
  ): Billing.RecurringBillingItemHandling.BeforeItemCreationResult {
    // Your implementation here
    return {
      items: 'other',
    };
  }
}
```

### Types

##### Billing.RecurringBillingItemHandling.Item 

```typescript
type Item = ({
        customPricingUnitOverageRate: CustomPricingUnitOverageRate;
        priceKind: 'customPricingUnitOverageRate';
    } | {
        licenseFee: LicenseFee;
        priceKind: 'licenseFee';
    } | {
        otherPriceKind: string;
        priceKind: 'other';
    } | {
        price: Price;
        priceKind: 'price';
    } | {
        priceKind: 'rateCardRate';
        rateCardRate: RateCardRate;
    }) & {
        isProration: boolean;
        key: string;
        prorationFactor: Decimal;
        servicePeriod: AnyTimeRange;
        type: ItemType;
    };
```

##### Billing.RecurringBillingItemHandling.ItemWithCreationStrategy 

```typescript
type ItemWithCreationStrategy = ({
        creationStrategy: 'other';
        otherCreationStrategy: string;
    } | { creationStrategy: 'doNotCreate' } | { creationStrategy: 'invoice' }) & { key: string };
```

### Filter Items 

Runs before invoices are created. Decides which items to include on the invoice. Items not included are deferred as pending invoice items.

|  |
| **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.RecurringBillingItemHandling.Item`](https://docs.stripe.com/extensions/recurring-billing-item-handling-extension.md#filter_items-billing-recurring-billing-item-handling-item) | No | The list of items to evaluate for inclusion on the invoice. |

#### Return value 

| Name | Type | Nullable | **Description** |
| --- | --- | --- | --- |
| `items` | [`Billing.RecurringBillingItemHandling.ItemToInvoice`](https://docs.stripe.com/extensions/recurring-billing-item-handling-extension.md#filter_items-billing-recurring-billing-item-handling-item-to-invoice) | No | The items to include on the invoice. |

#### Examples 

```typescript
export default class MyRecurringBillingItemHandling implements Billing.RecurringBillingItemHandling<MyRecurringBillingItemHandlingConfig> {
  filterItems(
    request: Billing.RecurringBillingItemHandling.FilterItemsInput,
    config: MyRecurringBillingItemHandlingConfig,
    context: Context,
  ): Billing.RecurringBillingItemHandling.FilterItemsResult {
    // Your implementation here
    return {
      items: {
        key: '',
      },
    };
  }
}
```

### Types

##### Billing.RecurringBillingItemHandling.Item 

```typescript
type Item = ({
        customPricingUnitOverageRate: CustomPricingUnitOverageRate;
        priceKind: 'customPricingUnitOverageRate';
    } | {
        licenseFee: LicenseFee;
        priceKind: 'licenseFee';
    } | {
        otherPriceKind: string;
        priceKind: 'other';
    } | {
        price: Price;
        priceKind: 'price';
    } | {
        priceKind: 'rateCardRate';
        rateCardRate: RateCardRate;
    }) & {
        isProration: boolean;
        key: string;
        prorationFactor: Decimal;
        servicePeriod: AnyTimeRange;
        type: ItemType;
    };
```

##### Billing.RecurringBillingItemHandling.ItemToInvoice 

An item selected for inclusion on the invoice.

| Name | Type | Nullable | **Description** |
| --- | --- | --- | --- |
| `key` | `string` | No | The unique identifier of the item, matching a key from the input. |

### Group Items 

Runs before invoices are created. Decides how items are grouped across one or more invoices.

|  |
| **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.RecurringBillingItemHandling.Item`](https://docs.stripe.com/extensions/recurring-billing-item-handling-extension.md#group_items-billing-recurring-billing-item-handling-item) | No | The list of items to group across invoices. |

#### Return value 

| Name | Type | Nullable | **Description** |
| --- | --- | --- | --- |
| `groups` | [`Billing.RecurringBillingItemHandling.ItemGroup`](https://docs.stripe.com/extensions/recurring-billing-item-handling-extension.md#group_items-billing-recurring-billing-item-handling-item-group) | No | The groups of items, each corresponding to a separate invoice. |

#### Examples 

```typescript
export default class MyRecurringBillingItemHandling implements Billing.RecurringBillingItemHandling<MyRecurringBillingItemHandlingConfig> {
  groupItems(
    request: Billing.RecurringBillingItemHandling.GroupItemsInput,
    config: MyRecurringBillingItemHandlingConfig,
    context: Context,
  ): Billing.RecurringBillingItemHandling.GroupItemsResult {
    // Your implementation here
    return {
      groups: {
        items: {
          key: '',
        },
        setsLatestInvoice: false,
      },
    };
  }
}
```

### Types

##### Billing.RecurringBillingItemHandling.GroupedItem 

An item assigned to a group.

| Name | Type | Nullable | **Description** |
| --- | --- | --- | --- |
| `key` | `string` | No | The unique identifier of the item, matching a key from the input. |

##### Billing.RecurringBillingItemHandling.Item 

```typescript
type Item = ({
        customPricingUnitOverageRate: CustomPricingUnitOverageRate;
        priceKind: 'customPricingUnitOverageRate';
    } | {
        licenseFee: LicenseFee;
        priceKind: 'licenseFee';
    } | {
        otherPriceKind: string;
        priceKind: 'other';
    } | {
        price: Price;
        priceKind: 'price';
    } | {
        priceKind: 'rateCardRate';
        rateCardRate: RateCardRate;
    }) & {
        isProration: boolean;
        key: string;
        prorationFactor: Decimal;
        servicePeriod: AnyTimeRange;
        type: ItemType;
    };
```

##### Billing.RecurringBillingItemHandling.ItemGroup 

A group of items to place on a single invoice.

| Name | Type | Nullable | **Description** |
| --- | --- | --- | --- |
| `items` | [`Billing.RecurringBillingItemHandling.GroupedItem`](https://docs.stripe.com/extensions/recurring-billing-item-handling-extension.md#group_items-billing-recurring-billing-item-handling-grouped-item) | No | The items in this group. |
| `setsLatestInvoice` | `boolean` | No | Whether this group sets the latest invoice reference on the subscription. |