createBillingAgreement

Manual recurring billing agreement scheduling only; manual collection mode. Requires an Idempotency-Key; identical replay returns the stored result, changed input conflicts.

App

Accounting

Contract

Accounting API 0.32.0

Lifecycle

preview

Runtime

not-public

Operation ID

createBillingAgreement

Canonical origin

https://accounting.runonvision.com

Purpose and use cases

POST /apps/accounting/v1/billing-agreements

The owning App is Vision Accounting. Accounting owns financial records, exact arithmetic, approvals, audit evidence, workspace grants, and ledger invariants.

Request

POST https://accounting.runonvision.com/apps/accounting/v1/billing-agreements

Authentication and authorization

Send a Vision-issued bearer token for the exact App audience. The token must include the accounting entitlement and satisfy the aws-… accounting workspace required binding.

• Required scope: accounting:billing:write

Human roles are not declared in OpenAPI. Record-level and business permission checks remain the owning App's authority.

Headers

• Authorization: Bearer <access-token> — required.
• Accept: application/json — recommended where a JSON response is declared.
• Content-Type: application/json — required for the documented request representation.

Undeclared tracing, idempotency, conditional-request, and version headers are not assumed on this page.

Path and query parameters

Request body

Media type: application/json. The body is required.

Runnable examples

curl 'https://accounting.runonvision.com/apps/accounting/v1/billing-agreements' \
  --request POST \
  --header 'authorization: Bearer ${ACCESS_TOKEN}' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "schemaVersion": "vision-accounting-billing-agreement-create.v1",
    "counterpartyReference": "<counterpartyReference>",
    "currency": "<currency>",
    "scale": 0,
    "cadence": "weekly",
    "interval": 1,
    "startDate": "2026-08-21",
    "firstBillingDate": "2026-08-21",
    "endDate": null,
    "occurrenceLimit": null,
    "timezone": "<timezone>",
    "collectionMode": "manual",
    "paymentTermsDays": 30,
    "taxAmount": {
      "currency": "<currency>",
      "minorUnits": "<minorUnits>",
      "scale": 0
    },
    "lines": [
      {
        "description": "<description>",
        "quantity": "<quantity>",
        "unitAmount": {
          "currency": "<currency>",
          "minorUnits": "<minorUnits>",
          "scale": 0
        }
      }
    ]
  }'

const response = await fetch('https://accounting.runonvision.com/apps/accounting/v1/billing-agreements', {
  method: 'POST',
  headers: {
    authorization: `Bearer ${ACCESS_TOKEN}`,
    accept: 'application/json',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
  "schemaVersion": "vision-accounting-billing-agreement-create.v1",
  "counterpartyReference": "<counterpartyReference>",
  "currency": "<currency>",
  "scale": 0,
  "cadence": "weekly",
  "interval": 1,
  "startDate": "2026-08-21",
  "firstBillingDate": "2026-08-21",
  "endDate": null,
  "occurrenceLimit": null,
  "timezone": "<timezone>",
  "collectionMode": "manual",
  "paymentTermsDays": 30,
  "taxAmount": {
    "currency": "<currency>",
    "minorUnits": "<minorUnits>",
    "scale": 0
  },
  "lines": [
    {
      "description": "<description>",
      "quantity": "<quantity>",
      "unitAmount": {
        "currency": "<currency>",
        "minorUnits": "<minorUnits>",
        "scale": 0
      }
    }
  ]
}),
}

if (!response.ok) throw new Error(`Vision API ${response.status}`)
const result = await response.json()

import json
import urllib.parse
import urllib.request

request = urllib.request.Request(
    'https://accounting.runonvision.com/apps/accounting/v1/billing-agreements',
    data=json.dumps({"schemaVersion":"vision-accounting-billing-agreement-create.v1","counterpartyReference":"<counterpartyReference>","currency":"<currency>","scale":0,"cadence":"weekly","interval":1,"startDate":"2026-08-21","firstBillingDate":"2026-08-21","endDate":null,"occurrenceLimit":null,"timezone":"<timezone>","collectionMode":"manual","paymentTermsDays":30,"taxAmount":{"currency":"<currency>","minorUnits":"<minorUnits>","scale":0},"lines":[{"description":"<description>","quantity":"<quantity>","unitAmount":{"currency":"<currency>","minorUnits":"<minorUnits>","scale":0}}]}).encode(),
    headers={
    "Accept": "application/json",
    "Authorization": "Bearer <ACCESS_TOKEN>",
    "Content-Type": "application/json"
},
    method='POST',
)
with urllib.request.urlopen(request, timeout=30) as response:
    result = json.load(response)

The current TypeScript reference client covers Platform token exchange and core reads. No native SDK helper is declared for this operation; use the HTTP contract directly and follow the SDK guidance.

Responses

Success response schema

{
  "schemaVersion": "vision-accounting-command-result.v1",
  "operation": "<operation>",
  "outcome": "succeeded",
  "commandReceiptReference": "<commandReceiptReference>",
  "subjectReference": "<subjectReference>",
  "recordVersion": 1,
  "replayed": true
}

Errors and troubleshooting

Error bodies and codes are shown only where the approved contract declares them. Use status, the declared error schema, and any correlation identifier returned by the App; do not infer that two Apps share one envelope.

• 400 — Safe Accounting error
• 401 — Safe Accounting error
• 403 — Safe Accounting error
• 404 — Safe Accounting error
• 409 — Safe Accounting error
• 422 — Safe Accounting error
• 503 — Safe Accounting error

Collection behavior

Pagination: not declared. Filtering/search: not declared. Sorting: not declared.

Cursor lifetime, cursor binding, stable ordering, maximum traversal, and unknown-filter behavior are not assumed unless stated by a parameter description or schema constraint above.

Operational behavior

• Rate limit: No operation-specific limit or 429 response is declared.
• Retry: Retry only when the documented error model or response headers authorize it. Timeout and backoff values are not declared by this operation.
• Idempotency: No idempotency header or replay window is declared.
• Concurrency: No ETag, If-Match, or optimistic-version header is declared.

Security and privacy

• Keep client credentials and bearer tokens on trusted servers.
• Send only to the exact approved HTTPS origin and audience.
• Treat response data according to the owning App's classification and retention policy; the OpenAPI contract does not itself grant data access.
• Do not log credentials, tokens, complete private payloads, or secrets.

Edge cases and known documentation gaps

• One or more parameters have no field-level description.
• The request body has no purpose or conditional-rule description.
• Business roles, timeout, retry budget, rate value, idempotency window, and concurrency behavior are absent unless explicitly stated above.

Related operations and workflows

• GET /apps/accounting/v1/meta — No summary declared
• GET /apps/accounting/v1/ready — No summary declared
• GET /apps/accounting/v1/actor — No summary declared
• GET /apps/accounting/v1/overview — No summary declared
• GET /apps/accounting/v1/counterparties — No summary declared
• POST /apps/accounting/v1/counterparties — No summary declared
• GET /apps/accounting/v1/invoices — No summary declared
• POST /apps/accounting/v1/invoice-drafts — No summary declared

Contract history and evidence

• Contract version: 0.32.0
• Approved snapshot SHA-256: 4dd988e12dc08be93bc7f1ebb4d725c40646c46f3d63a380a48a439077d53eea
• Approval: Anthony, 2026-11-03T01:23:28.091Z (anthony-docs-live-20261102)
• Download the authoritative OpenAPI 3.1 snapshot