---
title: "Manage agency billing-periods using a strict reviewed command."
method: POST
path: "/v1/agency-billing-periods"
---

# Manage agency billing-periods using a strict reviewed command.

`POST /v1/agency-billing-periods`

## Request

- Base URL: `https://www.kaicalls.com/api`
- URL: `https://www.kaicalls.com/api/v1/agency-billing-periods`
- Auth: HTTP bearer

IDs are in the body. Runtime refinements, current role, assignment and exact approval/hash/lease guards apply. Enrollment creation and commit require a stable Idempotency-Key. Installation run_scenarios also requires evals:write. Care requires sms:write and exact owner approval; preparation creates a draft, launch explicitly queues it. Provider-unknown outcomes require reconciliation. Configuration, testing, activation, billing and measured outcomes are distinct.

## Headers

- `Idempotency-Key` string

## Request body

- union
  - object
    - `action` 'retry_collection', required
    - `partnerId` string, uuid, required
    - `periodId` string, uuid, required
  - object
    - `action` 'record_adjustment', required
    - `partnerId` string, uuid, required
    - `lineId` string, uuid, required
    - `amountCents` integer, required
    - `reason` string, required
    - `providerCreditNoteId` string
    - `providerDebitInvoiceId` string
  - object
    - `action` 'set_plan', required
    - `partnerId` string, uuid, required
    - `businessId` string, uuid, required
    - `plan` string, nullable, required
  - object
    - `action` 'set_automatic_collection', required
    - `partnerId` string, uuid, required
    - `accepted` boolean, required
  - object
    - `action` 'publish_terms', required
    - `partnerId` string, uuid, nullable, required
    - `title` string, required
    - `discountBps` integer, required
    - `graceDays` integer, required
    - `document` string, required
    - `effectiveFrom` string, date-time, required
  - object
    - `action` 'accept_terms', required
    - `partnerId` string, uuid, required
    - `termsId` string, uuid, required
  - object
    - `action` 'setup_collection', required
    - `partnerId` string, uuid, required
    - `offerId` string, uuid
  - object
    - `action` 'freeze_period', required
    - `partnerId` string, uuid, required
    - `start` string, date-time, required
    - `end` string, date-time, required
  - object
    - `action` 'collect', required
    - `partnerId` string, uuid, required
    - `periodId` string, uuid, required

## Response `200`

Recorded command receipt; read back current evidence.

## Other responses

- `202`: Enrollment per-client receipt; inspect waiting and conflict states.
- `400`: Invalid command.
- `403`: Authority or approved owner revision required.
- `409`: State changed or provider reconciliation required.
- `503`: Dependency unavailable; durable operation retained.

---

[API](https://skmtc.dev/kaicalls/apis/kaicalls-public-api.md) · [All operations](https://skmtc.dev/kaicalls/apis/kaicalls-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kaicalls/apis/kaicalls-public-api/revisions/e607fc6cf36e?raw)