Billing

Get Billing Dashboard

get

Composite billing dashboard — KPIs, period comparison, top meters, invoice summary.

All computation is server-side. Frontend is a pure renderer.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Responses

200

Successful Response

application/json

workspace_idstring · uuidRequired

Workspace ID

current_period_totalnumberRequired

Total billing for the current period

previous_period_totalnumber · nullableRequired

Total billing for the previous period

delta_pctnumber · nullableRequired

Percentage change from previous period

period_startstring · nullableRequired

Current period start date (ISO-8601)

period_endstring · nullableRequired

Current period end date (ISO-8601)

get/v1/{workspace_id}/billing/dashboard

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/billing/dashboard HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Successful Response

{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "current_period_total": 1,
  "previous_period_total": 1,
  "delta_pct": 1,
  "top_meters": [
    {
      "meter_key": "text",
      "metering_source": "production",
      "display_name": "text",
      "value": 1,
      "unit": "text"
    }
  ],
  "invoice_status_summary": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "period_start": "text",
  "period_end": "text"
}

Get Workspace Usage

get

Aggregated billing summary — meters grouped by key, period range, totals.

All computation is server-side. Frontend is a pure renderer.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Responses

200

Successful Response

application/json

Other propertiesanyOptional

get/v1/{workspace_id}/billing/usage

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/billing/usage HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Successful Response

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Get Workspace Usage Trends

get

Usage time-series per meter for trend charts.

Returns one entry per (period, meter_key) within the date range. Default: last 30 days. Use date_from/date_to for custom ranges.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Query parameters

daysinteger · min: 1 · max: 365OptionalDefault: 30

date_fromstring · date · nullableOptional

date_tostring · date · nullableOptional

meter_keystring · max: 64 · nullableOptional

Responses

200

Successful Response

application/json

period_startstringRequired

Period start date (ISO-8601)

period_endstringRequired

Period end date (ISO-8601)

meter_keystringRequired

Meter identifier

metering_sourcestring · enumOptional

Traffic class

Default: productionPossible values:

valuenumberRequired

Metered value for this period

unitstringRequired

Unit of measurement

422

Validation Error

application/json

get/v1/{workspace_id}/billing/usage/trends

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/billing/usage/trends HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "period_start": "text",
    "period_end": "text",
    "meter_key": "text",
    "metering_source": "production",
    "value": 1,
    "unit": "text"
  }
]

List Workspace Invoices

get

Paginated invoice list for this workspace's billing customer.

Supports status filter and date range.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Query parameters

statusstring · enum · nullableOptionalPossible values:

date_fromstring · date · nullableOptional

Filter invoices with period_start on or after this date

date_tostring · date · nullableOptional

Filter invoices with period_end on or before this date

limitinteger · max: 100OptionalDefault: 10

continuation_tokenintegerOptionalDefault: 0

Responses

200

Successful Response

application/json

has_morebooleanRequired

continuation_tokeninteger · nullableOptional

totalinteger · nullableOptional

422

Validation Error

application/json

get/v1/{workspace_id}/billing/invoices

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/billing/invoices HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "text",
      "customer_id": "text",
      "invoice_number": "text",
      "period_start": "text",
      "period_end": "text",
      "subtotal": "text",
      "adjustments": "text",
      "total": "text",
      "status": "draft",
      "line_items": [
        {
          "meter_key": "text",
          "metering_source": "production",
          "description": "",
          "quantity": "text",
          "unit_price": "text",
          "total": "text"
        }
      ],
      "pdf_s3_key": "text",
      "sent_at": "text",
      "paid_at": "text",
      "created_at": "text",
      "updated_at": "text"
    }
  ],
  "has_more": true,
  "continuation_token": 1,
  "total": 1
}

Get Workspace Invoice

get

Get invoice detail — scoped to workspace's billing customer.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

invoice_idstring · uuidRequired

Responses

200

Successful Response

application/json

Other propertiesanyOptional

422

Validation Error

application/json

