Data API

Getting started

1. In Metricaas, add a Custom data source and answer the three questions (whether you'll enter payments, whether each subscription has a plan, whether you'll register customers).
2. Under Settings > API, generate a key. It is shown once.
3. Send your subscriptions. The dashboard moves within a minute.

Authentication

Every call carries your key in the header. The key belongs to your company and says which source it writes to.

Authorization: Bearer mtc_live_...

Base address: https://api.metricaas.ai/v1

We only store a cryptographic digest of the key, so not even we can show it again. Lose it, generate another and revoke the old one.

Your first call

Create and update are the same call: the id is yours, and sending the same id again updates instead of duplicating.

curl -X POST https://api.metricaas.ai/v1/subscriptions \
  -H "Authorization: Bearer mtc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"id":"sub_001","customer":"cli_001","plan":"Pro","currency":"BRL","cycle":"monthly","started_at":"2024-01-10","amounts":[{"from":"2024-01-10","cents":9990},{"from":"2025-03-01","cents":12990}]}'

Send in BATCH (an array in the body, up to 1000 objects). Either everything goes in or nothing does: a half-applied batch would leave you not knowing what landed.

An amount is a HISTORY, not a number

In a gateway, price history lives in the invoices: each one is a billed period, at that day's price. Here there are no invoices, so the history lives inside the subscription, in the `amounts` field.

Each band says what it became worth, and from when. The first one starts when the subscription started. That is what keeps March's MRR being March's after you raise the price in April.

{
  "amounts": [
    {
      "from": "2024-01-10",
      "cents": 9990
    },
    {
      "from": "2025-03-01",
      "cents": 12990
    }
  ]
}

So a request that SHORTENS or ALTERS an already declared band is rejected with 409: it would rewrite the MRR of months that already closed. If it was a price change, append a new band. If it was a typo, confirm you really want to rewrite:

POST https://api.metricaas.ai/v1/subscriptions?correct_history=true

Canceling is not deleting

Canceling is a fact about your business: the customer left, the subscription stays in your history and becomes churn on the declared date. Deleting is an erratum: it never existed, and past MRR is recomputed without it. Confusing the two corrupts your churn in both directions.

# the customer left (becomes churn)
PUT https://api.metricaas.ai/v1/subscriptions/sub_001   { "canceled_at": "2026-03-01", ... }

# I typed it wrong (erased from history)
DELETE https://api.metricaas.ai/v1/subscriptions/sub_001

/v1/customers

Optional. Only needed if one customer has more than one subscription. The only required field is the id, so you can group without telling us who they are.

{
  "id": "cli_001",
  "name": "Empresa Exemplo",
  "email": "contato@exemplo.com"
}

/v1/subscriptions

The heart of the source. This is where your MRR comes from.

{
  "id": "sub_001",
  "customer": "cli_001",
  "plan": "Pro",
  "currency": "BRL",
  "cycle": "monthly",
  "started_at": "2024-01-10",
  "amounts": [
    {
      "from": "2024-01-10",
      "cents": 9990
    },
    {
      "from": "2025-03-01",
      "cents": 12990
    }
  ]
}

/v1/payments

Optional. Declare payments and you get dunning, cash revenue, fees and refunds. Don't, and MRR stays whole while dunning simply doesn't exist in your account.

{
  "id": "pay_001",
  "customer": "cli_001",
  "subscription": "sub_001",
  "amount_cents": 9990,
  "paid_at": "2024-02-10",
  "fee_cents": 349
}

Errors

A rejection lists ALL the problems at once, with the field (and, for spreadsheets, the row). You won't be fixing one per request.

{
  "error": {
    "code": "invalid_request",
    "message": "a declaracao tem 2 problema(s)",
    "details": [
      {
        "field": "subscription.cycle (sub_002)",
        "line": 4,
        "reason": "invalid option"
      },
      {
        "field": "subscription.amounts (sub_007)",
        "line": 9,
        "reason": "..."
      }
    ]
  }
}

• 202 — accepted. Your dashboard moves within a minute.
• 400 — the declaration has problems. Nothing was written.
• 401 — invalid key, revoked, or without permission for this operation.
• 409 — this would rewrite already declared amount history. See the section above.
• 429 — too many requests. Send in batch.

Checking what you declared

GET returns what's in your vault, paginated by cursor. This same key will read your metrics once the read API exists.

GET https://api.metricaas.ai/v1/subscriptions?limit=100&cursor=sub_050