# Import unbilled charges

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


[Idempotency Supported](/docs/api/idempotency)

Imports one or more [unbilled charges](/docs/api/unbilled_charges) into an existing subscription. Use this operation to add usage-based or other unbilled charges recorded in external systems to the subscription.

### Prerequisites & Constraints

If you are trying to use this operation on your live site, ensure you have requested [Chargebee Support](https://www.chargebee.com/docs/billing/2.0/kb/getting-started/how-to-contact-chargebees-support-team?utm_source=docs_api&utm_medium=content&utm_campaign=support) to enable it, otherwise the API will return an "API not enabled" error.

### Impacts

**

Invoicing

**

-   Unbilled charges on the subscription are automatically invoiced on the next renewal.
-   You can also invoice unbilled charges on-demand using the [Create an invoice for unbilled charges API](/docs/api/unbilled_charges/create-an-invoice-for-unbilled-charges).

**

Accounting Integrations

**

Imported unbilled charges will not sync with your [accounting integration](https://www.chargebee.com/docs/billing/2.0/integrations/finance-integration-index) until they are invoiced.

## Sample Request

#### cURL

```bash
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdvHJGn/import_unbilled_charges \
     -X POST  \
     -u {site_api_key}:\
     -d "unbilled_charges[date_from][0]"=1517490271 \
     -d "unbilled_charges[date_to][0]"=1519909471 \
     -d "unbilled_charges[description][0]"="No Trial" \
     -d "unbilled_charges[unit_amount][0]"=4900 \
     -d "unbilled_charges[quantity][0]"=1 \
     -d "unbilled_charges[entity_id][0]"="no-trial" \
     -d "unbilled_charges[entity_type][0]"="PLAN_ITEM_PRICE"
```

#### .NET

```dotnet
using ChargeBee.Api;
using ChargeBee.Models;

ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Subscription.ImportUnbilledCharges("__test__8asukSOXdvHJGn")
		.UnbilledChargeDateFrom(0, 1517490271)
		.UnbilledChargeDateTo(0, 1519909471)
		.UnbilledChargeDescription(0, "No Trial")
		.UnbilledChargeUnitAmount(0, 4900)
		.UnbilledChargeQuantity(0, 1)
		.UnbilledChargeEntityId(0, "no-trial")
		.UnbilledChargeEntityType(0, UnbilledCharge.EntityTypeEnum.PlanItemPrice)
		.Request();

List<UnbilledCharge> unbilledCharges = result.UnbilledCharges;
```

#### Go

```go
package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    subscriptionAction "github.com/chargebee/chargebee-go/v3/actions/subscription"
    "github.com/chargebee/chargebee-go/v3/models/subscription"
    unbilledChargeEnum "github.com/chargebee/chargebee-go/v3/models/unbilledcharge/enum"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := subscriptionAction.ImportUnbilledCharges("__test__8asukSOXdvHJGn", &subscription.ImportUnbilledChargesRequestParams{
        UnbilledCharges : []*subscription.ImportUnbilledChargesUnbilledChargeParams{
            {
                DateFrom : chargebee.Int64(1517490271),
                DateTo : chargebee.Int64(1519909471),
                Description : "No Trial",
                UnitAmount : chargebee.Int64(4900),
                Quantity : chargebee.Int32(1),
                EntityId : "no-trial",
                EntityType : unbilledChargeEnum.EntityTypePlanItemPrice,
            },
        },
    }).Request()
    if err != nil {
        fmt.Println(err)
    } else {
        UnbilledCharges := res.UnbilledCharges
    }
}
```

#### Go

```go
package main

import (
  "fmt"
  "github.com/chargebee/chargebee-go/v4"
)

func main() {
  config := &chargebee.ClientConfig{
    SiteName: "{site}",
    ApiKey: "{site_api_key}",
  }    
  client := chargebee.NewClient(config)
  req := &chargebee.SubscriptionImportUnbilledChargesRequest{
    UnbilledCharges : []*chargebee.SubscriptionImportUnbilledChargesUnbilledCharge{
        {
            DateFrom : chargebee.Int64(1517490271),
            DateTo : chargebee.Int64(1519909471),
            Description : "No Trial",
            UnitAmount : chargebee.Int64(4900),
            Quantity : chargebee.Int32(1),
            EntityId : "no-trial",
            EntityType : chargebee.UnbilledChargeEntityTypePlanItemPrice,
        },
    },
}
  res, err := client.Subscription.ImportUnbilledCharges("__test__8asukSOXdvHJGn", req)
      if err != nil {
        fmt.Println(err)
    } else {
        UnbilledCharges := res.UnbilledCharges
    }
}
```

#### Java

```java
import com.chargebee.*;
import com.chargebee.ListResult;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
import java.io.IOException;
import java.util.List;
import java.sql.Timestamp;

public class Sample {

    public static void main(String args[]) throws IOException, Exception {
        Environment.configure("{site}", "{site_api_key}");
        Result result = Subscription.importUnbilledCharges("__test__8asukSOXdvHJGn")
            .unbilledChargeDateFrom(0, new Timestamp(1517490271L * 1000))
            .unbilledChargeDateTo(0, new Timestamp(1519909471L * 1000))
            .unbilledChargeDescription(0, "No Trial")
            .unbilledChargeUnitAmount(0, 4900L)
            .unbilledChargeQuantity(0, 1)
            .unbilledChargeEntityId(0, "no-trial")
            .unbilledChargeEntityType(0, UnbilledCharge.EntityType.PLAN_ITEM_PRICE)
            .request();

        List<UnbilledCharge> unbilledCharges = result.unbilledCharges();
    }
}
```

#### Java

```java
import com.chargebee.v4.client.ChargebeeClient;
import com.chargebee.v4.models.subscription.params.SubscriptionImportUnbilledChargesParams;
import com.chargebee.v4.models.subscription.responses.SubscriptionImportUnbilledChargesResponse;
import com.chargebee.v4.models.unbilledCharge.UnbilledCharge;
import java.sql.Timestamp;
import java.util.List;

public class SubscriptionImportUnbilledCharges {

    public static void main(String[] args) {
        ChargebeeClient client = ChargebeeClient.builder()
            .apiKey("{site_api_key}")
            .siteName("{site}")
            .build();

        SubscriptionImportUnbilledChargesParams.UnbilledChargesParams unbilledCharge0 =
            SubscriptionImportUnbilledChargesParams.UnbilledChargesParams.builder()
                .dateFrom(new Timestamp(1517490271L * 1000))
                .dateTo(new Timestamp(1519909471L * 1000))
                .description("No Trial")
                .unitAmount(4900L)
                .quantity(1)
                .entityId("no-trial")
                .entityType(SubscriptionImportUnbilledChargesParams.UnbilledChargesParams.EntityType.PLAN_ITEM_PRICE)
                .build();

        List<SubscriptionImportUnbilledChargesParams.UnbilledChargesParams> unbilledChargesList =
            List.of(unbilledCharge0);

        SubscriptionImportUnbilledChargesParams params = SubscriptionImportUnbilledChargesParams.builder()
            .unbilledCharges(unbilledChargesList)
            .build();

        SubscriptionImportUnbilledChargesResponse response = client
            .subscriptions()
            .importUnbilledCharges("__test__8asukSOXdvHJGn", params);

        List<UnbilledCharge> unbilledCharges = response.getUnbilledCharges();
    }
}
```

#### Node.js

```node
import Chargebee from "chargebee";

const chargebee = new Chargebee({
    site: "{site}",
    apiKey: "{site_api_key}",
});

try {
    const result = await chargebee.subscription.importUnbilledCharges("__test__8asukSOXdvHJGn", {
        unbilled_charges: [
            {
                date_from: 1517490271,
                date_to: 1519909471,
                description: "No Trial",
                unit_amount: 4900,
                quantity: 1,
                entity_id: "no-trial",
                entity_type: "plan_item_price"
            }
        ]
    });

    console.log(result);
    const unbilledCharges = result.unbilled_charges;
} catch (err) {
    console.log(err);
}
```

#### PHP

```php
<?php

require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
    "site" => "{site}",
    "apiKey" => "{site_api_key}",
]);
$result = $chargebee->subscription()->importUnbilledCharges("__test__8asukSOXdvHJGn", [
    "unbilled_charges" => [
        [
            "date_from" => 1517490271,
            "date_to" => 1519909471,
            "description" => "No Trial",
            "unit_amount" => 4900,
            "quantity" => 1,
            "entity_id" => "no-trial",
            "entity_type" => "plan_item_price"
        ]
    ]
]);
$unbilledCharges = $result->unbilled_charges;
```

#### Python

```python
import chargebee
from chargebee import Chargebee

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
response = cb_client.Subscription.import_unbilled_charges("__test__8asukSOXdvHJGn",
    cb_client.Subscription.ImportUnbilledChargesParams(
        unbilled_charges=[
            cb_client.Subscription.ImportUnbilledChargesUnbilledChargeParams(
              date_from=1517490271,
              date_to=1519909471,
              description="No Trial",
              unit_amount=4900,
              quantity=1,
              entity_id="no-trial",
              entity_type=chargebee.UnbilledCharge.EntityType.PLAN_ITEM_PRICE
            )
        ]
    )
)
unbilled_charges = response.unbilled_charges
```

#### Ruby

```ruby
require 'chargebee'

ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")

result = ChargeBee::Subscription.import_unbilled_charges("__test__8asukSOXdvHJGn",{
  :unbilled_charges => [
    {
      :date_from => 1517490271,
      :date_to => 1519909471,
      :description => "No Trial",
      :unit_amount => 4900,
      :quantity => 1,
      :entity_id => "no-trial",
      :entity_type => "PLAN_ITEM_PRICE"
    }
  ]
})

unbilled_charges = result.unbilled_charges
```

## Sample Response

```json
{
  "unbilled_charges": [
    {
      "id": "li___dev__8asq9TI2eBrV1",
      "customer_id": "active",
      "subscription_id": "active",
      "date_from": 1517490271,
      "date_to": 1519909471,
      "unit_amount": 4900,
      "pricing_model": "per_unit",
      "quantity": 1,
      "amount": 4900,
      "discount_amount": 0,
      "description": "No Trial",
      "entity_id": "no-trial",
      "is_voided": false,
      "updated_at": 1663736354,
      "deleted": false,
      "object": "unbilled_charge",
      "entity_type": "plan",
      "currency_code": "USD"
    },
    {..}
  ]
}
```

## URL Format

**POST** https://[site].chargebee.com/api/v2/subscriptions/{subscription-id}/import_unbilled_charges

## Input Parameters

- `unbilled_charges` (optional, array)
  Parameters for unbilled\_charges
  - `id` (optional, string, max chars=40)
    Uniquely identifies an unbilled charge.
  - `date_from` (required, timestamp(UTC) in seconds)
    Start date of this charge.
  - `date_to` (required, timestamp(UTC) in seconds)
    End date of this charge.
  - `entity_type` (required, enumerated string)
    Specifies the modelled entity this line item is based on.
    Possible enum values:
      - `adhoc`
        Indicates that this lineitem is not modelled. i.e created adhoc. So the 'entity\_id' attribute will be null in this case
      - `plan_item_price`
        Indicates that this line item is based on plan Item Price
      - `addon_item_price`
        Indicates that this line item is based on addon Item Price
      - `charge_item_price`
        Indicates that this line item is based on charge Item Price
  - `entity_id` (optional, string, max chars=100)
    The identifier of the modelled entity this charge is based on. Will be null for 'adhoc' entity type.
  - `description` (optional, string, max chars=250)
    Detailed description about this charge.
  - `unit_amount` (optional, in cents)
    Unit amount of the charge item.
  - `quantity` (optional, integer)
    Quantity of the item which is represented by this charge.
  - `amount` (optional, in cents)
    Total amount of this charge. Typically equals to unit amount x quantity.
  - `unit_amount_in_decimal` (optional, string, max chars=39)
    The decimal representation of the amount for the charge, in major units of the currency. Typically equals to `unit_amount_in_decimal` x `quantity_in_decimal`. Returned when [multi-decimal pricing](/docs/api/currencies) is enabled.
  - `quantity_in_decimal` (optional, string, max chars=33)
    The decimal representation of the quantity of this entity. Returned when the entity is quantity-based and [multi-decimal pricing](/docs/api/currencies) is enabled.
  - `amount_in_decimal` (optional, string, max chars=39)
    The decimal representation of the unit amount for the entity. The value is in major units of the currency. Returned when the entity is quantity-based and [multi-decimal pricing](/docs/api/currencies) is enabled.
  - `discount_amount` (optional, in cents)
    Total discounts for this charge.
  - `use_for_proration` (optional, boolean)
    If the unbilled charge falls within the subscription's current term it will be used for proration.
  - `is_advance_charge` (optional, boolean)
    The value of this parameter will be true if it is a recurring unbilled charge for a future term.

- `discounts` (optional, array)
  Parameters for discounts
  - `unbilled_charge_id` (optional, string, max chars=40)
    Uniquely identifies an unbilled charge.
  - `entity_type` (optional, enumerated string)
    The type of deduction and the amount to which it is applied.
    Possible enum values:
      - `item_level_coupon`
        The deduction is due to a coupon applied to line item. The coupon `id` is passed as `entity_id` .
      - `document_level_coupon`
        The deduction is due to a coupon applied to the invoice `sub_total`. The coupon id is passed as `entity_id` .
      - `item_level_discount`
        The deduction is due to a [discount](/docs/api/discounts) applied to a line item of the invoice. The discount `id` is available as the `entity_id`.
      - `document_level_discount`
        The deduction is due to a [discount](/docs/api/discounts) applied to the invoice `sub_total`. The discount `id` is available as the `entity_id`.
  - `entity_id` (optional, string, max chars=100)
    When the deduction is due to a `coupon` , then this is the `id` of the coupon. Is required when `discounts[entity_type]` is `item_level_coupon` or `document_level_coupon` .
  - `description` (optional, string, max chars=250)
    Description for this deduction.
  - `amount` (required, in cents)
    The amount deducted. The format of this value depends on the [kind of currency](/docs/api/currencies) .

- `tiers` (optional, array)
  Parameters for tiers
  - `unbilled_charge_id` (required, string, max chars=40)
    Uniquely identifies an unbilled charge.
  - `starting_unit` (optional, integer)
    The lower limit of a range of units for the tier
  - `ending_unit` (optional, integer)
    The upper limit of a range of units for the tier
  - `quantity_used` (optional, integer)
    The number of units purchased in a range.
  - `unit_amount` (optional, in cents)
    The price of the tier if the charge model is a `stairtstep` pricing , or the price of each unit in the tier if the charge model is `tiered` /`volume` pricing.
  - `starting_unit_in_decimal` (optional, string, max chars=33)
    The decimal representation of the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as `ending_unit_in_decimal` of the next lower tier. Returned only when the `line_items.pricing_model` is `tiered` , `volume` or `stairstep` and [multi-decimal pricing](/docs/api/currencies) is enabled.
  - `ending_unit_in_decimal` (optional, string, max chars=33)
    The decimal representation of the highest value of quantity in this tier. This attribute is not applicable for the highest tier. For all other tiers, it must be equal to the `starting_unit_in_decimal` of the next higher tier. Returned only when the `line_items.pricing_model` is `tiered` , `volume` or stairstep and [multi-decimal pricing](/docs/api/currencies) is enabled.
  - `quantity_used_in_decimal` (optional, string, max chars=33)
    The decimal representation of the quantity purchased from this tier. Returned when the `line_item` is quantity-based and [multi-decimal pricing](/docs/api/currencies) is enabled.
  - `unit_amount_in_decimal` (optional, string, max chars=40)
    The decimal representation of the per-unit price for the tier when the `pricing_model` is `tiered` or `volume`. When the `pricing_model` is `stairstep` , it is the decimal representation of the total price for `line_item`. The value is in major units of the currency. Returned when the `line_item` is quantity-based and [multi-decimal pricing](/docs/api/currencies) is enabled.

## Returns

- `unbilled_charges` (always returned)
  Resource object representing unbilled\_charge