---
isPrivate: true
title: Custom Costs
description: Datadog, the leading service for cloud-scale monitoring.
breadcrumbs: Docs > Cloud Cost Management > Setup > Custom Costs
---

# Custom Costs

{% callout %}
##### Join the Preview!

Custom Costs are in Preview.
{% /callout %}

## Overview{% #overview %}

Custom Costs allow you to upload *any cost data source* to Datadog, so that you can understand the total cost of your services.

Custom Costs accepts costs in pre-defined file structures (CSV or JSON). These files are aligned with the [FinOps FOCUS specification](https://focus.finops.org/#specification), and you can upload multiple files in either format. For example, you can upload a mix of CSV or JSON files as desired with 1+ line items (rows for CSV or objects for JSON).

All line items must meet the following requirements and include the properties below:

- All column names (CSV), property names (JSON), and values are UTF-8 encoded.
- All required column names (CSV) or property names (JSON) are [PascalCased](https://en.wiktionary.org/wiki/Pascal_case). For example, you must use `"ProviderName"`, not `"providername"` or `"ProviderNAME"`.
- All column names (CSV) and values or property names (JSON) and values have a maximum of 1,000 characters.
- NULL or blank ("") parameter values are not accepted.
- Cost data that contains future dates are not accepted.

Additionally, all dates are transformed into UTC timestamps. For example, "2024-01-01" becomes "2024-01-01 00:00:00".

## Setup{% #setup %}

To use Custom Costs in Datadog, you must [configure Cloud Cost Management](https://docs.datadoghq.com/cloud_cost_management.md) for either AWS, Azure, Google Cloud, or Oracle Cloud, even if your custom costs are not related to any of these cloud providers. This configuration is required to enable the Custom Costs feature.

### Collect the required fields{% #collect-the-required-fields %}

| Parameter           | Description                                           | Valid example  | Invalid example     | Additional Requirements                                               |
| ------------------- | ----------------------------------------------------- | -------------- | ------------------- | --------------------------------------------------------------------- |
| `ProviderName`      | The service being consumed.                           | Snowflake      | "" or NULL          |
| `ChargeDescription` | Identifies what aspect of a service is being charged. | Database Costs | "" or NULL          |
| `ChargePeriodStart` | Start day of a charge.                                | 2023-09-01     | 2023-01-01 12:34:56 | Formatted YYYY-MM-DD, where `ChargePeriodStart` <= `ChargePeriodEnd`. |
| `ChargePeriodEnd`   | Last day of a charge (inclusive).                     | 2023-09-30     | 01/01/2023          | Formatted YYYY-MM-DD.                                                 |
| `BilledCost`        | The amount being charged.                             | 10.00          | NaN                 | Number-based decimal.                                                 |
| `BillingCurrency`   | Currency of billed cost.                              | USD            | EUR                 | Must be USD.                                                          |

### Create a CSV or JSON file with required fields{% #create-a-csv-or-json-file-with-required-fields %}

You can upload multiple CSV and JSON files, in either or both formats. Ensure that you don't upload the same file twice, since the cost will appear as doubled in the product.

{% tab title="CSV" %}
The required fields must appear as columns in your CSV in the order listed above. You need to use a comma (`,`) as a separator for your CSV.

Example of a valid CSV:

| ProviderName | ChargeDescription | ChargePeriodStart | ChargePeriodEnd | BilledCost | BillingCurrency |
| ------------ | ----------------- | ----------------- | --------------- | ---------- | --------------- |
| GitHub       | User Costs        | 2023-01-01        | 2023-01-31      | 300.00     | USD             |

Example of an invalid CSV (`ChargePeriodStart` is listed before `ChargeDescription`):

| ProviderName | ChargePeriodStart | ChargeDescription | ChargePeriodEnd | BilledCost | BillingCurrency |
| ------------ | ----------------- | ----------------- | --------------- | ---------- | --------------- |
| GitHub       | 2023-01-01        | User Costs        | 2023-01-31      | 300.00     | USD             |

{% /tab %}

{% tab title="JSON" %}
The required fields must appear within all objects of a JSON file adhering to the [ECMA-404 standard](https://www.ecma-international.org/publications-and-standards/standards/ecma-404/) and all objects must be encapsulated by an array.

Example of a valid JSON file:

```json
[
    {
        "ProviderName": "Zoom",
        "ChargeDescription": "Video Usage",
        "ChargePeriodStart": "2023-01-01",
        "ChargePeriodEnd": "2023-12-31",
        "BilledCost": 100.00,
        "BillingCurrency": "USD"
    }
]
```

Example of an invalid JSON file:

```json
[
    {
        "providername": "Zoom",
        "chargedescription": "Video Usage",
        "chargeperiodstart": "2023-01-01",
        "chargeperiodend": "2023-12-31",
        "billedcost": 100.00,
        "billingcurrency": "USD"
    }
]
```

{% /tab %}

### Add optional tags{% #add-optional-tags %}

You can optionally add any number of tags to CSV or JSON files to allocate costs *after* the required fields as additional columns.

{% tab title="CSV" %}
For a CSV file, add a column per tag.

Example of a valid CSV file:

| ProviderName | ChargePeriodStart | ChargeDescription | ChargePeriodEnd | BilledCost | BillingCurrency | team | service |
| ------------ | ----------------- | ----------------- | --------------- | ---------- | --------------- | ---- | ------- |
| GitHub       | 2023-01-01        | User Costs        | 2023-01-31      | 300.00     | USD             | web  | ops     |

In this example, the `team` and `service` columns are added after the `BillingCurrency` column, and appears as tags on this cost.
{% /tab %}

{% tab title="JSON" %}
For a JSON file, add a `Tags` object property to encapsulate any desired tags associated to this cost.

Example of a valid JSON file:

```json
[
    {
        "ProviderName": "Zoom",
        "ChargeDescription": "Video Usage",
        "ChargePeriodStart": "2023-01-01",
        "ChargePeriodEnd": "2023-12-31",
        "BilledCost": 100.00,
        "BillingCurrency": "USD",
        "Tags": {
            "team": "web",
            "service": "ops"
        }
    }
]
```

In this example, an additional `Tags` object property has been added with two key-value pairs to allocate `team` and `service` tags to this cost.
{% /tab %}

### Configure Custom Costs{% #configure-custom-costs %}

After your data is formatted to the requirements above, upload your CSV and JSON files to Cloud Cost Management on the [**Custom Costs Files** page](https://app.datadoghq.com/cost/settings/cost-files) or programmatically by using the API.

In Datadog:

1. Navigate to [**Cloud Cost > Settings > Custom Costs**](https://app.datadoghq.com/cost/settings/cost-files).

1. Click the **+ Upload Costs** button.

   {% image
      source="https://docs.dd-static.net/images/cloud_cost/upload_file.9f0128207666fe1246181574a0adfe49.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/cloud_cost/upload_file.9f0128207666fe1246181574a0adfe49.png?auto=format&fit=max&w=850&dpr=2 2x"
      alt="Upload a CSV or JSON file to Datadog" /%}

To send a file programmatically, use the `PUT api/v2/cost/custom_costs` API endpoint.

For example, using cURL:

```
curl -L -X PUT "" \
-H "Content-Type: multipart/form-data" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-F "file=${file};type=text/json"
```

To send the content of the file programmatically, use the `PUT api/v2/cost/custom_costs` endpoint.

For example, using cURL:

```
curl -L -X PUT "" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-d '${file_content}'
```

Cost data appears in Datadog after 24 hours.

## Cost metric types{% #cost-metric-types %}

You can visualize your ingested data using the following cost types:

| Cost Type               | Description                                                              |
| ----------------------- | ------------------------------------------------------------------------ |
| `custom.cost.amortized` | Total cost of resources accrued over an interval.                        |
| `custom.cost.basis`     | Total cost of resources allocated at the time of usage over an interval. |

All costs submitted to Custom Costs appear in these metrics. For example, if a $4 purchase was made on September 1, over the September 1-4 period, the following costs are attributed to each metric:

| Days        | `custom.cost.basis` | `custom.cost.amortized` |
| ----------- | ------------------- | ----------------------- |
| September 1 | $4                  | $1                      |
| September 2 | -                   | $1                      |
| September 3 | -                   | $1                      |
| September 4 | -                   | $1                      |

## Use Custom Costs data{% #use-custom-costs-data %}

You can view custom costs data on the [**Cloud Cost Explorer** page](https://app.datadoghq.com/cost/explorer), the [Cloud Cost Tag Explorer](https://app.datadoghq.com/cost/tags?cloud=custom), and in [dashboards](https://docs.datadoghq.com/dashboards.md), [notebooks](https://docs.datadoghq.com/notebooks.md), or [monitors](https://docs.datadoghq.com/monitors/types/cloud_cost.md). You can also combine Custom Cost metrics with other cloud cost metrics or observability metrics.

## Further reading{% #further-reading %}

- [Cloud Cost Management](https://docs.datadoghq.com/cloud_cost_management.md)
- [Gain insights into your AWS bill](https://docs.datadoghq.com/cloud_cost_management/setup/aws.md)
- [Gain insights into your Azure bill](https://docs.datadoghq.com/cloud_cost_management/setup/azure.md)
- [Gain insights into your Google Cloud bill](https://docs.datadoghq.com/cloud_cost_management/setup/google_cloud.md)
- [Gain insights into your Oracle bill](https://docs.datadoghq.com/cloud_cost_management/setup/oracle.md)