get/v1/{workspace_id}/billing/invoices/{invoice_id}

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/billing/invoices/{invoice_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Get Invoice Pdf

get

Get presigned S3 URL for invoice PDF download — scoped to workspace's billing customer.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

invoice_idstring · uuidRequired

Responses

200

Successful Response

application/json

Other propertiesanyOptional

422

Validation Error

application/json

get/v1/{workspace_id}/billing/invoices/{invoice_id}/pdf

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/billing/invoices/{invoice_id}/pdf HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

List Customers

get

Paginated customer list with optional status filter and search.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Query parameters

statusstring · enum · nullableOptionalPossible values:

searchstring · max: 200 · nullableOptional

Search by name or slug

limitinteger · max: 100OptionalDefault: 10

continuation_tokenintegerOptionalDefault: 0

Responses

200

Successful Response

application/json

has_morebooleanRequired

continuation_tokeninteger · nullableOptional

totalinteger · nullableOptional

422

Validation Error

application/json

get/v1/billing/customers

HTTPcURLJavaScriptPython

GET /v1/billing/customers HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "text",
      "name": "text",
      "slug": "text",
      "billing_email": "text",
      "billing_contact": "text",
      "mercury_memo": "text",
      "address": {
        "line1": "",
        "line2": "text",
        "city": "",
        "state": "",
        "postal_code": "",
        "country": "US"
      },
      "status": "active",
      "created_at": "text",
      "updated_at": "text"
    }
  ],
  "has_more": true,
  "continuation_token": 1,
  "total": 1
}

Create Customer

post

Create a billing customer.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Body

application/json

namestring · min: 1 · max: 256Required

slugstring · min: 2 · max: 63RequiredPattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$

billing_emailstring · emailRequired

billing_contactstring · max: 256 · nullableOptional

mercury_memostring · max: 256 · nullableOptional

Responses

201

Successful Response

application/json

Other propertiesanyOptional

422

Validation Error

application/json

post/v1/billing/customers

HTTPcURLJavaScriptPython

POST /v1/billing/customers HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 158

{
  "name": "text",
  "slug": "text",
  "billing_email": "[e-mail]",
  "billing_contact": "text",
  "mercury_memo": "text",
  "address": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Get Customer

get

Get customer detail with workspace mappings.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

customer_idstring · uuidRequired

Responses

200

Successful Response

application/json

Other propertiesanyOptional

422

Validation Error

application/json

get/v1/billing/customers/{customer_id}

HTTPcURLJavaScriptPython

GET /v1/billing/customers/{customer_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Update Customer

put

Update a billing customer.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

customer_idstring · uuidRequired

Body

application/json

namestring · min: 1 · max: 256 · nullableOptional

billing_emailstring · email · nullableOptional

billing_contactstring · max: 256 · nullableOptional

mercury_memostring · max: 256 · nullableOptional

statusstring · enum · nullableOptionalPossible values:

Responses

200

Successful Response

application/json

Other propertiesanyOptional

422

Validation Error

application/json

put/v1/billing/customers/{customer_id}

HTTPcURLJavaScriptPython

PUT /v1/billing/customers/{customer_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 162

{
  "name": "text",
  "billing_email": "[e-mail]",
  "billing_contact": "text",
  "mercury_memo": "text",
  "address": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "status": "active"
}

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Attach Workspace

post

Attach a workspace to a billing customer.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

customer_idstring · uuidRequired

Body

application/json

workspace_idstring · uuidRequired

environmentstring · enumOptionalDefault: productionPossible values:

billablebooleanOptionalDefault: true

Responses

201

Successful Response

application/json

Other propertiesanyOptional

422

Validation Error

application/json

post/v1/billing/customers/{customer_id}/workspaces

HTTPcURLJavaScriptPython

POST /v1/billing/customers/{customer_id}/workspaces HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 98

{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "environment": "production",
  "billable": true
}

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Detach Workspace

delete

Detach a workspace from a billing customer.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

customer_idstring · uuidRequired

workspace_idstring · uuidRequired

Responses

204

Successful Response

No content

422

Validation Error

application/json

delete/v1/billing/customers/{customer_id}/workspaces/{workspace_id}

HTTPcURLJavaScriptPython

DELETE /v1/billing/customers/{customer_id}/workspaces/{workspace_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Get Config

get

Get billing configuration for a customer.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

customer_idstring · uuidRequired

Responses

200

Successful Response

application/json

Other propertiesanyOptional

422

Validation Error

application/json

get/v1/billing/customers/{customer_id}/config

HTTPcURLJavaScriptPython

GET /v1/billing/customers/{customer_id}/config HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Update Config

put

Update billing config and price rules.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

customer_idstring · uuidRequired

Body

application/json

strategystring · enum · nullableOptionalPossible values:

currencystring · max: 3 · nullableOptional

billing_cyclestring · enum · nullableOptionalPossible values:

billing_dayinteger · min: 1 · max: 28 · nullableOptional

minimum_chargeany of · nullableOptional

numberOptional

or

stringOptionalPattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

effective_fromstring · date · nullableOptional

effective_tostring · date · nullableOptional

Responses

200

Successful Response

application/json

Other propertiesanyOptional

422

Validation Error

application/json

put/v1/billing/customers/{customer_id}/config

HTTPcURLJavaScriptPython

PUT /v1/billing/customers/{customer_id}/config HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 212

{
  "strategy": "usage",
  "currency": "text",
  "billing_cycle": "monthly",
  "billing_day": 1,
  "price_rules": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "minimum_charge": 1,
  "effective_from": "2026-07-10",
  "effective_to": "2026-07-10"
}

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Get Customer Usage

get

Paginated meter values for a customer with date range and meter filter.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

customer_idstring · uuidRequired

Query parameters

date_fromstring · date · nullableOptional

Filter meter values with period_start on or after

date_tostring · date · nullableOptional

Filter meter values with period_end on or before

meter_keystring · max: 64 · nullableOptional

Filter by meter key

limitinteger · max: 100OptionalDefault: 10

continuation_tokenintegerOptionalDefault: 0

Responses

200

Successful Response

application/json

has_morebooleanRequired

continuation_tokeninteger · nullableOptional

totalinteger · nullableOptional

422

Validation Error

application/json

get/v1/billing/customers/{customer_id}/usage

HTTPcURLJavaScriptPython

GET /v1/billing/customers/{customer_id}/usage HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "text",
      "customer_id": "text",
      "meter_key": "text",
      "metering_source": "production",
      "period_start": "text",
      "period_end": "text",
      "value": "text",
      "unit": "text",
      "breakdown": {
        "categories": {
          "ANY_ADDITIONAL_PROPERTY": 1
        }
      },
      "updated_at": "text"
    }
  ],
  "has_more": true,
  "continuation_token": 1,
  "total": 1
}

List Customer Invoices

get

Paginated invoice list for a customer with status and date filters.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

customer_idstring · uuidRequired

Query parameters

statusstring · enum · nullableOptionalPossible values:

date_fromstring · date · nullableOptional

Filter invoices with period_start on or after

date_tostring · date · nullableOptional

Filter invoices with period_end on or before

limitinteger · max: 100OptionalDefault: 10

continuation_tokenintegerOptionalDefault: 0

Responses

200

Successful Response

application/json

has_morebooleanRequired

continuation_tokeninteger · nullableOptional

totalinteger · nullableOptional

422

Validation Error

application/json

get/v1/billing/customers/{customer_id}/invoices

HTTPcURLJavaScriptPython

GET /v1/billing/customers/{customer_id}/invoices HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "text",
      "customer_id": "text",
      "invoice_number": "text",
      "period_start": "text",
      "period_end": "text",
      "subtotal": "text",
      "adjustments": "text",
      "total": "text",
      "status": "draft",
      "line_items": [
        {
          "meter_key": "text",
          "metering_source": "production",
          "description": "",
          "quantity": "text",
          "unit_price": "text",
          "total": "text"
        }
      ],
      "pdf_s3_key": "text",
      "sent_at": "text",
      "paid_at": "text",
      "created_at": "text",
      "updated_at": "text"
    }
  ],
  "has_more": true,
  "continuation_token": 1,
  "total": 1
}

