> ## 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. Import account bill details, including Seedance and ModelArk, into Explorer next to AWS, GCP, and Azure.

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 <Tooltip tip="Costory's main interface for exploring cloud costs across all connected providers." cta="See Glossary" href="/docs/glossary#cost-explorer">Explorer</Tooltip> with your other [billing datasources](/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.

<Info>
  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.
</Info>

<Tabs>
  <Tab title="Manual setup">
    <Steps>
      <Step title="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`).
      </Step>

      <Step title="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.
      </Step>

      <Step title="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;
      </Step>

      <Step title="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**.
      </Step>

      <Step title="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.
      </Step>
    </Steps>

    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](/docs/data-refresh) cadence. SaaS sources typically appear in about **10 minutes**.
  </Tab>

  <Tab title="Terraform">
    Not supported yet.
  </Tab>
</Tabs>

## 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 <Tooltip tip="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)." cta="See Glossary" href="/docs/glossary#standard-columns">Standard Columns</Tooltip>.

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`

<Info>
  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.
</Info>

## 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

<CardGroup cols={2}>
  <Card title="Billing Data" icon="database" href="/setup/billing">
    All billing providers and shared setup notes.
  </Card>

  <Card title="Kling AI billing" icon="film" href="/setup/billing/kling-ai">
    Connect Kling Open Platform unit deductions.
  </Card>

  <Card title="OpenRouter billing" icon="robot" href="/setup/billing/openrouter">
    Import OpenRouter organization costs.
  </Card>

  <Card title="Explorer" icon="chart-line" href="/features/cost-explorer">
    Filter and group BytePlus spend with the rest of your stack.
  </Card>
</CardGroup>