> ## Documentation Index
> Fetch the complete documentation index at: https://docs.costory.io/llms.txt
> Use this file to discover all available pages before exploring further.

# BytePlus Billing Setup

> Connect BytePlus Platform billing to Costory with an IAM Access Key and import account bill details, including Seedance and ModelArk, into Explorer.

BytePlus account spend sits on a separate bill from AWS, GCP, and Azure. Connect with an **IAM Access Key ID** and **Secret Access Key** so bill details land in Explorer (Costory's main interface for exploring cloud costs across all connected providers.) with your other [billing datasources](https://docs.costory.io/setup/billing).

This connector imports **ListBillDetail** for the whole BytePlus account. That includes Seedance and other ModelArk products, plus the rest of the account bill. Costory stores it as a billing datasource, the same as other SaaS billing sources.

> [!NOTE]
>
> Use a BytePlus **IAM Access Key**, not a ModelArk or Seedance API key. Attach **BillingCenterReadOnlyAccess**. `ArkReadOnlyAccess` cannot call ListBillDetail. Costory currently ingests the **whole BytePlus account bill**. There is no Seedance product-code filter yet.

> [tab] Manual setup
>
> **1. Create an IAM Access Key**
>
> In [BytePlus Console > IAM > Key Management](https://console.byteplus.com/), create an **IAM Access Key ID** and **Secret Access Key**. Copy the secret immediately. It is shown once.
>
> Do **not** use a ModelArk or Seedance API key (Bearer). Costory signs Billing OpenAPI with HMAC-SHA256 (`service=billing`).
>
> **2. Attach BillingCenterReadOnlyAccess**
>
> Attach **BillingCenterReadOnlyAccess** to that IAM user. Main-account keys can call billing by default. IAM-user keys need that policy. `ArkReadOnlyAccess` is not enough.
>
> **3. Connect in Costory**
>
> Go to [Integrations](https://app.costory.io/integration), click **+ Add integration**, then choose **BytePlus Platform** under **Billing**. The connect URL is `/integration/new/seedance-ai/billing`.&#x20;
>
> **4. Enter connection details**
>
> Fill **Connection name** (default **BytePlus Platform**), **Access Key ID**, and **Secret Access Key**.
>
> **Region** is optional. It is the HMAC signing region, not a hostname. Leave it empty for `ap-singapore-1`. The billing host stays `billing.byteplusapi.com` (International). A wrong signing region typically fails as `SignatureDoesNotMatch`.
>
> **Start date** is optional. Leave it empty to use Costory's default lookback. The BytePlus API cap is the last **24 months**, earliest **2022-01**.
>
> **5. Validate, then save**
>
> Click **Validate**. Costory calls [ListBillDetail](https://docs.byteplus.com/en/docs/byteplus-platform/ListBillDetail) with a signed HMAC request. **Save** stays disabled until the Access Key can read bill details. An empty current-month list is still success. If this is the only billing source and it is demo data, Costory asks you to confirm before replacing it.
>
> On first sync, Costory backfills up to **24 months** of bill details (earliest 2022-01), depending on what BytePlus retains. New data then follows the usual [data refresh](https://docs.costory.io/docs/data-refresh.md) cadence. SaaS sources typically appear in about **10 minutes**.

> [tab] Terraform
>
> Not supported yet.

## Field reference

| Field | Required | Description |
| - | - | - |
| **Connection name** | Yes | Label in **Integrations**. |
| **Access Key ID** | Yes | BytePlus IAM Access Key ID. Not a ModelArk API key. Stored in Costory's secret manager. |
| **Secret Access Key** | Yes | BytePlus IAM Secret Access Key. Stored in Costory's secret manager. |
| **Region** | No | HMAC signing region. Leave empty for `ap-singapore-1`. Host stays `billing.byteplusapi.com`. |
| **Start date** | No | Optional start of the first sync. Leave empty for the default lookback (API cap: 24 months). |

## What Costory includes

Costory pulls [ListBillDetail](https://docs.byteplus.com/en/docs/byteplus-platform/ListBillDetail) and maps it into Standard Columns (Costory's unified billing schema: the same dimensions everywhere (Provider, Billing account id, Service name, SKU ID, Region, Category, and more). In SQL and exports, column names use a cos\_ prefix (for example cos\_service\_name).).

Typical lines are billed BytePlus products for that account, including Seedance and ModelArk when they appear on the invoice.

Explorer dollars are **invoice cash**: billed amount is `PayableAmount`, list amount is `OriginalBillAmount`.

**How to analyze BytePlus costs**

* Spend over time: use the same date presets as other billing sources in Explorer
* Spend by product or SKU: group by **Service name** or **SKU** when those fields are populated from bill details

**What Costory does not include**

* ModelArk or Seedance Bearer API keys (wrong credential)
* A Seedance-only product filter (Costory currently ingests the whole account bill)
* Volcengine China billing (`billing.byteplusapi.com.cn`, `cn-*` regions)
* CNY to USD conversion beyond what BytePlus already returns
* Savings-plan amortization beyond `PayableAmount`

> [!NOTE]
>
> Rotate the Access Key pair from **Integrations** when you need a new credential. The stored region stays the same. A region move is a different signing scope: create a new datasource.

## Troubleshooting

| Issue | What to check |
| - | - |
| Failed to authenticate | Paste an **IAM Access Key ID + Secret** from [IAM Key Management](https://console.byteplus.com/), not a ModelArk or Seedance API key. |
| Access denied | Attach **BillingCenterReadOnlyAccess**. `ArkReadOnlyAccess` cannot call ListBillDetail. |
| ListBillDetail endpoint not found | Confirm International billing (`billing.byteplusapi.com`) and the signing region (default `ap-singapore-1`). China hosts are not supported. |
| `SignatureDoesNotMatch` | Recheck the secret and **Region**. Region is HMAC scope only. Leave it empty unless this account uses a non-default signing region. |
| Validation succeeds but Explorer is empty | Wait for the first sync (about 10 minutes). Check the datasource date range on [Integrations](https://app.costory.io/integration). A new BytePlus account can have no lines yet. |

## Related pages

> [card] [Billing Data](https://docs.costory.io/setup/billing)
>
> All billing providers and shared setup notes.

> [card] [Kling AI billing](https://docs.costory.io/setup/billing/kling-ai.md)
>
> Connect Kling Open Platform unit deductions.

> [card] [OpenRouter billing](https://docs.costory.io/setup/billing/openrouter.md)
>
> Import OpenRouter organization costs.

> [card] [Explorer](https://docs.costory.io/features/cost-explorer.md)
>
> Filter and group BytePlus spend with the rest of your stack.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.