Generate Invoice

post

Generate invoice for the most recently closed billing period.

Reads meter_values (populated by Databricks SDP pipeline), applies price rules, computes line items, creates invoice. Idempotent.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

customer_idstring · uuidRequired

Responses

201

Successful Response

application/json

Other propertiesanyOptional

422

Validation Error

application/json

post/v1/billing/customers/{customer_id}/generate-invoice

HTTPcURLJavaScriptPython

POST /v1/billing/customers/{customer_id}/generate-invoice HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Send Invoice

post

Mark invoice as sent.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

customer_idstring · uuidRequired

invoice_idstring · uuidRequired

Responses

200

Successful Response

application/json

Other propertiesanyOptional

422

Validation Error

application/json

post/v1/billing/customers/{customer_id}/invoices/{invoice_id}/send

HTTPcURLJavaScriptPython

POST /v1/billing/customers/{customer_id}/invoices/{invoice_id}/send HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Mark Paid

post

Mark invoice as paid.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

customer_idstring · uuidRequired

invoice_idstring · uuidRequired

Responses

200

Successful Response

application/json

Other propertiesanyOptional

422

Validation Error

application/json

post/v1/billing/customers/{customer_id}/invoices/{invoice_id}/paid

HTTPcURLJavaScriptPython

POST /v1/billing/customers/{customer_id}/invoices/{invoice_id}/paid HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Void Invoice

post

Void an invoice.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

customer_idstring · uuidRequired

invoice_idstring · uuidRequired

Responses

200

Successful Response

application/json

Other propertiesanyOptional

422

Validation Error

application/json

post/v1/billing/customers/{customer_id}/invoices/{invoice_id}/void

HTTPcURLJavaScriptPython

POST /v1/billing/customers/{customer_id}/invoices/{invoice_id}/void HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}