openapi: 3.1.0 info: title: API do Faturamento Automático version: 1.0.0 description: |- Hey dev, have fun! ✨ > **Documentation index** — fetch the full index at [https://docs.billing.kobana.com.br/llms.txt](https://docs.billing.kobana.com.br/llms.txt). Use this file to discover every available page before exploring further. > **Mind the API versions** — you are reading the **v1.0** documentation of the Automatic Billing API, which covers the **Subscriptions** endpoints (create, plan change, pause, cancel, manual invoicing, item sync) and related resources. Resources like **Payments, Transfers, Statements and Pix Receivables** live in other Kobana APIs — use the product picker in the top menu to switch. ## Format The API only accepts `JSON`. Every request must use `Content-Type: application/json`. All responses use `snake_case`. | Field type | Format | | :--- | :--- | | **DateTime** | [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format. Examples — Date: `2026-01-24`. Date and time: `2026-01-24T10:07Z` | | **Money** | Decimal number in BRL, with up to 4 decimal places. E.g.: `100.5` = R$ 100.50 | | **UUID** | Resource identifiers as UUID v4 | ## Conventions Conventions used in this documentation: | Convention | Description | | :--- | :--- | | **`:variable`** | A variable name that must be replaced in the URL. | | **`#{variable}`** | A variable name that must be replaced with values from your account. | | **`...`** | Response content truncated for readability. | | **`$KOBANA_TOKEN`** | Access token. For command-line testing, export it: `export KOBANA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx` then paste the docs commands into your terminal. | ## Return Codes The API returns standard HTTP status codes: | | Code | Description | | :--- | :--- | :--- | | ✅ | **200 OK** | Successful request with a response body. | | ✅ | **201 Created** | Resource created successfully. | | ✅ | **204 No Content** | Successful request without a response body. | | ❌ | **400 Bad Request** | Invalid request, usually malformed content. | | ❌ | **401 Unauthorized** | Missing or invalid access token. | | ❌ | **403 Forbidden** | API access blocked or user not authorized. | | ❌ | **404 Not Found** | Resource not found. | | ❌ | **422 Unprocessable Entity** | Valid request, but the data is not. | | ❌ | **429 Too Many Requests** | Rate limit reached. | | ❌ | **500 Internal Server Error** | Internal processing error. Check [server status](https://status.kobana.com.br). | ## Request ID Every request has an associated identifier in the `Request-Id` response header. This value helps with debugging and auditing — requests and their IDs are available in the system dashboard. Request logs are retained for **30 days**. When opening a support ticket about a specific request, provide the `Request-Id` to speed up the investigation. ## Security The Kobana API uses **2048-bit SSL** certificates. Every request must use **HTTPS** — calls on port 80 are redirected to 443. Clients must support `TLSv1.2` or `TLSv1.3` with one of the ciphers: `TLS_AES_128_GCM_SHA256`, `TLS_AES_256_GCM_SHA384`, `TLS_CHACHA20_POLY1305_SHA256`, `ECDHE-RSA-AES128-GCM-SHA256`, `ECDHE-RSA-AES128-SHA256`, `ECDHE-RSA-AES256-GCM-SHA384`, `ECDHE-RSA-CHACHA20-POLY1305`, `ECDHE-RSA-AES256-SHA384`. `TLSv1` and `TLSv1.1` are not supported. ## HTTP Caching Use HTTP cache headers to reduce load and improve speed. Most responses include `ETag` and/or `Last-Modified` — store these values and send them back on follow-up requests via `If-None-Match` and `If-Modified-Since`. If the resource hasn't changed you'll get `304 Not Modified` — no body, no reprocessing. More info: [HTTP Cache Docs](http://www.mnot.net/cache_docs/). ## Error Handling 5xx errors mean a server failure: **500 Internal Server Error** (application unavailable), **502 Bad Gateway**, **503 Service Unavailable** and **504 Gateway Timeout** (point-in-time infrastructure failures). Your application must catch these and retry the request after a few minutes with backoff. Server status: [https://status.kobana.com.br](https://status.kobana.com.br). ## Monetary values Every monetary value — in requests and responses — is a decimal number in BRL, with up to 4 decimal places. There are no cent-based fields: send `100.5` for R$ 100.50 and `0.0125` for R$ 0.0125. Pricing fields keep all 4 decimals; the others are rounded to 2. license: name: Proprietário — Kobana url: https://kobana.com.br servers: - url: https://api.billing.kobana.com.br description: Production. Overridden at runtime when `API_V1_PUBLIC_URL` is set. - url: https://api.billing.sandbox.kobana.com.br description: Sandbox — isolated testing environment, separate from production. components: schemas: ApiV1Error: type: object properties: error: type: object properties: code: type: string description: Stable error code. Use this field to handle errors programmatically — never parse `message`. example: invalid_token message: type: string description: Human-readable message. Never includes user data verbatim. example: Cabeçalho Authorization ausente. details: description: "Optional error-specific payload (e.g.: `{ required, granted }` in `insufficient_scope`)." required: - code - message description: Error envelope. Present in every 4xx and 5xx response. required: - error PaginationMeta: type: object properties: total: type: integer description: Total items across all pages. page: type: integer description: Current page (starts at 1). per_page: type: integer description: Items per page. total_pages: type: integer description: Total pages. required: - total - page - per_page - total_pages DeletedResponse: type: object properties: data: type: object properties: deleted: type: boolean example: true required: - deleted required: - data SubscriptionV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. billing_account_id: type: string format: uuid company_id: type: - string - "null" format: uuid plan_id: type: - string - "null" format: uuid product_group_id: type: - string - "null" format: uuid status: type: string enum: - draft - confirmed - trialing - active - past_due - canceled - paused - suspended description: "Subscription state. Lifecycle: `draft` → `confirmed` → `trialing` → `active` ↔ `past_due` → `canceled`. Also accepts `paused`." billing_cycle: type: string enum: - monthly - quarterly - semiannual - annual description: "Billing cycle: monthly, quarterly, semiannual or annual." current_period_start: type: string format: date-time description: Start of the current billing period. current_period_end: type: string format: date-time description: End of the current billing period. cycle_billing_date: type: string format: date-time description: "Cycle billing date: when the next subscription invoice is generated. Its day of month also drives the monthly overage (usage) invoices." trial_start: type: - string - "null" format: date-time trial_end: type: - string - "null" format: date-time activated_at: type: - string - "null" format: date-time confirmed_at: type: - string - "null" format: date-time cancel_at_period_end: type: boolean description: When `true`, the subscription is canceled at the end of the current period instead of immediately. canceled_at: type: - string - "null" format: date-time cancellation_reason: type: - string - "null" pause_collection: description: When paused, contains `{ behavior, resumes_at }`. `null` when active. paused_at: type: - string - "null" format: date-time resumes_at: type: - string - "null" format: date-time resumed_at: type: - string - "null" format: date-time discount_percent: type: - string - "null" description: 'Decimal as string (e.g.: `"10.00"` = 10%). Range: 0–100.' discount_amount: type: - number - "null" description: "Fixed per-invoice (billing-cycle) discount in BRL (float, up to 4 decimal places). Sovereign over `discount_percent`: setting the percent recomputes this value; setting this value clears the percent." example: 50 recurring_amount: type: - number - "null" description: Recurring amount in BRL (float, up to 4 decimal places). example: 99.9 proration_behavior: type: string enum: - create_prorations - none - always_invoice description: "Proration behavior when switching plans. `create_prorations` (default): generates an adjustment; `none`: ignores; `always_invoice`: emits an immediate invoice." late_fee_policy_id: type: - string - "null" format: uuid description: Late fee policy applied to invoices born of this subscription. Null inherits from the billing account, then the organization default. collection_method: type: - string - "null" enum: - charge_automatically - manual_charge - manual_invoice description: "`charge_automatically`: automatic invoicing and charging. `manual_charge`: automatic invoicing, manual charging. `manual_invoice`: both manual." nfe_issuance_policy: type: - string - "null" enum: - disabled - on_finalization - on_full_payment - per_installment description: "NF-e issuance policy: `disabled`, `on_finalization`, `on_full_payment` or `per_installment`." renewal_settings: description: '`{ type: "auto_renew" | "cancel" | "downgrade_to_flexible", ... }`.' commitment: {} commitment_months: type: - integer - "null" description: "Commitment (loyalty) period: number of contracted months (copied from the accepted proposal). Inside the commitment window — subscription start + months — the customer cannot cancel through the portal. Use `null` to clear." allow_pause: type: boolean allow_cancel: type: boolean proposal_id: type: - string - "null" format: uuid notes: type: - string - "null" metadata: type: - object - "null" additionalProperties: {} description: Read-only internal metadata generated by the system. custom_metadata: type: - object - "null" additionalProperties: {} created_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel through which the record was created (dashboard, import, api, mcp, cli, other). On API calls it comes from the `X-Request-Source` header. created_via_other: type: - string - "null" description: Name of the app that created the record when `created_via` is `other` (`X-Request-Source-Other` header). created_by_email: type: - string - "null" description: Email of the user who created the record. updated_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel of the last update to the record. updated_via_other: type: - string - "null" description: Name of the app behind the last update when `updated_via` is `other` (`X-Request-Source-Other` header). updated_by_email: type: - string - "null" description: Email of the user who made the last update. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - external_id - billing_account_id - company_id - plan_id - product_group_id - status - billing_cycle - current_period_start - current_period_end - cycle_billing_date - trial_start - trial_end - activated_at - confirmed_at - cancel_at_period_end - canceled_at - cancellation_reason - discount_percent - discount_amount - recurring_amount - proration_behavior - late_fee_policy_id - collection_method - nfe_issuance_policy - commitment_months - allow_pause - allow_cancel - proposal_id - notes - metadata - custom_metadata - created_via - created_via_other - created_by_email - updated_via - updated_via_other - updated_by_email - created_at - updated_at SubscriptionListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/SubscriptionV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta SubscriptionResponse: type: object properties: data: $ref: "#/components/schemas/SubscriptionV1" required: - data SubscriptionCreateRequest: type: object properties: billing_account_id: type: string format: uuid description: UUID of the billing account that will receive this subscription. external_id: type: string description: Identifier in your external system, for idempotency/sync. company_id: type: string format: uuid plan_id: type: string format: uuid description: Plan UUID. Required when `items` is not provided. product_group_id: type: string format: uuid billing_cycle: type: string enum: - monthly - quarterly - semiannual - annual collection_method: type: - string - "null" enum: - charge_automatically - manual_charge - manual_invoice trial_end: type: string format: date-time description: Trial end date (ISO 8601). trial_period_days: type: integer minimum: 0 description: Alternative to `trial_end`. Trial days from creation. proration_behavior: type: string enum: - create_prorations - none - always_invoice nfe_issuance_policy: type: string enum: - disabled - on_finalization - on_full_payment - per_installment items: type: array items: type: object properties: product_id: type: string format: uuid price_id: type: string format: uuid quantity: type: integer minimum: 1 default: 1 unit_amount: type: number minimum: 0 description: 4-decimal precision (float, up to 4 decimal places). Overrides the price amount. required: - product_id - price_id commitment_months: type: - integer - "null" minimum: 1 maximum: 120 description: "Commitment (loyalty) period: number of contracted months (copied from the accepted proposal). Inside the commitment window — subscription start + months — the customer cannot cancel through the portal. Use `null` to clear." notes: type: - string - "null" custom_metadata: type: - object - "null" additionalProperties: {} required: - billing_account_id SubscriptionUpdateRequest: type: object properties: external_id: type: - string - "null" description: New identifier in your external system. Use `null` to clear. plan_id: type: - string - "null" format: uuid billing_cycle: type: string enum: - monthly - quarterly - semiannual - annual collection_method: type: - string - "null" enum: - charge_automatically - manual_charge - manual_invoice cancel_at_period_end: type: boolean discount_percent: type: - number - "null" minimum: 0 maximum: 100 discount_amount: type: - number - "null" minimum: 0 description: "Fixed per-invoice (billing-cycle) discount in BRL (float, up to 4 decimal places). Sovereign over `discount_percent`: setting the percent recomputes this value; setting this value clears the percent." proration_behavior: type: string enum: - create_prorations - none - always_invoice nfe_issuance_policy: type: - string - "null" enum: - disabled - on_finalization - on_full_payment - per_installment allow_pause: type: boolean allow_cancel: type: boolean commitment_months: type: - integer - "null" minimum: 1 maximum: 120 description: "Commitment (loyalty) period: number of contracted months (copied from the accepted proposal). Inside the commitment window — subscription start + months — the customer cannot cancel through the portal. Use `null` to clear." notes: type: - string - "null" custom_metadata: type: - object - "null" additionalProperties: {} custom_metadata_mode: type: string enum: - replace - merge description: How the submitted `custom_metadata` is reconciled with the stored value. `replace` (default) overwrites the whole object; `merge` deep-merges over the current value — nested objects merge recursively, scalars and arrays overwrite the key, and `null` keys are kept (they do not delete the key). Accepted on update only. example: merge SubscriptionPauseRequest: type: object properties: behavior: type: string enum: - mark_uncollectible - keep_as_draft - void description: "How to treat invoices generated during the pause. Default: `mark_uncollectible`." resumes_at: type: string format: date-time description: Auto-resume date. Omit for manual resume. SubscriptionChangePlanRequest: type: object properties: plan_id: type: string format: uuid description: UUID of the new plan. timing: type: string enum: - immediate - end_of_period description: "When the plan change takes effect. Default: `immediate`." reason: type: string description: Change reason (optional, recorded in audit log). required: - plan_id SubscriptionChangeAnniversaryRequest: type: object properties: anniversary_day: type: integer minimum: 1 maximum: 28 description: New day of the month (1 to 28) on which cycles start. Use 1 for calendar months. example: 1 charge_proration: type: boolean description: "Bill the added days. Default: `true`, unless the subscription `proration_behavior` is `none`." dry_run: type: boolean description: When `true`, only computes and returns the result, changing nothing. reason: type: string description: Change reason (optional, recorded in audit log). required: - anniversary_day SubscriptionChangeAnniversaryResult: type: object properties: dry_run: type: boolean description: Whether this was only a simulation. anniversary_day: type: integer description: New cycle start day. previous_next_cycle_start: type: string format: date-time description: Next cycle start before the change. next_cycle_start: type: string format: date-time description: Next cycle start after the change. current_period_end: type: string format: date-time description: New (inclusive) end of the cycle in progress. proration_period_start: type: string format: date-time description: First day added to the cycle in progress. proration_period_end: type: string format: date-time description: Last day added to the cycle in progress. proration_days: type: integer description: Number of added days. cycle_days: type: integer description: Cycle days used as the proration divisor. cycle_amount: type: number description: Contracted amount of a full cycle, net of discount. example: 310 proration_amount: type: number description: Prorated amount for the added days. example: 280 charge_proration: type: boolean description: Whether the added days are billed. will_invoice: type: boolean description: Whether an invoice is (or would be) generated. False for courtesy, zero amount or `charge_proration=false`. invoice_id: type: - string - "null" format: uuid description: Proration invoice, when generated. pending_usage: type: - object - "null" properties: period_start: type: string format: date-time description: Start of the usage month. period_end: type: string format: date-time description: End of the usage month. amount: type: number description: Usage invoice amount. example: 45.5 required: - period_start - period_end - amount description: Previous month's usage that the new day would leave unbilled (the old day has not come yet and the new one already passed this month). It is billed at change time, as automatic billing would. Only filled on a simulation (`dry_run`); on the actual change, see `usage_invoice_id`. `null` when nothing is at risk or there is no usage. usage_invoice_id: type: - string - "null" format: uuid description: Usage invoice generated by the change, if any. required: - dry_run - anniversary_day - previous_next_cycle_start - next_cycle_start - current_period_end - proration_period_start - proration_period_end - proration_days - cycle_days - cycle_amount - proration_amount - charge_proration - will_invoice - invoice_id - pending_usage - usage_invoice_id SubscriptionCancelRequest: type: object properties: cancel_at_period_end: type: boolean description: "When `true`, schedules cancellation for end of current period. Default: `false` (cancels immediately)." reason: type: string BillingAccountCustomerV1: type: object properties: id: type: string format: uuid external_id: type: - string - "null" name: type: string nickname: type: - string - "null" legal_name: type: - string - "null" document_type: type: - string - "null" enum: - cpf - cnpj document_number: type: - string - "null" kind: type: - string - "null" enum: - individual - company birthday: type: - string - "null" notes: type: - string - "null" addresses: {} phones: {} emails: {} websites: {} tags: type: - array - "null" items: type: string custom_metadata: type: - object - "null" additionalProperties: {} created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - name BillingAccountV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. external_id: type: - string - "null" description: External identifier for the account in the client's system. currency: type: string description: "ISO 4217 currency (e.g.: `BRL`)." example: BRL billing_email: type: - string - "null" format: email description: Email address invoices and notices are sent to. late_fee_policy_id: type: - string - "null" format: uuid description: Late fee policy negotiated for this customer. Null inherits the organization default — it never means "no charges", which is an explicit policy. payment_terms_days: type: integer description: "Invoice due period in days (default: 10)." example: 10 auto_collection: type: boolean description: When `true`, charges are collected automatically. balance: type: number description: Account balance in BRL (float, up to 4 decimal places). example: 0 status: type: string enum: - active - suspended - closed description: "Account status: `active`, `suspended` or `closed`." suspended_at: type: - string - "null" format: date-time suspension_reason: type: - string - "null" tax_exempt: type: boolean description: Whether the account is tax-exempt. tax_exemption_certificate: type: - string - "null" description: Tax exemption certificate number. customer_tax_type: type: - string - "null" enum: - individual - business - exempt description: "Customer tax type: individual, business or exempt." metadata: type: - object - "null" additionalProperties: {} description: Read-only internal metadata generated by the system. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). created_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel through which the record was created (dashboard, import, api, mcp, cli, other). On API calls it comes from the `X-Request-Source` header. created_via_other: type: - string - "null" description: Name of the app that created the record when `created_via` is `other` (`X-Request-Source-Other` header). created_by_email: type: - string - "null" description: Email of the user who created the record. updated_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel of the last update to the record. updated_via_other: type: - string - "null" description: Name of the app behind the last update when `updated_via` is `other` (`X-Request-Source-Other` header). updated_by_email: type: - string - "null" description: Email of the user who made the last update. created_at: type: string format: date-time updated_at: type: string format: date-time customer: allOf: - $ref: "#/components/schemas/BillingAccountCustomerV1" - description: Associated customer, present when the relation is loaded. required: - id - public_id - external_id - currency - billing_email - late_fee_policy_id - payment_terms_days - auto_collection - balance - status - suspended_at - suspension_reason - tax_exempt - tax_exemption_certificate - customer_tax_type - metadata - custom_metadata - created_via - created_via_other - created_by_email - updated_via - updated_via_other - updated_by_email - created_at - updated_at BillingAccountListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/BillingAccountV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta BillingAccountResponse: type: object properties: data: $ref: "#/components/schemas/BillingAccountV1" required: - data BillingAccountCustomerInput: type: object properties: id: type: string description: UUID or external_id of the existing customer. external_id: type: string description: External code to locate/create the customer. document_number: type: string description: CPF or CNPJ to locate/create the customer. name: type: string description: Required when creating a new customer. nickname: type: string legal_name: type: string kind: type: string enum: - individual - company birthday: type: string email: type: string format: email phone: type: string notes: type: string addresses: {} phones: {} emails: {} websites: {} tags: type: array items: type: string custom_metadata: type: - object - "null" additionalProperties: {} BillingAccountCreateRequest: type: object properties: customer: allOf: - $ref: "#/components/schemas/BillingAccountCustomerInput" - description: Customer to associate — existing or new. external_id: type: string description: External identifier for the account in the client's system. billing_email: type: string format: email description: "Billing email. Default: `customer.email`." payment_terms_days: type: integer minimum: 1 maximum: 90 description: "Invoice due period in days (1–90). Default: the organization's configured default payment terms (10 when not configured)." auto_collection: type: boolean description: "Enables automatic collection. Default: `true`." custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). required: - customer BillingAccountUpdateRequest: type: object properties: external_id: type: - string - "null" description: New external identifier for the account in the client's system. Send `null` to clear. name: type: string minLength: 1 maxLength: 255 email: type: string format: email phone: type: string address: type: object additionalProperties: {} billing_email: type: string format: email payment_terms_days: type: integer minimum: 1 maximum: 90 auto_collection: type: boolean custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). custom_metadata_mode: type: string enum: - replace - merge description: How the submitted `custom_metadata` is reconciled with the stored value. `replace` (default) overwrites the whole object; `merge` deep-merges over the current value — nested objects merge recursively, scalars and arrays overwrite the key, and `null` keys are kept (they do not delete the key). Accepted on update only. example: merge BillingAccountReasonRequest: type: object properties: reason: type: string description: Operation reason (recorded in the audit log). CustomerV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. external_id: type: - string - "null" description: Customer identifier in your source system. name: type: string nickname: type: - string - "null" legal_name: type: - string - "null" description: Legal name (for businesses). document_type: type: - string - "null" enum: - cpf - cnpj description: Primary document type. Inferred from `document_number`'s length. document_number: type: - string - "null" description: CPF (11 digits) or CNPJ (14 digits). May include a mask. kind: type: - string - "null" enum: - natural - juridical description: "`natural` for individuals; `juridical` for businesses." birthday: type: - string - "null" description: Birth date (ISO 8601). notes: type: - string - "null" addresses: type: - array - "null" items: type: object properties: kind: type: string description: "Address kind (e.g.: `billing`, `shipping`)." street: type: string number: type: string complement: type: - string - "null" neighborhood: type: string city: type: string state: type: string postal_code: type: string country: type: string description: "ISO country code (e.g.: `BR`)." phones: type: - array - "null" items: type: object properties: kind: type: string value: type: string required: - value emails: type: - array - "null" items: type: object properties: kind: type: string value: type: string required: - value websites: type: - array - "null" items: type: object properties: kind: type: string value: type: string required: - value tags: type: - array - "null" items: type: string metadata: type: - object - "null" additionalProperties: {} description: Read-only internal metadata generated by the system. custom_metadata: type: - object - "null" additionalProperties: {} description: Custom metadata defined by the organization. created_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel through which the record was created (dashboard, import, api, mcp, cli, other). On API calls it comes from the `X-Request-Source` header. created_via_other: type: - string - "null" description: Name of the app that created the record when `created_via` is `other` (`X-Request-Source-Other` header). created_by_email: type: - string - "null" description: Email of the user who created the record. updated_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel of the last update to the record. updated_via_other: type: - string - "null" description: Name of the app behind the last update when `updated_via` is `other` (`X-Request-Source-Other` header). updated_by_email: type: - string - "null" description: Email of the user who made the last update. created_at: type: string format: date-time updated_at: type: string format: date-time billing_accounts: type: array items: $ref: "#/components/schemas/BillingAccountV1" description: Included only when the customer is loaded with billing accounts. required: - id - public_id - external_id - name - nickname - legal_name - document_type - document_number - kind - birthday - notes - addresses - phones - emails - websites - tags - metadata - custom_metadata - created_via - created_via_other - created_by_email - updated_via - updated_via_other - updated_by_email - created_at - updated_at CustomerListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/CustomerV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta CustomerResponse: type: object properties: data: $ref: "#/components/schemas/CustomerV1" required: - data CustomerCreateResponse: type: object properties: data: type: object properties: customer: $ref: "#/components/schemas/CustomerV1" billing_account: allOf: - $ref: "#/components/schemas/BillingAccountV1" - type: - object - "null" required: - customer - billing_account required: - data CustomerCreateRequest: type: object properties: name: type: string description: Customer name (required). public_id: type: string format: uuid description: Public UUID of the customer. Generated when omitted; supply one only to carry over an identifier from your system. Must be unique. external_id: type: string description: External customer identifier in the source system. nickname: type: string legal_name: type: string description: Legal name (for businesses). document_number: type: string description: CPF or CNPJ. The `document_type` is inferred from the length (≤11 → cpf, otherwise cnpj). kind: type: string enum: - natural - juridical birthday: type: string description: Birth date (ISO 8601). email: type: string description: Primary contact email. phone: type: string notes: type: string addresses: type: array items: type: object properties: kind: type: string description: "Address kind (e.g.: `billing`, `shipping`)." street: type: string number: type: string complement: type: - string - "null" neighborhood: type: string city: type: string state: type: string postal_code: type: string country: type: string description: "ISO country code (e.g.: `BR`)." phones: type: array items: type: object properties: kind: type: string value: type: string required: - value emails: type: array items: type: object properties: kind: type: string value: type: string required: - value websites: type: array items: type: object properties: kind: type: string value: type: string required: - value tags: type: array items: type: string custom_metadata: type: - object - "null" additionalProperties: {} create_billing_account: type: boolean description: "When `false`, doesn't automatically create a billing account. Default: `true`." billing_email: type: string description: "Email for sending invoices. Default: uses `email` when omitted." payment_terms_days: type: integer minimum: 0 description: "Invoice due period in days. Default: the organization's configured default payment terms (10 when not configured)." auto_collection: type: boolean description: "Automatic collection on the created account. Default: `true`." required: - name CustomerUpdateRequest: type: object properties: name: type: string public_id: type: string format: uuid description: New public UUID for the customer. Must be unique. external_id: type: string nickname: type: string legal_name: type: string document_number: type: string kind: type: string enum: - natural - juridical birthday: type: string email: type: string phone: type: string notes: type: string addresses: type: array items: type: object properties: kind: type: string description: "Address kind (e.g.: `billing`, `shipping`)." street: type: string number: type: string complement: type: - string - "null" neighborhood: type: string city: type: string state: type: string postal_code: type: string country: type: string description: "ISO country code (e.g.: `BR`)." phones: type: array items: type: object properties: kind: type: string value: type: string required: - value emails: type: array items: type: object properties: kind: type: string value: type: string required: - value websites: type: array items: type: object properties: kind: type: string value: type: string required: - value tags: type: array items: type: string custom_metadata: type: - object - "null" additionalProperties: {} custom_metadata_mode: type: string enum: - replace - merge description: How the submitted `custom_metadata` is reconciled with the stored value. `replace` (default) overwrites the whole object; `merge` deep-merges over the current value — nested objects merge recursively, scalars and arrays overwrite the key, and `null` keys are kept (they do not delete the key). Accepted on update only. example: merge CustomerUpsertRequest: allOf: - $ref: "#/components/schemas/CustomerCreateRequest" - type: object properties: name: type: string description: Customer name. Required only when no customer is found by the dedup keys. public_id: type: string format: uuid description: Public UUID of the customer. Locates the record and, when none is found, is written onto the created customer. id: type: string format: uuid description: Customer UUID. Used only to locate the record — never written. custom_metadata_mode: type: string enum: - replace - merge description: How the submitted `custom_metadata` is reconciled with the stored value. `replace` (default) overwrites the whole object; `merge` deep-merges over the current value — nested objects merge recursively, scalars and arrays overwrite the key, and `null` keys are kept (they do not delete the key). Accepted on update only. example: merge CustomerUpsertResponse: type: object properties: data: type: object properties: customer: $ref: "#/components/schemas/CustomerV1" billing_account: allOf: - $ref: "#/components/schemas/BillingAccountV1" - type: - object - "null" matched_by: type: - string - "null" enum: - id - public_id - external_id - document_number description: Key that located the existing customer. `null` when the customer was created. required: - customer - billing_account - matched_by required: - data CustomerStatementItem: type: object properties: id: type: string format: uuid billing_account_id: type: string format: uuid kind: type: string description: "Entry kind (e.g.: `invoice`, `payment`, `credit_application`)." occurred_at: type: string format: date-time description: type: - string - "null" amount: type: number description: Entry amount in BRL (float, up to 4 decimal places). Can be negative. parent_id: type: - string - "null" parent_type: type: - string - "null" created_at: type: string format: date-time required: - id - billing_account_id - kind - occurred_at - description - amount - parent_id - parent_type - created_at CustomerStatementListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/CustomerStatementItem" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta CustomerStatementSyncResponse: type: object properties: data: type: object properties: customer_id: type: string format: uuid billing_account_id: type: string format: uuid invoices_created: type: integer payments_created: type: integer credit_applications_created: type: integer total_created: type: integer required: - customer_id - billing_account_id - invoices_created - payments_created - credit_applications_created - total_created required: - data CustomerStatementSyncRequest: type: object properties: billing_account_id: type: string format: uuid description: Required when the customer has multiple billing accounts. CustomerRecalculateMrrResponse: type: object properties: data: type: object properties: customer_id: type: string format: uuid total_mrr: type: number description: Consolidated MRR across all accounts, in BRL (float, up to 4 decimal places). billing_accounts: type: array items: type: object properties: billing_account_id: type: string format: uuid mrr_amount: type: number required: - billing_account_id - mrr_amount required: - customer_id - total_mrr - billing_accounts required: - data CustomerPortalUserV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. email: type: string status: type: string enum: - active - pending_verification - pending_invitation - suspended - locked sso_only: type: boolean external_id: type: - string - "null" email_verified_at: type: - string - "null" format: date-time last_login_at: type: - string - "null" format: date-time metadata: type: - object - "null" additionalProperties: {} description: Read-only internal metadata generated by the system. custom_metadata: type: - object - "null" additionalProperties: {} created_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel through which the record was created (dashboard, import, api, mcp, cli, other). On API calls it comes from the `X-Request-Source` header. created_via_other: type: - string - "null" description: Name of the app that created the record when `created_via` is `other` (`X-Request-Source-Other` header). created_by_email: type: - string - "null" description: Email of the user who created the record. updated_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel of the last update to the record. updated_via_other: type: - string - "null" description: Name of the app behind the last update when `updated_via` is `other` (`X-Request-Source-Other` header). updated_by_email: type: - string - "null" description: Email of the user who made the last update. created_at: type: string format: date-time updated_at: type: string format: date-time name: type: - string - "null" description: Linked `Person` name, when loaded. required: - id - public_id - email - status - sso_only - external_id - email_verified_at - last_login_at - metadata - custom_metadata - created_via - created_via_other - created_by_email - updated_via - updated_via_other - updated_by_email - created_at - updated_at CustomerPortalUserListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/CustomerPortalUserV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta CustomerPortalUserResponse: type: object properties: data: $ref: "#/components/schemas/CustomerPortalUserV1" required: - data CustomerPortalUserInviteRequest: type: object properties: email: type: string description: Invitee's email (required). external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). required: - email CustomerPortalUserUpdateRequest: type: object properties: email: type: string external_id: type: - string - "null" sso_only: type: boolean status: type: string enum: - active - suspended description: "Allowed transitions: `active` ↔ `suspended`." custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). CustomerPortalUserEmailPreviewResponse: type: object properties: data: type: object properties: type: type: string enum: - invitation - verification from: type: string to: type: string subject: type: string message: type: string required: - type - from - to - subject - message required: - data CustomerPortalUserResendResponse: type: object properties: data: type: object properties: resent: type: boolean type: type: string enum: - invitation - verification required: - resent - type required: - data PlanItemV1: type: object properties: id: type: string format: uuid plan_id: type: string format: uuid product_id: type: string format: uuid price_id: type: string format: uuid quantity: type: integer description: Quantity of the product included in the plan. example: 1 included: type: boolean description: When `true`, the item is included in the plan's price. When `false`, it's an add-on charged separately. created_at: type: string format: date-time required: - id - plan_id - product_id - price_id - quantity - included - created_at PlanV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. organization_id: type: - string - "null" format: uuid company_id: type: - string - "null" format: uuid plan_group_id: type: - string - "null" format: uuid billing_account_id: type: - string - "null" format: uuid description: When set, the plan is specific to one billing account (custom plan). name: type: string slug: type: string description: Unique identifier per organization. Only `[a-z0-9-]`. description: type: - string - "null" status: type: string enum: - draft - active - archived description: "Plan state: `draft`, `active` or `archived`." plan_type: type: string enum: - standard - custom - promotional description: "`standard`: standard public plan. `custom`: customer-specific plan. `promotional`: temporary promotional plan." visibility: type: string enum: - public - private description: "`public`: visible in the catalog. `private`: hidden." features: type: array items: type: string description: List of plan features (free-form strings). limits: type: object properties: users: type: integer subaccounts: type: integer operations_per_month: type: integer api_requests_per_day: type: integer description: Plan limits (users, subaccounts, operations, etc.). trial_period_days: type: - integer - "null" description: Trial days granted when creating a subscription for this plan. default_billing_cycle: type: string enum: - monthly - quarterly - semiannual - annual description: Default billing cycle. available_billing_cycles: type: array items: type: string enum: - monthly - quarterly - semiannual - annual description: Billing cycles allowed for this plan. metadata: type: - object - "null" additionalProperties: {} description: Read-only internal metadata generated by the system. custom_metadata: type: - object - "null" additionalProperties: {} description: Free-form custom metadata (`object`). created_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel through which the record was created (dashboard, import, api, mcp, cli, other). On API calls it comes from the `X-Request-Source` header. created_via_other: type: - string - "null" description: Name of the app that created the record when `created_via` is `other` (`X-Request-Source-Other` header). created_by_email: type: - string - "null" description: Email of the user who created the record. updated_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel of the last update to the record. updated_via_other: type: - string - "null" description: Name of the app behind the last update when `updated_via` is `other` (`X-Request-Source-Other` header). updated_by_email: type: - string - "null" description: Email of the user who made the last update. created_at: type: string format: date-time updated_at: type: string format: date-time items: type: array items: $ref: "#/components/schemas/PlanItemV1" description: Plan items. Present when included via relations. required: - id - public_id - external_id - organization_id - company_id - plan_group_id - billing_account_id - name - slug - description - status - plan_type - visibility - features - limits - trial_period_days - default_billing_cycle - available_billing_cycles - metadata - custom_metadata - created_via - created_via_other - created_by_email - updated_via - updated_via_other - updated_by_email - created_at - updated_at PlanListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/PlanV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta PlanResponse: type: object properties: data: $ref: "#/components/schemas/PlanV1" required: - data PlanItemListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/PlanItemV1" required: - data PlanItemInput: type: object properties: product_id: type: string format: uuid price_id: type: string format: uuid quantity: type: integer minimum: 1 default: 1 included: type: boolean default: true required: - product_id - price_id PlanCreateRequest: type: object properties: external_id: type: string description: Identifier in your external system, for idempotency/sync. company_id: type: string format: uuid plan_group_id: type: - string - "null" format: uuid name: type: string minLength: 1 maxLength: 255 slug: type: string minLength: 1 maxLength: 100 pattern: ^[a-z0-9-]+$ description: Lowercase letters, digits and hyphens only. description: type: - string - "null" status: type: string enum: - draft - active - archived plan_type: type: string enum: - standard - custom - promotional description: "Default: `standard`." billing_account_id: type: - string - "null" format: uuid visibility: type: string enum: - public - private description: "Default: `public`." features: type: array items: type: string limits: type: object properties: users: type: integer subaccounts: type: integer operations_per_month: type: integer api_requests_per_day: type: integer trial_period_days: type: integer minimum: 0 maximum: 90 default_billing_cycle: type: string enum: - monthly - quarterly - semiannual - annual available_billing_cycles: type: array items: type: string enum: - monthly - quarterly - semiannual - annual items: type: array items: $ref: "#/components/schemas/PlanItemInput" custom_metadata: type: - object - "null" additionalProperties: {} description: Free-form custom metadata (`object`). required: - name - slug PlanUpdateRequest: type: object properties: external_id: type: string description: Identifier in your external system, for idempotency/sync. company_id: type: - string - "null" format: uuid plan_group_id: type: - string - "null" format: uuid name: type: string minLength: 1 maxLength: 255 slug: type: string minLength: 1 maxLength: 100 pattern: ^[a-z0-9-]+$ description: Lowercase letters, digits and hyphens only. description: type: - string - "null" status: type: string enum: - draft - active - archived plan_type: type: string enum: - standard - custom - promotional description: "Default: `standard`." billing_account_id: type: - string - "null" format: uuid visibility: type: string enum: - public - private description: "Default: `public`." features: type: array items: type: string limits: type: object properties: users: type: integer subaccounts: type: integer operations_per_month: type: integer api_requests_per_day: type: integer trial_period_days: type: integer minimum: 0 maximum: 90 default_billing_cycle: type: string enum: - monthly - quarterly - semiannual - annual available_billing_cycles: type: array items: type: string enum: - monthly - quarterly - semiannual - annual items: type: array items: $ref: "#/components/schemas/PlanItemInput" custom_metadata: type: - object - "null" additionalProperties: {} description: Free-form custom metadata (`object`). PlanItemsReplaceRequest: type: object properties: items: type: array items: $ref: "#/components/schemas/PlanItemInput" required: - items PlanItemsReplaceResponse: type: array items: $ref: "#/components/schemas/PlanItemV1" PlanBulkIdsRequest: type: object properties: ids: type: array items: type: string format: uuid minItems: 1 description: List of plan UUIDs. Minimum 1. required: - ids PlanBulkMoveGroupRequest: type: object properties: ids: type: array items: type: string format: uuid minItems: 1 plan_group_id: type: - string - "null" format: uuid description: Target group UUID. Use `null` to remove the grouping. required: - ids - plan_group_id PlanBulkArchiveResponse: type: object properties: data: type: object properties: archived_count: type: integer skipped_count: type: integer skipped_ids: type: array items: type: string format: uuid required: - archived_count - skipped_count - skipped_ids required: - data PlanBulkDeleteResponse: type: object properties: data: type: object properties: deleted_count: type: integer skipped_count: type: integer skipped_ids: type: array items: type: string format: uuid required: - deleted_count - skipped_count - skipped_ids required: - data PlanBulkMoveGroupResponse: type: object properties: data: type: object properties: moved_count: type: integer required: - moved_count required: - data PlanGroupV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. organization_id: type: string format: uuid company_id: type: - string - "null" format: uuid name: type: string description: Plan group name. slug: type: - string - "null" description: Readable identifier used in public URLs. display_order: type: integer description: Display position (lower value shown first). archived_at: type: - string - "null" format: date-time description: Archive date. `null` when active. metadata: type: - object - "null" additionalProperties: {} description: Read-only internal metadata generated by the system. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - external_id - organization_id - company_id - name - slug - display_order - archived_at - metadata - custom_metadata - created_at - updated_at PlanGroupListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/PlanGroupV1" required: - data PlanGroupResponse: type: object properties: data: $ref: "#/components/schemas/PlanGroupV1" required: - data PlanGroupCreateRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 description: Plan group name. slug: type: string minLength: 1 maxLength: 100 description: Readable identifier (optional). Auto-generated when omitted. external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). required: - name PlanGroupUpdateRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 slug: type: string minLength: 1 maxLength: 100 external_id: type: string description: New identifier in your external system. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). PlanGroupReorderRequest: type: object properties: group_ids: type: array items: type: string format: uuid minItems: 1 description: List of group UUIDs in the new display order. All must belong to the current organization. required: - group_ids PlanGroupReorderResponse: type: object properties: data: type: object properties: success: type: boolean example: true required: - success required: - data ProductV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. organization_id: type: - string - "null" format: uuid company_id: type: - string - "null" format: uuid parent_product_id: type: - string - "null" format: uuid product_group_id: type: - string - "null" format: uuid service_item_id: type: - string - "null" format: uuid name: type: string description: Product display name. slug: type: string description: Readable identifier unique within the product group. Accepts only `[a-z0-9_-]+`. description: type: - string - "null" status: type: string enum: - draft - active - archived description: "Product state: `draft`, `active` or `archived`." visibility: type: string enum: - public - private description: "Visibility in the customer portal. `public`: visible to customers; `private`: operators only." product_type: type: string enum: - base - addon_quantity - addon_fixed - metered - one_time_fixed - one_time_quantity - credits description: "Product type. `base`: main plan; `addon_quantity`/`addon_fixed`: add-ons; `metered`: usage-based charging; `one_time_fixed`/`one_time_quantity`: one-time charging; `credits`: prepaid credits, bought standalone." unit_label: type: - string - "null" description: 'Unit label (e.g.: "user", "GB"). Used in invoices and the portal.' increment: type: integer description: Minimum quantity increment when changing the item. website_url: type: - string - "null" display_order: type: integer description: Display order (smaller first). is_required: type: boolean description: When `true`, the product is required in any plan it is included in. metadata: type: - object - "null" additionalProperties: {} description: Read-only internal metadata generated by the system. custom_metadata: type: - object - "null" additionalProperties: {} created_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel through which the record was created (dashboard, import, api, mcp, cli, other). On API calls it comes from the `X-Request-Source` header. created_via_other: type: - string - "null" description: Name of the app that created the record when `created_via` is `other` (`X-Request-Source-Other` header). created_by_email: type: - string - "null" description: Email of the user who created the record. updated_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel of the last update to the record. updated_via_other: type: - string - "null" description: Name of the app behind the last update when `updated_via` is `other` (`X-Request-Source-Other` header). updated_by_email: type: - string - "null" description: Email of the user who made the last update. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - external_id - organization_id - company_id - parent_product_id - product_group_id - service_item_id - name - slug - description - status - visibility - product_type - unit_label - increment - website_url - display_order - is_required - metadata - custom_metadata - created_via - created_via_other - created_by_email - updated_via - updated_via_other - updated_by_email - created_at - updated_at ProductListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/ProductV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta ProductResponse: type: object properties: data: $ref: "#/components/schemas/ProductV1" required: - data ProductCreateRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 description: Product name. slug: type: string minLength: 1 maxLength: 100 pattern: ^[a-z0-9_-]+$ description: Unique slug within the group. Accepts only `[a-z0-9_-]+`. description: type: string product_type: type: string enum: - base - addon_quantity - addon_fixed - metered - one_time_fixed - one_time_quantity - credits description: "Product type. Default: `base`." visibility: type: string enum: - public - private description: "Portal visibility. Default: `public`." unit_label: type: string increment: type: integer exclusiveMinimum: 0 description: "Minimum increment. Default: `1`." website_url: type: string format: uri is_required: type: boolean parent_product_id: type: string format: uuid product_group_id: type: string format: uuid company_id: type: string format: uuid external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: object additionalProperties: {} required: - name - slug ProductUpdateRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 slug: type: string minLength: 1 maxLength: 100 pattern: ^[a-z0-9_-]+$ description: type: string status: type: string enum: - draft - active - archived product_type: type: string enum: - base - addon_quantity - addon_fixed - metered - one_time_fixed - one_time_quantity - credits visibility: type: string enum: - public - private unit_label: type: string increment: type: integer exclusiveMinimum: 0 website_url: type: string format: uri is_required: type: boolean parent_product_id: type: - string - "null" format: uuid product_group_id: type: - string - "null" format: uuid company_id: type: - string - "null" format: uuid external_id: type: string description: New identifier in your external system. custom_metadata: type: object additionalProperties: {} ProductReorderRequest: type: object properties: product_ids: type: array items: type: string format: uuid minItems: 1 description: Product IDs in the new desired order. Index 0 becomes the first in the list. required: - product_ids ProductBulkArchiveRequest: type: object properties: ids: type: array items: type: string format: uuid minItems: 1 description: IDs of products to archive. required: - ids ProductBulkDeleteRequest: type: object properties: ids: type: array items: type: string format: uuid minItems: 1 description: IDs of products to permanently delete. required: - ids ProductBulkVisibilityRequest: type: object properties: ids: type: array items: type: string format: uuid minItems: 1 visibility: type: string enum: - public - private description: New visibility to apply to all products. required: - ids - visibility ProductBulkMoveGroupRequest: type: object properties: ids: type: array items: type: string format: uuid minItems: 1 product_group_id: type: - string - "null" format: uuid description: Target group. Use `null` to remove from the current group. required: - ids - product_group_id ProductBulkChangeCompanyRequest: type: object properties: ids: type: array items: type: string format: uuid minItems: 1 company_id: type: - string - "null" format: uuid description: Target company. Use `null` to clear the link. required: - ids - company_id ProductBulkResultResponse: type: object properties: data: {} ProductGroupV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. organization_id: type: string format: uuid company_id: type: - string - "null" format: uuid description: UUID of the issuing company associated with the group (optional). proposal_template_id: type: - string - "null" format: uuid description: UUID of the group's default proposal template (optional). service_item_id: type: - string - "null" format: uuid description: UUID of the group's default fiscal service item (optional). name: type: string description: Product group name. slug: type: string description: Readable identifier used in public URLs. Unique per organization. display_order: type: integer description: Group display order (smaller first). visibility: type: string enum: - public - private description: "Visibility in the customer portal. `public`: visible to customers; `private`: operators only." archived_at: type: - string - "null" format: date-time description: Archive date. `null` when active. metadata: type: - object - "null" additionalProperties: {} description: Read-only internal metadata generated by the system. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). created_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel through which the record was created (dashboard, import, api, mcp, cli, other). On API calls it comes from the `X-Request-Source` header. created_via_other: type: - string - "null" description: Name of the app that created the record when `created_via` is `other` (`X-Request-Source-Other` header). created_by_email: type: - string - "null" description: Email of the user who created the record. updated_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel of the last update to the record. updated_via_other: type: - string - "null" description: Name of the app behind the last update when `updated_via` is `other` (`X-Request-Source-Other` header). updated_by_email: type: - string - "null" description: Email of the user who made the last update. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - external_id - organization_id - company_id - proposal_template_id - service_item_id - name - slug - display_order - visibility - archived_at - metadata - custom_metadata - created_via - created_via_other - created_by_email - updated_via - updated_via_other - updated_by_email - created_at - updated_at ProductGroupListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/ProductGroupV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta ProductGroupResponse: type: object properties: data: $ref: "#/components/schemas/ProductGroupV1" required: - data ProductGroupCreateRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 description: Group name. slug: type: string description: Group slug. Generated from the name when omitted. visibility: type: string enum: - public - private description: "Visibility in the customer portal. Default: `public`." company_id: type: - string - "null" format: uuid proposal_template_id: type: - string - "null" format: uuid service_item_id: type: - string - "null" format: uuid external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). required: - name ProductGroupUpdateRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 slug: type: string visibility: type: string enum: - public - private description: New visibility in the customer portal (`public` or `private`). company_id: type: - string - "null" format: uuid proposal_template_id: type: - string - "null" format: uuid service_item_id: type: - string - "null" format: uuid external_id: type: string description: New identifier in your external system. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). ProductGroupReorderRequest: type: object properties: group_ids: type: array items: type: string format: uuid minItems: 1 description: List of UUIDs in the new desired order. All IDs must belong to the organization. required: - group_ids ProductGroupReorderResponse: type: object properties: data: type: object properties: success: type: boolean example: true required: - success required: - data ProductGroupDeletedResponse: type: object properties: data: type: object properties: deleted: type: boolean example: true required: - deleted required: - data OrganizationPersonV1: type: object properties: id: type: string format: uuid name: type: string description: Legal name or display name. nickname: type: - string - "null" legal_name: type: - string - "null" document_type: type: - string - "null" enum: - cpf - cnpj description: "Document type: `cpf` or `cnpj`." document_number: type: - string - "null" description: Document number (digits only). kind: type: - string - "null" enum: - individual - company birthday: type: - string - "null" notes: type: - string - "null" addresses: description: List of addresses. phones: description: List of contact phones. emails: description: List of contact emails. websites: {} tags: type: - array - "null" items: type: string custom_metadata: type: - object - "null" additionalProperties: {} metadata: type: - object - "null" additionalProperties: {} type: type: string parent_id: type: - string - "null" format: uuid external_id: type: - string - "null" created_at: type: string format: date-time updated_at: type: string format: date-time required: - name OrganizationV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. external_id: type: - string - "null" description: External identifier for the organization in Kobana's system. status: type: string description: "Organization status (e.g.: `active`)." created_at: type: string format: date-time updated_at: type: string format: date-time metadata: type: - object - "null" additionalProperties: {} description: Arbitrary metadata. Internal keys (`apiKeys`, `encryptionKey`, `secrets`) are stripped before the response. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). Unlike `metadata`, it is not sanitized — do not store secrets here. person: allOf: - $ref: "#/components/schemas/OrganizationPersonV1" - description: Organization registration data (name, document, contacts, addresses). Always included. required: - id - public_id - external_id - status - created_at - updated_at - person OrganizationResponse: type: object properties: data: $ref: "#/components/schemas/OrganizationV1" required: - data OrganizationUpdateRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 description: Display name of the organization. email: type: string format: email description: Primary contact email of the organization. phone: type: string description: Primary contact phone of the organization. addresses: type: array items: {} description: List of organization addresses. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). CompanyPersonV1: type: object properties: id: type: string format: uuid name: type: string nickname: type: - string - "null" legal_name: type: - string - "null" description: Legal name. document_type: type: - string - "null" enum: - cpf - cnpj description: "Document type: `cpf` or `cnpj`." document_number: type: - string - "null" description: Document number (CPF or CNPJ), stored as digits only. kind: type: - string - "null" birthday: type: - string - "null" notes: type: - string - "null" addresses: {} phones: {} emails: {} websites: {} tags: type: - array - "null" items: type: string custom_metadata: type: - object - "null" additionalProperties: {} metadata: type: - object - "null" additionalProperties: {} type: type: string parent_id: type: - string - "null" external_id: type: - string - "null" description: Identifier of the `Person` record in the source system. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - name CompanyV1: type: object properties: id: type: string format: uuid public_id: type: - string - "null" description: Short public identifier of the company (stable and safe to display). external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. organization_id: type: string format: uuid description: UUID of the owning organization (tenant). person_id: type: string format: uuid description: UUID of the associated `Person` record (legal identity) for this company. parent_company_id: type: - string - "null" format: uuid description: Head office UUID when this company is a branch; `null` for head offices. is_default: type: boolean description: Whether this is the default company for the organization. Only head offices can be default. status: type: string enum: - active - inactive description: "Company status: `active` or `inactive`." metadata: type: - object - "null" additionalProperties: {} description: Internal company metadata (free-form key/value). custom_metadata: type: - object - "null" additionalProperties: {} description: Custom metadata defined by the client (free-form key/value). created_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel through which the record was created (dashboard, import, api, mcp, cli, other). On API calls it comes from the `X-Request-Source` header. created_via_other: type: - string - "null" description: Name of the app that created the record when `created_via` is `other` (`X-Request-Source-Other` header). created_by_email: type: - string - "null" description: Email of the user who created the record. updated_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel of the last update to the record. updated_via_other: type: - string - "null" description: Name of the app behind the last update when `updated_via` is `other` (`X-Request-Source-Other` header). updated_by_email: type: - string - "null" description: Email of the user who made the last update. created_at: type: string format: date-time updated_at: type: string format: date-time person: allOf: - $ref: "#/components/schemas/CompanyPersonV1" - description: Company's legal identity (name, legal name, document, contacts). required: - id - public_id - organization_id - person_id - parent_company_id - is_default - status - metadata - custom_metadata - created_via - created_via_other - created_by_email - updated_via - updated_via_other - updated_by_email - created_at - updated_at CompanyListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/CompanyV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta CompanyResponse: type: object properties: data: $ref: "#/components/schemas/CompanyV1" required: - data CompanyMatrizListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/CompanyV1" required: - data CompanyDeleteResponse: type: object properties: data: type: object properties: deleted: type: boolean example: true required: - deleted required: - data CompanyCreateRequest: type: object properties: parent_company_id: type: string format: uuid description: Head office UUID when creating a branch. Omit to create a head office. name: type: string minLength: 1 maxLength: 255 description: Trade name of the company. external_id: type: string description: Identifier in your external system, for idempotency/sync. legal_name: type: string maxLength: 255 description: Legal name. document_type: type: string enum: - cpf - cnpj description: "Document type: `cpf` or `cnpj`. Only `cnpj` can have branches." document_number: type: string minLength: 11 maxLength: 18 description: CPF or CNPJ (with or without mask — will be normalized to digits only). email: type: string format: email description: Primary company email. phone: type: string description: Primary company phone. When provided, it is added to the `phones` array. addresses: type: array items: type: object additionalProperties: {} description: List of company addresses. emails: type: array items: type: object additionalProperties: {} description: List of additional emails. If omitted, the primary `email` is used. phones: type: array items: type: object additionalProperties: {} description: List of company phones. websites: type: array items: type: object additionalProperties: {} description: List of company websites. is_default: type: boolean description: When `true`, sets this company as the organization default. Only head offices can be default. custom_metadata: type: - object - "null" additionalProperties: {} description: Custom metadata (free-form key/value). required: - name - document_type - document_number - email CompanyUpdateRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 description: New trade name. external_id: type: string description: Identifier in your external system, for idempotency/sync. legal_name: type: string maxLength: 255 description: New legal name. email: type: string format: email description: New primary email. Updates the first entry of the `emails` array. phone: type: string description: New primary phone. Updates the first entry of the `phones` array. addresses: type: array items: type: object additionalProperties: {} description: Replaces the addresses list. emails: type: array items: type: object additionalProperties: {} description: Replaces the emails list. phones: type: array items: type: object additionalProperties: {} description: Replaces the phones list. websites: type: array items: type: object additionalProperties: {} description: Replaces the websites list. is_default: type: boolean description: When `true`, marks this company as default. Use the `set-default` endpoint for the dedicated operation. custom_metadata: type: - object - "null" additionalProperties: {} description: Replaces the custom metadata. custom_metadata_mode: type: string enum: - replace - merge description: How the submitted `custom_metadata` is reconciled with the stored value. `replace` (default) overwrites the whole object; `merge` deep-merges over the current value — nested objects merge recursively, scalars and arrays overwrite the key, and `null` keys are kept (they do not delete the key). Accepted on update only. example: merge CompanyFiscalProfileUpsertRequest: type: object properties: taxation_regime: type: string enum: - simple_national - presumed_profit - real_profit - mei description: "Taxation regime: `simple_national`, `presumed_profit`, `real_profit` or `mei`." simples_annex: type: - string - "null" enum: - annex_iii - annex_iv - annex_v description: "Simples Nacional annex: `annex_iii`, `annex_iv` or `annex_v`." rbt12: type: - number - "null" minimum: 0 description: Gross revenue accumulated over the last 12 months, in BRL (float, up to 4 decimal places). factor_r: type: - number - "null" description: Factor R (payroll ÷ revenue), used for Simples Nacional bracket classification. cpp_inside_das: type: boolean description: Whether CPP (employer social security contribution) is bundled into DAS. presumption_rate: type: - number - "null" description: "Presumption rate (presumed profit), as decimal (e.g.: 0.32)." iss_municipality: type: - string - "null" description: Municipality where ISS is levied. iss_rate: type: - number - "null" description: ISS rate, as decimal. pis_rate: type: - number - "null" description: PIS rate, as decimal. cofins_rate: type: - number - "null" description: COFINS rate, as decimal. csll_rate: type: - number - "null" description: CSLL rate, as decimal. irpj_rate: type: - number - "null" description: IRPJ rate, as decimal. cbs_ibs_enabled: type: boolean description: Enables the CBS/IBS fields (Brazilian tax reform). cbs_rate: type: - number - "null" description: CBS rate, as decimal. ibs_rate: type: - number - "null" description: IBS rate, as decimal. cbs_ibs_mode: type: string enum: - informative - compositive description: "CBS/IBS calculation mode: `informative` (display only) or `compositive` (composes the price)." required: - taxation_regime CompanyFiscalProfileResponse: type: object properties: data: {} CertificatePersonV1: type: object properties: id: type: string format: uuid description: Person UUID. name: type: string description: Person name. document_number: type: - string - "null" description: Person CPF or CNPJ. required: - id - name - document_number CertificateV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. person_id: type: - string - "null" format: uuid description: UUID of the associated `person` (when the document matches an existing record). name: type: string description: Friendly name for the certificate. status: type: string enum: - active - expired - revoked description: "Certificate status: `active`, `expired` or `revoked`." format: type: string enum: - pfx - pem description: "Stored certificate format: `pfx` or `pem`." document: type: - string - "null" description: CPF or CNPJ extracted from the certificate (digits only). common_name: type: - string - "null" description: Subject common name (`CN`) of the certificate. organization_name: type: - string - "null" description: Subject organization name (`O`). organizational_unit: type: - string - "null" description: Subject organizational unit (`OU`). issuer_common_name: type: - string - "null" description: Issuer (CA) common name (`CN`). issuer_organization: type: - string - "null" description: Issuer (CA) organization (`O`). serial_number: type: - string - "null" description: Certificate serial number. thumbprint: type: - string - "null" description: Certificate SHA-1 thumbprint (uppercase hex). Unique per certificate. not_before: type: - string - "null" format: date-time description: Certificate validity start (UTC). not_after: type: - string - "null" format: date-time description: Certificate validity end (UTC). metadata: type: object additionalProperties: {} description: Internal certificate metadata. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata. created_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel through which the record was created (dashboard, import, api, mcp, cli, other). On API calls it comes from the `X-Request-Source` header. created_via_other: type: - string - "null" description: Name of the app that created the record when `created_via` is `other` (`X-Request-Source-Other` header). created_by_email: type: - string - "null" description: Email of the user who created the record. updated_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel of the last update to the record. updated_via_other: type: - string - "null" description: Name of the app behind the last update when `updated_via` is `other` (`X-Request-Source-Other` header). updated_by_email: type: - string - "null" description: Email of the user who made the last update. created_at: type: string format: date-time updated_at: type: string format: date-time person: allOf: - $ref: "#/components/schemas/CertificatePersonV1" - type: - object - "null" description: Summary of the associated `person` (id, name, document_number), when loaded. required: - id - public_id - person_id - name - status - format - document - common_name - organization_name - organizational_unit - issuer_common_name - issuer_organization - serial_number - thumbprint - not_before - not_after - created_via - created_via_other - created_by_email - updated_via - updated_via_other - updated_by_email - created_at - updated_at CertificateListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/CertificateV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta CertificateResponse: type: object properties: data: $ref: "#/components/schemas/CertificateV1" required: - data CertificateUploadRequest: type: object properties: type: type: string enum: - pfx - cert_key - combined_pem - cert_key_password description: "Upload format: `pfx`, `cert_key`, `combined_pem` or `cert_key_password`." name: type: string description: Friendly certificate name. When omitted, it is derived from `common_name` or the document. file: type: string description: Binary file (PFX/P12) when `type=pfx`, or combined PEM when `type=combined_pem`. format: binary cert_file: type: string description: Certificate PEM file (only for `type=cert_key` or `type=cert_key_password`). format: binary key_file: type: string description: Private key PEM file (only for `type=cert_key` or `type=cert_key_password`). format: binary password: type: string description: PFX password (`type=pfx`) or private key password (`type=cert_key_password`). Stored encrypted and never returned. external_id: type: string description: Identifier in your external system, for idempotency/sync. required: - type CouponTargetV1: type: object properties: plan_ids: type: array items: type: string format: uuid description: List of plan UUIDs. product_ids: type: array items: type: string format: uuid description: List of product UUIDs. CouponV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. code: type: string description: Public coupon code — used by customers when applying the discount. Unique per organization. name: type: string description: Internal coupon name (shown in the dashboard). description: type: - string - "null" description: Optional coupon description. discount_type: type: string enum: - percentage - fixed_amount description: "Discount type: `percentage` (in percentage points) or `fixed_amount` (in BRL, ÷100 → BRL)." discount_value: type: number description: Discount value. When `discount_type=percentage`, an integer between `0` and `100`. When `discount_type=fixed_amount`, the amount in BRL (float, up to 4 decimal places). example: 10 currency: type: string description: "ISO 4217 currency. Default: `BRL`." example: BRL min_purchase: type: - number - "null" description: Minimum invoice amount (in BRL, ÷100 → BRL) for the coupon to be applicable. max_discount: type: - number - "null" description: Absolute discount cap (in BRL, ÷100 → BRL). Mainly used with percentage coupons. usage_limit: type: - integer - "null" description: Total number of times the coupon can be redeemed across the organization. `null` = unlimited. usage_limit_per_user: type: - integer - "null" description: Maximum number of redemptions per billing account. `null` = unlimited. usage_count: type: integer description: Number of redemptions already recorded for the coupon. example: 0 valid_from: type: - string - "null" format: date-time description: Start of the validity window (ISO 8601). `null` = no defined start. valid_until: type: - string - "null" format: date-time description: End of the validity window (ISO 8601). `null` = no expiration. applies_to: allOf: - $ref: "#/components/schemas/CouponTargetV1" - type: - object - "null" description: Restricts the coupon to specific plans and/or products. When `null`, applies to any item. excludes: allOf: - $ref: "#/components/schemas/CouponTargetV1" - type: - object - "null" description: List of plans and/or products where the coupon **cannot** be applied. is_active: type: boolean description: When `false`, the coupon no longer accepts new redemptions. metadata: type: - object - "null" additionalProperties: {} description: Read-only internal metadata generated by the system. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). created_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel through which the record was created (dashboard, import, api, mcp, cli, other). On API calls it comes from the `X-Request-Source` header. created_via_other: type: - string - "null" description: Name of the app that created the record when `created_via` is `other` (`X-Request-Source-Other` header). created_by_email: type: - string - "null" description: Email of the user who created the record. updated_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel of the last update to the record. updated_via_other: type: - string - "null" description: Name of the app behind the last update when `updated_via` is `other` (`X-Request-Source-Other` header). updated_by_email: type: - string - "null" description: Email of the user who made the last update. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - code - name - description - discount_type - discount_value - currency - min_purchase - max_discount - usage_limit - usage_limit_per_user - usage_count - valid_from - valid_until - applies_to - excludes - is_active - custom_metadata - created_via - created_via_other - created_by_email - updated_via - updated_via_other - updated_by_email - created_at - updated_at CouponListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/CouponV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta CouponResponse: type: object properties: data: $ref: "#/components/schemas/CouponV1" required: - data CouponCreateRequest: type: object properties: code: type: string minLength: 1 description: Public coupon code — unique per organization. external_id: type: string description: Identifier in your external system, for idempotency/sync. name: type: string minLength: 1 description: Internal coupon name. description: type: string description: Optional description. discount_type: type: string enum: - percentage - fixed_amount description: "Discount type: `percentage` or `fixed_amount`." discount_value: type: number minimum: 0 description: Discount value. For `percentage`, integer between `0` and `100`. For `fixed_amount`, amount in BRL (float, up to 4 decimal places). currency: type: string description: "ISO 4217 currency. Default: `BRL`." min_purchase: type: number minimum: 0 description: Minimum invoice amount, in BRL (float, up to 4 decimal places), for the coupon to be applicable. max_discount: type: number minimum: 0 description: Absolute discount cap, in BRL (float, up to 4 decimal places). usage_limit: type: integer exclusiveMinimum: 0 description: Maximum total redemptions across the organization. Omit for unlimited. usage_limit_per_user: type: integer exclusiveMinimum: 0 description: Maximum redemptions per billing account. Omit for unlimited. valid_from: type: string description: Start of the validity window (ISO 8601 — date or date-time). valid_until: type: string description: End of the validity window (ISO 8601 — date or date-time). applies_to: allOf: - $ref: "#/components/schemas/CouponTargetV1" - description: Restricts the coupon to plans and/or products. excludes: allOf: - $ref: "#/components/schemas/CouponTargetV1" - description: List of plans and/or products where the coupon cannot be applied. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). required: - code - name - discount_type - discount_value CouponUpdateRequest: type: object properties: name: type: string minLength: 1 description: New internal coupon name. external_id: type: string description: Identifier in your external system, for idempotency/sync. description: type: - string - "null" description: New description. Send `null` to clear. usage_limit: type: - integer - "null" exclusiveMinimum: 0 description: New total redemption limit. `null` = unlimited. usage_limit_per_user: type: - integer - "null" exclusiveMinimum: 0 description: New per-billing-account limit. `null` = unlimited. valid_from: type: - string - "null" description: New validity start (ISO 8601). `null` = removes the restriction. valid_until: type: - string - "null" description: New validity end (ISO 8601). `null` = removes the expiration. applies_to: allOf: - $ref: "#/components/schemas/CouponTargetV1" - type: - object - "null" description: New plan/product restriction. `null` = removes the restriction. excludes: allOf: - $ref: "#/components/schemas/CouponTargetV1" - type: - object - "null" description: New exclusion list. `null` = removes the exclusions. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). custom_metadata_mode: type: string enum: - replace - merge description: How the submitted `custom_metadata` is reconciled with the stored value. `replace` (default) overwrites the whole object; `merge` deep-merges over the current value — nested objects merge recursively, scalars and arrays overwrite the key, and `null` keys are kept (they do not delete the key). Accepted on update only. example: merge CouponRedemptionV1: type: object properties: id: type: string format: uuid coupon_id: type: string format: uuid description: UUID of the redeemed coupon. billing_account_id: type: string format: uuid description: UUID of the billing account that applied the coupon. invoice_id: type: - string - "null" format: uuid description: UUID of the invoice the discount was applied to, when applicable. discount: type: number description: Discount actually applied in this redemption, in BRL (float, up to 4 decimal places). created_at: type: string format: date-time required: - id - coupon_id - billing_account_id - invoice_id - discount - created_at CouponRedemptionListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/CouponRedemptionV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta CreditV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. billing_account_id: type: string format: uuid description: UUID of the billing account that owns the credit. organization_id: type: string format: uuid description: Organization (tenant) UUID. company_id: type: - string - "null" format: uuid description: Optional UUID of the linked `company`. When set, the credit can only be applied to invoices from the same `company`. type: type: string enum: - promotional - adjustment - refund - manual description: "Credit type: `promotional`, `adjustment`, `refund` or `manual`." amount: type: number description: Original credit amount in BRL (float, up to 4 decimal places). example: 100 amount_remaining: type: number description: Remaining credit balance in BRL (float, up to 4 decimal places). example: 100 currency: type: string description: "ISO 4217 currency (e.g.: `BRL`)." example: BRL description: type: - string - "null" description: Free-form description — shown in the statement and audit log. expires_at: type: - string - "null" format: date-time description: Expiration date and time (ISO8601). `null` when the credit does not expire. metadata: type: - object - "null" additionalProperties: {} description: Internal credit metadata. custom_metadata: type: - object - "null" additionalProperties: {} description: Custom metadata validated against the organization schema. created_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel through which the record was created (dashboard, import, api, mcp, cli, other). On API calls it comes from the `X-Request-Source` header. created_via_other: type: - string - "null" description: Name of the app that created the record when `created_via` is `other` (`X-Request-Source-Other` header). created_by_email: type: - string - "null" description: Email of the user who created the record. updated_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel of the last update to the record. updated_via_other: type: - string - "null" description: Name of the app behind the last update when `updated_via` is `other` (`X-Request-Source-Other` header). updated_by_email: type: - string - "null" description: Email of the user who made the last update. created_at: type: string format: date-time updated_at: type: string format: date-time applications: type: array items: {} description: Applications of this credit to invoices, when the relation is loaded. required: - id - public_id - external_id - billing_account_id - organization_id - company_id - type - amount - amount_remaining - currency - description - expires_at - metadata - custom_metadata - created_via - created_via_other - created_by_email - updated_via - updated_via_other - updated_by_email - created_at - updated_at CreditListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/CreditV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta CreditResponse: type: object properties: data: $ref: "#/components/schemas/CreditV1" required: - data CreditCreateRequest: type: object properties: billing_account_id: type: string format: uuid description: UUID of the billing account that will receive the credit. external_id: type: string description: Identifier in your external system, for idempotency/sync. company_id: type: string format: uuid description: Optional UUID of the `company` the credit is tied to. When set, restricts credit application to invoices from the same `company`. type: type: string enum: - promotional - adjustment - refund - manual description: "Credit type: `promotional`, `adjustment`, `refund` or `manual`." amount: type: number exclusiveMinimum: 0 description: Credit amount in BRL (float, up to 4 decimal places). Must be a positive integer. example: 100 description: type: string maxLength: 500 description: Free-form description (up to 500 characters) — shown in the statement and audit log. expires_at: type: string format: date-time description: Expiration date and time (ISO8601). After this date the remaining balance is discarded. custom_metadata: type: - object - "null" additionalProperties: {} description: Custom metadata validated against the organization schema. required: - billing_account_id - type - amount CreditUpdateRequest: type: object properties: external_id: type: - string - "null" description: New identifier in your external system. Send `null` to clear. type: type: string enum: - promotional - adjustment - refund - manual description: "New credit type: `promotional`, `adjustment`, `refund` or `manual`." amount: type: number exclusiveMinimum: 0 description: New amount in BRL (float, up to 4 decimal places). Positive integer. Can only change if the credit has not been used yet. description: type: - string - "null" maxLength: 500 description: New description. Send `null` to clear. expires_at: type: - string - "null" format: date-time description: New expiration date (ISO8601). Send `null` to remove the expiration. custom_metadata: type: - object - "null" additionalProperties: {} description: Custom metadata validated against the organization schema. custom_metadata_mode: type: string enum: - replace - merge description: How the submitted `custom_metadata` is reconciled with the stored value. `replace` (default) overwrites the whole object; `merge` deep-merges over the current value — nested objects merge recursively, scalars and arrays overwrite the key, and `null` keys are kept (they do not delete the key). Accepted on update only. example: merge CreditDeleteResponse: type: object properties: data: type: object properties: deleted: type: boolean example: true required: - deleted required: - data InvoiceLineItemV1: type: object properties: id: type: string format: uuid invoice_id: type: string format: uuid subscription_item_id: type: - string - "null" format: uuid product_id: type: - string - "null" format: uuid price_id: type: - string - "null" format: uuid service_item_id: type: - string - "null" format: uuid type: type: - string - "null" description: type: - string - "null" description: Item description. quantity: type: number description: Quantity. unit_amount: type: number description: Unit amount in sub-cents (float, up to 4 decimal places). amount: type: number description: Item subtotal in BRL (float, up to 4 decimal places). discount: type: - number - "null" tax: type: - number - "null" period_start: type: - string - "null" format: date-time period_end: type: - string - "null" format: date-time proration: type: - boolean - "null" proration_details: {} metadata: type: - object - "null" additionalProperties: {} created_at: type: string format: date-time required: - id - invoice_id - quantity - unit_amount - amount - created_at InvoiceInstallmentV1: type: object properties: id: type: string format: uuid public_id: type: - string - "null" invoice_id: type: string format: uuid number: type: integer description: Sequential installment number (starts at 1). amount: type: number description: Gross (fiscal) installment amount in BRL (float, up to 4 decimal places). The installments add up to the invoice total. The payable amount is `net`. credit_applied: type: number description: "Portion of the installment already covered by account credits, in BRL (float, up to 4 decimal places). Credits applied to the invoice are distributed FIFO: the first installment is covered first and the surplus overflows to the next one. The payable amount is `net`." withheld: type: number description: Share of the invoice withholdings (taxes withheld at source by the customer) allocated to the installment, in BRL (float, up to 4 decimal places). Withholdings are split proportionally to each installment amount, in whole cents, with the rounding residual on the first installment. This amount is not charged to the customer. net: type: number description: "Payable installment amount in BRL: `amount − withheld − credit_applied` (float, up to 4 decimal places). This is the amount `POST /invoices/{id}/pay` requires when the installment is selected." due_date: type: string format: date-time description: Installment due date. status: type: string enum: - pending - paid - canceled description: "Installment status: `pending`, `paid` or `canceled`." payment_id: type: - string - "null" format: uuid paid_at: type: - string - "null" format: date-time late_fine_received: type: number description: Late-payment fine received on this installment, in BRL. Each installment goes late and accrues on its own. late_interest_received: type: number description: Late-payment interest received on this installment, in BRL. metadata: type: - object - "null" additionalProperties: {} created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - invoice_id - number - amount - credit_applied - withheld - net - due_date - status - created_at - updated_at InvoiceV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. number: type: - string - "null" description: Human-readable invoice number (generated on finalization). billing_account_id: type: string format: uuid description: Target billing account UUID. company_id: type: - string - "null" format: uuid description: Issuing company UUID (optional — defaults to the organization's `default_company`). subscription_id: type: - string - "null" format: uuid description: Originating subscription UUID, when the invoice comes from a subscription. product_group_id: type: - string - "null" format: uuid description: Product group UUID, when the invoice is scoped to a group. status: type: string enum: - draft - open - paid - void - uncollectible description: "Status: `draft`, `open`, `paid`, `void` or `uncollectible`." collection_method: type: string enum: - charge_automatically - manual_charge - manual_invoice description: "Collection method: `charge_automatically`, `manual_charge` or `manual_invoice`." currency: type: string description: "ISO 4217 currency (e.g.: `BRL`)." example: BRL subtotal: type: number description: Sum of line items in BRL (float, up to 4 decimal places). discount: type: number description: Discount applied in BRL (float, up to 4 decimal places). tax: type: number description: Computed taxes in BRL (float, up to 4 decimal places). total_withheld: type: number description: Total tax withholdings (IRRF/ISS/INSS/CSRF) in BRL. net_value: type: - number - "null" description: Net value after withholdings, in BRL. total: type: number description: Invoice total in BRL (float, up to 4 decimal places). amount_due: type: number description: Amount due (charged) in BRL. amount_paid: type: number description: Amount already paid in BRL. amount_remaining: type: number description: Amount remaining to pay in BRL. late_fine_received: type: number description: Late-payment fine actually received, in BRL. Cumulative; not part of `total`, since a fine is financial revenue and sits outside the NFe tax base. late_interest_received: type: number description: Late-payment interest actually received, in BRL. Cumulative; not part of `total`, for the same reason as the fine. late_fee_policy_id: type: - string - "null" format: uuid description: Late fee policy for this invoice. Null inherits from the subscription, then the billing account, then the organization default. At finalization the invoice freezes the policy in force, so a later renegotiation does not change what it charges. period_start: type: - string - "null" format: date-time description: Start of the billing period (subscription invoices). period_end: type: - string - "null" format: date-time description: End of the billing period (subscription invoices). due_date: type: - string - "null" format: date-time description: Due date. paid_at: type: - string - "null" format: date-time description: Date and time the invoice was settled. voided_at: type: - string - "null" format: date-time description: Date and time the invoice was voided. finalized_at: type: - string - "null" format: date-time description: Date and time the invoice left draft (`draft` → `open`). billing_reason: type: - string - "null" description: "Generation reason: `subscription_cycle`, `subscription_create`, `manual`, etc." description: type: - string - "null" description: Free-form description shown at the top of the invoice. footer: type: - string - "null" description: Free-form footer shown at the bottom of the invoice. hosted_invoice_url: type: - string - "null" description: Public hosted invoice URL. invoice_pdf_url: type: - string - "null" description: Direct URL to the invoice PDF. next_payment_attempt: type: - string - "null" format: date-time description: Next automatic charge attempt (dunning). payment_attempts: type: integer description: Number of charge attempts made. installment_count: type: - integer - "null" description: Number of installments (when the invoice is split). nfe_issuance_policy: type: - string - "null" enum: - disabled - on_finalization - on_full_payment - per_installment description: "NF-e issuance policy: `disabled`, `on_finalization`, `on_full_payment` or `per_installment`." metadata: type: - object - "null" additionalProperties: {} description: Read-only internal metadata generated by the system. custom_metadata: type: - object - "null" additionalProperties: {} description: Custom fields defined by the organization. created_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel through which the record was created (dashboard, import, api, mcp, cli, other). On API calls it comes from the `X-Request-Source` header. created_via_other: type: - string - "null" description: Name of the app that created the record when `created_via` is `other` (`X-Request-Source-Other` header). created_by_email: type: - string - "null" description: Email of the user who created the record. updated_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel of the last update to the record. updated_via_other: type: - string - "null" description: Name of the app behind the last update when `updated_via` is `other` (`X-Request-Source-Other` header). updated_by_email: type: - string - "null" description: Email of the user who made the last update. created_at: type: string format: date-time updated_at: type: string format: date-time line_items: type: array items: $ref: "#/components/schemas/InvoiceLineItemV1" description: Line items — present when included via `include=line_items`. installments: type: array items: $ref: "#/components/schemas/InvoiceInstallmentV1" description: Installments — present when included via `include=installments`. required: - id - public_id - external_id - number - billing_account_id - company_id - subscription_id - product_group_id - status - collection_method - currency - subtotal - discount - tax - total_withheld - net_value - total - amount_due - amount_paid - amount_remaining - late_fine_received - late_interest_received - late_fee_policy_id - period_start - period_end - due_date - paid_at - voided_at - finalized_at - billing_reason - description - footer - hosted_invoice_url - invoice_pdf_url - next_payment_attempt - payment_attempts - installment_count - nfe_issuance_policy - metadata - created_via - created_via_other - created_by_email - updated_via - updated_via_other - updated_by_email - created_at - updated_at InvoiceListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/InvoiceV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta InvoiceResponse: type: object properties: data: $ref: "#/components/schemas/InvoiceV1" required: - data InvoiceLineItemCreateInput: type: object properties: description: type: string minLength: 1 description: Item description. **Required**. quantity: type: number minimum: 1 description: "Quantity. Default: 1." unit_amount: type: number minimum: 0 description: Unit amount in BRL. product_id: type: string format: uuid description: Product UUID (optional). price_id: type: string format: uuid description: Price UUID (optional). service_item_id: type: string format: uuid description: Service item UUID (optional). required: - description - unit_amount InvoiceInstallmentCreateInput: type: object properties: amount: type: number exclusiveMinimum: 0 description: Installment amount in BRL. due_date: type: string description: Installment due date. required: - amount - due_date InvoiceCreateRequest: type: object properties: billing_account_id: type: string format: uuid description: Target billing account UUID. **Required**. external_id: type: string description: Identifier in your external system, for idempotency/sync. company_id: type: string format: uuid description: "Issuing company UUID. Default: organization's default company." subscription_id: type: string format: uuid description: Originating subscription UUID. product_group_id: type: string format: uuid description: Product group UUID. collection_method: type: string enum: - charge_automatically - manual_charge - manual_invoice description: "Collection method. Default: `manual_invoice`." due_date: type: string description: "Due date. Default: today + the account's `payment_terms_days`." description: type: string description: Free-form description shown at the top of the invoice. footer: type: string description: Free-form footer shown at the bottom of the invoice. line_items: type: array items: $ref: "#/components/schemas/InvoiceLineItemCreateInput" minItems: 1 maxItems: 200 description: Line items. Minimum 1. discount: type: number minimum: 0 description: Fixed discount in BRL. discount_description: type: string description: 'Discount description (e.g.: "20% annual payment discount").' installments: type: array items: $ref: "#/components/schemas/InvoiceInstallmentCreateInput" minItems: 2 maxItems: 60 description: Installment schedule (minimum 2). Each item has `amount` and `due_date`. nfe_issuance_policy: type: string enum: - disabled - on_finalization - on_full_payment - per_installment description: NF-e issuance policy for installment invoices. period_start: type: string description: Start of the billing period (auto-set for subscription invoices). period_end: type: string description: End of the billing period (auto-set for subscription invoices). custom_metadata: type: - object - "null" additionalProperties: {} description: Custom fields (validated against the organization's schema). required: - billing_account_id - line_items InvoiceLineItemUpdateInput: type: object properties: id: type: string format: uuid description: type: string minLength: 1 quantity: type: number minimum: 1 unit_amount: type: number minimum: 0 required: - description - unit_amount InvoiceUpdateRequest: type: object properties: external_id: type: - string - "null" description: New identifier in your external system. Use `null` to clear. company_id: type: - string - "null" format: uuid description: Update the issuing company. Use `null` to clear. collection_method: type: string enum: - charge_automatically - manual_charge - manual_invoice description: Update the collection method. due_date: type: string description: Update the due date. period_start: type: - string - "null" description: Update the start of the billing period. Use `null` to clear. period_end: type: - string - "null" description: Update the end of the billing period. Use `null` to clear. description: type: string footer: type: string line_items: type: array items: $ref: "#/components/schemas/InvoiceLineItemUpdateInput" maxItems: 200 description: Replaces line items. To preserve an item, pass its `id`. nfe_issuance_policy: type: - string - "null" enum: - disabled - on_finalization - on_full_payment - per_installment description: Update the NF-e policy. Use `null` to clear. custom_metadata: type: - object - "null" additionalProperties: {} custom_metadata_mode: type: string enum: - replace - merge description: How the submitted `custom_metadata` is reconciled with the stored value. `replace` (default) overwrites the whole object; `merge` deep-merges over the current value — nested objects merge recursively, scalars and arrays overwrite the key, and `null` keys are kept (they do not delete the key). Accepted on update only. example: merge InvoiceVoidRequest: type: object properties: reason: type: string description: Void reason (recorded in the audit log). InvoiceUndoPaymentRequest: type: object properties: reason: type: string description: Reversal reason (recorded in the audit log). InvoicePayRequest: type: object properties: payment_method: type: string enum: - pix - bank_slip - card - bank_transfer description: When provided, triggers the gateway (`pix`, `bank_slip` or `card`) or creates a transfer charge (`bank_transfer`, requires `bank_account_id` or `pix_key_id`). Omit to mark as paid manually. payment_method_id: type: string format: uuid description: "UUID of a saved payment method (e.g.: tokenized card)." card: type: object properties: card_token: type: string minLength: 1 description: Card token obtained on the front-end via the gateway SDK. holder_name: type: string minLength: 3 description: Name printed on the card (minimum 3 characters). required: - card_token - holder_name description: Card data when `payment_method = card` and no `payment_method_id` is provided. bank_account_id: type: string format: uuid description: "With `payment_method = bank_transfer`: UUID of the organization bank account the customer should transfer to (see `/bank_accounts`). Send this or `pix_key_id`, never both." pix_key_id: type: string format: uuid description: "With `payment_method = bank_transfer`: UUID of the organization Pix key the customer should transfer to (see `/pix_keys`). Send this or `bank_account_id`, never both." amount: type: number exclusiveMinimum: 0 description: "Amount to charge in BRL. Default: invoice remaining amount. Required when `installment_ids` is given, and must equal the sum of the selected installments' `net`." installment_ids: type: array items: type: string format: uuid description: UUIDs of the installments the payment covers (split invoices). InvoicePayResponse: type: object properties: data: type: object additionalProperties: {} required: - data InvoiceApplyCreditsRequest: type: object properties: credit_ids: type: array items: type: string format: uuid minItems: 1 description: UUIDs of the credits to apply (minimum 1). amount: type: number exclusiveMinimum: 0 description: "Amount to apply in BRL. Default: covers the entire invoice." required: - credit_ids InvoiceCreditsResponse: type: object properties: data: type: object additionalProperties: {} required: - data InvoiceNfeResponse: type: object properties: data: type: object additionalProperties: {} required: - data InvoicePaymentMethodsResponse: type: object properties: data: type: object properties: invoice_id: type: string format: uuid methods: type: array items: type: string enum: - card - bank_slip - pix - bank_transfer details: type: array items: type: object properties: type: type: string enum: - card - bank_slip - pix - bank_transfer gateway_id: type: - string - "null" format: uuid gateway_name: type: - string - "null" is_default: type: boolean required: - type - gateway_id - gateway_name - is_default pagarme_public_key: type: string required: - invoice_id - methods - details required: - data InvoiceInstallmentsListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/InvoiceInstallmentV1" required: - data InvoiceInstallmentsCreateRequest: type: object properties: installments: type: array items: $ref: "#/components/schemas/InvoiceInstallmentCreateInput" minItems: 2 maxItems: 60 description: Installment list. Minimum 2. required: - installments InvoiceInstallmentResponse: type: object properties: data: allOf: - $ref: "#/components/schemas/InvoiceInstallmentV1" - type: - object - "null" required: - data InvoiceInstallmentPayRequest: type: object properties: payment_method: type: string enum: - pix - bank_slip - card - bank_transfer description: When provided, triggers the gateway (`pix`, `bank_slip` or `card`) or creates a transfer charge (`bank_transfer`, requires `bank_account_id` or `pix_key_id`). Omit to mark as paid manually. payment_method_id: type: string format: uuid description: "UUID of a saved payment method (e.g.: tokenized card)." card: type: object properties: card_token: type: string minLength: 1 description: Card token obtained on the front-end via the gateway SDK. holder_name: type: string minLength: 3 description: Name printed on the card (minimum 3 characters). required: - card_token - holder_name description: Card data when `payment_method = card` and no `payment_method_id` is provided. bank_account_id: type: string format: uuid description: "With `payment_method = bank_transfer`: UUID of the organization bank account the customer should transfer to (see `/bank_accounts`). Send this or `pix_key_id`, never both." pix_key_id: type: string format: uuid description: "With `payment_method = bank_transfer`: UUID of the organization Pix key the customer should transfer to (see `/pix_keys`). Send this or `bank_account_id`, never both." required: - payment_method InvoiceDeletedResponse: type: object properties: data: type: object properties: deleted: type: boolean example: true required: - deleted required: - data PaymentV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. invoice_id: type: - string - "null" format: uuid description: UUID of the associated invoice, when present. billing_account_id: type: - string - "null" format: uuid description: Billing account UUID. company_id: type: - string - "null" format: uuid description: Issuing company UUID. payment_method_id: type: - string - "null" format: uuid description: UUID of the payment method used. gateway_id: type: - string - "null" format: uuid description: UUID of the gateway that processed the payment. bank_account_id: type: - string - "null" format: uuid description: UUID of the organization bank account the customer was pointed to on a `bank_transfer` charge. The details sent are frozen in `metadata.transfer`. pix_key_id: type: - string - "null" format: uuid description: UUID of the organization Pix key the customer was pointed to on a `bank_transfer` charge. The details sent are frozen in `metadata.transfer`. payment_method_type: type: - string - "null" enum: - card - bank_slip - pix - bank_transfer description: "Payment method type: `card`, `bank_slip`, `pix` or `bank_transfer`." amount: type: number description: Charged amount in BRL (float, up to 4 decimal places). example: 100 principal_amount: type: - number - "null" description: The share of `paid_amount` that reduced the invoice balance. This is what counts as service revenue — fine and interest are financial revenue. Null for payments settled before the breakdown existed, where `paid_amount` WAS the principal. fine_amount: type: number description: Late-payment fine contained in `paid_amount`, in BRL. interest_amount: type: number description: Late-payment interest contained in `paid_amount`, in BRL. discount_amount: type: number description: Discount or rebate granted at settlement, in BRL. paid_amount: type: - number - "null" description: Amount actually received in BRL (float, up to 4 decimal places). currency: type: string description: "ISO 4217 currency (e.g.: `BRL`)." example: BRL status: type: string enum: - pending - processing - succeeded - failed - canceled - partial - refunded - partially_refunded description: "Status: `pending`, `processing`, `succeeded`, `failed`, `canceled`, `partial`, `refunded` or `partially_refunded`." payment_gateway: type: - string - "null" description: "Upstream gateway name (e.g.: `KOBANA`, `PAGARME`)." gateway_payment_id: type: - string - "null" description: Payment identifier at the upstream gateway. failure_code: type: - string - "null" description: Failure code returned by the gateway. failure_message: type: - string - "null" description: Failure message returned by the gateway. idempotency_key: type: - string - "null" description: Idempotency key provided when creating the payment. paid_at: type: - string - "null" format: date-time description: Date/time the payment was confirmed. metadata: type: - object - "null" additionalProperties: {} description: Read-only internal metadata generated by the system. custom_metadata: type: - object - "null" additionalProperties: {} description: Free-form metadata defined by the client. created_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel through which the record was created (dashboard, import, api, mcp, cli, other). On API calls it comes from the `X-Request-Source` header. created_via_other: type: - string - "null" description: Name of the app that created the record when `created_via` is `other` (`X-Request-Source-Other` header). created_by_email: type: - string - "null" description: Email of the user who created the record. updated_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel of the last update to the record. updated_via_other: type: - string - "null" description: Name of the app behind the last update when `updated_via` is `other` (`X-Request-Source-Other` header). updated_by_email: type: - string - "null" description: Email of the user who made the last update. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - external_id - invoice_id - billing_account_id - company_id - payment_method_id - gateway_id - bank_account_id - pix_key_id - payment_method_type - amount - principal_amount - fine_amount - interest_amount - discount_amount - paid_amount - currency - status - payment_gateway - gateway_payment_id - failure_code - failure_message - idempotency_key - paid_at - metadata - custom_metadata - created_via - created_via_other - created_by_email - updated_via - updated_via_other - updated_by_email - created_at - updated_at PaymentListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/PaymentV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta PaymentResponse: type: object properties: data: $ref: "#/components/schemas/PaymentV1" required: - data PaymentCreateCard: type: object properties: card_token: type: string minLength: 1 description: Card token issued by the gateway (preferred). number: type: string minLength: 13 maxLength: 19 description: Card number (PAN). Use the token whenever possible. exp_month: type: integer minimum: 1 maximum: 12 description: Expiration month (1–12). exp_year: type: integer description: Expiration year (≥ current year). cvv: type: string minLength: 3 maxLength: 4 description: Card CVV/CVC (3 to 4 digits). holder_name: type: string minLength: 1 description: Cardholder name as printed on the card. required: - holder_name PaymentCreatePaymentMethod: type: object properties: type: type: string enum: - card - bank_slip - pix description: "Payment method type: `card`, `bank_slip` or `pix`." card: allOf: - $ref: "#/components/schemas/PaymentCreateCard" - description: Card data — token (preferred) **or** PAN/expiry/CVV. required: - type PaymentCreateRequest: type: object properties: invoice_id: type: string format: uuid description: UUID of the invoice to be paid. payment_method_id: type: string format: uuid description: UUID of a payment method previously registered for the account. payment_method: allOf: - $ref: "#/components/schemas/PaymentCreatePaymentMethod" - description: Block with payment method data — used when no `payment_method_id` is provided. amount: type: number exclusiveMinimum: 0 description: "Amount to charge in BRL (float, up to 4 decimal places). Default: invoice open balance." external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: object additionalProperties: {} description: Free-form metadata defined by the client for internal correlation. required: - invoice_id PaymentCancelRequest: type: object properties: reason: type: string description: Cancellation reason (recorded in the audit log). cancel_on_gateway: type: boolean description: When `true` (default), also cancels at the upstream gateway. PaymentRetryCard: type: object properties: card_token: type: string minLength: 1 description: Card token issued by the gateway. holder_name: type: string minLength: 3 description: Cardholder name as printed on the card. required: - card_token - holder_name PaymentRetryRequest: type: object properties: card: allOf: - $ref: "#/components/schemas/PaymentRetryCard" - description: Alternative card (token and holder) for the retry attempt. payment_method_id: type: string format: uuid description: UUID of a saved payment method to use in the retry. PaymentChangeCardRequest: type: object properties: credit_card_id: type: string format: uuid description: UUID of the billing account's active credit card. required: - credit_card_id PaymentChangeDueDateRequest: type: object properties: due_date: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: New due date in `YYYY-MM-DD` format. example: 2026-08-15 required: - due_date PaymentChangeDueDateResponse: type: object properties: data: type: object properties: due_date: type: string updated: type: boolean required: - due_date - updated required: - data PaymentSendEmailRequest: type: object properties: email: type: string format: email description: Recipient's email address. message: type: string description: Optional message included in the email body. required: - email PaymentSendEmailResponse: type: object properties: data: type: object properties: sent: type: boolean email: type: string format: email required: - sent - email required: - data PaymentRefundRequest: type: object properties: amount: type: number exclusiveMinimum: 0 description: "Amount to refund in BRL (float, up to 4 decimal places). Default: full payment amount." reason: type: string description: Refund reason (recorded in the audit log). PaymentBulkUpdateInvoiceRequest: type: object properties: payment_ids: type: array items: type: string format: uuid minItems: 1 description: List of UUIDs of the payments to update. invoice_id: type: string format: uuid description: UUID of the target invoice. required: - payment_ids - invoice_id PaymentBulkUpdateInvoiceResponse: type: object properties: data: type: object properties: updated_count: type: integer required: - updated_count required: - data PaymentDeletedResponse: type: object properties: data: type: object properties: deleted: type: boolean example: true required: - deleted required: - data PaymentMethodCreditCardV1: type: object properties: id: type: string format: uuid description: Card record UUID. status: type: string enum: - active - expired - removed description: "Card status: `active`, `expired`, `removed`." brand: type: - string - "null" description: "Card brand (e.g.: `visa`, `mastercard`)." example: visa last_four_digits: type: - string - "null" description: Last four digits of the card. example: "4242" holder_name: type: - string - "null" description: Cardholder name as printed on the card. expiration_month: type: - integer - "null" description: Expiration month (1–12). example: 12 expiration_year: type: - integer - "null" description: Expiration year (4 digits). example: 2030 required: - id - status - brand - last_four_digits - holder_name - expiration_month - expiration_year PaymentMethodBankAccountV1: type: object properties: bank_code: type: - string - "null" description: Bank clearing code (FEBRABAN, 3 digits). example: "341" bank_name: type: - string - "null" description: Bank name, resolved from `bank_code`. example: Itaú agency: type: - string - "null" description: Bank branch / agency. account: type: - string - "null" description: Bank account number. account_type: type: - string - "null" enum: - checking - savings description: "Account type: `checking` or `savings`." holder_name: type: - string - "null" description: Account holder name. required: - bank_code - bank_name - agency - account - account_type - holder_name PaymentMethodV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. billing_account_id: type: string format: uuid description: UUID of the owner billing account. credit_card_id: type: - string - "null" format: uuid description: UUID of the associated `credit_card`, when `type=card`. type: type: string enum: - card - bank_slip - pix - bank_transfer description: "Method type: `card`, `bank_slip`, `pix` or `bank_transfer`." status: type: string enum: - active - expired - failed - removed description: "Method status: `active`, `expired`, `failed` or `removed`." is_default: type: boolean description: Whether this is the default method for the billing account. is_backup: type: boolean description: Whether the method is used as a backup for the default. billing_details: type: - object - "null" additionalProperties: {} description: Optional billing details (name, email, phone, address) sent to the gateway. metadata: type: - object - "null" additionalProperties: {} description: Read-only internal metadata generated by the system. custom_metadata: type: - object - "null" additionalProperties: {} description: Free-form custom metadata (`object`). created_at: type: string format: date-time updated_at: type: string format: date-time bank_account: allOf: - $ref: "#/components/schemas/PaymentMethodBankAccountV1" - description: Public preview of the bank account, present when `type=bank_transfer`. Holder document is omitted. credit_card: allOf: - $ref: "#/components/schemas/PaymentMethodCreditCardV1" - description: Public preview of the card, present when `type=card`. Gateway tokens and fingerprint are omitted. required: - id - public_id - external_id - billing_account_id - credit_card_id - type - status - is_default - is_backup - created_at - updated_at PaymentMethodListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/PaymentMethodV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta PaymentMethodResponse: type: object properties: data: $ref: "#/components/schemas/PaymentMethodV1" required: - data PaymentMethodCardInput: type: object properties: card_token: type: string minLength: 1 description: Card token produced by the gateway client-side tokenization. holder_name: type: string minLength: 1 description: Cardholder name as printed on the card. required: - card_token - holder_name PaymentMethodBankAccountInput: type: object properties: bank_code: type: string minLength: 3 maxLength: 3 description: Bank clearing code (FEBRABAN, 3 digits). example: "341" agency: type: string minLength: 1 description: Bank branch / agency. account: type: string minLength: 1 description: Bank account number. account_type: type: string enum: - checking - savings description: "Account type: `checking` or `savings`." holder_name: type: string minLength: 1 description: Account holder name. holder_document: type: string minLength: 11 maxLength: 14 description: Holder's CPF or CNPJ (11–14 digits). required: - bank_code - agency - account - account_type - holder_name - holder_document PaymentMethodBillingAddress: type: object properties: street: type: string number: type: string complement: type: string neighborhood: type: string city: type: string state: type: string minLength: 2 maxLength: 2 zip_code: type: string country: type: string required: - street - number - neighborhood - city - state - zip_code PaymentMethodBillingDetailsInput: type: object properties: name: type: string description: Name for the billing details. email: type: string format: email description: Email for the billing details. phone: type: string description: Phone for the billing details. address: allOf: - $ref: "#/components/schemas/PaymentMethodBillingAddress" - description: Billing address. PaymentMethodCreateRequest: type: object properties: billing_account_id: type: string format: uuid description: UUID of the billing account that owns the payment method. type: type: string enum: - card - bank_slip - pix - bank_transfer description: "Method type: `card`, `bank_slip`, `pix` or `bank_transfer`." is_default: type: boolean description: When `true`, marks this method as the account default (unsets previous defaults). The first method created for an account also becomes the default automatically. card: allOf: - $ref: "#/components/schemas/PaymentMethodCardInput" - description: Card block. Required when `type=card`. bank_account: allOf: - $ref: "#/components/schemas/PaymentMethodBankAccountInput" - description: Bank account block. Required when `type=bank_transfer`. billing_details: allOf: - $ref: "#/components/schemas/PaymentMethodBillingDetailsInput" - description: Optional billing details (name, email, phone, address) used by the gateway. external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: object additionalProperties: {} description: Free-form custom metadata (`object`). required: - billing_account_id - type PaymentMethodUpdateRequest: type: object properties: exp_month: type: integer minimum: 1 maximum: 12 description: Card expiration month (1–12). exp_year: type: integer description: Card expiration year (>= current year). external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: - object - "null" additionalProperties: {} description: Free-form custom metadata (`object`). required: - exp_month - exp_year NfeV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. invoice_id: type: - string - "null" format: uuid description: Linked invoice UUID (when the NF-e was issued for an invoice). transaction_id: type: - string - "null" format: uuid description: Originating transaction UUID, when applicable. billing_account_id: type: string format: uuid description: NF-e billing account (taker) UUID. organization_id: type: string format: uuid description: Issuing organization UUID. company_id: type: - string - "null" format: uuid description: Issuing company (provider) UUID. Optional when the organization has a default company. person_id: type: - string - "null" format: uuid description: Person (taker) UUID associated with the NF-e. status: type: string enum: - draft - pending - processing - issued - pending_cancel - canceling - canceled - error description: "Status: `draft`, `pending`, `processing`, `issued`, `pending_cancel`, `canceling`, `canceled` or `error`." nfe_number: type: - integer - "null" description: NF-e number assigned by the municipality (set after issuance). nfe_series: type: - string - "null" description: NF-e series. nfe_key: type: - string - "null" description: Unique NF-e access key (44 or 50 digits, depending on the municipality). verification_code: type: - string - "null" description: Verification/authenticity code printed on the DANFSE. issue_date: type: - string - "null" format: date-time description: Date and time of issuance by the municipality. cancelled_at: type: - string - "null" format: date-time description: Cancellation date and time (when applicable). amount: type: number description: NF-e amount in BRL (float, up to 4 decimal places). service_code: type: - string - "null" description: Service code per the municipal table. service_description: type: - string - "null" description: Free-form description of the service provided. lc116_code: type: - string - "null" description: LC 116 code (national service list). cnae_code: type: - string - "null" description: Activity CNAE code. nbs_code: type: - string - "null" description: NBS code (Brazilian Service Nomenclature). ncm_code: type: - string - "null" description: NCM code (Mercosur Common Nomenclature), when applicable. c_class_trib: type: - string - "null" description: IBS/CBS Tax Classification (cClassTrib), required alongside the service/NBS code by the tax reform (Anexo VIII). ind_op: type: - string - "null" description: IBS/CBS Operation Indicator (indOp) on the national NFS-e (SNNFSE). customer_snapshot: type: object additionalProperties: {} description: Snapshot of taker data at issuance time (name, document, address). taxes: type: object additionalProperties: {} description: Tax rates and amounts (ISS, PIS, COFINS, CSLL, IR, INSS). xml_url: type: - string - "null" description: Public URL for the XML hosted by the provider. pdf_url: type: - string - "null" description: Public URL for the PDF (DANFE/DANFSE) hosted by the provider. provider_company_id: type: - string - "null" description: Company identifier on the external provider. rps_number: type: - integer - "null" description: RPS (Provisional Service Receipt) number. rps_serial_number: type: - string - "null" description: RPS series. issue_attempts: type: integer description: Number of issuance attempts made. cancel_attempts: type: integer description: Number of cancellation attempts made. next_retry_at: type: - string - "null" format: date-time description: Date and time of the next automatic retry (issuance or cancellation). error_message: type: - string - "null" description: Error message returned by the provider on the last attempt. metadata: type: - object - "null" additionalProperties: {} description: Read-only internal metadata generated by the system. custom_metadata: type: - object - "null" additionalProperties: {} description: Custom fields defined by the organization. pdf_downloaded_at: type: - string - "null" format: date-time description: Date the PDF was downloaded and stored in the database. xml_downloaded_at: type: - string - "null" format: date-time description: Date the XML was downloaded and stored in the database. created_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel through which the record was created (dashboard, import, api, mcp, cli, other). On API calls it comes from the `X-Request-Source` header. created_via_other: type: - string - "null" description: Name of the app that created the record when `created_via` is `other` (`X-Request-Source-Other` header). created_by_email: type: - string - "null" description: Email of the user who created the record. updated_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel of the last update to the record. updated_via_other: type: - string - "null" description: Name of the app behind the last update when `updated_via` is `other` (`X-Request-Source-Other` header). updated_by_email: type: - string - "null" description: Email of the user who made the last update. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - external_id - invoice_id - transaction_id - billing_account_id - organization_id - company_id - person_id - status - nfe_number - nfe_series - nfe_key - verification_code - issue_date - cancelled_at - amount - service_code - service_description - lc116_code - cnae_code - nbs_code - ncm_code - c_class_trib - ind_op - customer_snapshot - taxes - xml_url - pdf_url - provider_company_id - rps_number - rps_serial_number - issue_attempts - cancel_attempts - next_retry_at - error_message - metadata - pdf_downloaded_at - xml_downloaded_at - created_via - created_via_other - created_by_email - updated_via - updated_via_other - updated_by_email - created_at - updated_at NfeListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/NfeV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta NfeResponse: type: object properties: data: $ref: "#/components/schemas/NfeV1" required: - data NfeCustomerAddressInput: type: object properties: street: type: string description: Street. number: type: string description: Address number. complement: type: string description: Complement (optional). neighborhood: type: string description: Neighborhood. city: type: string description: City. city_code: type: string description: IBGE city code (optional). state: type: string description: State (two-letter code). zip_code: type: string description: ZIP code. country: type: string description: Country (optional, defaults to `BR`). required: - street - number - neighborhood - city - state - zip_code description: Taker's address. NfeCustomerInput: type: object properties: name: type: string minLength: 1 description: Taker's name or legal name. email: type: string format: email description: Taker's email. document_type: type: string enum: - cpf - cnpj description: "Document type: `cpf` or `cnpj`." document_number: type: string minLength: 1 description: Document number (digits only or formatted). phone: type: string description: Taker's phone. address: $ref: "#/components/schemas/NfeCustomerAddressInput" required: - name - email - document_type - document_number description: Taker data at issuance time. **Required**. NfeTaxesInput: type: object properties: iss_rate: type: number description: ISS rate (decimal). pis_rate: type: number description: PIS rate (decimal). cofins_rate: type: number description: COFINS rate (decimal). csll_rate: type: number description: CSLL rate (decimal). ir_rate: type: number description: IR (income tax) rate (decimal). inss_rate: type: number description: INSS rate (decimal). description: "Tax rates (as decimals, e.g.: `0.05` for 5%). Falls back to company defaults when omitted." NfeCreateRequest: type: object properties: billing_account_id: type: string format: uuid description: Billing account (taker) UUID. **Required**. company_id: type: string format: uuid description: "Issuing company (provider) UUID. Default: organization's default company." external_id: type: string description: Identifier in your external system, for idempotency/sync. invoice_id: type: string format: uuid description: Linked invoice UUID (optional). transaction_id: type: string format: uuid description: Originating transaction UUID (optional). amount: type: number exclusiveMinimum: 0 description: NF-e amount in BRL (float, up to 4 decimal places). **Required**, must be positive. service_code: type: string description: Service code per the municipal table. service_description: type: string description: Free-form description of the service provided. lc116_code: type: string description: LC 116 code. cnae_code: type: string description: CNAE code. nbs_code: type: string description: NBS code. c_class_trib: type: string description: IBS/CBS Tax Classification (cClassTrib). ind_op: type: string description: IBS/CBS Operation Indicator (indOp). rps_number: type: integer description: RPS number (when numbering is managed by the application). rps_serial_number: type: string description: RPS series. customer: $ref: "#/components/schemas/NfeCustomerInput" taxes: $ref: "#/components/schemas/NfeTaxesInput" custom_metadata: type: - object - "null" additionalProperties: {} description: Custom fields (validated against the organization's schema). required: - billing_account_id - amount - customer NfeUpdateRequest: type: object properties: external_id: type: - string - "null" description: New identifier in your external system. Use `null` to clear. service_code: type: string description: Update the service code. service_description: type: string description: Update the service description. amount: type: number exclusiveMinimum: 0 description: Update the NF-e amount in BRL. lc116_code: type: - string - "null" description: Update the LC 116 code. Use `null` to clear. cnae_code: type: - string - "null" description: Update the CNAE code. Use `null` to clear. nbs_code: type: - string - "null" description: Update the NBS code. Use `null` to clear. ncm_code: type: - string - "null" description: Update the NCM code. Use `null` to clear. c_class_trib: type: - string - "null" description: Update the Tax Classification (cClassTrib). Use `null` to clear. ind_op: type: - string - "null" description: Update the Operation Indicator (indOp). Use `null` to clear. rps_number: type: - integer - "null" description: Update the RPS number. Use `null` to clear. rps_serial_number: type: - string - "null" description: Update the RPS series. Use `null` to clear. customer_snapshot: type: object additionalProperties: {} description: Replace the taker snapshot. taxes: type: object additionalProperties: {} description: Replace the tax rates and amounts. custom_metadata: type: - object - "null" additionalProperties: {} description: Update custom fields. custom_metadata_mode: type: string enum: - replace - merge description: How the submitted `custom_metadata` is reconciled with the stored value. `replace` (default) overwrites the whole object; `merge` deep-merges over the current value — nested objects merge recursively, scalars and arrays overwrite the key, and `null` keys are kept (they do not delete the key). Accepted on update only. example: merge NfeCancelRequest: type: object properties: reason: type: string minLength: 15 description: Cancellation reason. **Minimum 15 characters**. Recorded in the audit log and sent to the provider. required: - reason NfeDeletedResponse: type: object properties: data: type: object properties: deleted: type: boolean example: true required: - deleted required: - data NfeBulkUpdateRequest: type: object properties: nfe_ids: type: array items: type: string format: uuid minItems: 1 description: UUIDs of the NF-e to update. Minimum 1. invoice_id: type: - string - "null" format: uuid description: UUID of the invoice to link. Send `null` to unlink. required: - nfe_ids - invoice_id NfeBulkUpdateResponse: type: object properties: data: type: object properties: updated: type: integer required: - updated required: - data NfeBulkDeleteRequest: type: object properties: ids: type: array items: type: string format: uuid minItems: 1 maxItems: 100 description: UUIDs of the NF-e to delete. Minimum 1, maximum 100. required: - ids NfeBulkDeleteResponse: type: object properties: data: type: object properties: deleted_count: type: integer required: - deleted_count required: - data NfeSyncOrgResponse: type: object properties: data: type: object properties: job_id: type: string status: type: string required: - job_id - status required: - data NfeRequestTryV1: type: object properties: id: type: string format: uuid nfe_id: type: string format: uuid action: type: string description: "Attempted action: `issue`, `cancel` or `query`." endpoint: type: string description: Provider endpoint called. request_body: type: - string - "null" response_body: type: - string - "null" http_status: type: - string - "null" description: HTTP status returned by the provider. success: type: boolean error_message: type: - string - "null" duration_ms: type: - integer - "null" description: Request duration in milliseconds. created_at: type: string format: date-time required: - id - nfe_id - action - endpoint - request_body - response_body - http_status - success - error_message - duration_ms - created_at NfeRequestTryListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/NfeRequestTryV1" required: - data NfeRequestTryPaginatedResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/NfeRequestTryV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta NfeExternalRequestSummaryV1: type: object properties: id: type: string format: uuid nfe_id: type: - string - "null" format: uuid invoice_id: type: - string - "null" format: uuid direction: type: string enum: - outbound - inbound description: "Request direction: `outbound` (outgoing call) or `inbound` (incoming webhook)." service: type: - string - "null" description: "External provider/service (e.g.: `nfeio`, `barueri`)." method: type: string endpoint: type: string http_status: type: - integer - "null" success: type: boolean error_message: type: - string - "null" duration_ms: type: - integer - "null" created_at: type: string format: date-time required: - id - nfe_id - invoice_id - direction - service - method - endpoint - http_status - success - error_message - duration_ms - created_at NfeExternalRequestV1: allOf: - $ref: "#/components/schemas/NfeExternalRequestSummaryV1" - type: object properties: request_headers: type: - object - "null" additionalProperties: {} request_body: type: - string - "null" response_headers: type: - object - "null" additionalProperties: {} response_body: type: - string - "null" metadata: type: - object - "null" additionalProperties: {} required: - request_headers - request_body - response_headers - response_body - metadata NfeExternalRequestListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/NfeExternalRequestSummaryV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta NfeExternalRequestResponse: type: object properties: data: $ref: "#/components/schemas/NfeExternalRequestV1" required: - data NfeFetchBarueriRequest: type: object properties: codigo_autenticidade: type: string minLength: 1 description: Authenticity code printed on the NFS-e DANFSE. cnpj_tomador: type: string minLength: 1 description: Taker's CPF or CNPJ (digits only or formatted). ambiente: type: string enum: - production - homologation description: "Municipal environment: `production` or `homologation`. Default: `production`." required: - codigo_autenticidade - cnpj_tomador NfeFetchBarueriResponse: type: object properties: data: type: object additionalProperties: {} required: - data NfeImportBarueriRequest: type: object properties: xml: type: string description: Raw XML returned by `POST /nfes/fetch-barueri`. Optional — when omitted, the NFS-e is re-fetched with `codigo_autenticidade` + `cnpj_tomador`. codigo_autenticidade: type: string minLength: 1 description: Authenticity code printed on the NFS-e DANFSE. cnpj_tomador: type: string minLength: 1 description: Taker's CPF or CNPJ (digits only or formatted). ambiente: type: string enum: - production - homologation description: "Municipal environment: `production` or `homologation`. Default: `production`." required: - codigo_autenticidade - cnpj_tomador NfeImportBarueriResponse: type: object properties: data: type: object additionalProperties: {} required: - data NfeValidateBarueriResponse: type: object properties: data: type: object additionalProperties: {} required: - data NfeFetchFromSefazRequest: type: object properties: access_key: type: string minLength: 1 description: NFS-e access key (50 digits). certificate_id: type: string minLength: 1 description: UUID of the digital certificate registered in the organization (used for mTLS authentication). ambiente: anyOf: - type: number enum: - 1 - type: number enum: - 2 description: "SEFAZ environment: `1` (production) or `2` (homologation). Default: `2`." required: - access_key - certificate_id NfeFetchFromSefazResponse: type: object properties: data: type: object additionalProperties: {} required: - data ProposalItemV1: type: object properties: id: type: string format: uuid proposal_id: type: string format: uuid product_id: type: - string - "null" format: uuid description: Product UUID. price_id: type: - string - "null" format: uuid description: Price UUID. quantity: type: number description: Quantity. unit_amount: type: number description: Unit amount in sub-cents (float, up to 4 decimal places). setup_amount: type: - number - "null" description: Unit setup amount in sub-cents (float, up to 4 decimal places). excess_amount: type: - number - "null" description: Excess (overage) amount in sub-cents (float, up to 4 decimal places). metadata: type: - object - "null" additionalProperties: {} created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - proposal_id - product_id - price_id - quantity - unit_amount - created_at - updated_at ProposalV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Public UUID — exposed in portal URLs (`/p/{code}`). external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. company_id: type: - string - "null" format: uuid description: Issuing company UUID (optional). code: type: string description: "Short code, unique per organization (e.g.: `PROP-0001`)." title: type: string description: 'Proposal title (default: "Proposta Comercial").' description: type: - string - "null" description: Free-form description shown on the proposal. billing_account_id: type: - string - "null" format: uuid description: Target billing account UUID, when the proposal targets an existing customer. prospect_id: type: - string - "null" format: uuid description: Prospect UUID (juridical person being prospected), when no `billing_account_id` exists yet. contact_id: type: - string - "null" format: uuid description: Contact UUID (natural person responsible inside the prospect). coupon_id: type: - string - "null" format: uuid description: Coupon UUID applied to the proposal. template_id: type: - string - "null" format: uuid description: Template UUID used to generate the PDF. document_google_id: type: - string - "null" description: Google Doc ID generated by the App Script. document_url: type: - string - "null" description: Google Doc URL. pdf_url: type: - string - "null" description: Public proposal PDF URL. generated_at: type: - string - "null" format: date-time description: Date and time of the last PDF generation. pdf_outdated_at: type: - string - "null" format: date-time description: Marks when the PDF became stale compared to current items/prices. expires_at: type: - string - "null" format: date-time description: Proposal expiration date. status: type: string enum: - draft - sent - viewed - accepted - rejected - expired - canceled description: "Status: `draft`, `sent`, `viewed`, `accepted`, `rejected`, `expired` or `canceled`." rejection_reason: type: - string - "null" description: Rejection reason provided by the prospect. discount_percent: type: - string - "null" description: 'Negotiated discount percent, decimal as string (e.g.: `"10.00"` = 10%). Range: 0–100. Applied to the monthly amount; the discounted value is the base for each cycle and the cycle discount applies on top, then the coupon. Mutually exclusive with `discount_amount`.' discount_amount: type: - number - "null" description: "Negotiated fixed PER-MONTH discount in BRL (float, up to 4 decimal places), applied to the monthly amount. The discounted value is the base for each cycle; the cycle discount applies on top. Mutually exclusive with `discount_percent`: setting one clears the other. On acceptance the combined proposal + cycle discount is carried to the subscription." example: 50 commitment_months: type: - integer - "null" description: "Commitment (loyalty) period: number of contracted months. Copied to the subscription on acceptance; inside the commitment window the customer cannot cancel the subscription through the portal." example: 12 setup_amount: type: number description: Setup (one-time) amount in BRL (float, up to 4 decimal places). monthly_amount: type: number description: Recurring monthly amount in BRL (float, up to 4 decimal places). notes: type: - string - "null" description: Internal notes (not shown to the customer). metadata: type: - object - "null" additionalProperties: {} description: Read-only internal metadata generated by the system. custom_metadata: type: - object - "null" additionalProperties: {} description: Custom fields defined by the organization. created_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel through which the record was created (dashboard, import, api, mcp, cli, other). On API calls it comes from the `X-Request-Source` header. created_via_other: type: - string - "null" description: Name of the app that created the record when `created_via` is `other` (`X-Request-Source-Other` header). created_by_email: type: - string - "null" description: Email of the user who created the record. updated_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel of the last update to the record. updated_via_other: type: - string - "null" description: Name of the app behind the last update when `updated_via` is `other` (`X-Request-Source-Other` header). updated_by_email: type: - string - "null" description: Email of the user who made the last update. created_at: type: string format: date-time updated_at: type: string format: date-time sent_at: type: - string - "null" format: date-time description: Date and time the proposal was sent. viewed_at: type: - string - "null" format: date-time description: Date and time of the first view by the recipient. accepted_at: type: - string - "null" format: date-time description: Date and time of acceptance. rejected_at: type: - string - "null" format: date-time description: Date and time of rejection. items: type: array items: $ref: "#/components/schemas/ProposalItemV1" description: Proposal items — present when included via `include=items`. required: - id - public_id - external_id - company_id - code - title - description - billing_account_id - prospect_id - contact_id - coupon_id - template_id - document_google_id - document_url - pdf_url - generated_at - pdf_outdated_at - expires_at - status - rejection_reason - discount_percent - discount_amount - commitment_months - setup_amount - monthly_amount - notes - created_via - created_via_other - created_by_email - updated_via - updated_via_other - updated_by_email - created_at - updated_at - sent_at - viewed_at - accepted_at - rejected_at ProposalListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/ProposalV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta ProposalResponse: type: object properties: data: $ref: "#/components/schemas/ProposalV1" required: - data ProposalItemInput: type: object properties: product_id: type: string format: uuid description: Product UUID. **Required**. price_id: type: string format: uuid description: Price UUID. **Required**. quantity: type: number minimum: 1 description: "Quantity. Default: 1." unit_amount: type: number minimum: 0 description: Unit amount in sub-cents (float, up to 4 decimal places). custom_metadata: type: - object - "null" additionalProperties: {} description: Item custom fields. required: - product_id - price_id - unit_amount ProspectDataInput: type: object properties: document: type: string description: Prospect CNPJ (digits only or formatted). name: type: string minLength: 1 description: Prospect legal/company name. legal_name: type: string description: Alternate legal name. nickname: type: string description: Trade name. email: type: string format: email description: Primary prospect email. phone: type: string description: Primary prospect phone. required: - name description: Data to create a prospect inline (juridical person). Alternative to `prospect_id`/`billing_account_id`. ContactDataInput: type: object properties: name: type: string minLength: 1 description: Contact name (person in charge). email: type: string format: email description: Contact email. phone: type: string description: Contact phone. required: - name description: Data to create a contact inline (natural person in charge). ProposalCreateRequest: type: object properties: company_id: type: - string - "null" format: uuid description: Issuing company UUID. Use `null` to clear. title: type: string minLength: 1 maxLength: 255 description: 'Proposal title. Default: "Proposta Comercial".' description: type: - string - "null" description: Free-form proposal description. billing_account_id: type: - string - "null" format: uuid description: Target billing account UUID (existing customer). Required if `prospect_id` and `prospect_data` are not provided. prospect_id: type: - string - "null" format: uuid description: UUID of an existing prospect. Alternative to `billing_account_id`/`prospect_data`. contact_id: type: - string - "null" format: uuid description: UUID of an existing contact linked to the prospect. prospect_data: $ref: "#/components/schemas/ProspectDataInput" contact_data: $ref: "#/components/schemas/ContactDataInput" coupon_id: type: - string - "null" format: uuid description: Coupon UUID to apply. template_id: type: - string - "null" format: uuid description: Template UUID for PDF generation. discount_percent: type: - number - "null" minimum: 0 maximum: 100 description: Negotiated discount percent (0–100), applied to the monthly amount; the cycle discount applies over the discounted value. Do not send together with `discount_amount`. discount_amount: type: - number - "null" minimum: 0 description: Negotiated fixed per-month discount in BRL (float, up to 4 decimal places), applied to the monthly amount; the cycle discount applies over the discounted value. Do not send together with `discount_percent`. example: 50 commitment_months: type: - integer - "null" minimum: 1 maximum: 120 description: Commitment period in months (1–120). Use `null` to clear. Copied to the subscription when the proposal is accepted. example: 12 expires_at: type: string description: Expiration date. notes: type: - string - "null" description: Internal notes. items: type: array items: $ref: "#/components/schemas/ProposalItemInput" minItems: 1 description: Proposal items. Minimum 1. external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: - object - "null" additionalProperties: {} description: Custom fields (validated against the organization's schema). ProposalUpdateRequest: type: object properties: company_id: type: - string - "null" format: uuid title: type: string minLength: 1 maxLength: 255 description: Update the title. description: type: - string - "null" description: Update the description. Use `null` to clear. billing_account_id: type: - string - "null" format: uuid prospect_id: type: - string - "null" format: uuid contact_id: type: - string - "null" format: uuid prospect_data: $ref: "#/components/schemas/ProspectDataInput" contact_data: $ref: "#/components/schemas/ContactDataInput" coupon_id: type: - string - "null" format: uuid template_id: type: - string - "null" format: uuid discount_percent: type: - number - "null" minimum: 0 maximum: 100 description: Negotiated discount percent (0–100). Setting it clears the fixed amount. Use `null` to clear the discount. Do not send together with `discount_amount`. discount_amount: type: - number - "null" minimum: 0 description: Negotiated fixed per-month discount in BRL (float, up to 4 decimal places), applied to the monthly amount; the cycle discount applies over the discounted value. Setting it clears the percent. Use `null` to clear. Do not send together with `discount_percent`. example: 50 commitment_months: type: - integer - "null" minimum: 1 maximum: 120 description: Commitment period in months (1–120). Use `null` to clear. Copied to the subscription when the proposal is accepted. example: 12 expires_at: type: - string - "null" description: Update the expiration date. Use `null` to clear. notes: type: - string - "null" description: Update the notes. Use `null` to clear. items: type: array items: $ref: "#/components/schemas/ProposalItemInput" description: Replaces the proposal items list. external_id: type: string description: New identifier in your external system. custom_metadata: type: - object - "null" additionalProperties: {} custom_metadata_mode: type: string enum: - replace - merge description: How the submitted `custom_metadata` is reconciled with the stored value. `replace` (default) overwrites the whole object; `merge` deep-merges over the current value — nested objects merge recursively, scalars and arrays overwrite the key, and `null` keys are kept (they do not delete the key). Accepted on update only. example: merge ProposalAcceptRequest: type: object properties: cycle: type: string enum: - monthly - quarterly - semiannual - annual description: "Billing cycle of the subscription created on acceptance: `monthly`, `quarterly`, `semiannual` or `annual`." required: - cycle ProposalAcceptResponse: type: object properties: data: type: object properties: proposal: $ref: "#/components/schemas/ProposalV1" subscription_id: type: - string - "null" format: uuid invoice_id: type: - string - "null" format: uuid required: - proposal - subscription_id - invoice_id required: - data ProposalSendRequest: type: object properties: subject: type: string description: "Custom email subject. Default: `Proposta {code}`." message: type: string description: Custom HTML message for the email body. ProposalGeneratePdfResponse: type: object properties: data: type: object properties: proposal: $ref: "#/components/schemas/ProposalV1" pdf: type: object properties: document_id: type: - string - "null" document_url: type: - string - "null" pdf_url: type: - string - "null" required: - document_id - document_url - pdf_url required: - proposal - pdf required: - data ProposalJsonResponse: type: object properties: data: type: object properties: template_data: {} proposal: type: object properties: id: type: string format: uuid code: type: string template_google_doc_id: type: - string - "null" document_google_id: type: - string - "null" required: - id - code - template_google_doc_id - document_google_id required: - proposal required: - data ProposalPricingResponse: type: object properties: data: type: object additionalProperties: {} required: - data ProposalItemsListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/ProposalItemV1" required: - data ProposalItemResponse: type: object properties: data: $ref: "#/components/schemas/ProposalItemV1" required: - data ProposalItemUpdateRequest: type: object properties: quantity: type: integer minimum: 1 description: Update quantity. unit_amount: type: number minimum: 0 description: Update unit amount in sub-cents (float, up to 4 decimal places). setup_amount: type: number minimum: 0 description: Update unit setup amount in sub-cents (float, up to 4 decimal places). custom_metadata: type: - object - "null" additionalProperties: {} description: proposals.items.update.body.custom_metadata ProposalBulkRequest: type: object properties: ids: type: array items: type: string format: uuid minItems: 1 maxItems: 100 description: List of target proposal UUIDs. Minimum 1, maximum 100. required: - ids ProposalBulkResponse: type: object properties: data: type: object properties: success_count: type: integer failed_count: type: integer errors: type: array items: type: object additionalProperties: {} required: - success_count - failed_count - errors required: - data ProposalStatsResponse: type: object properties: data: type: object additionalProperties: type: integer required: - data ProposalDeletedResponse: type: object properties: data: type: object properties: deleted: type: boolean example: true required: - deleted required: - data ProposalTemplateV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the template. external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. name: type: string description: Template name (unique per organization). description: type: - string - "null" description: Free-form template description. document_type: type: string enum: - google_doc - google_slides description: "Base document type: `google_doc` or `google_slides`." google_doc_id: type: string description: Google Doc/Slides ID used as the template base. app_script_url: type: - string - "null" description: URL of the Apps Script that renders the template, when configured. google_drive_folder_id: type: - string - "null" description: Google Drive folder ID where generated copies are saved. is_active: type: boolean description: Indicates whether the template is available for use in new proposals. metadata: type: - object - "null" additionalProperties: {} description: Internal template metadata (free-form structure). custom_metadata: type: - object - "null" additionalProperties: {} description: Free-form metadata defined by the client for internal correlation. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - external_id - name - description - document_type - google_doc_id - app_script_url - google_drive_folder_id - is_active - metadata - custom_metadata - created_at - updated_at ProposalTemplateListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/ProposalTemplateV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta ProposalTemplateResponse: type: object properties: data: $ref: "#/components/schemas/ProposalTemplateV1" required: - data ProposalTemplateCreateRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 description: Template name (unique per organization). description: type: - string - "null" description: Optional template description. document_type: type: string enum: - google_doc - google_slides description: "Base document type: `google_doc` or `google_slides`. Default: `google_doc`." google_doc_id: type: string minLength: 1 description: Google Doc/Slides ID used as the template (unique per organization). app_script_url: type: - string - "null" format: uri description: URL of the published Apps Script that renders the template, when applicable. google_drive_folder_id: type: - string - "null" description: Google Drive folder ID where generated copies will be saved. is_active: type: boolean description: When `false`, creates the template already deactivated. external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: object additionalProperties: {} description: Free-form metadata defined by the client for internal correlation. required: - name - google_doc_id ProposalTemplateUpdateRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 description: New template name. description: type: - string - "null" description: New template description. document_type: type: string enum: - google_doc - google_slides description: "New base document type: `google_doc` or `google_slides`." google_doc_id: type: string minLength: 1 description: New Google Doc/Slides ID used as the template. app_script_url: type: - string - "null" format: uri description: New URL of the published Apps Script. google_drive_folder_id: type: - string - "null" description: New Google Drive folder ID. is_active: type: boolean description: Enables or disables the template. external_id: type: string description: New identifier in your external system. custom_metadata: type: object additionalProperties: {} description: New free-form metadata defined by the client. PlanChangeV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. subscription_id: type: string format: uuid description: UUID of the subscription targeted by the change. billing_account_id: type: string format: uuid description: Billing account UUID. organization_id: type: string format: uuid description: UUID of the organization that owns the resource. from_plan_id: type: string format: uuid description: UUID of the source plan. to_plan_id: type: string format: uuid description: UUID of the target plan. change_type: type: string enum: - upgrade - downgrade - lateral description: "Change type: `upgrade`, `downgrade` or `lateral`." status: type: string enum: - pending - scheduled - completed - canceled - failed description: "Status: `pending`, `scheduled`, `completed`, `canceled` or `failed`." timing: type: string enum: - immediate - end_of_period description: "When the change is/was applied: `immediate` or `end_of_period`." proration_method: type: string enum: - full_proration - no_proration - partial_proration description: Proration method effectively used. effective_date: type: string format: date-time description: Date when the change becomes effective. scheduled_date: type: - string - "null" format: date-time description: Date scheduled for application (when `timing = end_of_period`). completed_at: type: - string - "null" format: date-time description: When the change was completed. canceled_at: type: - string - "null" format: date-time description: When the change was canceled. from_price: type: number description: Source plan price in sub-cents (float, up to 4 decimal places). example: 100 to_price: type: number description: Target plan price in sub-cents (float, up to 4 decimal places). example: 200 price_difference: type: number description: Difference `to - from` in sub-cents (float, up to 4 decimal places). proration_credit: type: number description: Credit generated by proration in sub-cents (float, up to 4 decimal places). proration_charge: type: number description: Additional charge from proration in sub-cents (float, up to 4 decimal places). days_remaining: type: integer description: Days remaining in the current period at the moment of the change. total_days_in_period: type: integer description: Total days in the billing period. invoice_id: type: - string - "null" format: uuid description: UUID of the proration invoice issued (if any). credit_id: type: - string - "null" format: uuid description: UUID of the generated credit (if any). reason: type: - string - "null" description: Reason recorded by the change initiator. initiated_by: type: - string - "null" description: Initiator identifier (user email, API key name or `api`). metadata: type: - object - "null" additionalProperties: {} description: Read-only internal metadata generated by the system. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). Populated by the plan-change engine; not editable via the API. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - external_id - subscription_id - billing_account_id - organization_id - from_plan_id - to_plan_id - change_type - status - timing - proration_method - effective_date - scheduled_date - completed_at - canceled_at - from_price - to_price - price_difference - proration_credit - proration_charge - days_remaining - total_days_in_period - invoice_id - credit_id - reason - initiated_by - metadata - custom_metadata - created_at - updated_at PlanChangeListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/PlanChangeV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta PlanChangeResponse: type: object properties: data: $ref: "#/components/schemas/PlanChangeV1" required: - data PlanChangeExecuteRequest: type: object properties: subscription_id: type: string format: uuid description: UUID of the subscription that will have its plan changed. to_plan_id: type: string format: uuid description: UUID of the target plan. timing: type: string enum: - immediate - end_of_period description: "When to apply the change: `immediate` (default for upgrades) or `end_of_period` (default for downgrades)." reason: type: string description: Reason for the change (recorded in the audit log). required: - subscription_id - to_plan_id PlanChangeExecuteResponse: type: object properties: data: type: object properties: plan_change_id: type: string format: uuid description: UUID of the created plan change. invoice_id: type: - string - "null" format: uuid description: UUID of the proration invoice issued (if any). credit_id: type: - string - "null" format: uuid description: UUID of the generated credit (if any). required: - plan_change_id - invoice_id - credit_id required: - data PlanChangeStatsResponse: type: object properties: data: type: object properties: total: type: integer description: Total changes in the window. by_type: type: object additionalProperties: type: integer description: "Count by type (keys: `upgrade`, `downgrade`, `lateral`)." by_status: type: object additionalProperties: type: integer description: Count by status. upgrades: type: integer description: Number of upgrades in the window. downgrades: type: integer description: Number of downgrades in the window. total_proration_credits: type: number description: Sum of proration credits issued in sub-cents (float, up to 4 decimal places). total_proration_charges: type: number description: Sum of proration charges in sub-cents (float, up to 4 decimal places). required: - total - by_type - by_status - upgrades - downgrades - total_proration_credits - total_proration_charges required: - data PlanChangeConfigV1: type: object properties: id: type: string format: uuid organization_id: type: string format: uuid description: UUID of the organization that owns the configuration. allow_upgrade: type: boolean description: Upgrades are enabled. allow_downgrade: type: boolean description: Downgrades are enabled. upgrade_proration: type: string enum: - full_proration - no_proration - partial_proration description: Default proration method for upgrades. downgrade_proration: type: string enum: - full_proration - no_proration - partial_proration description: Default proration method for downgrades. upgrade_timing: type: string enum: - immediate - end_of_period description: When to apply upgrades by default. downgrade_timing: type: string enum: - immediate - end_of_period description: When to apply downgrades by default. refund_on_downgrade: type: boolean description: Refunds the difference when downgrading. credit_on_downgrade: type: boolean description: Generates credit when downgrading. apply_discount_on_change: type: boolean description: Keeps active discounts when changing plans. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - organization_id - allow_upgrade - allow_downgrade - upgrade_proration - downgrade_proration - upgrade_timing - downgrade_timing - refund_on_downgrade - credit_on_downgrade - apply_discount_on_change - created_at - updated_at PlanChangeConfigResponse: type: object properties: data: $ref: "#/components/schemas/PlanChangeConfigV1" required: - data PlanChangeConfigUpdateRequest: type: object properties: allow_upgrade: type: boolean description: Enables plan upgrades for the organization. allow_downgrade: type: boolean description: Enables plan downgrades for the organization. upgrade_proration: type: string enum: - full_proration - no_proration - partial_proration description: "Default proration method for upgrades: `full_proration`, `no_proration` or `partial_proration`." downgrade_proration: type: string enum: - full_proration - no_proration - partial_proration description: Default proration method for downgrades. upgrade_timing: type: string enum: - immediate - end_of_period description: "When to apply upgrades: `immediate` or `end_of_period`." downgrade_timing: type: string enum: - immediate - end_of_period description: "When to apply downgrades: `immediate` or `end_of_period`." refund_on_downgrade: type: boolean description: Refunds the difference when downgrading. credit_on_downgrade: type: boolean description: Generates credit (instead of refund) when downgrading. apply_discount_on_change: type: boolean description: Keeps active discounts when changing plans. PlanChangeRuleV1: type: object properties: id: type: string format: uuid from_plan_id: type: - string - "null" format: uuid description: UUID of the source plan, or `null` for any. to_plan_id: type: - string - "null" format: uuid description: UUID of the target plan, or `null` for any. change_type: type: - string - "null" enum: - upgrade - downgrade - lateral description: "Change type covered: `upgrade`, `downgrade` or `lateral` (or `null` for any)." allowed: type: boolean description: When `false`, the transition is blocked. timing: type: - string - "null" enum: - immediate - end_of_period description: Timing overridden by this rule. proration_method: type: - string - "null" enum: - full_proration - no_proration - partial_proration description: Proration method overridden by this rule. discount_percent: type: - integer - "null" description: Percent discount (0–100) applied. bonus_days: type: - integer - "null" description: Bonus days granted. message: type: - string - "null" description: Message shown to the customer. is_active: type: boolean description: Whether the rule is active. priority: type: integer description: Priority for conflict resolution (higher wins). created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - from_plan_id - to_plan_id - change_type - allowed - timing - proration_method - discount_percent - bonus_days - message - is_active - priority - created_at - updated_at PlanChangeRuleListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/PlanChangeRuleV1" required: - data PlanChangeRuleResponse: type: object properties: data: $ref: "#/components/schemas/PlanChangeRuleV1" required: - data PlanChangeRuleCreateRequest: type: object properties: from_plan_id: type: string format: uuid description: UUID of the source plan. When omitted, the rule covers any source plan. to_plan_id: type: string format: uuid description: UUID of the target plan. When omitted, the rule covers any target plan. change_type: type: string enum: - upgrade - downgrade - lateral description: "Change type: `upgrade`, `downgrade` or `lateral`." allowed: type: boolean description: When `false`, explicitly blocks the transition. timing: type: string enum: - immediate - end_of_period description: "Overrides the change timing: `immediate` or `end_of_period`." proration_method: type: string enum: - full_proration - no_proration - partial_proration description: "Overrides the proration method: `full_proration`, `no_proration` or `partial_proration`." discount_percent: type: number minimum: 0 maximum: 100 description: Percent discount applied when this rule matches (0 to 100). bonus_days: type: integer minimum: 0 description: Bonus days added to the current period when this rule is applied. message: type: string description: "Free-form message shown in the portal/checkout (e.g.: block reason)." priority: type: integer description: Priority for conflict resolution when multiple rules match (higher wins). PlanChangeRuleUpdateRequest: type: object properties: allowed: type: boolean description: When `false`, explicitly blocks the transition. timing: type: string enum: - immediate - end_of_period description: "Overrides the change timing: `immediate` or `end_of_period`." proration_method: type: string enum: - full_proration - no_proration - partial_proration description: "Overrides the proration method: `full_proration`, `no_proration` or `partial_proration`." discount_percent: type: number minimum: 0 maximum: 100 description: Percent discount applied when this rule matches (0 to 100). bonus_days: type: integer minimum: 0 description: Bonus days added to the current period when this rule is applied. message: type: string description: "Free-form message shown in the portal/checkout (e.g.: block reason)." priority: type: integer description: Priority for conflict resolution when multiple rules match (higher wins). is_active: type: boolean description: Deactivates the rule without removing it. PlanChangeRuleDeletedResponse: type: object properties: data: type: object properties: deleted: type: boolean example: true required: - deleted required: - data SubscriptionChangeConfigV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. organization_id: type: string format: uuid description: UUID of the organization that owns the settings. external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. allow_item_add: type: boolean description: When `true`, allows adding new items to the subscription. allow_item_remove: type: boolean description: When `true`, allows removing items from the subscription. allow_quantity_change: type: boolean description: When `true`, allows changing the quantity of existing items. allow_price_swap: type: boolean description: When `true`, allows swapping an item price (variant) without removing it. add_proration: type: string enum: - full_proration - no_proration - partial_proration description: Default proration method when adding items. remove_proration: type: string enum: - full_proration - no_proration - partial_proration description: Default proration method when removing items. quantity_up_proration: type: string enum: - full_proration - no_proration - partial_proration description: Default proration method when increasing quantity. quantity_down_proration: type: string enum: - full_proration - no_proration - partial_proration description: Default proration method when decreasing quantity. add_timing: type: string enum: - immediate - end_of_period description: Default timing when adding items. remove_timing: type: string enum: - immediate - end_of_period description: Default timing when removing items. quantity_up_timing: type: string enum: - immediate - end_of_period description: Default timing when increasing quantity. quantity_down_timing: type: string enum: - immediate - end_of_period description: Default timing when decreasing quantity. refund_on_remove: type: boolean description: When `true`, issues a refund when items are removed. Requires `creditOnRemove`. credit_on_remove: type: boolean description: When `true`, issues a credit for the customer when items are removed. portal_self_service: type: boolean description: When `true`, enables customer self-service from the portal. portal_require_confirmation: type: boolean description: When `true`, requires explicit customer confirmation in the portal. metadata: type: - object - "null" additionalProperties: {} description: Free-form metadata attached to the settings. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - organization_id - external_id - allow_item_add - allow_item_remove - allow_quantity_change - allow_price_swap - add_proration - remove_proration - quantity_up_proration - quantity_down_proration - add_timing - remove_timing - quantity_up_timing - quantity_down_timing - refund_on_remove - credit_on_remove - portal_self_service - portal_require_confirmation - metadata - custom_metadata - created_at - updated_at SubscriptionChangeConfigResponse: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. organization_id: type: string format: uuid description: UUID of the organization that owns the settings. external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. allow_item_add: type: boolean description: When `true`, allows adding new items to the subscription. allow_item_remove: type: boolean description: When `true`, allows removing items from the subscription. allow_quantity_change: type: boolean description: When `true`, allows changing the quantity of existing items. allow_price_swap: type: boolean description: When `true`, allows swapping an item price (variant) without removing it. add_proration: type: string enum: - full_proration - no_proration - partial_proration description: Default proration method when adding items. remove_proration: type: string enum: - full_proration - no_proration - partial_proration description: Default proration method when removing items. quantity_up_proration: type: string enum: - full_proration - no_proration - partial_proration description: Default proration method when increasing quantity. quantity_down_proration: type: string enum: - full_proration - no_proration - partial_proration description: Default proration method when decreasing quantity. add_timing: type: string enum: - immediate - end_of_period description: Default timing when adding items. remove_timing: type: string enum: - immediate - end_of_period description: Default timing when removing items. quantity_up_timing: type: string enum: - immediate - end_of_period description: Default timing when increasing quantity. quantity_down_timing: type: string enum: - immediate - end_of_period description: Default timing when decreasing quantity. refund_on_remove: type: boolean description: When `true`, issues a refund when items are removed. Requires `creditOnRemove`. credit_on_remove: type: boolean description: When `true`, issues a credit for the customer when items are removed. portal_self_service: type: boolean description: When `true`, enables customer self-service from the portal. portal_require_confirmation: type: boolean description: When `true`, requires explicit customer confirmation in the portal. metadata: type: - object - "null" additionalProperties: {} description: Free-form metadata attached to the settings. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - organization_id - external_id - allow_item_add - allow_item_remove - allow_quantity_change - allow_price_swap - add_proration - remove_proration - quantity_up_proration - quantity_down_proration - add_timing - remove_timing - quantity_up_timing - quantity_down_timing - refund_on_remove - credit_on_remove - portal_self_service - portal_require_confirmation - metadata - custom_metadata - created_at - updated_at SubscriptionChangeConfigUpdateRequest: type: object properties: allow_item_add: type: boolean description: Allows adding new items to an existing subscription. allow_item_remove: type: boolean description: Allows removing items from an existing subscription. allow_quantity_change: type: boolean description: Allows changing the quantity of items already on the subscription. allow_price_swap: type: boolean description: Allows swapping the price (variant) of an existing item without removing it. add_proration: type: string enum: - full_proration - no_proration - partial_proration description: "Proration method when adding items: `full_proration`, `no_proration` or `partial_proration`." remove_proration: type: string enum: - full_proration - no_proration - partial_proration description: "Proration method when removing items: `full_proration`, `no_proration` or `partial_proration`." quantity_up_proration: type: string enum: - full_proration - no_proration - partial_proration description: Proration method when increasing an item quantity. quantity_down_proration: type: string enum: - full_proration - no_proration - partial_proration description: Proration method when decreasing an item quantity. add_timing: type: string enum: - immediate - end_of_period description: "Timing when adding items: `immediate` or `end_of_period`." remove_timing: type: string enum: - immediate - end_of_period description: "Timing when removing items: `immediate` or `end_of_period`." quantity_up_timing: type: string enum: - immediate - end_of_period description: "Timing when increasing quantity: `immediate` or `end_of_period`." quantity_down_timing: type: string enum: - immediate - end_of_period description: "Timing when decreasing quantity: `immediate` or `end_of_period`." refund_on_remove: type: boolean description: When `true`, issues a refund to the customer when items are removed. Requires `credit_on_remove` to be enabled. credit_on_remove: type: boolean description: When `true`, issues a credit in favor of the customer when items are removed. portal_self_service: type: boolean description: When `true`, lets customers change their own subscription from the portal. portal_require_confirmation: type: boolean description: When `true`, requires explicit customer confirmation before applying the change in the portal. external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). SubscriptionItemChangeV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Public identifier (UUID) used for external integration. subscription_id: type: string format: uuid description: UUID of the subscription targeted by the change. billing_account_id: type: string format: uuid description: UUID of the billing account of the subscription. external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. status: type: string enum: - pending - scheduled - completed - canceled - failed description: "Status: `pending`, `scheduled`, `completed`, `canceled` or `failed`." timing: type: string enum: - immediate - end_of_period description: "Timing: `immediate` or `end_of_period`." initiated_by_role: type: string description: "Origin of the change: `dashboard`, `portal` or `api`." initiated_by: type: - string - "null" description: Identifier of the user/integration that initiated the change. proration_method: type: string enum: - full_proration - no_proration - partial_proration description: "Proration method actually applied: `full_proration`, `no_proration` or `partial_proration`." proration_credit: type: number description: Proration credit in BRL (float, up to 4 decimal places) issued to the customer. example: 100 proration_charge: type: number description: Proration charge in BRL (float, up to 4 decimal places) issued to the customer. example: 0 days_remaining: type: integer description: Days remaining in the billing period when applied. total_days_in_period: type: integer description: Total days in the billing period used for the proration calculation. changes: type: array items: type: object additionalProperties: {} description: 'Snapshot of the applied batch of operations. Each entry has the shape `{ op: "add"|"remove"|"update_qty"|"update_price", productId, priceId, quantity, prevQuantity?, prevPriceId?, prevUnitAmountSubcents?, unitAmountSubcents }`.' effective_date: type: string format: date-time description: Effective date of the change (when it takes effect). scheduled_date: type: - string - "null" format: date-time description: Date scheduled for application, when `timing = end_of_period`. completed_at: type: - string - "null" format: date-time description: Date/time the change was actually applied. canceled_at: type: - string - "null" format: date-time description: Date/time the change was canceled, when applicable. invoice_id: type: - string - "null" format: uuid description: UUID of the invoice generated by the change, when present. credit_id: type: - string - "null" format: uuid description: UUID of the credit generated by the change, when present. reason: type: - string - "null" description: Free-form reason informed by the operator when registering the change. idempotency_key: type: - string - "null" description: Per-organization idempotency key — safely allows retrying the same execution. metadata: type: - object - "null" additionalProperties: {} description: Free-form metadata defined by the client. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - subscription_id - billing_account_id - external_id - status - timing - initiated_by_role - initiated_by - proration_method - proration_credit - proration_charge - days_remaining - total_days_in_period - changes - effective_date - scheduled_date - completed_at - canceled_at - invoice_id - credit_id - reason - idempotency_key - metadata - custom_metadata - created_at - updated_at SubscriptionItemChangeListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/SubscriptionItemChangeV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta SubscriptionItemChangeResponse: type: object properties: data: $ref: "#/components/schemas/SubscriptionItemChangeV1" required: - data UsageRecordV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. subscription_item_id: type: string format: uuid description: UUID of the subscription item the usage belongs to. quantity: type: number description: Quantity reported in the record. example: 5 action: type: string enum: - increment - set description: "Action type: `increment` (adds) or `set` (replaces previous values in the period)." timestamp: type: string format: date-time description: Usage date/time (ISO 8601). idempotency_key: type: - string - "null" description: Idempotency key used at creation, if any. metadata: type: - object - "null" additionalProperties: {} description: Free-form metadata defined by the client. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). created_at: type: string format: date-time required: - id - public_id - external_id - subscription_item_id - quantity - action - timestamp - idempotency_key - metadata - custom_metadata - created_at UsageListMeta: type: object properties: total: type: integer limit: type: integer offset: type: integer total_quantity: type: number product_slug: type: string customer_id: type: string required: - total - limit - offset - total_quantity UsageListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/UsageRecordV1" meta: $ref: "#/components/schemas/UsageListMeta" required: - data - meta UsageRecordCreateInput: type: object properties: subscription_item_id: type: string format: uuid description: Subscription item UUID (option 1 — alternative to `product_slug` + `customer_id`). product_slug: type: string description: Product slug (option 2). Combine with `customer_id` to locate the active subscription. customer_id: type: string description: Customer external identifier (the billing account `external_id`). Combine with `product_slug`. quantity: type: number minimum: 0 description: "Quantity to record — non-negative number. E.g.: `5`, `0`, `1500`." example: 5 action: type: string enum: - increment - set description: "`increment` (default) adds to the period quantity; `set` replaces any previous value in the period up to now." timestamp: type: string format: date-time description: "Usage date/time in ISO 8601. Default: now." idempotency_key: type: string description: "Optional idempotency key. If a record with the same key already exists for the item, returns the existing one with `duplicate: true`." external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: - object - "null" additionalProperties: {} description: usage.create.body.custom_metadata required: - quantity UsageRecordBatchCreateInput: type: object properties: records: type: array items: $ref: "#/components/schemas/UsageRecordCreateInput" minItems: 1 maxItems: 100 description: Batch of records (1 to 100). When present, processes the batch and ignores the top-level record. required: - records UsageRecordCreateRequest: anyOf: - $ref: "#/components/schemas/UsageRecordCreateInput" - $ref: "#/components/schemas/UsageRecordBatchCreateInput" UsageRecordBatchResult: type: object properties: id: type: string format: uuid description: UUID of the created or existing record. public_id: type: string format: uuid description: Stable public identifier of the created or existing record. subscription_item_id: type: string format: uuid product_slug: type: string customer_id: type: string success: type: boolean description: Indicates whether the record was processed successfully. duplicate: type: boolean description: When `true`, indicates the record already existed with the same `idempotency_key`. error: type: string description: Error message when `success` is `false`. required: - success UsageRecordCreateResponse: type: object properties: success: type: boolean processed: type: integer failed: type: integer partial: type: boolean results: anyOf: - $ref: "#/components/schemas/UsageRecordBatchResult" - type: array items: $ref: "#/components/schemas/UsageRecordBatchResult" required: - success - processed - results UsageSummaryProduct: type: object properties: id: type: string format: uuid description: UUID of the product associated with the subscription item. name: type: string description: Product name. slug: type: string description: Product slug. required: - id - name - slug UsageSummaryPeriod: type: object properties: start: type: string format: date-time description: Period start used by the aggregation (ISO 8601). end: type: string format: date-time description: Period end used by the aggregation (ISO 8601). required: - start - end UsageSummaryUsage: type: object properties: total_quantity: type: number description: Total quantity consolidated in the period. record_count: type: integer description: Number of records considered. first_record_at: type: - string - "null" format: date-time description: Date/time of the first record in the period (ISO 8601). last_record_at: type: - string - "null" format: date-time description: Date/time of the last record in the period (ISO 8601). required: - total_quantity - record_count - first_record_at - last_record_at UsageSummaryBilling: type: object properties: estimated_cost: type: - number - "null" description: Estimated cost in BRL (float, up to 4 decimal places). `null` when the price does not allow the calculation. price_id: type: - string - "null" format: uuid description: UUID of the price used for the estimate. usage_type: type: - string - "null" description: "Usage type configured on the price (e.g.: `metered`, `licensed`)." required: - estimated_cost - price_id - usage_type UsageSummaryResponse: type: object properties: subscription_item_id: type: string format: uuid description: UUID of the subscription item the usage belongs to. subscription_id: type: string format: uuid description: Subscription UUID. subscription_status: type: string description: "Current subscription status (e.g.: `active`, `trialing`)." product: allOf: - $ref: "#/components/schemas/UsageSummaryProduct" - type: - object - "null" customer_id: type: string period: $ref: "#/components/schemas/UsageSummaryPeriod" usage: $ref: "#/components/schemas/UsageSummaryUsage" billing: $ref: "#/components/schemas/UsageSummaryBilling" required: - subscription_item_id - subscription_id - subscription_status - product - period - usage - billing UsageDailySnapshotV1: type: object properties: id: type: string format: uuid organization_id: type: string format: uuid description: UUID of the organization owning the snapshot. billing_account_id: type: string format: uuid description: UUID of the billing account associated with the snapshot. product_group_id: type: string format: uuid description: UUID of the product group. product_id: type: string format: uuid description: UUID of the product. snapshot_date: type: string format: date-time description: Snapshot date (ISO 8601, daily granularity). quantity: type: number description: Quantity reported in the record. cumulative_quantity: type: number description: Cumulative quantity of the snapshot. idempotency_key: type: string description: Idempotency key used at creation, if any. calculated_at: type: string format: date-time description: Date/time when the snapshot was calculated (ISO 8601). metadata: type: - object - "null" additionalProperties: {} description: Free-form metadata defined by the client. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - organization_id - billing_account_id - product_group_id - product_id - snapshot_date - quantity - cumulative_quantity - idempotency_key - calculated_at - metadata - created_at - updated_at UsageSnapshotListMeta: type: object properties: total: type: integer limit: type: integer offset: type: integer required: - total - limit - offset UsageDailySnapshotListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/UsageDailySnapshotV1" meta: $ref: "#/components/schemas/UsageSnapshotListMeta" required: - data - meta UsageDailySnapshotCreateInput: type: object properties: billing_account_id: type: string format: uuid description: Billing account UUID. Alternative to `billing_account_public_id`. billing_account_public_id: type: string description: Billing account public identifier. Alternative to `billing_account_id`. product_group_slug: type: string description: Product group slug — required. Scopes the `product_slug`/`product_id` lookup. product_slug: type: string description: Product slug within the group. Alternative to `product_id`. product_id: type: string format: uuid description: Product UUID within the group. Alternative to `product_slug`. snapshot_date: type: string description: Snapshot date in `YYYY-MM-DD` format (ISO 8601). example: 2026-03-15 quantity: type: number minimum: 0 description: Consolidated daily quantity — non-negative number. cumulative_quantity: type: number minimum: 0 description: "Cumulative quantity up to the day — non-negative number. Default: 0." idempotency_key: type: string minLength: 1 description: Idempotency key **required**. Must be unique across snapshots. calculated_at: type: string format: date-time description: "Date/time when the quantity was calculated (ISO 8601). Default: now." custom_metadata: type: - object - "null" additionalProperties: {} description: usage.daily_snapshots.create.body.custom_metadata required: - product_group_slug - snapshot_date - quantity - idempotency_key UsageDailySnapshotBatchCreateInput: type: object properties: records: type: array items: $ref: "#/components/schemas/UsageDailySnapshotCreateInput" minItems: 1 maxItems: 100 description: Daily snapshots batch (1 to 100). required: - records UsageDailySnapshotCreateRequest: anyOf: - $ref: "#/components/schemas/UsageDailySnapshotCreateInput" - $ref: "#/components/schemas/UsageDailySnapshotBatchCreateInput" UsageDailySnapshotBatchResult: type: object properties: id: type: string format: uuid description: UUID of the created or existing record. billing_account_id: type: string format: uuid product_id: type: string format: uuid success: type: boolean description: Indicates whether the record was processed successfully. overwritten: type: boolean description: When `true`, indicates a pre-existing snapshot was overwritten. error: type: string description: Error message when `success` is `false`. data: $ref: "#/components/schemas/UsageDailySnapshotV1" required: - success UsageDailySnapshotCreateResponse: type: object properties: success: type: boolean processed: type: integer failed: type: integer partial: type: boolean results: anyOf: - $ref: "#/components/schemas/UsageDailySnapshotBatchResult" - type: array items: $ref: "#/components/schemas/UsageDailySnapshotBatchResult" required: - success - processed - results UsageMonthlySnapshotV1: type: object properties: id: type: string format: uuid organization_id: type: string format: uuid description: UUID of the organization owning the snapshot. billing_account_id: type: string format: uuid description: UUID of the billing account associated with the snapshot. product_group_id: type: string format: uuid description: UUID of the product group. product_id: type: string format: uuid description: UUID of the product. month: type: string format: date-time description: Reference month (ISO 8601 — first day of the month). total_quantity: type: number description: Total accumulated quantity for the month. cumulative_quantity: type: number description: Cumulative quantity of the snapshot. avg_daily_quantity: type: number description: Average daily usage for the month. days_with_usage: type: integer description: Number of days with recorded usage in the month. plan_limit: type: - number - "null" description: Contracted plan limit for the period. `null` when unlimited. excess_quantity: type: number description: Excess quantity over the `plan_limit`. idempotency_key: type: string description: Idempotency key used at creation, if any. calculated_at: type: string format: date-time description: Date/time when the snapshot was calculated (ISO 8601). metadata: type: - object - "null" additionalProperties: {} description: Free-form metadata defined by the client. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - organization_id - billing_account_id - product_group_id - product_id - month - total_quantity - cumulative_quantity - avg_daily_quantity - days_with_usage - plan_limit - excess_quantity - idempotency_key - calculated_at - metadata - created_at - updated_at UsageMonthlySnapshotListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/UsageMonthlySnapshotV1" meta: $ref: "#/components/schemas/UsageSnapshotListMeta" required: - data - meta UsageMonthlySnapshotCreateInput: type: object properties: billing_account_id: type: string format: uuid description: Billing account UUID. Alternative to `billing_account_public_id`. billing_account_public_id: type: string description: Billing account public identifier. Alternative to `billing_account_id`. product_group_slug: type: string description: Product group slug — required. product_slug: type: string description: Product slug within the group. Alternative to `product_id`. product_id: type: string format: uuid description: Product UUID within the group. Alternative to `product_slug`. month: type: string description: "Reference month in `YYYY-MM-DD` format (use the first day of the month, e.g.: `2026-03-01`)." example: 2026-03-01 total_quantity: type: number minimum: 0 description: Total accumulated quantity for the month — non-negative number. cumulative_quantity: type: number minimum: 0 description: "Cumulative quantity up to the month — non-negative number. Default: 0." avg_daily_quantity: type: number minimum: 0 description: Average daily usage for the month — non-negative number. days_with_usage: type: integer minimum: 0 description: Number of days with recorded usage (non-negative integer). plan_limit: type: - number - "null" description: Contracted plan limit for the period (optional). Use `null` for unlimited. excess_quantity: type: number minimum: 0 description: Excess quantity over the `plan_limit` — non-negative number. idempotency_key: type: string minLength: 1 description: Idempotency key **required**. Must be unique across snapshots. calculated_at: type: string format: date-time description: "Date/time when the numbers were calculated (ISO 8601). Default: now." custom_metadata: type: - object - "null" additionalProperties: {} description: usage.monthly_snapshots.create.body.custom_metadata required: - product_group_slug - month - total_quantity - avg_daily_quantity - days_with_usage - excess_quantity - idempotency_key UsageMonthlySnapshotBatchCreateInput: type: object properties: records: type: array items: $ref: "#/components/schemas/UsageMonthlySnapshotCreateInput" minItems: 1 maxItems: 100 description: Monthly snapshots batch (1 to 100). required: - records UsageMonthlySnapshotCreateRequest: anyOf: - $ref: "#/components/schemas/UsageMonthlySnapshotCreateInput" - $ref: "#/components/schemas/UsageMonthlySnapshotBatchCreateInput" UsageMonthlySnapshotBatchResult: type: object properties: id: type: string format: uuid description: UUID of the created or existing record. billing_account_id: type: string format: uuid product_id: type: string format: uuid success: type: boolean description: Indicates whether the record was processed successfully. overwritten: type: boolean description: When `true`, indicates a pre-existing snapshot was overwritten. error: type: string description: Error message when `success` is `false`. data: $ref: "#/components/schemas/UsageMonthlySnapshotV1" required: - success UsageMonthlySnapshotCreateResponse: type: object properties: success: type: boolean processed: type: integer failed: type: integer partial: type: boolean results: anyOf: - $ref: "#/components/schemas/UsageMonthlySnapshotBatchResult" - type: array items: $ref: "#/components/schemas/UsageMonthlySnapshotBatchResult" required: - success - processed - results TaxRuleItemV1: type: object properties: id: type: string format: uuid tax_rule_id: type: string format: uuid description: UUID of the rule the item belongs to. tax_type: type: string enum: - iss - pis - cofins - csll - irpj - irrf - inss - cbs - ibs description: "Tax: `iss`, `pis`, `cofins`, `csll`, `irpj`, `irrf`, `csrf`, `inss`, `cbs` or `ibs`." rate: type: number description: "Percentage rate (0–100), up to 2 decimals. E.g.: `5.00` = 5%." example: 5 is_withheld: type: boolean description: When `true`, the tax is withheld at source. base_type: type: string enum: - service_value - service_value_minus_iss - presumed_base description: "Calculation base: `service_value`, `service_value_minus_iss` or `presumed_base`." is_exempt: type: boolean description: When `true`, indicates tax exemption. exemption_reason: type: - string - "null" description: Exemption reason, when `is_exempt = true`. created_at: type: string format: date-time required: - id - tax_rule_id - tax_type - rate - is_withheld - base_type - is_exempt - exemption_reason - created_at TaxRuleV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. scope: type: string enum: - global - organization - company - service - customer - municipality description: "Rule scope: `global`, `organization`, `company`, `service`, `customer` or `municipality`." priority: type: integer description: Priority. Higher value overrides lower-priority rules. example: 0 company_id: type: - string - "null" format: uuid description: Company UUID when `scope = company`. service_item_id: type: - string - "null" format: uuid description: Service item UUID when `scope = service`. billing_account_id: type: - string - "null" format: uuid description: Billing account UUID when `scope = customer`. customer_tax_type: type: - string - "null" enum: - pessoa_fisica - pessoa_juridica - mei - simples_optante - entidade_publica description: Customer tax type that the rule covers. municipality: type: - string - "null" description: IBGE municipality code (7 digits) when `scope = municipality`. operation_type: type: - string - "null" enum: - interno - externo description: "Operation type: `interno` or `externo`." name: type: string description: Human-readable rule name. description: type: - string - "null" description: Rule description. is_active: type: boolean description: Indicates whether the rule is active. effective_from: type: string format: date-time description: ISO 8601 date/time from which the rule is effective. effective_to: type: - string - "null" format: date-time description: ISO 8601 date/time when the rule stops being effective. `null` means open-ended. items: type: array items: $ref: "#/components/schemas/TaxRuleItemV1" description: Rule items list — one entry per tax. metadata: type: - object - "null" additionalProperties: {} description: Read-only internal metadata generated by the system. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - external_id - scope - priority - company_id - service_item_id - billing_account_id - customer_tax_type - municipality - operation_type - name - description - is_active - effective_from - effective_to - items - metadata - custom_metadata - created_at - updated_at TaxRuleListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/TaxRuleV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta TaxRuleResponse: type: object properties: data: $ref: "#/components/schemas/TaxRuleV1" required: - data TaxRuleItemInput: type: object properties: tax_type: type: string enum: - iss - pis - cofins - csll - irpj - irrf - inss - cbs - ibs description: "Tax: `iss`, `pis`, `cofins`, `csll`, `irpj`, `irrf`, `csrf`, `inss`, `cbs` or `ibs`." rate: type: number minimum: 0 maximum: 100 description: "Percentage rate (0–100), up to 2 decimals. E.g.: `5.00` = 5%." example: 5 is_withheld: type: boolean description: When `true`, the tax is withheld at source. base_type: type: string enum: - service_value - service_value_minus_iss - presumed_base description: "Calculation base: `service_value`, `service_value_minus_iss` or `presumed_base`." is_exempt: type: boolean description: When `true`, indicates tax exemption. exemption_reason: type: - string - "null" description: Exemption reason, when `is_exempt = true`. required: - tax_type - rate TaxRuleCreateRequest: type: object properties: name: type: string minLength: 1 description: Human-readable rule name. description: type: - string - "null" description: Optional rule description. scope: type: string enum: - global - organization - company - service - customer - municipality description: "Rule scope: `global`, `organization`, `company`, `service`, `customer` or `municipality`." priority: type: integer description: "Rule priority. Higher value overrides lower-priority rules. Default: `0`." example: 0 company_id: type: - string - "null" format: uuid description: Company UUID when `scope = company`. The company must belong to the current organization. service_item_id: type: - string - "null" format: uuid description: Service item UUID when `scope = service`. The item must belong to the current organization. billing_account_id: type: - string - "null" format: uuid description: Billing account UUID when `scope = customer`. The account must belong to the current organization. customer_tax_type: type: - string - "null" enum: - pessoa_fisica - pessoa_juridica - mei - simples_optante - entidade_publica description: "Customer tax type: `pessoa_fisica`, `pessoa_juridica`, `mei`, `simples_optante` or `entidade_publica`." municipality: type: - string - "null" description: IBGE municipality code (7 digits) when `scope = municipality`. operation_type: type: - string - "null" enum: - interno - externo description: "Operation type: `interno` (same municipality) or `externo` (different municipality)." effective_from: type: string format: date-time description: ISO 8601 date/time when the rule becomes effective. effective_to: type: - string - "null" format: date-time description: ISO 8601 date/time when the rule stops being effective. `null` means open-ended. items: type: array items: $ref: "#/components/schemas/TaxRuleItemInput" minItems: 1 description: List of items (per-tax rates). At least 1 item is required. external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). required: - name - scope - items TaxRuleUpdateRequest: type: object properties: name: type: string minLength: 1 description: New rule name. description: type: - string - "null" description: New rule description. priority: type: integer description: New rule priority. is_active: type: boolean description: When `false`, deactivates the rule without removing it. effective_to: type: - string - "null" format: date-time description: New ISO 8601 end-of-effectiveness date/time (or `null` for open-ended). items: type: array items: $ref: "#/components/schemas/TaxRuleItemInput" description: When provided, fully replaces the rule items list. external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). TaxRuleDeletedResponse: type: object properties: data: type: object properties: deleted: type: boolean example: true required: - deleted required: - data LateFeePolicyV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid name: type: string description: Policy name, unique within the organization. example: Padrão is_default: type: boolean description: Whether this is the organization default policy. fine_mode: type: string enum: - none - percentage - fixed description: How the fine is computed. Charged once. `percentage` uses `fine_percent`, `fixed` uses `fine_amount`. fine_percent: type: - number - "null" description: Fine as a percentage of the outstanding balance, 0 to 100. Populated only when `fine_mode` is `percentage`. example: 2 fine_amount: type: - number - "null" description: Flat fine amount, in BRL. Populated only when `fine_mode` is `fixed`. example: 50 fine_days: type: integer description: Days past the due date when the fine starts applying. Default is 1 — the day after the due date. example: 1 interest_mode: type: string enum: - none - daily_amount - daily_percentage - monthly_percentage - yearly_percentage description: How interest accrues. The percentage modes use `interest_percent`; `daily_amount` uses `interest_amount`. Interest is charged on the principal alone, never on principal plus fine. interest_percent: type: - number - "null" description: Interest percentage per day, month or year, per `interest_mode`. The monthly rate is divided pro rata die by 30; the yearly one by 360. example: 1 interest_amount: type: - number - "null" description: Flat interest amount per day, in BRL. Populated only when `interest_mode` is `daily_amount`. example: 1.5 interest_days: type: integer description: Days past the due date when interest starts accruing. Default is 1. example: 1 day_count: type: string enum: - calendar - business description: "Day-count basis for the delay. Only `calendar` is accepted for now: the local accrual has no holiday calendar yet, and counting business days without one would overstate the charge against what the bank collects." max_interest_months: type: - integer - "null" description: Ceiling on accumulated months of interest. Null means uncapped. max_total_charge_percent: type: - number - "null" description: Ceiling on the total charge (fine plus interest) as a percentage of the outstanding balance. The fine is kept whole and the interest is trimmed when the cap bites. enforce_legal_caps: type: boolean description: When true, refuses a fine above 2% and interest above 1% per month. Turning it off is a deliberate choice for contracts outside consumer relations, and is audited. partial_allocation: type: string enum: - charges_first - principal_first description: "Imputation order when a payment covers neither principal nor charges. `charges_first` follows art. 354 of the Brazilian Civil Code: interest before capital." register_on_charge: type: boolean description: Registers the fine and interest instruction with the bank when issuing a bank slip or Pix, so the charge itself collects them after the due date. apply_on_dynamic_charge: type: boolean description: Recomputes the charged amount on card charges and re-issues, where no bank instruction can collect the charge. charge_instructions: type: - string - "null" description: Free text printed in the bank slip instructions. metadata: type: - object - "null" additionalProperties: {} custom_metadata: type: - object - "null" additionalProperties: {} created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - name - is_default - fine_mode - fine_percent - fine_amount - fine_days - interest_mode - interest_percent - interest_amount - interest_days - day_count - max_interest_months - max_total_charge_percent - enforce_legal_caps - partial_allocation - register_on_charge - apply_on_dynamic_charge - charge_instructions - metadata - custom_metadata - created_at - updated_at LateFeePolicyListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/LateFeePolicyV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta LateFeePolicyResponse: type: object properties: data: $ref: "#/components/schemas/LateFeePolicyV1" required: - data LateFeePolicyCreateRequest: type: object properties: name: type: string minLength: 1 maxLength: 120 description: Policy name, unique within the organization. example: Padrão is_default: type: boolean description: Whether this is the organization default policy. fine_mode: type: string enum: - none - percentage - fixed description: How the fine is computed. Charged once. `percentage` uses `fine_percent`, `fixed` uses `fine_amount`. fine_percent: type: number minimum: 0 maximum: 100 description: Fine as a percentage of the outstanding balance, 0 to 100. Populated only when `fine_mode` is `percentage`. example: 2 fine_amount: type: number minimum: 0 description: Flat fine amount, in BRL. Populated only when `fine_mode` is `fixed`. fine_days: type: integer minimum: 0 maximum: 365 description: Days past the due date when the fine starts applying. Default is 1 — the day after the due date. interest_mode: type: string enum: - none - daily_amount - daily_percentage - monthly_percentage - yearly_percentage description: How interest accrues. The percentage modes use `interest_percent`; `daily_amount` uses `interest_amount`. Interest is charged on the principal alone, never on principal plus fine. interest_percent: type: number minimum: 0 maximum: 100 description: Interest percentage per day, month or year, per `interest_mode`. The monthly rate is divided pro rata die by 30; the yearly one by 360. example: 1 interest_amount: type: number minimum: 0 description: Flat interest amount per day, in BRL. Populated only when `interest_mode` is `daily_amount`. interest_days: type: integer minimum: 0 maximum: 365 description: Days past the due date when interest starts accruing. Default is 1. day_count: type: string enum: - calendar - business description: "Day-count basis for the delay. Only `calendar` is accepted for now: the local accrual has no holiday calendar yet, and counting business days without one would overstate the charge against what the bank collects." max_interest_months: type: - integer - "null" minimum: 1 maximum: 120 description: Ceiling on accumulated months of interest. Null means uncapped. max_total_charge_percent: type: - number - "null" minimum: 0 maximum: 100 description: Ceiling on the total charge (fine plus interest) as a percentage of the outstanding balance. The fine is kept whole and the interest is trimmed when the cap bites. enforce_legal_caps: type: boolean description: When true, refuses a fine above 2% and interest above 1% per month. Turning it off is a deliberate choice for contracts outside consumer relations, and is audited. partial_allocation: type: string enum: - charges_first - principal_first description: "Imputation order when a payment covers neither principal nor charges. `charges_first` follows art. 354 of the Brazilian Civil Code: interest before capital." register_on_charge: type: boolean description: Registers the fine and interest instruction with the bank when issuing a bank slip or Pix, so the charge itself collects them after the due date. apply_on_dynamic_charge: type: boolean description: Recomputes the charged amount on card charges and re-issues, where no bank instruction can collect the charge. charge_instructions: type: - string - "null" maxLength: 500 description: Free text printed in the bank slip instructions. required: - name LateFeePolicyUpdateRequest: type: object properties: name: type: string minLength: 1 maxLength: 120 description: Policy name, unique within the organization. is_default: type: boolean description: Whether this is the organization default policy. fine_mode: type: string enum: - none - percentage - fixed description: How the fine is computed. Charged once. `percentage` uses `fine_percent`, `fixed` uses `fine_amount`. fine_percent: type: number minimum: 0 maximum: 100 description: Fine as a percentage of the outstanding balance, 0 to 100. Populated only when `fine_mode` is `percentage`. example: 2 fine_amount: type: number minimum: 0 description: Flat fine amount, in BRL. Populated only when `fine_mode` is `fixed`. fine_days: type: integer minimum: 0 maximum: 365 description: Days past the due date when the fine starts applying. Default is 1 — the day after the due date. interest_mode: type: string enum: - none - daily_amount - daily_percentage - monthly_percentage - yearly_percentage description: How interest accrues. The percentage modes use `interest_percent`; `daily_amount` uses `interest_amount`. Interest is charged on the principal alone, never on principal plus fine. interest_percent: type: number minimum: 0 maximum: 100 description: Interest percentage per day, month or year, per `interest_mode`. The monthly rate is divided pro rata die by 30; the yearly one by 360. example: 1 interest_amount: type: number minimum: 0 description: Flat interest amount per day, in BRL. Populated only when `interest_mode` is `daily_amount`. interest_days: type: integer minimum: 0 maximum: 365 description: Days past the due date when interest starts accruing. Default is 1. day_count: type: string enum: - calendar - business description: "Day-count basis for the delay. Only `calendar` is accepted for now: the local accrual has no holiday calendar yet, and counting business days without one would overstate the charge against what the bank collects." max_interest_months: type: - integer - "null" minimum: 1 maximum: 120 description: Ceiling on accumulated months of interest. Null means uncapped. max_total_charge_percent: type: - number - "null" minimum: 0 maximum: 100 description: Ceiling on the total charge (fine plus interest) as a percentage of the outstanding balance. The fine is kept whole and the interest is trimmed when the cap bites. enforce_legal_caps: type: boolean description: When true, refuses a fine above 2% and interest above 1% per month. Turning it off is a deliberate choice for contracts outside consumer relations, and is audited. partial_allocation: type: string enum: - charges_first - principal_first description: "Imputation order when a payment covers neither principal nor charges. `charges_first` follows art. 354 of the Brazilian Civil Code: interest before capital." register_on_charge: type: boolean description: Registers the fine and interest instruction with the bank when issuing a bank slip or Pix, so the charge itself collects them after the due date. apply_on_dynamic_charge: type: boolean description: Recomputes the charged amount on card charges and re-issues, where no bank instruction can collect the charge. charge_instructions: type: - string - "null" maxLength: 500 description: Free text printed in the bank slip instructions. LateFeePolicyDeletedResponse: type: object properties: data: type: object properties: deleted: type: boolean required: - deleted required: - data LateChargesSimulateRequest: type: object properties: principal: type: number exclusiveMinimum: 0 description: Outstanding balance to accrue the charges on, in BRL. example: 1000 due_date: type: string format: date-time description: Due date the delay is counted from. reference_date: type: string format: date-time description: Date to accrue at. Defaults to now. Days are counted on the civil date in America/Sao_Paulo. policy_id: type: string format: uuid description: Existing policy to use. Alternative to `policy`. policy: allOf: - $ref: "#/components/schemas/LateFeePolicyUpdateRequest" - description: Inline policy, with the same fields as on create. Alternative to `policy_id`. required: - principal - due_date LateChargesSimulateResponse: type: object properties: data: type: object properties: days_past_due: type: integer description: Calendar days past the due date. interest_days_elapsed: type: integer description: Days interest actually accrued for, after `interest_days` and any cap. fine: type: number description: Fine accrued, in BRL. example: 20 interest: type: number description: Interest accrued, in BRL. example: 10 total: type: number description: Fine plus interest, in BRL. example: 30 principal: type: number description: Outstanding balance to accrue the charges on, in BRL. example: 1000 total_due: type: number description: Outstanding balance plus the charges. example: 1030 capped_by: type: - string - "null" enum: - max_interest_months - max_total_charge description: Which ceiling truncated the result, if any. as_of: type: string format: date-time description: Accrual date used. The charges change every day, which is why the result is not stored. required: - days_past_due - interest_days_elapsed - fine - interest - total - principal - total_due - capped_by - as_of required: - data HolidayV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid date: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: "Calendar day of the holiday, as `YYYY-MM-DD`. No time of day: a holiday is a date on a wall calendar, and accepting an instant would make the stored day depend on the sender timezone." example: 2026-01-01 name: type: string description: Holiday name. Together with the date it identifies the row — a municipal and a national holiday can fall on the same day. example: Confraternização mundial type: type: string enum: - national - state - municipal - optional - custom description: "Scope: national, state, municipal, an optional day off (`optional`), or the organization own (`custom`)." source: type: string enum: - brasil_api - manual description: "Where the row came from: `brasil_api` for what the import brought, `manual` for what was entered. The import refreshes what it brought and leaves typed rows alone." notes: type: - string - "null" description: Free text — the city of a municipal holiday, or any note. metadata: type: - object - "null" additionalProperties: {} custom_metadata: type: - object - "null" additionalProperties: {} created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - date - name - type - source - notes - metadata - custom_metadata - created_at - updated_at HolidayListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/HolidayV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta HolidayResponse: type: object properties: data: $ref: "#/components/schemas/HolidayV1" required: - data HolidayCreateRequest: type: object properties: date: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: "Calendar day of the holiday, as `YYYY-MM-DD`. No time of day: a holiday is a date on a wall calendar, and accepting an instant would make the stored day depend on the sender timezone." example: 2026-07-09 name: type: string minLength: 1 maxLength: 120 description: Holiday name. Together with the date it identifies the row — a municipal and a national holiday can fall on the same day. example: Revolução Constitucionalista type: type: string enum: - national - state - municipal - optional - custom description: "Scope: national, state, municipal, an optional day off (`optional`), or the organization own (`custom`)." notes: type: - string - "null" maxLength: 500 description: Free text — the city of a municipal holiday, or any note. required: - date - name HolidayUpdateRequest: type: object properties: date: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: "Calendar day of the holiday, as `YYYY-MM-DD`. No time of day: a holiday is a date on a wall calendar, and accepting an instant would make the stored day depend on the sender timezone." name: type: string minLength: 1 maxLength: 120 description: Holiday name. Together with the date it identifies the row — a municipal and a national holiday can fall on the same day. type: type: string enum: - national - state - municipal - optional - custom description: "Scope: national, state, municipal, an optional day off (`optional`), or the organization own (`custom`)." notes: type: - string - "null" maxLength: 500 description: Free text — the city of a municipal holiday, or any note. HolidayDeletedResponse: type: object properties: data: type: object properties: deleted: type: boolean required: - deleted required: - data HolidaySyncRequest: type: object properties: years: type: array items: type: integer minimum: 1900 maximum: 2199 minItems: 1 maxItems: 20 description: Years to import. Defaults to the current one plus the next two. example: - 2026 - 2027 HolidaySyncResponse: type: object properties: data: type: object properties: years: type: array items: type: integer description: Years processed. created: type: integer description: Holidays inserted. existing: type: integer description: Already present — nothing to do. skipped_removed: type: integer description: Present but removed, so deliberately left out. required: - years - created - existing - skipped_removed required: - data BankV1: type: object properties: id: type: string format: uuid code: type: string description: Three-digit COMPE code. example: "341" name: type: string description: Bank name. example: Itaú Unibanco S.A. required: - id - code - name BankListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/BankV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta BankAccountV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid external_id: type: - string - "null" description: Identifier in the source system (reserved for the Financeiro Inteligente integration). company_id: type: - string - "null" format: uuid description: Issuing company it belongs to (optional). bank_id: type: string format: uuid description: Bank UUID (see `/banks`). name: type: string description: Account nickname, for the operator. example: Conta principal Itaú type: type: string enum: - checking - savings description: "`checking` or `savings`." agency: type: string description: Branch number, digits only. example: "1234" agency_digit: type: - string - "null" description: Branch check digit, when there is one. account_number: type: string description: Account number, digits only. example: "56789" account_digit: type: - string - "null" description: Account check digit, when there is one. example: "0" holder_name: type: - string - "null" description: Holder shown to the customer. Empty uses the legal name of the invoice issuing company (or the organization). holder_document: type: - string - "null" description: Holder CPF/CNPJ, digits only. Empty uses the document of the issuing company (or the organization). example: "12345678000190" active: type: boolean description: Only active destinations can be chosen for a new charge. metadata: type: - object - "null" additionalProperties: {} custom_metadata: type: - object - "null" additionalProperties: {} created_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel through which the record was created (dashboard, import, api, mcp, cli, other). On API calls it comes from the `X-Request-Source` header. created_by_email: type: - string - "null" description: Email of the user who created the record. updated_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel of the last update to the record. updated_by_email: type: - string - "null" description: Email of the user who made the last update. created_at: type: string format: date-time updated_at: type: string format: date-time bank: allOf: - $ref: "#/components/schemas/BankV1" - type: - object - "null" description: The account bank. required: - id - public_id - external_id - company_id - bank_id - name - type - agency - agency_digit - account_number - account_digit - holder_name - holder_document - active - metadata - custom_metadata - created_via - created_by_email - updated_via - updated_by_email - created_at - updated_at - bank BankAccountListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/BankAccountV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta BankAccountResponse: type: object properties: data: $ref: "#/components/schemas/BankAccountV1" required: - data BankAccountCreateRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 description: Account nickname, for the operator. example: Conta principal Itaú bank_id: type: string format: uuid description: Bank UUID (see `/banks`). type: type: string enum: - checking - savings description: "`checking` or `savings`." agency: type: string minLength: 1 maxLength: 50 description: Branch number, digits only. example: "1234" agency_digit: type: - string - "null" maxLength: 5 description: Branch check digit, when there is one. account_number: type: string minLength: 1 maxLength: 50 description: Account number, digits only. example: "56789" account_digit: type: - string - "null" maxLength: 5 description: Account check digit, when there is one. example: "0" holder_name: type: - string - "null" maxLength: 255 description: Holder shown to the customer. Empty uses the legal name of the invoice issuing company (or the organization). holder_document: type: - string - "null" maxLength: 20 description: Holder CPF/CNPJ, digits only. Empty uses the document of the issuing company (or the organization). company_id: type: - string - "null" format: uuid description: Issuing company it belongs to (optional). active: type: boolean description: Only active destinations can be chosen for a new charge. required: - name - bank_id - agency - account_number BankAccountUpdateRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 description: Account nickname, for the operator. example: Conta principal Itaú bank_id: type: string format: uuid description: Bank UUID (see `/banks`). type: type: string enum: - checking - savings description: "`checking` or `savings`." agency: type: string minLength: 1 maxLength: 50 description: Branch number, digits only. example: "1234" agency_digit: type: - string - "null" maxLength: 5 description: Branch check digit, when there is one. account_number: type: string minLength: 1 maxLength: 50 description: Account number, digits only. example: "56789" account_digit: type: - string - "null" maxLength: 5 description: Account check digit, when there is one. example: "0" holder_name: type: - string - "null" maxLength: 255 description: Holder shown to the customer. Empty uses the legal name of the invoice issuing company (or the organization). holder_document: type: - string - "null" maxLength: 20 description: Holder CPF/CNPJ, digits only. Empty uses the document of the issuing company (or the organization). company_id: type: - string - "null" format: uuid description: Issuing company it belongs to (optional). active: type: boolean description: Only active destinations can be chosen for a new charge. PixKeyV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid external_id: type: - string - "null" description: Identifier in the source system (reserved for the Financeiro Inteligente integration). company_id: type: - string - "null" format: uuid description: Issuing company it belongs to (optional). key: type: string description: The key, unmasked (documents as digits only, phone with `+55`, email and random key lowercased). example: "12345678000190" key_type: type: string enum: - cpf - cnpj - email - phone - random description: "Key type: `cpf`, `cnpj`, `email`, `phone` or `random`." description: type: - string - "null" description: Free description for the operator (e.g. "Main Pix"). example: Pix principal holder_name: type: - string - "null" description: Holder shown to the customer. Empty uses the legal name of the invoice issuing company (or the organization). holder_document: type: - string - "null" description: Holder CPF/CNPJ, digits only. Empty uses the document of the issuing company (or the organization). example: "12345678000190" active: type: boolean description: Only active destinations can be chosen for a new charge. metadata: type: - object - "null" additionalProperties: {} custom_metadata: type: - object - "null" additionalProperties: {} created_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel through which the record was created (dashboard, import, api, mcp, cli, other). On API calls it comes from the `X-Request-Source` header. created_by_email: type: - string - "null" description: Email of the user who created the record. updated_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel of the last update to the record. updated_by_email: type: - string - "null" description: Email of the user who made the last update. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - external_id - company_id - key - key_type - description - holder_name - holder_document - active - metadata - custom_metadata - created_via - created_by_email - updated_via - updated_by_email - created_at - updated_at PixKeyListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/PixKeyV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta PixKeyResponse: type: object properties: data: $ref: "#/components/schemas/PixKeyV1" required: - data PixKeyCreateRequest: type: object properties: key: type: string minLength: 1 maxLength: 255 description: The key, unmasked (documents as digits only, phone with `+55`, email and random key lowercased). example: financeiro@empresa.com.br key_type: type: string enum: - cpf - cnpj - email - phone - random description: "Key type: `cpf`, `cnpj`, `email`, `phone` or `random`." description: type: - string - "null" maxLength: 255 description: Free description for the operator (e.g. "Main Pix"). holder_name: type: - string - "null" maxLength: 255 description: Holder shown to the customer. Empty uses the legal name of the invoice issuing company (or the organization). holder_document: type: - string - "null" maxLength: 20 description: Holder CPF/CNPJ, digits only. Empty uses the document of the issuing company (or the organization). company_id: type: - string - "null" format: uuid description: Issuing company it belongs to (optional). active: type: boolean description: Only active destinations can be chosen for a new charge. required: - key PixKeyUpdateRequest: type: object properties: key: type: string minLength: 1 maxLength: 255 description: The key, unmasked (documents as digits only, phone with `+55`, email and random key lowercased). example: financeiro@empresa.com.br key_type: type: string enum: - cpf - cnpj - email - phone - random description: "Key type: `cpf`, `cnpj`, `email`, `phone` or `random`." description: type: - string - "null" maxLength: 255 description: Free description for the operator (e.g. "Main Pix"). holder_name: type: - string - "null" maxLength: 255 description: Holder shown to the customer. Empty uses the legal name of the invoice issuing company (or the organization). holder_document: type: - string - "null" maxLength: 20 description: Holder CPF/CNPJ, digits only. Empty uses the document of the issuing company (or the organization). company_id: type: - string - "null" format: uuid description: Issuing company it belongs to (optional). active: type: boolean description: Only active destinations can be chosen for a new charge. TransferDestinationDeletedResponse: type: object properties: data: type: object properties: deleted: type: boolean required: - deleted required: - data TaxPeriodV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. company_id: type: string format: uuid description: Issuing company UUID. period_type: type: string enum: - monthly - quarterly description: "Period type: `monthly` or `quarterly`." year: type: integer description: Reference year. example: 2026 month: type: - integer - "null" minimum: 1 maximum: 12 description: Reference month (1 to 12) — only set on monthly periods. quarter: type: - integer - "null" minimum: 1 maximum: 4 description: Reference quarter (1 to 4) — only set on quarterly periods. status: type: string enum: - open - calculated - closed description: "Period status: `open`, `calculated` or `closed`." gross_revenue: type: number description: Gross revenue computed for the period, in BRL (float, up to 4 decimal places). example: 1000 taxable_revenue: type: number description: Taxable revenue for the period, in BRL (float, up to 4 decimal places). iss_due: type: number description: ISS due for the period, in BRL (float, up to 4 decimal places). pis_due: type: number description: PIS due for the period, in BRL (float, up to 4 decimal places). cofins_due: type: number description: COFINS due for the period, in BRL (float, up to 4 decimal places). irpj_due: type: number description: IRPJ due (monthly estimate), in BRL (float, up to 4 decimal places). csll_due: type: number description: CSLL due (monthly estimate), in BRL (float, up to 4 decimal places). irrf_to_compensate: type: number description: IRRF withheld pending compensation, in BRL (float, up to 4 decimal places). csrf_to_compensate: type: number description: CSRF (withheld PIS/COFINS/CSLL) pending compensation, in BRL (float, up to 4 decimal places). iss_to_compensate: type: number description: ISS withheld pending compensation, in BRL (float, up to 4 decimal places). das_estimated: type: - number - "null" description: Estimated DAS (Simples Nacional), in BRL (float, up to 4 decimal places). simples_effective_rate: type: - string - "null" description: Effective Simples Nacional rate applied in the period (percent). simples_annex: type: - string - "null" description: "Applicable Simples Nacional annex (e.g.: `annex_iii`, `annex_v`)." cbs_due: type: number description: CBS due (2026+ tax reform), in BRL (float, up to 4 decimal places). ibs_due: type: number description: IBS due (2026+ tax reform), in BRL (float, up to 4 decimal places). calculation_log: type: - object - "null" additionalProperties: {} description: JSON log of the calculation memory (regime, NFes considered, rates). closed_at: type: - string - "null" format: date-time description: Date/time when the period was closed. metadata: type: - object - "null" additionalProperties: {} description: Read-only internal metadata generated by the system. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - external_id - company_id - period_type - year - month - quarter - status - gross_revenue - taxable_revenue - iss_due - pis_due - cofins_due - irpj_due - csll_due - irrf_to_compensate - csrf_to_compensate - iss_to_compensate - das_estimated - simples_effective_rate - simples_annex - cbs_due - ibs_due - calculation_log - closed_at - metadata - custom_metadata - created_at - updated_at TaxPeriodListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/TaxPeriodV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta TaxPeriodResponse: type: object properties: data: $ref: "#/components/schemas/TaxPeriodV1" required: - data TaxPeriodCreateRequest: type: object properties: company_id: type: string format: uuid description: UUID of the issuing company. Omit to use the organization default company. year: type: integer minimum: 2020 maximum: 2100 description: "Reference year (e.g.: `2026`)." example: 2026 month: type: integer minimum: 1 maximum: 12 description: Reference month (1 to 12). example: 6 external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). required: - year - month TaxPeriodUpdateRequest: type: object properties: action: type: string enum: - recalculate - close - reopen description: "Action to execute: `recalculate`, `close` or `reopen`." required: - action TaxPeriodDeletedResponse: type: object properties: data: type: object properties: deleted: type: boolean example: true required: - deleted required: - data WithholdingV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. organization_id: type: string format: uuid description: UUID of the organization that owns the withholding. invoice_id: type: - string - "null" format: uuid description: UUID of the associated invoice, when present. nfe_id: type: - string - "null" format: uuid description: UUID of the associated NF-e, when present. tax_type: type: string enum: - iss - pis - cofins - csll - irpj - irrf - csrf - inss - cbs - ibs description: "Withheld tax type: `iss`, `pis`, `cofins`, `csll`, `irpj`, `irrf`, `csrf`, `inss`, `cbs` or `ibs`." base: type: number description: Calculation base in BRL (float, up to 4 decimal places). example: 1000 rate: type: number description: "Applied rate as a percentage (e.g.: `1.5` for 1.5%)." example: 1.5 amount: type: number description: Withheld amount in BRL (float, up to 4 decimal places). example: 15 withholder_id: type: string format: uuid description: UUID of the withholder's billing account (the entity that withheld the tax). status: type: string enum: - retained - compensated - partially_compensated description: "Withholding status: `retained`, `compensated` or `partially_compensated`." compensated: type: number description: Amount already compensated/converted into credit, in BRL (float, up to 4 decimal places). example: 0 competence_month: type: integer minimum: 1 maximum: 12 description: Competence month (1–12). competence_year: type: integer description: Competence year (2000–3000). metadata: type: - object - "null" additionalProperties: {} description: Free-form metadata attached to the withholding. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - external_id - organization_id - invoice_id - nfe_id - tax_type - base - rate - amount - withholder_id - status - compensated - competence_month - competence_year - metadata - custom_metadata - created_at - updated_at WithholdingListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/WithholdingV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta WithholdingResponse: type: object properties: data: $ref: "#/components/schemas/WithholdingV1" required: - data WithholdingConvertToCreditRequest: type: object properties: amount: type: number exclusiveMinimum: 0 description: "Amount to convert in BRL (float, up to 4 decimal places). Default: pending balance of the withholding." WithholdingConvertToCreditResponse: type: object properties: credit: allOf: - $ref: "#/components/schemas/CreditV1" - description: Credit generated by converting the withholding. required: - credit WithholdingBulkConvertRequest: type: object properties: tax_type: type: string enum: - iss - pis - cofins - csll - irpj - irrf - csrf - inss - cbs - ibs description: "Restricts conversion to a specific tax type (e.g.: `irrf`, `pis`, `cofins`)." competence_year: type: integer minimum: 2000 maximum: 3000 description: Restricts conversion to the given competence year. competence_month: type: integer minimum: 1 maximum: 12 description: Restricts conversion to the given competence month (1–12). WithholdingBulkConvertResponse: type: object properties: credits: type: array items: $ref: "#/components/schemas/CreditV1" description: List of credits generated by the conversion. total_converted: type: integer description: Total number of withholdings converted into credits. total_amount: type: number description: Sum of converted amounts in BRL (float, up to 4 decimal places). required: - credits - total_converted - total_amount WithholdingCreateRequest: type: object properties: tax_type: type: string enum: - iss - pis - cofins - csll - irpj - irrf - csrf - inss - cbs - ibs description: Withheld tax. base: type: number minimum: 0 description: Calculation base, in BRL (float, up to 4 decimal places). example: 1000 rate: type: number minimum: 0 description: Applied rate, as a percentage. example: 1.5 amount: type: number minimum: 0 description: Withheld amount, in BRL (float, up to 4 decimal places). example: 15 withholder_id: type: string format: uuid description: Billing account that performed the withholding. competence_month: type: integer minimum: 1 maximum: 12 description: Competence month (1–12). competence_year: type: integer minimum: 2000 maximum: 3000 description: Competence year. invoice_id: type: string format: uuid description: Originating invoice, when there is one. nfe_id: type: string format: uuid description: Related invoice document (NF-e), when there is one. metadata: type: object additionalProperties: {} external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: object additionalProperties: {} required: - tax_type - base - rate - amount - withholder_id - competence_month - competence_year WithholdingUpdateRequest: type: object properties: competence_month: type: integer minimum: 1 maximum: 12 description: Competence month (1–12). competence_year: type: integer minimum: 2000 maximum: 3000 description: Competence year. metadata: type: object additionalProperties: {} external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: object additionalProperties: {} ServiceItemV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. organization_id: type: string format: uuid company_id: type: - string - "null" format: uuid description: UUID of the issuing company associated with the item. `null` when the item applies to all companies in the organization. name: type: string description: Service item name (shown on invoices and NFS-e). description: type: - string - "null" description: Optional service description. internal_code: type: string description: Internal item code — immutable after creation. lc116_code: type: string description: Service code per Complementary Law 116/2003 (e.g. `01.05`). example: "01.05" municipal_code: type: - string - "null" description: Municipal service code, when the municipality requires its own coding. nbs_code: type: - string - "null" description: NBS code — Brazilian Service Nomenclature. cnae_code: type: - string - "null" description: CNAE code related to the service provided. simples_annex: type: - string - "null" enum: - annex_iii - annex_iv - annex_v description: "Simples Nacional annex applicable to the service: `annex_iii`, `annex_iv` or `annex_v`." default_iss_rate: type: - string - "null" description: Default ISS rate in percentage points (e.g. `2.5` means 2.5%). Decimal with up to two places. example: "2.50" c_class_trib: type: - string - "null" description: Tax classification (IBS/CBS CST) applicable to the item. cbs_ibs_category: type: - string - "null" description: CBS/IBS category for the item, per the tax reform. indop_code: type: - string - "null" description: Operation Indicator (`indOp`) used in SNNFSE NFS-e. is_active: type: boolean description: When `false`, the item cannot be selected on new invoices or NFS-e. metadata: type: - object - "null" additionalProperties: {} description: Internal item metadata (platform use). custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). created_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel through which the record was created (dashboard, import, api, mcp, cli, other). On API calls it comes from the `X-Request-Source` header. created_via_other: type: - string - "null" description: Name of the app that created the record when `created_via` is `other` (`X-Request-Source-Other` header). created_by_email: type: - string - "null" description: Email of the user who created the record. updated_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel of the last update to the record. updated_via_other: type: - string - "null" description: Name of the app behind the last update when `updated_via` is `other` (`X-Request-Source-Other` header). updated_by_email: type: - string - "null" description: Email of the user who made the last update. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - external_id - organization_id - company_id - name - description - internal_code - lc116_code - municipal_code - nbs_code - cnae_code - simples_annex - default_iss_rate - c_class_trib - cbs_ibs_category - indop_code - is_active - metadata - custom_metadata - created_via - created_via_other - created_by_email - updated_via - updated_via_other - updated_by_email - created_at - updated_at ServiceItemListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/ServiceItemV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta ServiceItemResponse: type: object properties: data: $ref: "#/components/schemas/ServiceItemV1" required: - data ServiceItemCreateRequest: type: object properties: external_id: type: string description: Identifier in your external system, for idempotency/sync. company_id: type: - string - "null" format: uuid description: UUID of the associated issuing company. Omit or send `null` for an item applicable to all companies. name: type: string minLength: 1 description: Service item name. description: type: - string - "null" description: Optional description. internal_code: type: string minLength: 1 description: Internal item code — immutable after creation. lc116_code: type: string minLength: 1 description: LC 116/2003 service code (e.g. `01.05`). example: "01.05" municipal_code: type: - string - "null" description: Municipal service code, when applicable. nbs_code: type: - string - "null" description: NBS code. cnae_code: type: - string - "null" description: Related CNAE code. simples_annex: type: - string - "null" enum: - annex_iii - annex_iv - annex_v description: "Applicable Simples Nacional annex: `annex_iii`, `annex_iv` or `annex_v`." default_iss_rate: type: - number - "null" description: Default ISS rate in percentage points (e.g. `2.5`). example: 2.5 c_class_trib: type: - string - "null" description: IBS/CBS CST tax classification. cbs_ibs_category: type: - string - "null" description: CBS/IBS category for the item. indop_code: type: - string - "null" description: SNNFSE NFS-e Operation Indicator (`indOp`). custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). required: - name - internal_code - lc116_code ServiceItemUpdateRequest: type: object properties: external_id: type: - string - "null" description: New identifier in your external system. Send `null` to clear. company_id: type: - string - "null" format: uuid description: New associated issuing company. Send `null` to disassociate. name: type: string minLength: 1 description: New item name. description: type: - string - "null" description: New description. Send `null` to clear. lc116_code: type: string minLength: 1 description: New LC 116/2003 code. municipal_code: type: - string - "null" description: New municipal code. Send `null` to clear. nbs_code: type: - string - "null" description: New NBS code. Send `null` to clear. cnae_code: type: - string - "null" description: New CNAE code. Send `null` to clear. simples_annex: type: - string - "null" enum: - annex_iii - annex_iv - annex_v description: New Simples Nacional annex. Send `null` to clear. default_iss_rate: type: - number - "null" description: New default ISS rate in percentage points. Send `null` to clear. c_class_trib: type: - string - "null" description: New IBS/CBS CST tax classification. Send `null` to clear. cbs_ibs_category: type: - string - "null" description: New CBS/IBS category. Send `null` to clear. indop_code: type: - string - "null" description: New Operation Indicator (`indOp`). Send `null` to clear. is_active: type: boolean description: Activates (`true`) or deactivates (`false`) the service item. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). custom_metadata_mode: type: string enum: - replace - merge description: How the submitted `custom_metadata` is reconciled with the stored value. `replace` (default) overwrites the whole object; `merge` deep-merges over the current value — nested objects merge recursively, scalars and arrays overwrite the key, and `null` keys are kept (they do not delete the key). Accepted on update only. example: merge DashboardUserRoleSummary: type: object properties: id: type: string format: uuid description: Role UUID. name: type: string description: Role name. slug: type: string description: Role slug (stable identifier). required: - id - name - slug DashboardUserV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. organization_id: type: string format: uuid description: UUID of the organization the user belongs to. person_id: type: - string - "null" format: uuid description: UUID of the person (identity record) linked to the user, when present. external_id: type: string description: External user identifier in Kobana OAuth. email: type: string format: email description: User email. name: type: - string - "null" description: Display name. picture: type: - string - "null" description: URL of the user picture. status: type: string enum: - active - pending_invitation - suspended description: "Current user status: `active`, `pending_invitation` or `suspended`." permissions: type: array items: type: string description: Ad-hoc permissions assigned directly to the user (on top of those inherited from roles). last_login_at: type: - string - "null" format: date-time description: Date/time of the last login. login_count: type: integer description: Total number of logins performed. show_getting_started: type: boolean description: Indicates whether the "Getting started" panel should be shown to the user. email_signature: type: - string - "null" description: Email signature configured by the user. metadata: type: - object - "null" additionalProperties: {} description: Internal system metadata. custom_metadata: type: - object - "null" additionalProperties: {} description: Free-form metadata defined by the client. created_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel through which the record was created (dashboard, import, api, mcp, cli, other). On API calls it comes from the `X-Request-Source` header. created_via_other: type: - string - "null" description: Name of the app that created the record when `created_via` is `other` (`X-Request-Source-Other` header). created_by_email: type: - string - "null" description: Email of the user who created the record. updated_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel of the last update to the record. updated_via_other: type: - string - "null" description: Name of the app behind the last update when `updated_via` is `other` (`X-Request-Source-Other` header). updated_by_email: type: - string - "null" description: Email of the user who made the last update. created_at: type: string format: date-time updated_at: type: string format: date-time roles: type: array items: $ref: "#/components/schemas/DashboardUserRoleSummary" description: Roles assigned to the user, expanded as `{ id, name, slug }`. required: - id - public_id - organization_id - person_id - external_id - email - name - picture - status - permissions - last_login_at - login_count - show_getting_started - email_signature - metadata - custom_metadata - created_via - created_via_other - created_by_email - updated_via - updated_via_other - updated_by_email - created_at - updated_at DashboardUserListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/DashboardUserV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta DashboardUserResponse: type: object properties: data: $ref: "#/components/schemas/DashboardUserV1" required: - data DashboardUserCreateRequest: type: object properties: email: type: string format: email description: Email of the user to invite. name: type: string description: User name (optional — may be filled in by the user on first login). external_id: type: string description: External user identifier in Kobana OAuth, when already known. role_ids: type: array items: type: string format: uuid minItems: 1 description: List of role UUIDs (`team_roles`) to assign to the user. Must contain at least one item. permissions: type: array items: type: string description: Additional ad-hoc permissions (on top of those inherited from roles). Accepts the same permission slugs. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). required: - email - role_ids DashboardUserUpdateRequest: type: object properties: name: type: string description: New display name. picture: type: string description: URL of the user picture. status: type: string enum: - active - pending_invitation - suspended description: "New status: `active`, `pending_invitation` or `suspended`." permissions: type: array items: type: string description: Full list of ad-hoc permissions (replaces the previous list). role_ids: type: array items: type: string format: uuid description: Full list of role UUIDs (replaces the current assignments). external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). TeamRoleV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. organization_id: type: string format: uuid description: UUID of the organization the role belongs to. name: type: string description: Role name. slug: type: string description: Stable role slug. description: type: - string - "null" description: Role description. permissions: type: array items: type: string description: Permission slugs granted by the role. is_system: type: boolean description: Indicates whether the role is system-managed (not editable/removable). is_active: type: boolean description: Indicates whether the role is active and available for assignment. display_order: type: integer description: Display order of the role in the UI. metadata: type: - object - "null" additionalProperties: {} description: Internal role metadata. external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). created_at: type: string format: date-time updated_at: type: string format: date-time users_count: type: integer description: Number of users currently linked to the role. required: - id - public_id - organization_id - name - slug - description - permissions - is_system - is_active - display_order - metadata - external_id - custom_metadata - created_at - updated_at TeamRoleListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/TeamRoleV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta TeamRoleResponse: type: object properties: data: $ref: "#/components/schemas/TeamRoleV1" required: - data TeamRoleCreateRequest: type: object properties: name: type: string minLength: 1 description: Role name (shown in the UI). slug: type: string pattern: ^[a-z][a-z0-9_]*$ description: "Stable slug used to reference the role (e.g.: `billing_manager`)." example: billing_manager description: type: string description: Optional description of what the role grants. permissions: type: array items: type: string description: List of permission slugs granted by the role. is_active: type: boolean description: Indicates whether the role is active and can be assigned. external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). required: - name - slug - permissions TeamRoleUpdateRequest: type: object properties: name: type: string minLength: 1 description: New role name. slug: type: string pattern: ^[a-z][a-z0-9_]*$ description: New role slug (same rules as on creation). description: type: string description: New description. permissions: type: array items: type: string description: Full permission list (replaces the previous one). is_active: type: boolean description: Activates or deactivates the role. external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). ProposalItemCreateRequest: type: object properties: product_id: type: string format: uuid description: Product UUID. **Required**. price_id: type: string format: uuid description: Price UUID. **Required**. quantity: type: number minimum: 1 description: "Quantity. Default: 1." unit_amount: type: number minimum: 0 description: Unit amount in sub-cents (float, up to 4 decimal places). metadata: type: object additionalProperties: {} description: Arbitrary item metadata. custom_metadata: type: object additionalProperties: {} description: Item custom fields. required: - product_id - price_id - unit_amount CreditUsageDailyInput: type: object properties: billing_account_id: type: string format: uuid description: Billing account ID. Send this **or** `billing_account_public_id`. billing_account_public_id: type: string format: uuid description: Public identifier of the billing account (takes precedence over `billing_account_id`). product_id: type: string format: uuid description: Credits product ID. Send this **or** `product_slug`. product_slug: type: string description: Credits product slug (takes precedence over `product_id`). usage_date: type: string description: Usage day (`YYYY-MM-DD`). example: 2026-10-13 requests: type: integer minimum: 0 description: Number of requests. prompt_tokens: type: integer minimum: 0 description: Prompt (input) tokens. completion_tokens: type: integer minimum: 0 description: Completion (output) tokens. total_tokens: type: integer minimum: 0 description: Total tokens. When omitted, `prompt_tokens + completion_tokens`. credits_consumed: type: number minimum: 0 description: Credits consumed, in the product unit (up to 6 decimal places). example: 0.07 calculated_at: type: string format: date-time description: "When the usage was computed at the source (ISO 8601). Default: now." metadata: type: object additionalProperties: {} description: Free-form data from the source, stored as sent. required: - usage_date - credits_consumed CreditUsageDailyRequest: anyOf: - $ref: "#/components/schemas/CreditUsageDailyInput" - type: object properties: records: type: array items: $ref: "#/components/schemas/CreditUsageDailyInput" maxItems: 100 required: - records CreditUsageDailyResult: type: object properties: id: type: string format: uuid billing_account_id: type: string format: uuid product_id: type: string format: uuid usage_date: type: string success: type: boolean overwritten: type: boolean description: "`true` when usage already existed for that day and was replaced." error: type: string required: - success CreditUsageDailyResponse: type: object properties: success: type: boolean processed: type: integer failed: type: integer partial: type: boolean results: anyOf: - $ref: "#/components/schemas/CreditUsageDailyResult" - type: array items: $ref: "#/components/schemas/CreditUsageDailyResult" required: - success - processed - results CreditUsageReport: type: object properties: products: type: array items: type: object properties: id: type: string format: uuid name: type: string slug: type: string unit_label: type: - string - "null" status: type: string product_group_id: type: - string - "null" format: uuid description: Family (product group) of the credits product. product_group_name: type: - string - "null" description: Name of the product family. unit_amount: type: - number - "null" description: Default price of one credit, in BRL. increment: type: integer required: - id - name - slug - unit_label - status - product_group_id - product_group_name - unit_amount - increment product_id: type: - string - "null" format: uuid description: Product the report refers to. Null when the organization has no credits product. period: type: object properties: start_date: type: string end_date: type: string required: - start_date - end_date totals: type: object properties: requests: type: integer description: Number of requests. prompt_tokens: type: integer description: Prompt (input) tokens. completion_tokens: type: integer description: Completion (output) tokens. total_tokens: type: integer description: Total tokens. credits_consumed: type: number description: Credits consumed, in the product unit (up to 6 decimal places). required: - requests - prompt_tokens - completion_tokens - total_tokens - credits_consumed daily: type: array items: type: object properties: date: type: string requests: type: integer description: Number of requests. prompt_tokens: type: integer description: Prompt (input) tokens. completion_tokens: type: integer description: Completion (output) tokens. total_tokens: type: integer description: Total tokens. credits_consumed: type: number description: Credits consumed, in the product unit (up to 6 decimal places). required: - date - requests - prompt_tokens - completion_tokens - total_tokens - credits_consumed balance: type: object properties: purchased: type: number description: Credits bought on paid invoices. consumed: type: number description: Credits consumed to date. available: type: number description: "Available balance: purchased − consumed." pending_purchase: type: number description: Credits on purchase invoices still open. required: - purchased - consumed - available - pending_purchase description: Current balance (independent of the period). required: - products - product_id - period - totals - daily - balance CreditUsageReportResponse: type: object properties: data: $ref: "#/components/schemas/CreditUsageReport" required: - data CreditPurchaseCreateRequest: type: object properties: billing_account_id: type: string format: uuid description: Billing account ID. Send this **or** `billing_account_public_id`. billing_account_public_id: type: string format: uuid description: Public identifier of the billing account. product_id: type: string format: uuid description: A `credits` product. price_id: type: string format: uuid description: "Price to charge. Default: the product active default price." quantity: type: integer minimum: 1 description: Number of credits (integer; a multiple of the product increment). example: 100 collection_method: type: string enum: - charge_automatically - manual_charge description: "`manual_charge` (default): the customer pays the invoice. `charge_automatically`: charges the default card on finalization." due_date: type: string description: "Due date. Default: the account payment terms." required: - product_id - quantity SubscriptionUpsertResponse: type: object properties: data: $ref: "#/components/schemas/SubscriptionV1" matched_by: type: - string - "null" description: Key that located the existing record. `null` when the record was created. required: - data - matched_by SubscriptionUpsertRequest: type: object properties: billing_account_id: type: string format: uuid description: UUID of the billing account that will receive this subscription. external_id: type: string description: Identifier in your external system, for idempotency/sync. company_id: type: string format: uuid plan_id: type: string format: uuid description: Plan UUID. Required when `items` is not provided. product_group_id: type: string format: uuid billing_cycle: type: string enum: - monthly - quarterly - semiannual - annual collection_method: type: - string - "null" enum: - charge_automatically - manual_charge - manual_invoice trial_end: type: string format: date-time description: Trial end date (ISO 8601). trial_period_days: type: integer minimum: 0 description: Alternative to `trial_end`. Trial days from creation. proration_behavior: type: string enum: - create_prorations - none - always_invoice nfe_issuance_policy: type: string enum: - disabled - on_finalization - on_full_payment - per_installment items: type: array items: type: object properties: product_id: type: string format: uuid price_id: type: string format: uuid quantity: type: integer minimum: 1 default: 1 unit_amount: type: number minimum: 0 description: 4-decimal precision (float, up to 4 decimal places). Overrides the price amount. required: - product_id - price_id commitment_months: type: - integer - "null" minimum: 1 maximum: 120 description: "Commitment (loyalty) period: number of contracted months (copied from the accepted proposal). Inside the commitment window — subscription start + months — the customer cannot cancel through the portal. Use `null` to clear." notes: type: - string - "null" custom_metadata: type: - object - "null" additionalProperties: {} id: type: string format: uuid description: Record UUID. Used only to locate it — never written. public_id: type: string format: uuid description: Public UUID of the record, used to locate it. SubscriptionItemsExecuteResponse: type: object properties: data: type: object properties: success: type: boolean item_change_id: type: - string - "null" format: uuid invoice_id: type: - string - "null" format: uuid credit_id: type: - string - "null" format: uuid required: - success - item_change_id - invoice_id - credit_id required: - data SubscriptionItemOp: oneOf: - type: object properties: op: type: string enum: - add product_id: type: string format: uuid price_id: type: string format: uuid quantity: type: integer exclusiveMinimum: 0 required: - op - product_id - price_id - quantity - type: object properties: op: type: string enum: - remove subscription_item_id: type: string format: uuid required: - op - subscription_item_id - type: object properties: op: type: string enum: - update_qty subscription_item_id: type: string format: uuid quantity: type: integer exclusiveMinimum: 0 required: - op - subscription_item_id - quantity - type: object properties: op: type: string enum: - update_price subscription_item_id: type: string format: uuid price_id: type: string format: uuid required: - op - subscription_item_id - price_id - type: object properties: op: type: string enum: - update_unit_amount subscription_item_id: type: string format: uuid unit_amount: type: number minimum: 0 description: New unit amount, in BRL (float, up to 4 decimal places). example: 99.9 required: - op - subscription_item_id - unit_amount SubscriptionItemsExecuteRequest: type: object properties: changes: type: array items: $ref: "#/components/schemas/SubscriptionItemOp" minItems: 1 maxItems: 50 description: Operations to apply, from 1 to 50. Each item is discriminated by `op`. timing: type: string enum: - immediate - end_of_period description: "When to apply: `immediate` (default) or `end_of_period`." reason: type: string description: Free-form reason, stored alongside the change record. idempotency_key: type: string description: Idempotency key. The `Idempotency-Key` header takes precedence over this field. required: - changes BillingAccountUpsertResponse: type: object properties: data: $ref: "#/components/schemas/BillingAccountV1" matched_by: type: - string - "null" description: Key that located the existing record. `null` when the record was created. required: - data - matched_by BillingAccountUpsertRequest: type: object properties: customer: allOf: - $ref: "#/components/schemas/BillingAccountCustomerInput" - description: Customer to associate — existing or new. external_id: type: string description: External identifier for the account in the client's system. billing_email: type: string format: email description: "Billing email. Default: `customer.email`." payment_terms_days: type: integer minimum: 1 maximum: 90 description: "Invoice due period in days (1–90). Default: the organization's configured default payment terms (10 when not configured)." auto_collection: type: boolean description: "Enables automatic collection. Default: `true`." custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). id: type: string format: uuid description: Record UUID. Used only to locate it — never written. public_id: type: string format: uuid description: Public UUID of the record, used to locate it. PlanUpsertResponse: type: object properties: data: $ref: "#/components/schemas/PlanV1" matched_by: type: - string - "null" description: Key that located the existing record. `null` when the record was created. required: - data - matched_by PlanUpsertRequest: type: object properties: external_id: type: string description: Identifier in your external system, for idempotency/sync. company_id: type: string format: uuid plan_group_id: type: - string - "null" format: uuid name: type: string minLength: 1 maxLength: 255 slug: type: string minLength: 1 maxLength: 100 pattern: ^[a-z0-9-]+$ description: Lowercase letters, digits and hyphens only. description: type: - string - "null" status: type: string enum: - draft - active - archived plan_type: type: string enum: - standard - custom - promotional description: "Default: `standard`." billing_account_id: type: - string - "null" format: uuid visibility: type: string enum: - public - private description: "Default: `public`." features: type: array items: type: string limits: type: object properties: users: type: integer subaccounts: type: integer operations_per_month: type: integer api_requests_per_day: type: integer trial_period_days: type: integer minimum: 0 maximum: 90 default_billing_cycle: type: string enum: - monthly - quarterly - semiannual - annual available_billing_cycles: type: array items: type: string enum: - monthly - quarterly - semiannual - annual items: type: array items: $ref: "#/components/schemas/PlanItemInput" custom_metadata: type: - object - "null" additionalProperties: {} description: Free-form custom metadata (`object`). id: type: string format: uuid description: Record UUID. Used only to locate it — never written. public_id: type: string format: uuid description: Public UUID of the record, used to locate it. PlanGroupUpsertResponse: type: object properties: data: $ref: "#/components/schemas/PlanGroupV1" matched_by: type: - string - "null" description: Key that located the existing record. `null` when the record was created. required: - data - matched_by PlanGroupUpsertRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 description: Plan group name. slug: type: string minLength: 1 maxLength: 100 description: Readable identifier (optional). Auto-generated when omitted. external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). id: type: string format: uuid description: Record UUID. Used only to locate it — never written. public_id: type: string format: uuid description: Public UUID of the record, used to locate it. ProductUpsertResponse: type: object properties: data: $ref: "#/components/schemas/ProductV1" matched_by: type: - string - "null" description: Key that located the existing record. `null` when the record was created. required: - data - matched_by ProductUpsertRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 description: Product name. slug: type: string minLength: 1 maxLength: 100 pattern: ^[a-z0-9_-]+$ description: Unique slug within the group. Accepts only `[a-z0-9_-]+`. description: type: string product_type: type: string enum: - base - addon_quantity - addon_fixed - metered - one_time_fixed - one_time_quantity - credits description: "Product type. Default: `base`." visibility: type: string enum: - public - private description: "Portal visibility. Default: `public`." unit_label: type: string increment: type: integer exclusiveMinimum: 0 description: "Minimum increment. Default: `1`." website_url: type: string format: uri is_required: type: boolean parent_product_id: type: string format: uuid product_group_id: type: string format: uuid company_id: type: string format: uuid external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: object additionalProperties: {} id: type: string format: uuid description: Record UUID. Used only to locate it — never written. public_id: type: string format: uuid description: Public UUID of the record, used to locate it. ProductGroupUpsertResponse: type: object properties: data: $ref: "#/components/schemas/ProductGroupV1" matched_by: type: - string - "null" description: Key that located the existing record. `null` when the record was created. required: - data - matched_by ProductGroupUpsertRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 description: Group name. slug: type: string description: Group slug. Generated from the name when omitted. visibility: type: string enum: - public - private description: "Visibility in the customer portal. Default: `public`." company_id: type: - string - "null" format: uuid proposal_template_id: type: - string - "null" format: uuid service_item_id: type: - string - "null" format: uuid external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). id: type: string format: uuid description: Record UUID. Used only to locate it — never written. public_id: type: string format: uuid description: Public UUID of the record, used to locate it. CompanyUpsertResponse: type: object properties: data: $ref: "#/components/schemas/CompanyV1" matched_by: type: - string - "null" description: Key that located the existing record. `null` when the record was created. required: - data - matched_by CompanyUpsertRequest: type: object properties: parent_company_id: type: string format: uuid description: Head office UUID when creating a branch. Omit to create a head office. name: type: string minLength: 1 maxLength: 255 description: Trade name of the company. external_id: type: string description: Identifier in your external system, for idempotency/sync. legal_name: type: string maxLength: 255 description: Legal name. document_type: type: string enum: - cpf - cnpj description: "Document type: `cpf` or `cnpj`. Only `cnpj` can have branches." document_number: type: string minLength: 11 maxLength: 18 description: CPF or CNPJ (with or without mask — will be normalized to digits only). email: type: string format: email description: Primary company email. phone: type: string description: Primary company phone. When provided, it is added to the `phones` array. addresses: type: array items: type: object additionalProperties: {} description: List of company addresses. emails: type: array items: type: object additionalProperties: {} description: List of additional emails. If omitted, the primary `email` is used. phones: type: array items: type: object additionalProperties: {} description: List of company phones. websites: type: array items: type: object additionalProperties: {} description: List of company websites. is_default: type: boolean description: When `true`, sets this company as the organization default. Only head offices can be default. custom_metadata: type: - object - "null" additionalProperties: {} description: Custom metadata (free-form key/value). id: type: string format: uuid description: Record UUID. Used only to locate it — never written. public_id: type: string format: uuid description: Public UUID of the record, used to locate it. CouponUpsertResponse: type: object properties: data: $ref: "#/components/schemas/CouponV1" matched_by: type: - string - "null" description: Key that located the existing record. `null` when the record was created. required: - data - matched_by CouponUpsertRequest: type: object properties: code: type: string minLength: 1 description: Public coupon code — unique per organization. external_id: type: string description: Identifier in your external system, for idempotency/sync. name: type: string minLength: 1 description: Internal coupon name. description: type: string description: Optional description. discount_type: type: string enum: - percentage - fixed_amount description: "Discount type: `percentage` or `fixed_amount`." discount_value: type: number minimum: 0 description: Discount value. For `percentage`, integer between `0` and `100`. For `fixed_amount`, amount in BRL (float, up to 4 decimal places). currency: type: string description: "ISO 4217 currency. Default: `BRL`." min_purchase: type: number minimum: 0 description: Minimum invoice amount, in BRL (float, up to 4 decimal places), for the coupon to be applicable. max_discount: type: number minimum: 0 description: Absolute discount cap, in BRL (float, up to 4 decimal places). usage_limit: type: integer exclusiveMinimum: 0 description: Maximum total redemptions across the organization. Omit for unlimited. usage_limit_per_user: type: integer exclusiveMinimum: 0 description: Maximum redemptions per billing account. Omit for unlimited. valid_from: type: string description: Start of the validity window (ISO 8601 — date or date-time). valid_until: type: string description: End of the validity window (ISO 8601 — date or date-time). applies_to: allOf: - $ref: "#/components/schemas/CouponTargetV1" - description: Restricts the coupon to plans and/or products. excludes: allOf: - $ref: "#/components/schemas/CouponTargetV1" - description: List of plans and/or products where the coupon cannot be applied. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). id: type: string format: uuid description: Record UUID. Used only to locate it — never written. public_id: type: string format: uuid description: Public UUID of the record, used to locate it. CreditUpsertResponse: type: object properties: data: $ref: "#/components/schemas/CreditV1" matched_by: type: - string - "null" description: Key that located the existing record. `null` when the record was created. required: - data - matched_by CreditUpsertRequest: type: object properties: billing_account_id: type: string format: uuid description: UUID of the billing account that will receive the credit. external_id: type: string description: Identifier in your external system, for idempotency/sync. company_id: type: string format: uuid description: Optional UUID of the `company` the credit is tied to. When set, restricts credit application to invoices from the same `company`. type: type: string enum: - promotional - adjustment - refund - manual description: "Credit type: `promotional`, `adjustment`, `refund` or `manual`." amount: type: number exclusiveMinimum: 0 description: Credit amount in BRL (float, up to 4 decimal places). Must be a positive integer. example: 100 description: type: string maxLength: 500 description: Free-form description (up to 500 characters) — shown in the statement and audit log. expires_at: type: string format: date-time description: Expiration date and time (ISO8601). After this date the remaining balance is discarded. custom_metadata: type: - object - "null" additionalProperties: {} description: Custom metadata validated against the organization schema. id: type: string format: uuid description: Record UUID. Used only to locate it — never written. public_id: type: string format: uuid description: Public UUID of the record, used to locate it. InvoiceUpsertResponse: type: object properties: data: $ref: "#/components/schemas/InvoiceV1" matched_by: type: - string - "null" description: Key that located the existing record. `null` when the record was created. required: - data - matched_by InvoiceUpsertRequest: type: object properties: billing_account_id: type: string format: uuid description: Target billing account UUID. **Required**. external_id: type: string description: Identifier in your external system, for idempotency/sync. company_id: type: string format: uuid description: "Issuing company UUID. Default: organization's default company." subscription_id: type: string format: uuid description: Originating subscription UUID. product_group_id: type: string format: uuid description: Product group UUID. collection_method: type: string enum: - charge_automatically - manual_charge - manual_invoice description: "Collection method. Default: `manual_invoice`." due_date: type: string description: "Due date. Default: today + the account's `payment_terms_days`." description: type: string description: Free-form description shown at the top of the invoice. footer: type: string description: Free-form footer shown at the bottom of the invoice. line_items: type: array items: $ref: "#/components/schemas/InvoiceLineItemCreateInput" minItems: 1 maxItems: 200 description: Line items. Minimum 1. discount: type: number minimum: 0 description: Fixed discount in BRL. discount_description: type: string description: 'Discount description (e.g.: "20% annual payment discount").' installments: type: array items: $ref: "#/components/schemas/InvoiceInstallmentCreateInput" minItems: 2 maxItems: 60 description: Installment schedule (minimum 2). Each item has `amount` and `due_date`. nfe_issuance_policy: type: string enum: - disabled - on_finalization - on_full_payment - per_installment description: NF-e issuance policy for installment invoices. period_start: type: string description: Start of the billing period (auto-set for subscription invoices). period_end: type: string description: End of the billing period (auto-set for subscription invoices). custom_metadata: type: - object - "null" additionalProperties: {} description: Custom fields (validated against the organization's schema). id: type: string format: uuid description: Record UUID. Used only to locate it — never written. public_id: type: string format: uuid description: Public UUID of the record, used to locate it. PaymentMethodUpsertResponse: type: object properties: data: $ref: "#/components/schemas/PaymentMethodV1" matched_by: type: - string - "null" description: Key that located the existing record. `null` when the record was created. required: - data - matched_by PaymentMethodUpsertRequest: type: object properties: billing_account_id: type: string format: uuid description: UUID of the billing account that owns the payment method. type: type: string enum: - card - bank_slip - pix - bank_transfer description: "Method type: `card`, `bank_slip`, `pix` or `bank_transfer`." is_default: type: boolean description: When `true`, marks this method as the account default (unsets previous defaults). The first method created for an account also becomes the default automatically. card: allOf: - $ref: "#/components/schemas/PaymentMethodCardInput" - description: Card block. Required when `type=card`. bank_account: allOf: - $ref: "#/components/schemas/PaymentMethodBankAccountInput" - description: Bank account block. Required when `type=bank_transfer`. billing_details: allOf: - $ref: "#/components/schemas/PaymentMethodBillingDetailsInput" - description: Optional billing details (name, email, phone, address) used by the gateway. external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: object additionalProperties: {} description: Free-form custom metadata (`object`). id: type: string format: uuid description: Record UUID. Used only to locate it — never written. public_id: type: string format: uuid description: Public UUID of the record, used to locate it. NfeUpsertResponse: type: object properties: data: $ref: "#/components/schemas/NfeV1" matched_by: type: - string - "null" description: Key that located the existing record. `null` when the record was created. required: - data - matched_by NfeUpsertRequest: type: object properties: billing_account_id: type: string format: uuid description: Billing account (taker) UUID. **Required**. company_id: type: string format: uuid description: "Issuing company (provider) UUID. Default: organization's default company." external_id: type: string description: Identifier in your external system, for idempotency/sync. invoice_id: type: string format: uuid description: Linked invoice UUID (optional). transaction_id: type: string format: uuid description: Originating transaction UUID (optional). amount: type: number exclusiveMinimum: 0 description: NF-e amount in BRL (float, up to 4 decimal places). **Required**, must be positive. service_code: type: string description: Service code per the municipal table. service_description: type: string description: Free-form description of the service provided. lc116_code: type: string description: LC 116 code. cnae_code: type: string description: CNAE code. nbs_code: type: string description: NBS code. c_class_trib: type: string description: IBS/CBS Tax Classification (cClassTrib). ind_op: type: string description: IBS/CBS Operation Indicator (indOp). rps_number: type: integer description: RPS number (when numbering is managed by the application). rps_serial_number: type: string description: RPS series. customer: $ref: "#/components/schemas/NfeCustomerInput" taxes: $ref: "#/components/schemas/NfeTaxesInput" custom_metadata: type: - object - "null" additionalProperties: {} description: Custom fields (validated against the organization's schema). id: type: string format: uuid description: Record UUID. Used only to locate it — never written. public_id: type: string format: uuid description: Public UUID of the record, used to locate it. ProposalUpsertResponse: type: object properties: data: $ref: "#/components/schemas/ProposalV1" matched_by: type: - string - "null" description: Key that located the existing record. `null` when the record was created. required: - data - matched_by ProposalUpsertRequest: type: object properties: company_id: type: - string - "null" format: uuid description: Issuing company UUID. Use `null` to clear. title: type: string minLength: 1 maxLength: 255 description: 'Proposal title. Default: "Proposta Comercial".' description: type: - string - "null" description: Free-form proposal description. billing_account_id: type: - string - "null" format: uuid description: Target billing account UUID (existing customer). Required if `prospect_id` and `prospect_data` are not provided. prospect_id: type: - string - "null" format: uuid description: UUID of an existing prospect. Alternative to `billing_account_id`/`prospect_data`. contact_id: type: - string - "null" format: uuid description: UUID of an existing contact linked to the prospect. prospect_data: $ref: "#/components/schemas/ProspectDataInput" contact_data: $ref: "#/components/schemas/ContactDataInput" coupon_id: type: - string - "null" format: uuid description: Coupon UUID to apply. template_id: type: - string - "null" format: uuid description: Template UUID for PDF generation. discount_percent: type: - number - "null" minimum: 0 maximum: 100 description: Negotiated discount percent (0–100), applied to the monthly amount; the cycle discount applies over the discounted value. Do not send together with `discount_amount`. discount_amount: type: - number - "null" minimum: 0 description: Negotiated fixed per-month discount in BRL (float, up to 4 decimal places), applied to the monthly amount; the cycle discount applies over the discounted value. Do not send together with `discount_percent`. example: 50 commitment_months: type: - integer - "null" minimum: 1 maximum: 120 description: Commitment period in months (1–120). Use `null` to clear. Copied to the subscription when the proposal is accepted. example: 12 expires_at: type: string description: Expiration date. notes: type: - string - "null" description: Internal notes. items: type: array items: $ref: "#/components/schemas/ProposalItemInput" minItems: 1 description: Proposal items. Minimum 1. external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: - object - "null" additionalProperties: {} description: Custom fields (validated against the organization's schema). id: type: string format: uuid description: Record UUID. Used only to locate it — never written. public_id: type: string format: uuid description: Public UUID of the record, used to locate it. ProposalTemplateUpsertResponse: type: object properties: data: $ref: "#/components/schemas/ProposalTemplateV1" matched_by: type: - string - "null" description: Key that located the existing record. `null` when the record was created. required: - data - matched_by ProposalTemplateUpsertRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 description: Template name (unique per organization). description: type: - string - "null" description: Optional template description. document_type: type: string enum: - google_doc - google_slides description: "Base document type: `google_doc` or `google_slides`. Default: `google_doc`." google_doc_id: type: string minLength: 1 description: Google Doc/Slides ID used as the template (unique per organization). app_script_url: type: - string - "null" format: uri description: URL of the published Apps Script that renders the template, when applicable. google_drive_folder_id: type: - string - "null" description: Google Drive folder ID where generated copies will be saved. is_active: type: boolean description: When `false`, creates the template already deactivated. external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: object additionalProperties: {} description: Free-form metadata defined by the client for internal correlation. id: type: string format: uuid description: Record UUID. Used only to locate it — never written. public_id: type: string format: uuid description: Public UUID of the record, used to locate it. TaxRuleUpsertResponse: type: object properties: data: $ref: "#/components/schemas/TaxRuleV1" matched_by: type: - string - "null" description: Key that located the existing record. `null` when the record was created. required: - data - matched_by TaxRuleUpsertRequest: type: object properties: name: type: string minLength: 1 description: Human-readable rule name. description: type: - string - "null" description: Optional rule description. scope: type: string enum: - global - organization - company - service - customer - municipality description: "Rule scope: `global`, `organization`, `company`, `service`, `customer` or `municipality`." priority: type: integer description: "Rule priority. Higher value overrides lower-priority rules. Default: `0`." example: 0 company_id: type: - string - "null" format: uuid description: Company UUID when `scope = company`. The company must belong to the current organization. service_item_id: type: - string - "null" format: uuid description: Service item UUID when `scope = service`. The item must belong to the current organization. billing_account_id: type: - string - "null" format: uuid description: Billing account UUID when `scope = customer`. The account must belong to the current organization. customer_tax_type: type: - string - "null" enum: - pessoa_fisica - pessoa_juridica - mei - simples_optante - entidade_publica description: "Customer tax type: `pessoa_fisica`, `pessoa_juridica`, `mei`, `simples_optante` or `entidade_publica`." municipality: type: - string - "null" description: IBGE municipality code (7 digits) when `scope = municipality`. operation_type: type: - string - "null" enum: - interno - externo description: "Operation type: `interno` (same municipality) or `externo` (different municipality)." effective_from: type: string format: date-time description: ISO 8601 date/time when the rule becomes effective. effective_to: type: - string - "null" format: date-time description: ISO 8601 date/time when the rule stops being effective. `null` means open-ended. items: type: array items: $ref: "#/components/schemas/TaxRuleItemInput" minItems: 1 description: List of items (per-tax rates). At least 1 item is required. external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). id: type: string format: uuid description: Record UUID. Used only to locate it — never written. public_id: type: string format: uuid description: Public UUID of the record, used to locate it. WithholdingUpsertResponse: type: object properties: data: $ref: "#/components/schemas/WithholdingV1" matched_by: type: - string - "null" description: Key that located the existing record. `null` when the record was created. required: - data - matched_by WithholdingUpsertRequest: type: object properties: tax_type: type: string enum: - iss - pis - cofins - csll - irpj - irrf - csrf - inss - cbs - ibs description: Withheld tax. base: type: number minimum: 0 description: Calculation base, in BRL (float, up to 4 decimal places). example: 1000 rate: type: number minimum: 0 description: Applied rate, as a percentage. example: 1.5 amount: type: number minimum: 0 description: Withheld amount, in BRL (float, up to 4 decimal places). example: 15 withholder_id: type: string format: uuid description: Billing account that performed the withholding. competence_month: type: integer minimum: 1 maximum: 12 description: Competence month (1–12). competence_year: type: integer minimum: 2000 maximum: 3000 description: Competence year. invoice_id: type: string format: uuid description: Originating invoice, when there is one. nfe_id: type: string format: uuid description: Related invoice document (NF-e), when there is one. metadata: type: object additionalProperties: {} external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: object additionalProperties: {} id: type: string format: uuid description: Record UUID. Used only to locate it — never written. public_id: type: string format: uuid description: Public UUID of the record, used to locate it. ServiceItemUpsertResponse: type: object properties: data: $ref: "#/components/schemas/ServiceItemV1" matched_by: type: - string - "null" description: Key that located the existing record. `null` when the record was created. required: - data - matched_by ServiceItemUpsertRequest: type: object properties: external_id: type: string description: Identifier in your external system, for idempotency/sync. company_id: type: - string - "null" format: uuid description: UUID of the associated issuing company. Omit or send `null` for an item applicable to all companies. name: type: string minLength: 1 description: Service item name. description: type: - string - "null" description: Optional description. internal_code: type: string minLength: 1 description: Internal item code — immutable after creation. lc116_code: type: string minLength: 1 description: LC 116/2003 service code (e.g. `01.05`). example: "01.05" municipal_code: type: - string - "null" description: Municipal service code, when applicable. nbs_code: type: - string - "null" description: NBS code. cnae_code: type: - string - "null" description: Related CNAE code. simples_annex: type: - string - "null" enum: - annex_iii - annex_iv - annex_v description: "Applicable Simples Nacional annex: `annex_iii`, `annex_iv` or `annex_v`." default_iss_rate: type: - number - "null" description: Default ISS rate in percentage points (e.g. `2.5`). example: 2.5 c_class_trib: type: - string - "null" description: IBS/CBS CST tax classification. cbs_ibs_category: type: - string - "null" description: CBS/IBS category for the item. indop_code: type: - string - "null" description: SNNFSE NFS-e Operation Indicator (`indOp`). custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). id: type: string format: uuid description: Record UUID. Used only to locate it — never written. public_id: type: string format: uuid description: Public UUID of the record, used to locate it. DashboardUserUpsertResponse: type: object properties: data: $ref: "#/components/schemas/DashboardUserV1" matched_by: type: - string - "null" description: Key that located the existing record. `null` when the record was created. required: - data - matched_by DashboardUserUpsertRequest: type: object properties: email: type: string format: email description: User's email. Besides being a resource field, it doubles as the natural lookup key. name: type: string description: User name (optional — may be filled in by the user on first login). external_id: type: string description: External user identifier in Kobana OAuth, when already known. role_ids: type: array items: type: string format: uuid minItems: 1 description: List of role UUIDs (`team_roles`) to assign to the user. Must contain at least one item. permissions: type: array items: type: string description: Additional ad-hoc permissions (on top of those inherited from roles). Accepts the same permission slugs. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). id: type: string format: uuid description: Record UUID. Used only to locate it — never written. public_id: type: string format: uuid description: Public UUID of the record, used to locate it. TeamRoleUpsertResponse: type: object properties: data: $ref: "#/components/schemas/TeamRoleV1" matched_by: type: - string - "null" description: Key that located the existing record. `null` when the record was created. required: - data - matched_by TeamRoleUpsertRequest: type: object properties: name: type: string minLength: 1 description: Role name (shown in the UI). slug: type: string pattern: ^[a-z][a-z0-9_]*$ description: "Stable slug used to reference the role (e.g.: `billing_manager`)." example: billing_manager description: type: string description: Optional description of what the role grants. permissions: type: array items: type: string description: List of permission slugs granted by the role. is_active: type: boolean description: Indicates whether the role is active and can be assigned. external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). id: type: string format: uuid description: Record UUID. Used only to locate it — never written. public_id: type: string format: uuid description: Public UUID of the record, used to locate it. parameters: {} securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: "Send the `Authorization: Bearer ` header. The token is an RS256 access token issued by the Kobana authorization server (`account.kobana.com.br`), with `aud` equal to `https://api.billing.kobana.com.br` and a required `exp`. The `org` claim (the Kobana account) is what scopes the data and is required too; `sub` is the **person** and is carried for audit. This API only verifies tokens — it issues none. The `scope` claim is enforced too: a `GET` needs `read`, `write` or `all`, and any other method needs `write` or `all` — otherwise the answer is `403 insufficient_scope`, with `{ required, granted }` in `details`." paths: /v1/subscriptions: get: tags: - Subscriptions summary: List subscriptions description: Returns a paginated list of the current organization's subscriptions. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Filter by associated person UUID. required: false name: person_id in: query - schema: type: string description: Filter by person CPF/CNPJ (exact match). required: false name: person_document_number in: query - schema: type: string description: Filter by person name (partial search, case-insensitive). required: false name: person_name_contains in: query - schema: type: string enum: - draft - trialing - active - past_due - canceled - paused - suspended description: Filter by subscription status. required: false name: status in: query - schema: type: string format: uuid description: Filter by plan. required: false name: plan_id in: query - schema: type: string enum: - monthly - quarterly - semiannual - annual description: Filter by billing cycle. required: false name: billing_cycle in: query - schema: type: string format: uuid description: Filter by billing account. required: false name: billing_account_id in: query - schema: type: string description: Free-text search. required: false name: search in: query - schema: type: string format: uuid description: Filter by company (UUID). required: false name: company_id in: query - schema: type: string enum: - charge_automatically - manual_charge - manual_invoice description: "Filter by collection method: `charge_automatically`, `manual_charge` or `manual_invoice`." required: false name: collection_method in: query - schema: type: string enum: - "true" - "false" description: Filter subscriptions scheduled to cancel at period end (`true`) or not (`false`). required: false name: cancel_at_period_end in: query - schema: type: string description: Filter by external identifier. required: false name: external_id in: query - schema: type: string format: uuid description: Filter by product group (UUID). required: false name: product_group_id in: query - schema: type: string format: uuid description: Filter by proposal (UUID). required: false name: proposal_id in: query - schema: type: - number - "null" minimum: 0 description: Minimum recurring amount in BRL (e.g. `50.00`). example: 100 required: false name: recurring_amount_min in: query - schema: type: - number - "null" minimum: 0 description: Maximum recurring amount in BRL (e.g. `500.00`). example: 100 required: false name: recurring_amount_max in: query - schema: type: string format: date description: Start of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_after in: query - schema: type: string format: date description: End of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_before in: query - schema: type: string format: date description: Current period start on or after this date (YYYY-MM-DD). example: 2026-01-15 required: false name: current_period_start_from in: query - schema: type: string format: date description: Current period start on or before this date (YYYY-MM-DD). example: 2026-01-15 required: false name: current_period_start_to in: query - schema: type: string format: date description: Current period end on or after this date (YYYY-MM-DD). example: 2026-01-15 required: false name: current_period_end_from in: query - schema: type: string format: date description: Current period end on or before this date (YYYY-MM-DD). example: 2026-01-15 required: false name: current_period_end_to in: query - schema: type: string format: date description: Trial end on or after this date (YYYY-MM-DD). example: 2026-01-15 required: false name: trial_end_from in: query - schema: type: string format: date description: Trial end on or before this date (YYYY-MM-DD). example: 2026-01-15 required: false name: trial_end_to in: query - schema: type: string format: date description: Canceled on or after this date (YYYY-MM-DD). example: 2026-01-15 required: false name: canceled_after in: query - schema: type: string format: date description: Canceled on or before this date (YYYY-MM-DD). example: 2026-01-15 required: false name: canceled_before in: query - schema: type: string format: date description: Activated on or after this date (YYYY-MM-DD). example: 2026-01-15 required: false name: activated_after in: query - schema: type: string format: date description: Activated on or before this date (YYYY-MM-DD). example: 2026-01-15 required: false name: activated_before in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of subscriptions. content: application/json: schema: $ref: "#/components/schemas/SubscriptionListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-subscriptions post: tags: - Subscriptions summary: Create subscription description: Creates a subscription. Either `plan_id` or `items` is required. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/SubscriptionCreateRequest" responses: "201": description: Subscription created. content: application/json: schema: $ref: "#/components/schemas/SubscriptionResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-subscriptions parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Subscriptions summary: Upsert subscription description: "Takes the same body as POST, plus `id` and `public_id`, and dedups on `id`, `public_id`, `external_id` and the resource's natural keys, in that order, stopping at the first key that finds a record. A match is updated and returns 200; otherwise the record is created and returns 201. The POST's required fields are required only when no record is found, and updates are partial: absent fields keep their stored value." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/SubscriptionUpsertRequest" responses: "200": description: Record updated. content: application/json: schema: $ref: "#/components/schemas/SubscriptionUpsertResponse" "201": description: Record created. content: application/json: schema: $ref: "#/components/schemas/SubscriptionUpsertResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-subscriptions parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/subscriptions/{id}: get: tags: - Subscriptions summary: Get subscription security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Subscription detail. content: application/json: schema: $ref: "#/components/schemas/SubscriptionResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-subscriptions-id patch: tags: - Subscriptions summary: Update subscription security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/SubscriptionUpdateRequest" responses: "200": description: Subscription updated. content: application/json: schema: $ref: "#/components/schemas/SubscriptionResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-subscriptions-id delete: tags: - Subscriptions summary: Cancel and remove subscription (soft delete) security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Soft delete confirmation. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-subscriptions-id /v1/subscriptions/{id}/pause: post: tags: - Subscriptions summary: Pause subscription description: Suspends charging while keeping the subscription open. `behavior` controls how invoices generated during the pause are handled. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/SubscriptionPauseRequest" responses: "200": description: Subscription paused. content: application/json: schema: $ref: "#/components/schemas/SubscriptionResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-subscriptions-id-pause /v1/subscriptions/{id}/resume: post: tags: - Subscriptions summary: Resume paused subscription security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Subscription resumed. content: application/json: schema: $ref: "#/components/schemas/SubscriptionResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-subscriptions-id-resume /v1/subscriptions/{id}/cancel: post: tags: - Subscriptions summary: Cancel subscription description: Cancels immediately, or schedules for end of period when `cancel_at_period_end=true`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/SubscriptionCancelRequest" responses: "200": description: Subscription canceled. content: application/json: schema: $ref: "#/components/schemas/SubscriptionResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-subscriptions-id-cancel /v1/subscriptions/{id}/activate: post: tags: - Subscriptions summary: Activate draft/confirmed subscription security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Subscription activated. content: application/json: schema: $ref: "#/components/schemas/SubscriptionResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-subscriptions-id-activate /v1/subscriptions/{id}/change-plan: post: tags: - Subscriptions summary: Change subscription plan description: Upgrade or downgrade. Proration follows the subscription's `proration_behavior`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/SubscriptionChangePlanRequest" responses: "200": description: Subscription updated. content: application/json: schema: $ref: "#/components/schemas/SubscriptionResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-subscriptions-id-change-plan /v1/subscriptions/{id}/change-anniversary: post: tags: - Subscriptions summary: Change the subscription anniversary (cycle start day) description: Moves the day of the month on which cycles start. The cycle in progress keeps its start and is extended to the day before the new day; the added days are billed pro rata (cycle amount × days ÷ cycle days) in a `subscription_update` invoice. The change always moves the date forward, never back. Use `dry_run` to compute without applying. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/SubscriptionChangeAnniversaryRequest" responses: "200": description: Change result (or the simulation, with `dry_run`). content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/SubscriptionChangeAnniversaryResult" required: - data "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-subscriptions-id-change-anniversary /v1/subscriptions/{id}/revert-to-confirmed: post: tags: - Subscriptions summary: Revert subscription to confirmed state security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Subscription reverted. content: application/json: schema: $ref: "#/components/schemas/SubscriptionResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-subscriptions-id-revert-to-confirmed /v1/subscriptions/{id}/create-invoice: post: tags: - Subscriptions summary: Generate an ad-hoc invoice for the subscription security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "201": description: Invoice generated. content: application/json: schema: type: object properties: data: {} "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-subscriptions-id-create-invoice /v1/subscriptions/{id}/items: get: tags: - Subscriptions summary: List subscription items security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: List of items. content: application/json: schema: type: object properties: data: type: array items: {} required: - data "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-subscriptions-id-items post: tags: - Subscriptions summary: Apply changes to the subscription items description: "Runs a batch of up to 50 operations over the items: add, remove, change quantity, swap price or set an ad-hoc unit amount. The operations are applied together and produce a single change record, along with the resulting proration invoice or credit." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/SubscriptionItemsExecuteRequest" responses: "200": description: Changes applied. `item_change_id` points to the record created; `invoice_id` and `credit_id` are filled in when the proration produced an invoice or a credit. content: application/json: schema: $ref: "#/components/schemas/SubscriptionItemsExecuteResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-subscriptions-id-items /v1/subscriptions/{id}/sync-plan-items: post: tags: - Subscriptions summary: Resync items with the current plan description: Realigns subscription items with the plan-items template (manual reconciliation). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Subscription synced. content: application/json: schema: $ref: "#/components/schemas/SubscriptionResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-subscriptions-id-sync-plan-items /v1/billing_accounts: get: tags: - Billing Accounts summary: List billing accounts description: Returns a paginated list of the current organization's billing accounts. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - active - suspended - closed description: Filter by billing account status. required: false name: status in: query - schema: type: string description: Free-text search. required: false name: search in: query - schema: type: string description: Filter by the external identifier of the account. required: false name: external_id in: query - schema: type: string description: "Filter by ISO 4217 currency (e.g.: `BRL`)." required: false name: currency in: query - schema: type: string enum: - "true" - "false" description: Filter by automatic collection enabled (`true`) or disabled (`false`). required: false name: auto_collection in: query - schema: type: string enum: - "true" - "false" description: Filter tax-exempt accounts (`true`) or non-exempt (`false`). required: false name: tax_exempt in: query - schema: type: string description: Filter by customer tax type. required: false name: customer_tax_type in: query - schema: type: - number - "null" minimum: 0 description: Minimum account balance in BRL (float, up to 4 decimal places). example: 100 required: false name: balance_min in: query - schema: type: - number - "null" minimum: 0 description: Maximum account balance in BRL (float, up to 4 decimal places). example: 100 required: false name: balance_max in: query - schema: type: - number - "null" minimum: 0 description: Minimum MRR in BRL (float, up to 4 decimal places). example: 100 required: false name: mrr_min in: query - schema: type: - number - "null" minimum: 0 description: Maximum MRR in BRL (float, up to 4 decimal places). example: 100 required: false name: mrr_max in: query - schema: type: - number - "null" minimum: 0 description: Minimum allowed negative balance in BRL (float, up to 4 decimal places). example: 100 required: false name: allowed_negative_balance_min in: query - schema: type: - number - "null" minimum: 0 description: Maximum allowed negative balance in BRL (float, up to 4 decimal places). example: 100 required: false name: allowed_negative_balance_max in: query - schema: type: string format: date description: Start of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_after in: query - schema: type: string format: date description: End of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_before in: query - schema: type: string format: date description: Start of update date range (YYYY-MM-DD). example: 2026-01-15 required: false name: updated_after in: query - schema: type: string format: date description: End of update date range (YYYY-MM-DD). example: 2026-01-15 required: false name: updated_before in: query - schema: type: string format: date description: Filter accounts suspended from this date onwards (format `YYYY-MM-DD`). example: 2026-01-15 required: false name: suspended_after in: query - schema: type: string format: date description: Filter accounts suspended up to this date (format `YYYY-MM-DD`). example: 2026-01-15 required: false name: suspended_before in: query - schema: type: string format: uuid description: Filter by associated person UUID. required: false name: person_id in: query - schema: type: string description: Filter by person CPF/CNPJ (exact match). required: false name: person_document_number in: query - schema: type: string description: Filter by person name (partial search, case-insensitive). required: false name: person_name_contains in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of billing accounts. content: application/json: schema: $ref: "#/components/schemas/BillingAccountListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-billing-accounts post: tags: - Billing Accounts summary: Create billing account description: Creates a billing account associated with a customer. The `customer` block locates an existing customer by `id`, `external_id` or `document_number`; when not found, creates a new one (requires `name` and `document_number`). security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/BillingAccountCreateRequest" responses: "201": description: Billing account created. content: application/json: schema: $ref: "#/components/schemas/BillingAccountResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-billing-accounts parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Billing Accounts summary: Upsert billing account description: "Takes the same body as POST, plus `id` and `public_id`, and dedups on `id`, `public_id`, `external_id` and the resource's natural keys, in that order, stopping at the first key that finds a record. A match is updated and returns 200; otherwise the record is created and returns 201. The POST's required fields are required only when no record is found, and updates are partial: absent fields keep their stored value." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/BillingAccountUpsertRequest" responses: "200": description: Record updated. content: application/json: schema: $ref: "#/components/schemas/BillingAccountUpsertResponse" "201": description: Record created. content: application/json: schema: $ref: "#/components/schemas/BillingAccountUpsertResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-billing-accounts parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/billing_accounts/{id}: get: tags: - Billing Accounts summary: Get billing account security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Billing account UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Billing account detail. content: application/json: schema: $ref: "#/components/schemas/BillingAccountResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-billing-accounts-id patch: tags: - Billing Accounts summary: Update billing account security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Billing account UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/BillingAccountUpdateRequest" responses: "200": description: Billing account updated. content: application/json: schema: $ref: "#/components/schemas/BillingAccountResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-billing-accounts-id delete: tags: - Billing Accounts summary: Close billing account description: Closes the billing account (equivalent to `POST /billing_accounts/{id}/close`). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Billing account UUID. required: true name: id in: path - schema: type: string description: Closing reason (recorded in the audit log). required: false name: reason in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Billing account closed. content: application/json: schema: $ref: "#/components/schemas/BillingAccountResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-billing-accounts-id /v1/billing_accounts/{id}/close: post: tags: - Billing Accounts summary: Close billing account (POST /close) description: Closes the billing account. The `reason` is recorded in the audit log. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Billing account UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/BillingAccountReasonRequest" responses: "200": description: Billing account closed. content: application/json: schema: $ref: "#/components/schemas/BillingAccountResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-billing-accounts-id-close /v1/billing_accounts/{id}/suspend: post: tags: - Billing Accounts summary: Suspend billing account description: Suspends the account. The `reason` is recorded in the audit log. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Billing account UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/BillingAccountReasonRequest" responses: "200": description: Billing account suspended. content: application/json: schema: $ref: "#/components/schemas/BillingAccountResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-billing-accounts-id-suspend /v1/billing_accounts/{id}/reactivate: post: tags: - Billing Accounts summary: Reactivate billing account description: Reactivates a suspended billing account. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Billing account UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Billing account reactivated. content: application/json: schema: $ref: "#/components/schemas/BillingAccountResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-billing-accounts-id-reactivate /v1/billing_accounts/{id}/invoices: get: tags: - Billing Accounts summary: List billing account invoices description: Returns a paginated list of the billing account's invoices. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Billing account UUID. required: true name: id in: path - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of invoices. content: application/json: schema: type: object properties: data: type: array items: {} required: - data "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-billing-accounts-id-invoices /v1/billing_accounts/{id}/subscriptions: get: tags: - Billing Accounts summary: List billing account subscriptions description: Returns a paginated list of the billing account's subscriptions. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Billing account UUID. required: true name: id in: path - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of subscriptions. content: application/json: schema: type: object properties: data: type: array items: {} required: - data "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-billing-accounts-id-subscriptions /v1/billing_accounts/{id}/entitlements: get: tags: - Billing Accounts summary: List billing account entitlements description: Returns a lean list of the products a billing account is entitled to, based on subscriptions that are trialing, active, or past due (dunning grace). Only parent products are returned; child (add-on) products are rolled up under their parent and omitted. Ideal for gating a product's usage in an external app. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Billing account UUID. required: true name: id in: path - schema: type: string format: uuid description: Filters contracted products by family (product group), by ID. required: false name: product_group_id in: query - schema: type: string description: Filters contracted products by family (product group), by slug. required: false name: product_group_slug in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: List of contracted products. content: application/json: schema: type: object properties: data: type: object properties: billing_account_id: type: string format: uuid entitlements: type: array items: type: object properties: product_id: type: string format: uuid product_parent_id: type: - string - "null" format: uuid product_external_id: type: - string - "null" product_slug: type: string product_name: type: string product_type: type: string product_group_id: type: - string - "null" format: uuid product_group_name: type: - string - "null" product_group_slug: type: - string - "null" quantity: type: number subscription_id: type: string format: uuid subscription_status: type: string enum: - trialing - active - past_due current_period_end: type: - string - "null" format: date-time cancel_at_period_end: type: boolean required: - product_id - product_parent_id - product_external_id - product_slug - product_name - product_type - product_group_id - product_group_name - product_group_slug - quantity - subscription_id - subscription_status - current_period_end - cancel_at_period_end required: - billing_account_id - entitlements required: - data "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-billing-accounts-id-entitlements /v1/billing_accounts/{id}/credits: get: tags: - Billing Accounts summary: List billing account credits description: Returns a paginated list of the billing account's credits. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Billing account UUID. required: true name: id in: path - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - "true" - "false" description: Includes expired credits when `true`. required: false name: include_expired in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of credits. content: application/json: schema: type: object properties: data: type: array items: {} required: - data "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-billing-accounts-id-credits /v1/customers: get: tags: - Customers summary: List customers description: Returns a paginated list of the current organization's customers. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string description: Free-text search by name, document or email. required: false name: search in: query - schema: type: string enum: - natural - juridical description: "Filter by person kind: `natural` (individual) or `juridical` (business)." required: false name: kind in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of customers. content: application/json: schema: $ref: "#/components/schemas/CustomerListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-customers post: tags: - Customers summary: Create customer description: Creates a customer and, by default, an associated billing account. Use `create_billing_account=false` to create only the customer. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/CustomerCreateRequest" responses: "201": description: Customer created. content: application/json: schema: $ref: "#/components/schemas/CustomerCreateResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-customers parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Customers summary: Upsert customer description: "Takes the same body as POST and dedups on `id`, `public_id`, `external_id` and `document_number`, in that order, stopping at the first key that finds a customer. A match is updated and returns 200; otherwise the customer is created and returns 201. Updates are partial: fields absent from the body keep their stored value." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/CustomerUpsertRequest" responses: "200": description: Customer updated. content: application/json: schema: $ref: "#/components/schemas/CustomerUpsertResponse" "201": description: Customer created. content: application/json: schema: $ref: "#/components/schemas/CustomerUpsertResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-customers parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/customers/{id}: get: tags: - Customers summary: Get customer description: The `{id}` parameter accepts the customer UUID or its `external_id`. security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Customer detail. content: application/json: schema: $ref: "#/components/schemas/CustomerResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-customers-id patch: tags: - Customers summary: Update customer description: The `{id}` parameter accepts the customer UUID or its `external_id`. security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/CustomerUpdateRequest" responses: "200": description: Customer updated. content: application/json: schema: $ref: "#/components/schemas/CustomerResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-customers-id delete: tags: - Customers summary: Remove customer (soft delete) description: Marks the customer as removed without deleting historical records. security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Soft delete confirmation. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-customers-id /v1/customers/{id}/statement: get: tags: - Customers summary: List customer financial statement description: Returns statement entries (invoices, payments, credit applications) for the customer's billing account. When the customer has multiple accounts, provide `billing_account_id`. security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Required when the customer has multiple billing accounts. required: false name: billing_account_id in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of statement items. content: application/json: schema: $ref: "#/components/schemas/CustomerStatementListResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-customers-id-statement /v1/customers/{id}/statement/sync: post: tags: - Customers summary: Rebuild the statement from history description: Recreates statement items from existing invoices, payments and credit applications. Returns a summary of what was created. security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/CustomerStatementSyncRequest" responses: "200": description: Statement rebuilt. content: application/json: schema: $ref: "#/components/schemas/CustomerStatementSyncResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-customers-id-statement-sync /v1/customers/{id}/recalculate-mrr: post: tags: - Customers summary: Recalculate customer MRR description: Recalculates the MRR (Monthly Recurring Revenue) of the customer's billing accounts from active subscriptions. security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: MRR recalculated. content: application/json: schema: $ref: "#/components/schemas/CustomerRecalculateMrrResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-customers-id-recalculate-mrr /v1/customers/{id}/users: get: tags: - Customers summary: List customer portal users description: Returns portal users linked to the customer's billing account. security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - active - pending_verification - pending_invitation - suspended - locked description: Filter portal users by status. required: false name: status in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of portal users. content: application/json: schema: $ref: "#/components/schemas/CustomerPortalUserListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-customers-id-users post: tags: - Customers summary: Invite portal user description: Creates a portal access invitation for the given email. The invitation expires in 7 days. security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/CustomerPortalUserInviteRequest" responses: "201": description: Invitation created and email queued for sending. content: application/json: schema: $ref: "#/components/schemas/CustomerPortalUserResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: A user or invitation already exists for this email. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-customers-id-users /v1/customers/{id}/users/invite: post: tags: - Customers summary: Invite portal user (verb) description: Equivalent to `POST /customers/{id}/users`. Available as a verb route for SDKs that prefer descriptive URLs. security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/CustomerPortalUserInviteRequest" responses: "201": description: Invitation created. content: application/json: schema: $ref: "#/components/schemas/CustomerPortalUserResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-customers-id-users-invite /v1/customers/{id}/users/{user_id}: get: tags: - Customers summary: Get portal user description: The `{user_id}` parameter accepts the user's UUID or `external_id`. security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - schema: type: string description: Portal user UUID or its `external_id`. required: true name: user_id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Portal user detail. content: application/json: schema: $ref: "#/components/schemas/CustomerPortalUserResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-customers-id-users-user-id patch: tags: - Customers summary: Update portal user description: "Updates `email`, `external_id`, `sso_only` and `status`. Allowed status transitions: `active` ↔ `suspended`." security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - schema: type: string description: Portal user UUID or its `external_id`. required: true name: user_id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/CustomerPortalUserUpdateRequest" responses: "200": description: User updated. content: application/json: schema: $ref: "#/components/schemas/CustomerPortalUserResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-customers-id-users-user-id delete: tags: - Customers summary: Remove portal user description: Pending invitations are permanently removed; active users are suspended. security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - schema: type: string description: Portal user UUID or its `external_id`. required: true name: user_id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Removal confirmation. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-customers-id-users-user-id /v1/customers/{id}/users/{user_id}/email-preview: get: tags: - Customers summary: Preview portal user email description: Returns the subject and body of the invitation or verification email that would be sent to the user, without actually sending it. Available only for `pending_invitation` or `pending_verification` users. security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - schema: type: string description: Portal user UUID or its `external_id`. required: true name: user_id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Email preview. content: application/json: schema: $ref: "#/components/schemas/CustomerPortalUserEmailPreviewResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-customers-id-users-user-id-email-preview /v1/customers/{id}/users/{user_id}/resend: post: tags: - Customers summary: Resend invitation or verification email description: Resends the invitation email (for `pending_invitation`, rotating the token) or verification email (for `pending_verification`). Other statuses return 400. security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - schema: type: string description: Portal user UUID or its `external_id`. required: true name: user_id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Email resent. content: application/json: schema: $ref: "#/components/schemas/CustomerPortalUserResendResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-customers-id-users-user-id-resend /v1/plans: get: tags: - Plans summary: List plans description: Returns a paginated list of the current organization's plans. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Filter by associated person UUID. required: false name: person_id in: query - schema: type: string description: Filter by person CPF/CNPJ (exact match). required: false name: person_document_number in: query - schema: type: string description: Filter by person name (partial search, case-insensitive). required: false name: person_name_contains in: query - schema: type: string enum: - draft - active - archived description: Filter by plan status. required: false name: status in: query - schema: type: string enum: - standard - custom - promotional description: Filter by plan type. required: false name: plan_type in: query - schema: type: string enum: - public - private description: Filter by visibility. required: false name: visibility in: query - schema: type: string format: uuid description: Filter by plan group. required: false name: plan_group_id in: query - schema: type: string format: uuid description: Filter by issuing company. required: false name: company_id in: query - schema: type: string format: uuid description: Filter custom plans associated with a billing account. required: false name: billing_account_id in: query - schema: type: string format: uuid description: Returns plans available for the given billing account (standard + account-specific custom plans). required: false name: scoped_billing_account_id in: query - schema: type: string enum: - "true" - "false" description: When `true`, excludes `custom` plan type from the results. required: false name: exclude_custom_plans in: query - schema: type: string enum: - monthly - quarterly - semiannual - annual description: Filter by the plan default billing cycle. required: false name: default_billing_cycle in: query - schema: type: string description: Filter by the plan external identifier. required: false name: external_id in: query - schema: type: string description: Filter by the plan slug. required: false name: slug in: query - schema: type: string description: Free-text search. required: false name: search in: query - schema: type: string format: date description: Start of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_after in: query - schema: type: string format: date description: End of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_before in: query - schema: type: string format: date description: Start of update date range (YYYY-MM-DD). example: 2026-01-15 required: false name: updated_after in: query - schema: type: string format: date description: End of update date range (YYYY-MM-DD). example: 2026-01-15 required: false name: updated_before in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of plans. content: application/json: schema: $ref: "#/components/schemas/PlanListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-plans post: tags: - Plans summary: Create plan description: Creates a plan for the authenticated organization. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanCreateRequest" responses: "201": description: Plan created. content: application/json: schema: $ref: "#/components/schemas/PlanResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-plans parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Plans summary: Upsert plan description: "Takes the same body as POST, plus `id` and `public_id`, and dedups on `id`, `public_id`, `external_id` and the resource's natural keys, in that order, stopping at the first key that finds a record. A match is updated and returns 200; otherwise the record is created and returns 201. The POST's required fields are required only when no record is found, and updates are partial: absent fields keep their stored value." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanUpsertRequest" responses: "200": description: Record updated. content: application/json: schema: $ref: "#/components/schemas/PlanUpsertResponse" "201": description: Record created. content: application/json: schema: $ref: "#/components/schemas/PlanUpsertResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-plans parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/plans/{id}: get: tags: - Plans summary: Get plan security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Plan detail. content: application/json: schema: $ref: "#/components/schemas/PlanResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-plans-id patch: tags: - Plans summary: Update plan security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanUpdateRequest" responses: "200": description: Plan updated. content: application/json: schema: $ref: "#/components/schemas/PlanResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-plans-id delete: tags: - Plans summary: Archive or delete plan description: By default archives the plan (soft delete). Use `?hard=true` to permanently delete a draft plan. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan UUID. required: true name: id in: path - schema: type: - boolean - "null" description: When `true`, permanently deletes the plan (drafts only). required: false name: hard in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Archive or delete confirmation. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-plans-id /v1/plans/{id}/duplicate: post: tags: - Plans summary: Duplicate plan description: Creates a copy of the plan (including its items) in draft state. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "201": description: Plan duplicated. content: application/json: schema: $ref: "#/components/schemas/PlanResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-plans-id-duplicate /v1/plans/{id}/items: get: tags: - Plans summary: List plan items security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: List of plan items. content: application/json: schema: $ref: "#/components/schemas/PlanItemListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-plans-id-items put: tags: - Plans summary: Replace plan items description: Atomically replaces all plan items. Only root products are accepted and each `product_id` must be unique in the list. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanItemsReplaceRequest" responses: "200": description: Plan items replaced. content: application/json: schema: $ref: "#/components/schemas/PlanItemsReplaceResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-plans-id-items /v1/plans/bulk-archive: post: tags: - Plans summary: Bulk archive plans security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanBulkIdsRequest" responses: "200": description: Bulk archive summary. content: application/json: schema: $ref: "#/components/schemas/PlanBulkArchiveResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-plans-bulk-archive parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/plans/bulk-delete: post: tags: - Plans summary: Bulk delete plans description: Permanently deletes the given plans. Plans with active subscriptions are skipped and returned in `skipped_ids`. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanBulkIdsRequest" responses: "200": description: Bulk delete summary. content: application/json: schema: $ref: "#/components/schemas/PlanBulkDeleteResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-plans-bulk-delete parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/plans/bulk-move-group: post: tags: - Plans summary: Bulk move plans to another group security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanBulkMoveGroupRequest" responses: "200": description: Bulk move summary. content: application/json: schema: $ref: "#/components/schemas/PlanBulkMoveGroupResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-plans-bulk-move-group parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/plan_groups: get: tags: - Plan Groups summary: List plan groups description: Returns all of the current organization's plan groups ordered by `display_order`. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string description: Free-text search by name or slug. required: false name: search in: query - schema: type: string enum: - "true" - "false" description: When `true`, includes archived groups in the list. required: false name: include_archived in: query - schema: type: string format: uuid description: Filter plan groups by the given company (UUID). required: false name: company_id in: query - schema: type: string format: date description: Start of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_after in: query - schema: type: string format: date description: End of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_before in: query - schema: type: string format: date description: Return only groups archived on or after this date (YYYY-MM-DD). example: 2026-01-15 required: false name: archived_after in: query - schema: type: string format: date description: Return only groups archived on or before this date (YYYY-MM-DD). example: 2026-01-15 required: false name: archived_before in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: List of plan groups. content: application/json: schema: $ref: "#/components/schemas/PlanGroupListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-plan-groups post: tags: - Plan Groups summary: Create plan group security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanGroupCreateRequest" responses: "201": description: Plan group created. content: application/json: schema: $ref: "#/components/schemas/PlanGroupResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-plan-groups parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Plan Groups summary: Upsert plan group description: "Takes the same body as POST, plus `id` and `public_id`, and dedups on `id`, `public_id`, `external_id` and the resource's natural keys, in that order, stopping at the first key that finds a record. A match is updated and returns 200; otherwise the record is created and returns 201. The POST's required fields are required only when no record is found, and updates are partial: absent fields keep their stored value." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanGroupUpsertRequest" responses: "200": description: Record updated. content: application/json: schema: $ref: "#/components/schemas/PlanGroupUpsertResponse" "201": description: Record created. content: application/json: schema: $ref: "#/components/schemas/PlanGroupUpsertResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-plan-groups parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/plan_groups/{id}: get: tags: - Plan Groups summary: Get plan group security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan group UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Plan group detail. content: application/json: schema: $ref: "#/components/schemas/PlanGroupResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-plan-groups-id patch: tags: - Plan Groups summary: Update plan group security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan group UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanGroupUpdateRequest" responses: "200": description: Plan group updated. content: application/json: schema: $ref: "#/components/schemas/PlanGroupResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-plan-groups-id delete: tags: - Plan Groups summary: Remove plan group security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan group UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Removal confirmation. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-plan-groups-id /v1/plan_groups/reorder: post: tags: - Plan Groups summary: Reorder plan groups description: Updates each group `display_order` according to the order of the `group_ids` array. All groups must belong to the current organization. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanGroupReorderRequest" responses: "200": description: Order updated. content: application/json: schema: $ref: "#/components/schemas/PlanGroupReorderResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-plan-groups-reorder parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/plan_groups/{id}/archive: post: tags: - Plan Groups summary: Archive plan group description: Marks the group as archived by setting `archived_at`. Archived groups are hidden from default listings. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan group UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Plan group archived. content: application/json: schema: $ref: "#/components/schemas/PlanGroupResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-plan-groups-id-archive /v1/products: get: tags: - Products summary: List products description: Returns a paginated list of the current organization's products. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - all - draft - active - archived description: Filter by product status. required: false name: status in: query - schema: type: string enum: - public - private description: Filter by visibility. required: false name: visibility in: query - schema: type: string enum: - base - addon_quantity - addon_fixed - metered - one_time_fixed - one_time_quantity - credits description: Filter by product type. required: false name: product_type in: query - schema: type: string format: uuid description: Filter by product group. required: false name: product_group_id in: query - schema: type: string format: uuid description: Filter by company. required: false name: company_id in: query - schema: type: string format: uuid description: Filter by parent product. required: false name: parent_product_id in: query - schema: type: string enum: - "true" - "false" description: When `true`, returns only root products (with no parent). required: false name: root_only in: query - schema: type: string description: Free-text search (name, slug). required: false name: search in: query - schema: type: string format: uuid description: Filter by linked service item. required: false name: service_item_id in: query - schema: type: string enum: - "true" - "false" description: When `true`, returns only products marked as required. required: false name: is_required in: query - schema: type: string enum: - "true" - "false" description: When `true`, returns only products that the customer can edit in the portal. required: false name: self_service_editable in: query - schema: type: string description: Filter by external identifier. required: false name: external_id in: query - schema: type: string description: Filter by exact product slug. required: false name: slug in: query - schema: type: string format: date description: Start of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_after in: query - schema: type: string format: date description: End of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_before in: query - schema: type: string format: date description: Start of update date range (YYYY-MM-DD). example: 2026-01-15 required: false name: updated_after in: query - schema: type: string format: date description: End of update date range (YYYY-MM-DD). example: 2026-01-15 required: false name: updated_before in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of products. content: application/json: schema: $ref: "#/components/schemas/ProductListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-products post: tags: - Products summary: Create product security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductCreateRequest" responses: "201": description: Product created. content: application/json: schema: $ref: "#/components/schemas/ProductResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-products parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Products summary: Upsert product description: "Takes the same body as POST, plus `id` and `public_id`, and dedups on `id`, `public_id`, `external_id` and the resource's natural keys, in that order, stopping at the first key that finds a record. A match is updated and returns 200; otherwise the record is created and returns 201. The POST's required fields are required only when no record is found, and updates are partial: absent fields keep their stored value." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductUpsertRequest" responses: "200": description: Record updated. content: application/json: schema: $ref: "#/components/schemas/ProductUpsertResponse" "201": description: Record created. content: application/json: schema: $ref: "#/components/schemas/ProductUpsertResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-products parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/products/{id}: get: tags: - Products summary: Get product security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Product UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Product detail. content: application/json: schema: $ref: "#/components/schemas/ProductResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-products-id patch: tags: - Products summary: Update product security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Product UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductUpdateRequest" responses: "200": description: Product updated. content: application/json: schema: $ref: "#/components/schemas/ProductResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-products-id delete: tags: - Products summary: Archive product (soft delete) description: Archives the product. Returns 422 when the product is in use by active subscriptions. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Product UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Soft delete confirmation. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-products-id /v1/products/{id}/archive: post: tags: - Products summary: Archive product description: Archives the product. Returns 422 when the product is in use by active subscriptions or is already archived. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Product UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Product archived. content: application/json: schema: $ref: "#/components/schemas/ProductResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-products-id-archive /v1/products/{id}/publish: post: tags: - Products summary: Publish product description: Promotes a draft product to active status. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Product UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Product published. content: application/json: schema: $ref: "#/components/schemas/ProductResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-products-id-publish /v1/products/{id}/restore: post: tags: - Products summary: Restore archived product description: Restores an archived product back to active status. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Product UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Product restored. content: application/json: schema: $ref: "#/components/schemas/ProductResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-products-id-restore /v1/products/reorder: post: tags: - Products summary: Reorder products description: Updates product display order. Array index 0 becomes the first item in the list. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductReorderRequest" responses: "200": description: Order updated. content: application/json: schema: $ref: "#/components/schemas/ProductBulkResultResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-products-reorder parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Products summary: Reorder products (PUT /reorder) description: Alias `PUT` for `/products/reorder`. Same behavior as the `POST` version. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductReorderRequest" responses: "200": description: Order updated. content: application/json: schema: $ref: "#/components/schemas/ProductBulkResultResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-products-reorder parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/products/bulk-archive: post: tags: - Products summary: Bulk archive products description: Archives multiple products. IDs in use by active subscriptions or already archived are skipped and reported in the response. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductBulkArchiveRequest" responses: "200": description: Bulk operation result. content: application/json: schema: $ref: "#/components/schemas/ProductBulkResultResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-products-bulk-archive parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/products/bulk-delete: post: tags: - Products summary: Bulk delete products description: Permanently deletes multiple products. IDs in use by active subscriptions are skipped and reported in the response. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductBulkDeleteRequest" responses: "200": description: Bulk operation result. content: application/json: schema: $ref: "#/components/schemas/ProductBulkResultResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-products-bulk-delete parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/products/bulk-visibility: post: tags: - Products summary: Bulk change visibility description: Updates the visibility (`public` or `private`) of multiple products. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductBulkVisibilityRequest" responses: "200": description: Bulk operation result. content: application/json: schema: $ref: "#/components/schemas/ProductBulkResultResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-products-bulk-visibility parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/products/bulk-move-group: post: tags: - Products summary: Move products to another group description: "Moves multiple products to a product group. Send `product_group_id: null` to remove from the current group." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductBulkMoveGroupRequest" responses: "200": description: Bulk operation result. content: application/json: schema: $ref: "#/components/schemas/ProductBulkResultResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-products-bulk-move-group parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/products/bulk-change-company: post: tags: - Products summary: Bulk change product company description: "Reassigns multiple products to another company. Send `company_id: null` to clear the link." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductBulkChangeCompanyRequest" responses: "200": description: Bulk operation result. content: application/json: schema: $ref: "#/components/schemas/ProductBulkResultResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-products-bulk-change-company parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/product_groups: get: tags: - Product Groups summary: List product groups description: Returns a paginated list of the current organization's product groups. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string description: Free-text search by group name. required: false name: search in: query - schema: type: string format: uuid description: Filter by associated issuing company. required: false name: company_id in: query - schema: type: - boolean - "null" description: "When `true`, includes archived groups in the listing. Default: `false`." required: false name: include_archived in: query - schema: type: string format: date description: Start of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_after in: query - schema: type: string format: date description: End of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_before in: query - schema: type: string format: date description: Returns groups archived from this date onwards (ISO 8601). example: 2026-01-15 required: false name: archived_after in: query - schema: type: string format: date description: Returns groups archived up to this date (ISO 8601). example: 2026-01-15 required: false name: archived_before in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of product groups. content: application/json: schema: $ref: "#/components/schemas/ProductGroupListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-product-groups post: tags: - Product Groups summary: Create product group security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductGroupCreateRequest" responses: "201": description: Product group created. content: application/json: schema: $ref: "#/components/schemas/ProductGroupResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-product-groups parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Product Groups summary: Upsert product group description: "Takes the same body as POST, plus `id` and `public_id`, and dedups on `id`, `public_id`, `external_id` and the resource's natural keys, in that order, stopping at the first key that finds a record. A match is updated and returns 200; otherwise the record is created and returns 201. The POST's required fields are required only when no record is found, and updates are partial: absent fields keep their stored value." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductGroupUpsertRequest" responses: "200": description: Record updated. content: application/json: schema: $ref: "#/components/schemas/ProductGroupUpsertResponse" "201": description: Record created. content: application/json: schema: $ref: "#/components/schemas/ProductGroupUpsertResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-product-groups parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/product_groups/{id}: get: tags: - Product Groups summary: Get product group security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Product group UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Product group detail. content: application/json: schema: $ref: "#/components/schemas/ProductGroupResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-product-groups-id patch: tags: - Product Groups summary: Update product group security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Product group UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductGroupUpdateRequest" responses: "200": description: Product group updated. content: application/json: schema: $ref: "#/components/schemas/ProductGroupResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-product-groups-id delete: tags: - Product Groups summary: Remove product group security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Product group UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Removal confirmation. content: application/json: schema: $ref: "#/components/schemas/ProductGroupDeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-product-groups-id /v1/product_groups/{id}/archive: post: tags: - Product Groups summary: Archive product group security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Product group UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Product group archived. content: application/json: schema: $ref: "#/components/schemas/ProductGroupResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-product-groups-id-archive delete: tags: - Product Groups summary: Unarchive product group security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Product group UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Product group unarchived. content: application/json: schema: $ref: "#/components/schemas/ProductGroupResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-product-groups-id-archive /v1/product_groups/reorder: post: tags: - Product Groups summary: Reorder product groups description: Updates the display order of product groups. The `group_ids` array defines the new order — index 0 becomes the first group. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductGroupReorderRequest" responses: "200": description: Order updated successfully. content: application/json: schema: $ref: "#/components/schemas/ProductGroupReorderResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-product-groups-reorder parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Product Groups summary: Reorder product groups (PUT alias) description: Alias `PUT` for `POST /product_groups/reorder`. Same contract. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductGroupReorderRequest" responses: "200": description: Order updated successfully. content: application/json: schema: $ref: "#/components/schemas/ProductGroupReorderResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-product-groups-reorder parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/organization: get: tags: - Organization summary: Get current organization description: Returns the data of the organization the authenticated token belongs to. There is no `:id` parameter — the organization is always resolved from the API key. security: - bearerAuth: [] responses: "200": description: Current organization detail. content: application/json: schema: $ref: "#/components/schemas/OrganizationResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-organization parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier patch: tags: - Organization summary: Update current organization description: Updates the profile of the authenticated organization. Only the fields below can be modified — identity (`id`, `external_id`, `status`) is not changeable through this endpoint. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/OrganizationUpdateRequest" responses: "200": description: Organization updated. content: application/json: schema: $ref: "#/components/schemas/OrganizationResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-organization parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/companies: get: tags: - Companies summary: List companies description: Returns a paginated list of the current organization's companies (head offices and branches). security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Filter by associated person UUID. required: false name: person_id in: query - schema: type: string description: Filter by person CPF/CNPJ (exact match). required: false name: person_document_number in: query - schema: type: string description: Filter by person name (partial search, case-insensitive). required: false name: person_name_contains in: query - schema: type: string enum: - active - inactive description: "Filter by status: `active` or `inactive`." required: false name: status in: query - schema: type: string description: Free-text search by name, legal name, email or document number. required: false name: search in: query - schema: type: string enum: - "true" - "false" description: Filter only the company flagged as the organization default. required: false name: is_default in: query - schema: type: string description: Filter branches by head office. Use the head office UUID to list its branches. required: false name: parent_company_id in: query - schema: type: string format: uuid description: Filter companies by the UUID of the associated email layout. required: false name: email_layout_id in: query - schema: type: string format: date description: Start of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_after in: query - schema: type: string format: date description: End of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_before in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of companies. content: application/json: schema: $ref: "#/components/schemas/CompanyListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-companies post: tags: - Companies summary: Create company description: Creates a company (head office or branch). To create a branch, provide `parent_company_id` — the CNPJ must share the same prefix as the head office. Only CNPJ companies can have branches. The first company created in the organization is flagged as `is_default` automatically. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/CompanyCreateRequest" responses: "201": description: Company created. content: application/json: schema: $ref: "#/components/schemas/CompanyResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-companies parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Companies summary: Upsert company description: "Takes the same body as POST, plus `id` and `public_id`, and dedups on `id`, `public_id`, `external_id` and the resource's natural keys, in that order, stopping at the first key that finds a record. A match is updated and returns 200; otherwise the record is created and returns 201. The POST's required fields are required only when no record is found, and updates are partial: absent fields keep their stored value." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/CompanyUpsertRequest" responses: "200": description: Record updated. content: application/json: schema: $ref: "#/components/schemas/CompanyUpsertResponse" "201": description: Record created. content: application/json: schema: $ref: "#/components/schemas/CompanyUpsertResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-companies parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/companies/matriz: get: tags: - Companies summary: List head office companies description: Lists the active head office companies (without `parent_company_id`) of the organization. Useful when selecting the parent company before creating a branch. Only CNPJ companies appear here. security: - bearerAuth: [] responses: "200": description: List of head office companies. content: application/json: schema: $ref: "#/components/schemas/CompanyMatrizListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-companies-matriz parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/companies/{id}: get: tags: - Companies summary: Get company security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Company UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Company detail. content: application/json: schema: $ref: "#/components/schemas/CompanyResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-companies-id patch: tags: - Companies summary: Update company security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Company UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/CompanyUpdateRequest" responses: "200": description: Company updated. content: application/json: schema: $ref: "#/components/schemas/CompanyResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-companies-id delete: tags: - Companies summary: Deactivate company description: Deactivates the company (soft delete — equivalent to `POST /companies/{id}/deactivate`). Cannot deactivate the only active company, nor a company that has active or trialing subscriptions. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Company UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Company deactivated. content: application/json: schema: $ref: "#/components/schemas/CompanyDeleteResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-companies-id /v1/companies/{id}/set-default: post: tags: - Companies summary: Set default company description: Marks the company as the organization's default. The previous default is unset in the same transaction. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Company UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Company set as default. content: application/json: schema: $ref: "#/components/schemas/CompanyResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-companies-id-set-default /v1/companies/{id}/deactivate: post: tags: - Companies summary: Deactivate company (POST /deactivate) description: Deactivates the company. Cannot deactivate the only active company, nor a company that has active or trialing subscriptions. If the deactivated company was the default, another active company is promoted automatically. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Company UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Company deactivated. content: application/json: schema: $ref: "#/components/schemas/CompanyResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-companies-id-deactivate /v1/companies/{id}/reactivate: post: tags: - Companies summary: Reactivate company description: Reactivates a previously deactivated company. Returns **422** when the company is already active. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Company UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Company reactivated. content: application/json: schema: $ref: "#/components/schemas/CompanyResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-companies-id-reactivate /v1/companies/{id}/fiscal: get: tags: - Companies summary: Get fiscal profile description: Returns the company's fiscal profile, or `null` when it has not been configured yet. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Company UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Company fiscal profile (or `null`). content: application/json: schema: $ref: "#/components/schemas/CompanyFiscalProfileResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-companies-id-fiscal patch: tags: - Companies summary: Update fiscal profile description: Creates or updates (upsert) the company fiscal profile. Includes taxation regime, rates (ISS, PIS, COFINS, CSLL, IRPJ) and CBS/IBS settings. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Company UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/CompanyFiscalProfileUpsertRequest" responses: "200": description: Fiscal profile updated. content: application/json: schema: $ref: "#/components/schemas/CompanyFiscalProfileResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-companies-id-fiscal /v1/companies/{id}/fiscal-profile: get: tags: - Companies summary: Get fiscal profile (alias) description: Alias of `GET /companies/{id}/fiscal` — same representation and behaviour. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Company UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Company fiscal profile (or `null`). content: application/json: schema: $ref: "#/components/schemas/CompanyFiscalProfileResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-companies-id-fiscal-profile patch: tags: - Companies summary: Update fiscal profile (alias) description: Alias of `PATCH /companies/{id}/fiscal` — same representation and behaviour. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Company UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/CompanyFiscalProfileUpsertRequest" responses: "200": description: Fiscal profile updated. content: application/json: schema: $ref: "#/components/schemas/CompanyFiscalProfileResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-companies-id-fiscal-profile /v1/certificates: get: tags: - Certificates summary: List digital certificates description: Returns a paginated list of the current organization’s digital (A1) certificates. For security reasons, the response **never** includes the private key nor the PFX password — only metadata extracted from the certificate. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Filter by associated person UUID. required: false name: person_id in: query - schema: type: string description: Filter by person CPF/CNPJ (exact match). required: false name: person_document_number in: query - schema: type: string description: Filter by person name (partial search, case-insensitive). required: false name: person_name_contains in: query - schema: type: string enum: - active - expired - revoked - expiring_soon description: Filter by certificate status. `expiring_soon` returns active certificates expiring within 30 days. required: false name: status in: query - schema: type: string description: Free-text search in `name`, `common_name`, `document` or `organization_name`. required: false name: search in: query - schema: type: string description: Filter by stored certificate format (`pfx`, `pem`). required: false name: format in: query - schema: type: string description: Filter by CPF or CNPJ extracted from the certificate (digits only). required: false name: document in: query - schema: type: string description: Filter by certificate serial number. required: false name: serial_number in: query - schema: type: string format: date description: Returns certificates whose expiry date (`not_after`) is greater than or equal to the given date (ISO 8601). example: 2026-01-15 required: false name: not_after_from in: query - schema: type: string format: date description: Returns certificates whose expiry date (`not_after`) is less than or equal to the given date (ISO 8601). example: 2026-01-15 required: false name: not_after_to in: query - schema: type: string format: date description: Returns certificates whose validity start date (`not_before`) is greater than or equal to the given date (ISO 8601). example: 2026-01-15 required: false name: not_before_from in: query - schema: type: string format: date description: Returns certificates whose validity start date (`not_before`) is less than or equal to the given date (ISO 8601). example: 2026-01-15 required: false name: not_before_to in: query - schema: type: string format: date description: Returns certificates created from the given date (ISO 8601). example: 2026-01-15 required: false name: created_after in: query - schema: type: string format: date description: Returns certificates created up to the given date (ISO 8601). example: 2026-01-15 required: false name: created_before in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of certificates. content: application/json: schema: $ref: "#/components/schemas/CertificateListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-certificates post: tags: - Certificates summary: Upload digital certificate description: |- Uploads an A1 digital certificate via `multipart/form-data`. The private key and password are encrypted at rest and are **never** returned by the API. The endpoint detects duplicates by `thumbprint` and automatically associates the certificate with a `person` based on the extracted CNPJ/CPF. Accepted `type` values: - `pfx` — send `file` (binary PFX/P12) and `password`. - `cert_key` — send `cert_file` (certificate PEM) and `key_file` (key PEM). - `combined_pem` — send `file` (PEM containing certificate + key). - `cert_key_password` — send `cert_file`, `key_file` and `password` (password-protected key). security: - bearerAuth: [] requestBody: content: multipart/form-data: schema: $ref: "#/components/schemas/CertificateUploadRequest" responses: "201": description: Certificate uploaded and stored successfully. content: application/json: schema: $ref: "#/components/schemas/CertificateResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-certificates parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/certificates/{id}: get: tags: - Certificates summary: Get certificate security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Certificate UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Certificate detail (no sensitive data). content: application/json: schema: $ref: "#/components/schemas/CertificateResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-certificates-id delete: tags: - Certificates summary: Delete certificate description: Removes the certificate via **soft delete**. Encrypted data remains in the database for audit purposes only. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Certificate UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Certificate deleted. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-certificates-id /v1/coupons: get: tags: - Coupons summary: List coupons description: Returns a paginated list of the current organization's coupons. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - "true" - "false" description: "Filter by status: `true` returns only active coupons; `false`, only inactive." required: false name: is_active in: query - schema: type: string description: Free-text search across `code` and `name`. required: false name: search in: query - schema: type: string enum: - percentage - fixed_amount description: "Filter by discount type: `percentage` or `fixed_amount`." required: false name: discount_type in: query - schema: type: string description: Filter by exact coupon code. required: false name: code in: query - schema: type: - number - "null" minimum: 0 description: Minimum value of `min_purchase` (in BRL) to filter coupons. example: 100 required: false name: min_purchase_min in: query - schema: type: - number - "null" minimum: 0 description: Maximum value of `min_purchase` (in BRL) to filter coupons. example: 100 required: false name: min_purchase_max in: query - schema: type: - number - "null" minimum: 0 description: Minimum value of `max_discount` (in BRL) to filter coupons. example: 100 required: false name: max_discount_min in: query - schema: type: - number - "null" minimum: 0 description: Maximum value of `max_discount` (in BRL) to filter coupons. example: 100 required: false name: max_discount_max in: query - schema: type: string format: date description: Returns coupons whose validity start date is on or after this date (YYYY-MM-DD). example: 2026-01-15 required: false name: valid_from_from in: query - schema: type: string format: date description: Returns coupons whose validity start date is on or before this date (YYYY-MM-DD). example: 2026-01-15 required: false name: valid_from_to in: query - schema: type: string format: date description: Returns coupons whose expiration date is on or after this date (YYYY-MM-DD). example: 2026-01-15 required: false name: valid_until_from in: query - schema: type: string format: date description: Returns coupons whose expiration date is on or before this date (YYYY-MM-DD). example: 2026-01-15 required: false name: valid_until_to in: query - schema: type: string format: date description: Returns coupons created on or after this date (YYYY-MM-DD). example: 2026-01-15 required: false name: created_after in: query - schema: type: string format: date description: Returns coupons created on or before this date (YYYY-MM-DD). example: 2026-01-15 required: false name: created_before in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of coupons. content: application/json: schema: $ref: "#/components/schemas/CouponListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-coupons post: tags: - Coupons summary: Create coupon description: Creates a discount coupon. The `code` must be unique per organization. Use `discount_type=percentage` with `discount_value` between `0` and `100`, or `discount_type=fixed_amount` with `discount_value` in BRL (float, up to 4 decimal places). security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/CouponCreateRequest" responses: "201": description: Coupon created. content: application/json: schema: $ref: "#/components/schemas/CouponResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-coupons parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Coupons summary: Upsert coupon description: "Takes the same body as POST, plus `id` and `public_id`, and dedups on `id`, `public_id`, `external_id` and the resource's natural keys, in that order, stopping at the first key that finds a record. A match is updated and returns 200; otherwise the record is created and returns 201. The POST's required fields are required only when no record is found, and updates are partial: absent fields keep their stored value." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/CouponUpsertRequest" responses: "200": description: Record updated. content: application/json: schema: $ref: "#/components/schemas/CouponUpsertResponse" "201": description: Record created. content: application/json: schema: $ref: "#/components/schemas/CouponUpsertResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-coupons parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/coupons/{id}: get: tags: - Coupons summary: Get coupon security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Coupon UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Coupon detail. content: application/json: schema: $ref: "#/components/schemas/CouponResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-coupons-id patch: tags: - Coupons summary: Update coupon description: Updates editable coupon fields. `code`, `discount_type`, `discount_value` and `currency` are immutable after creation. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Coupon UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/CouponUpdateRequest" responses: "200": description: Coupon updated. content: application/json: schema: $ref: "#/components/schemas/CouponResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-coupons-id delete: tags: - Coupons summary: Delete coupon description: Deletes the coupon permanently. Allowed only while the coupon **has no recorded redemptions** — otherwise use `POST /coupons/{id}/deactivate` to preserve history. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Coupon UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Coupon deleted. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-coupons-id /v1/coupons/{id}/deactivate: post: tags: - Coupons summary: Deactivate coupon description: "Deactivates the coupon: new redemptions are blocked, but previous redemptions are preserved." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Coupon UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Coupon deactivated. content: application/json: schema: $ref: "#/components/schemas/CouponResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-coupons-id-deactivate /v1/coupons/{id}/redemptions: get: tags: - Coupons summary: List coupon redemptions description: Returns a paginated list of the coupon's recorded redemptions. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Coupon UUID. required: true name: id in: path - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of coupon redemptions. content: application/json: schema: $ref: "#/components/schemas/CouponRedemptionListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-coupons-id-redemptions /v1/credits: get: tags: - Credits summary: List credits description: Returns a paginated list of credits in the current organization. By default, expired credits are omitted — use `usage` or `include_expired` to include them. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Filter by associated person UUID. required: false name: person_id in: query - schema: type: string description: Filter by person CPF/CNPJ (exact match). required: false name: person_document_number in: query - schema: type: string description: Filter by person name (partial search, case-insensitive). required: false name: person_name_contains in: query - schema: type: string format: uuid description: Filter credits by billing account. required: false name: billing_account_id in: query - schema: type: string format: uuid description: Filter credits by the linked `company`. required: false name: company_id in: query - schema: type: string enum: - promotional - adjustment - refund - manual description: "Filter by credit type: `promotional`, `adjustment`, `refund` or `manual`." required: false name: type in: query - schema: type: string enum: - available - used - expired description: Filter by usage state — `available` (remaining balance and not expired), `used` (fully consumed) or `expired` (past expiration). required: false name: usage in: query - schema: type: string enum: - "true" - "false" description: Includes expired credits when `true`. Ignored when `usage` is set. required: false name: include_expired in: query - schema: type: string format: date description: Start of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_after in: query - schema: type: string format: date description: End of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_before in: query - schema: type: - number - "null" minimum: 0 description: Minimum credit amount in BRL (inclusive). example: 100 required: false name: amount_min in: query - schema: type: - number - "null" minimum: 0 description: Maximum credit amount in BRL (inclusive). example: 100 required: false name: amount_max in: query - schema: type: - number - "null" minimum: 0 description: Minimum remaining balance in BRL (inclusive). example: 100 required: false name: amount_remaining_min in: query - schema: type: - number - "null" minimum: 0 description: Maximum remaining balance in BRL (inclusive). example: 100 required: false name: amount_remaining_max in: query - schema: type: string format: date description: Lower bound for `expires_at` (YYYY-MM-DD, inclusive). example: 2026-01-15 required: false name: expires_after in: query - schema: type: string format: date description: Upper bound for `expires_at` (YYYY-MM-DD, inclusive). example: 2026-01-15 required: false name: expires_before in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of credits. content: application/json: schema: $ref: "#/components/schemas/CreditListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-credits post: tags: - Credits summary: Add credit description: Adds a credit to a billing account. The amount is credited to the `BillingAccount` `balance` and becomes available to settle future invoices. When `company_id` is provided, the credit can only be applied to invoices from the same `company`. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/CreditCreateRequest" responses: "201": description: Credit created. content: application/json: schema: $ref: "#/components/schemas/CreditResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-credits parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Credits summary: Upsert credit description: "Takes the same body as POST, plus `id` and `public_id`, and dedups on `id`, `public_id`, `external_id` and the resource's natural keys, in that order, stopping at the first key that finds a record. A match is updated and returns 200; otherwise the record is created and returns 201. The POST's required fields are required only when no record is found, and updates are partial: absent fields keep their stored value." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/CreditUpsertRequest" responses: "200": description: Record updated. content: application/json: schema: $ref: "#/components/schemas/CreditUpsertResponse" "201": description: Record created. content: application/json: schema: $ref: "#/components/schemas/CreditUpsertResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-credits parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/credits/{id}: get: tags: - Credits summary: Get credit security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Credit UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Credit detail. content: application/json: schema: $ref: "#/components/schemas/CreditResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-credits-id patch: tags: - Credits summary: Update credit description: Adjusts the credit (type, amount, description or expiration). `amount` can only change if the credit has not been partially used — otherwise the API responds with `400`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Credit UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/CreditUpdateRequest" responses: "200": description: Credit updated. content: application/json: schema: $ref: "#/components/schemas/CreditResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-credits-id delete: tags: - Credits summary: Delete credit description: Removes the credit and reverses the matching balance on the billing account. Only allowed if no cents of the credit have been consumed — otherwise the API responds with `400`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Credit UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Credit deleted. content: application/json: schema: $ref: "#/components/schemas/CreditDeleteResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-credits-id /v1/invoices: get: tags: - Invoices summary: List invoices description: Returns a paginated list of the current organization's invoices. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - draft - open - paid - void - uncollectible description: "Filter by status: `draft`, `open`, `paid`, `void` or `uncollectible`." required: false name: status in: query - schema: type: string format: uuid description: Filter by `billing_account_id`. required: false name: billing_account_id in: query - schema: type: string format: uuid description: Filter by issuing `company_id`. required: false name: company_id in: query - schema: type: string format: uuid description: Filter by originating `subscription_id`. required: false name: subscription_id in: query - schema: type: string description: Filter by start `due_date` (inclusive). required: false name: due_date_from in: query - schema: type: string description: Filter by end `due_date` (inclusive). required: false name: due_date_to in: query - schema: type: string description: Filter by start `created_at` (inclusive). required: false name: date_from in: query - schema: type: string description: Filter by end `created_at` (inclusive). required: false name: date_to in: query - schema: type: string description: Free-text search. required: false name: search in: query - schema: type: - number - "null" description: Filter by minimum total amount, in BRL (float, up to 4 decimal places). required: false name: total_min in: query - schema: type: - number - "null" description: Filter by maximum total amount, in BRL (float, up to 4 decimal places). required: false name: total_max in: query - schema: type: string description: Filter by customer's CPF/CNPJ. required: false name: document_number in: query - schema: type: string enum: - "true" - "false" description: When `true`, returns only invoices without associated payments. required: false name: without_payments in: query - schema: type: string enum: - all - with_plan - without_plan description: "Filter by origin: `all`, `with_plan` (subscription) or `without_plan` (one-off)." required: false name: plan_filter in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of invoices. content: application/json: schema: $ref: "#/components/schemas/InvoiceListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-invoices post: tags: - Invoices summary: Create invoice description: Creates an invoice for a billing account. Accepts line items, optional installments (`installments`, minimum 2) and NF-e issuance policy. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/InvoiceCreateRequest" responses: "201": description: Invoice created. content: application/json: schema: $ref: "#/components/schemas/InvoiceResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-invoices parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Invoices summary: Upsert invoice description: "Takes the same body as POST, plus `id` and `public_id`, and dedups on `id`, `public_id`, `external_id` and the resource's natural keys, in that order, stopping at the first key that finds a record. A match is updated and returns 200; otherwise the record is created and returns 201. The POST's required fields are required only when no record is found, and updates are partial: absent fields keep their stored value." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/InvoiceUpsertRequest" responses: "200": description: Record updated. content: application/json: schema: $ref: "#/components/schemas/InvoiceUpsertResponse" "201": description: Record created. content: application/json: schema: $ref: "#/components/schemas/InvoiceUpsertResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-invoices parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/invoices/pending-payment: get: tags: - Invoices summary: List invoices with pending payment description: Returns finalized invoices (`status = open`) past their `due_date`. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Filter by `billing_account_id`. required: false name: billing_account_id in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of invoices with pending payment. content: application/json: schema: $ref: "#/components/schemas/InvoiceListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-invoices-pending-payment /v1/invoices/pending-nfe: get: tags: - Invoices summary: List invoices with pending NF-e description: Returns paid invoices that still need NF-e emission — no NF-e, or NF-e in `pending`, `processing` or `error` status. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Filter by `billing_account_id`. required: false name: billing_account_id in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of invoices with pending NF-e. content: application/json: schema: $ref: "#/components/schemas/InvoiceListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-invoices-pending-nfe /v1/invoices/{id}: get: tags: - Invoices summary: Get invoice security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Invoice detail. content: application/json: schema: $ref: "#/components/schemas/InvoiceResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-invoices-id patch: tags: - Invoices summary: Update invoice security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/InvoiceUpdateRequest" responses: "200": description: Invoice updated. content: application/json: schema: $ref: "#/components/schemas/InvoiceResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-invoices-id delete: tags: - Invoices summary: Delete invoice description: Deletes a draft (`draft`) invoice. Finalized invoices must be canceled via `POST /invoices/{id}/void`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Invoice deleted. content: application/json: schema: $ref: "#/components/schemas/InvoiceDeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-invoices-id /v1/invoices/{id}/finalize: post: tags: - Invoices summary: Finalize invoice description: Finalizes a draft invoice (`draft` → `open`). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Invoice finalized. content: application/json: schema: $ref: "#/components/schemas/InvoiceResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-invoices-id-finalize /v1/invoices/{id}/void: post: tags: - Invoices summary: Void invoice description: Voids an open invoice (`open` → `void`). The `reason` is recorded in the audit log. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/InvoiceVoidRequest" responses: "200": description: Invoice voided. content: application/json: schema: $ref: "#/components/schemas/InvoiceResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-invoices-id-void /v1/invoices/{id}/undo-payment: post: tags: - Invoices summary: Undo invoice payment description: Reverts the invoice payment (`paid` → `open`). The `reason` is recorded in the audit log. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/InvoiceUndoPaymentRequest" responses: "200": description: Payment undone. content: application/json: schema: $ref: "#/components/schemas/InvoiceResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-invoices-id-undo-payment /v1/invoices/{id}/pay: post: tags: - Invoices summary: Pay invoice description: "Two modes: (a) when `payment_method` is provided, creates a gateway payment (`pix`, `bank_slip` or `card`) and returns the method artifacts (QR code, barcode or card status) — or, with `bank_transfer`, a transfer charge to the organization bank account (`bank_account_id`) or Pix key (`pix_key_id`), with no gateway, returning the details in `bank_transfer` and staying pending until settled manually; (b) when omitted, marks the invoice as paid manually (reconciliation)." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/InvoicePayRequest" responses: "200": description: Payment result or invoice marked as paid. content: application/json: schema: $ref: "#/components/schemas/InvoicePayResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-invoices-id-pay /v1/invoices/{id}/send-reminder: post: tags: - Invoices summary: Send invoice reminder description: Sends an invoice payment reminder email to the billing account's `billing_email`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Reminder sent. content: application/json: schema: $ref: "#/components/schemas/InvoiceResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-invoices-id-send-reminder /v1/invoices/{id}/issue-nfe: post: tags: - Invoices summary: Issue NF-e for invoice description: Triggers issuance of the NF-e (Electronic Invoice) for the invoice. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: NF-e queued/issued. content: application/json: schema: $ref: "#/components/schemas/InvoiceNfeResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-invoices-id-issue-nfe /v1/invoices/{id}/apply-credits: post: tags: - Invoices summary: Apply credits to invoice description: Applies billing-account credits to an open (`status = open`) invoice. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/InvoiceApplyCreditsRequest" responses: "200": description: Credits applied. content: application/json: schema: $ref: "#/components/schemas/InvoiceCreditsResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-invoices-id-apply-credits /v1/invoices/{id}/remove-credits: post: tags: - Invoices summary: Remove applied credits description: Removes all credits applied to the invoice, returning them to the billing account. Only works on open (`status = open`) invoices. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Credits removed. content: application/json: schema: $ref: "#/components/schemas/InvoiceCreditsResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-invoices-id-remove-credits /v1/invoices/{id}/pdf: get: tags: - Invoices summary: Download invoice PDF description: Generates and downloads the invoice PDF as a binary attachment (`application/pdf`). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Invoice PDF. content: application/pdf: schema: type: string format: binary "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-invoices-id-pdf /v1/invoices/{id}/payment-methods: get: tags: - Invoices summary: List available payment methods description: Lists the payment methods available to pay this invoice, based on the organization's active gateways and portal settings. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Available payment methods. content: application/json: schema: $ref: "#/components/schemas/InvoicePaymentMethodsResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-invoices-id-payment-methods /v1/invoices/{id}/installments: get: tags: - Invoices summary: List invoice installments security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: List of installments. content: application/json: schema: $ref: "#/components/schemas/InvoiceInstallmentsListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-invoices-id-installments post: tags: - Invoices summary: Create/update installment schedule description: Creates or replaces the invoice installment schedule. Minimum of 2 installments. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/InvoiceInstallmentsCreateRequest" responses: "201": description: Installment schedule created. content: application/json: schema: $ref: "#/components/schemas/InvoiceInstallmentsListResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-invoices-id-installments /v1/invoices/{id}/installments/{installment_id}/mark-paid: post: tags: - Invoices summary: Mark installment as paid description: Manually marks an installment as paid (reconciliation, no gateway call). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - schema: type: string format: uuid description: Installment UUID. required: true name: installment_id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Installment marked as paid. content: application/json: schema: $ref: "#/components/schemas/InvoiceInstallmentResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-invoices-id-installments-installment-id-mark-paid /v1/invoices/{id}/installments/{installment_id}/pay: post: tags: - Invoices summary: Pay installment description: Processes payment for a specific installment via the gateway. The previous installment must be paid. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - schema: type: string format: uuid description: Installment UUID. required: true name: installment_id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/InvoiceInstallmentPayRequest" responses: "200": description: Installment payment result. content: application/json: schema: $ref: "#/components/schemas/InvoicePayResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-invoices-id-installments-installment-id-pay /v1/payments: get: tags: - Payments summary: List payments description: Returns a paginated list of the current organization's payments. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Filter by associated person UUID. required: false name: person_id in: query - schema: type: string description: Filter by person CPF/CNPJ (exact match). required: false name: person_document_number in: query - schema: type: string description: Filter by person name (partial search, case-insensitive). required: false name: person_name_contains in: query - schema: type: string enum: - pending - processing - succeeded - failed - canceled - partial - refunded - partially_refunded description: Filter by payment status. required: false name: status in: query - schema: type: string format: uuid description: Filter by payments of a specific invoice. required: false name: invoice_id in: query - schema: type: string format: uuid description: Filter by payments of a billing account. required: false name: billing_account_id in: query - schema: type: string format: uuid description: Filter by payments of a specific company. required: false name: company_id in: query - schema: type: string format: uuid description: Filter by payments processed by a specific gateway. required: false name: gateway_id in: query - schema: type: string format: uuid description: Filter by payments of a specific payment method. required: false name: payment_method_id in: query - schema: type: string enum: - card - bank_slip - pix - bank_transfer description: "Filter by payment method: `card`, `bank_slip`, `pix` or `bank_transfer`." required: false name: payment_method_type in: query - schema: type: string description: Filter by external ID (free field for legacy system identifiers). required: false name: external_id in: query - schema: type: string description: Filter by the payment identifier at the upstream gateway. required: false name: gateway_payment_id in: query - schema: type: string enum: - all - with_invoice - without_invoice description: "Filter by invoice presence: `all`, `with_invoice` or `without_invoice`." required: false name: invoice_filter in: query - schema: type: string description: Free-text search. required: false name: search in: query - schema: type: - number - "null" minimum: 0 description: Minimum charged amount (in BRL). example: 100 required: false name: amount_min in: query - schema: type: - number - "null" minimum: 0 description: Maximum charged amount (in BRL). example: 100 required: false name: amount_max in: query - schema: type: - number - "null" minimum: 0 description: Minimum amount actually received (in BRL). example: 100 required: false name: paid_amount_min in: query - schema: type: - number - "null" minimum: 0 description: Maximum amount actually received (in BRL). example: 100 required: false name: paid_amount_max in: query - schema: type: string format: date description: Start of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_after in: query - schema: type: string format: date description: End of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_before in: query - schema: type: string format: date description: Paid-at start date — ISO 8601 format. example: 2026-01-15 required: false name: paid_after in: query - schema: type: string format: date description: Paid-at end date — ISO 8601 format. example: 2026-01-15 required: false name: paid_before in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of payments. content: application/json: schema: $ref: "#/components/schemas/PaymentListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-payments post: tags: - Payments summary: Process payment description: Processes a payment for an existing invoice. Accepts a previously registered `payment_method_id` **or** a `payment_method` block with card/PIX/bank-slip data. When `amount` is omitted, charges the invoice open balance. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentCreateRequest" responses: "201": description: Payment created. content: application/json: schema: $ref: "#/components/schemas/PaymentResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-payments parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/payments/bulk-update-invoice: post: tags: - Payments summary: Reassign payments to another invoice description: Bulk-updates the invoice associated with the given payments. Useful for fixing links when payments arrived pointing to the wrong invoice. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentBulkUpdateInvoiceRequest" responses: "200": description: Payments reassigned. content: application/json: schema: $ref: "#/components/schemas/PaymentBulkUpdateInvoiceResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-payments-bulk-update-invoice parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/payments/{id}: get: tags: - Payments summary: Get payment security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Payment UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Payment detail. content: application/json: schema: $ref: "#/components/schemas/PaymentResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-payments-id delete: tags: - Payments summary: Delete payment description: Removes a payment. Confirmed payments cannot be deleted — use `cancel` or `refund` instead. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Payment UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Payment removed. content: application/json: schema: $ref: "#/components/schemas/PaymentDeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-payments-id /v1/payments/{id}/cancel: post: tags: - Payments summary: Cancel payment description: Cancels an open payment. When `cancel_on_gateway` is `true` (default), the cancellation is propagated to the gateway. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Payment UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentCancelRequest" responses: "200": description: Payment canceled. content: application/json: schema: $ref: "#/components/schemas/PaymentResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-payments-id-cancel /v1/payments/{id}/retry: post: tags: - Payments summary: Retry payment description: Reprocesses a failed payment. Optionally switches to a new card (via `card`) or to a saved payment method (`payment_method_id`). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Payment UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentRetryRequest" responses: "200": description: Payment retried. content: application/json: schema: $ref: "#/components/schemas/PaymentResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-payments-id-retry /v1/payments/{id}/change-card: post: tags: - Payments summary: Change payment card description: Replaces the credit card on a failed Pagar.me payment. The new card must be pre-registered in `payment_methods`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Payment UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentChangeCardRequest" responses: "200": description: Card changed. content: application/json: schema: $ref: "#/components/schemas/PaymentResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-payments-id-change-card /v1/payments/{id}/change-due-date: post: tags: - Payments summary: Change bank slip due date description: Changes the due date of a pending bank-slip payment issued via the Kobana gateway. The new date must be in the future. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Payment UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentChangeDueDateRequest" responses: "200": description: Due date updated. content: application/json: schema: $ref: "#/components/schemas/PaymentChangeDueDateResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-payments-id-change-due-date /v1/payments/{id}/send-email: post: tags: - Payments summary: Send bank slip by email description: Sends the bank-slip link by email to the given recipient. Only available for pending bank-slip payments. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Payment UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentSendEmailRequest" responses: "200": description: Email sent. content: application/json: schema: $ref: "#/components/schemas/PaymentSendEmailResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-payments-id-send-email /v1/payments/{id}/sync: post: tags: - Payments summary: Sync payment with gateway description: Syncs the payment status with the upstream gateway (Kobana PIX/boleto or Pagar.me refund). Returns the refreshed payment. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Payment UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Payment synced. content: application/json: schema: $ref: "#/components/schemas/PaymentResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-payments-id-sync /v1/payments/{id}/refund: post: tags: - Payments summary: Refund payment description: Refunds a successful payment. Without `amount`, refunds the full amount; with a partial amount, issues a partial refund. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Payment UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentRefundRequest" responses: "200": description: Payment refunded. content: application/json: schema: $ref: "#/components/schemas/PaymentResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-payments-id-refund /v1/payment_methods: get: tags: - Payment Methods summary: List payment methods description: "Returns a paginated list of the current organization's payment methods. Optional filters: `billing_account_id`, `type`, `status`." security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Filter by billing account UUID. required: false name: billing_account_id in: query - schema: type: string enum: - card - bank_slip - pix - bank_transfer description: "Filter by type: `card`, `bank_slip`, `pix` or `bank_transfer`." required: false name: type in: query - schema: type: string enum: - active - expired - failed description: "Filter by status: `active`, `expired` or `failed`." required: false name: status in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of payment methods. content: application/json: schema: $ref: "#/components/schemas/PaymentMethodListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-payment-methods post: tags: - Payment Methods summary: Create payment method description: Creates a payment method tied to a billing account. For `type=card`, send the `card` block with the `card_token` produced by client-side tokenization. For `type=bank_transfer`, send the `bank_account` block. For `bank_slip` and `pix`, only the `type` is required — the default gateway is resolved from the organization. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentMethodCreateRequest" responses: "201": description: Payment method created. content: application/json: schema: $ref: "#/components/schemas/PaymentMethodResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-payment-methods parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Payment Methods summary: Upsert payment method description: "Takes the same body as POST, plus `id` and `public_id`, and dedups on `id`, `public_id`, `external_id` and the resource's natural keys, in that order, stopping at the first key that finds a record. A match is updated and returns 200; otherwise the record is created and returns 201. The POST's required fields are required only when no record is found, and updates are partial: absent fields keep their stored value." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentMethodUpsertRequest" responses: "200": description: Record updated. content: application/json: schema: $ref: "#/components/schemas/PaymentMethodUpsertResponse" "201": description: Record created. content: application/json: schema: $ref: "#/components/schemas/PaymentMethodUpsertResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-payment-methods parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/payment_methods/{id}: get: tags: - Payment Methods summary: Get payment method security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Payment method UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Payment method detail. content: application/json: schema: $ref: "#/components/schemas/PaymentMethodResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-payment-methods-id patch: tags: - Payment Methods summary: Update card expiration description: Updates only the expiration month and year of the card tied to the method. Fails when `type` is not `card`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Payment method UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentMethodUpdateRequest" responses: "200": description: Payment method updated. content: application/json: schema: $ref: "#/components/schemas/PaymentMethodResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-payment-methods-id delete: tags: - Payment Methods summary: Delete payment method description: Soft-deletes the payment method (marks it as `removed`). Fails when there are pending or processing payments. If it was the default, another active method is automatically promoted. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Payment method UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Payment method deleted. content: application/json: schema: type: object properties: data: type: object properties: deleted: type: boolean required: - deleted required: - data "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-payment-methods-id /v1/payment_methods/{id}/set-default: post: tags: - Payment Methods summary: Set payment method as default description: Marks the method as the billing account's default and unsets previous defaults. Fails when the method is not `active`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Payment method UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Payment method set as default. content: application/json: schema: $ref: "#/components/schemas/PaymentMethodResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-payment-methods-id-set-default /v1/nfes: get: tags: - NF-e summary: List NF-e description: Returns a paginated list of the current organization's NF-e (electronic invoices). security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Filter by associated person UUID. required: false name: person_id in: query - schema: type: string description: Filter by person CPF/CNPJ (exact match). required: false name: person_document_number in: query - schema: type: string description: Filter by person name (partial search, case-insensitive). required: false name: person_name_contains in: query - schema: type: string format: uuid description: Filter by `billing_account_id`. required: false name: billing_account_id in: query - schema: type: string format: uuid description: Filter by issuing `company_id`. required: false name: company_id in: query - schema: type: string format: uuid description: Filter by linked `invoice_id`. required: false name: invoice_id in: query - schema: type: string format: uuid description: Filter by linked `payment_id`. required: false name: payment_id in: query - schema: type: string format: uuid description: Filter by linked `transaction_id`. required: false name: transaction_id in: query - schema: type: string enum: - draft - pending - processing - issued - pending_cancel - canceling - canceled - error description: "Filter by status: `draft`, `pending`, `processing`, `issued`, `pending_cancel`, `canceling`, `canceled` or `error`." required: false name: status in: query - schema: type: string enum: - with - without description: "Filter by invoice presence: `with` (with invoice only) or `without` (one-off only)." required: false name: invoice_filter in: query - schema: type: - integer - "null" description: Filter by NF-e number. required: false name: nfe_number in: query - schema: type: string description: Filter by NF-e series. required: false name: nfe_series in: query - schema: type: string description: Filter by NF-e access key. required: false name: nfe_key in: query - schema: type: string description: Filter by NF-e external identifier. required: false name: external_id in: query - schema: type: string description: Filter by LC 116 code. required: false name: lc116_code in: query - schema: type: string description: Filter by municipal service code. required: false name: service_code in: query - schema: type: - number - "null" minimum: 0 description: Minimum NF-e amount in BRL (filters `amount`). example: 100 required: false name: amount_min in: query - schema: type: - number - "null" minimum: 0 description: Maximum NF-e amount in BRL (filters `amount`). example: 100 required: false name: amount_max in: query - schema: type: string format: date description: Start of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_after in: query - schema: type: string format: date description: End of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_before in: query - schema: type: string format: date description: Filter by start `issue_date` (inclusive, YYYY-MM-DD format). example: 2026-01-15 required: false name: issue_date_from in: query - schema: type: string format: date description: Filter by end `issue_date` (inclusive, YYYY-MM-DD format). example: 2026-01-15 required: false name: issue_date_to in: query - schema: type: string format: date description: Filter by start `cancelled_at` (inclusive, YYYY-MM-DD format). example: 2026-01-15 required: false name: cancelled_after in: query - schema: type: string format: date description: Filter by end `cancelled_at` (inclusive, YYYY-MM-DD format). example: 2026-01-15 required: false name: cancelled_before in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of NF-e. content: application/json: schema: $ref: "#/components/schemas/NfeListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-nfes post: tags: - NF-e summary: Create draft NF-e description: Creates a draft (`draft`) NF-e for later issuance via `POST /nfes/{id}/issue`. Accepts taker data (`customer`) and optional tax rates. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/NfeCreateRequest" responses: "201": description: Draft NF-e created. content: application/json: schema: $ref: "#/components/schemas/NfeResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-nfes parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - NF-e summary: Upsert NFe description: "Takes the same body as POST, plus `id` and `public_id`, and dedups on `id`, `public_id`, `external_id` and the resource's natural keys, in that order, stopping at the first key that finds a record. A match is updated and returns 200; otherwise the record is created and returns 201. The POST's required fields are required only when no record is found, and updates are partial: absent fields keep their stored value." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/NfeUpsertRequest" responses: "200": description: Record updated. content: application/json: schema: $ref: "#/components/schemas/NfeUpsertResponse" "201": description: Record created. content: application/json: schema: $ref: "#/components/schemas/NfeUpsertResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-nfes parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/nfes/sync: post: tags: - NF-e summary: Sync organization NF-e description: Triggers a background job to sync every organization NF-e with the provider (updates status, downloads pending PDFs/XMLs). Returns the `job_id` for polling. Refuses if a sync is already running. security: - bearerAuth: [] responses: "201": description: Sync queued. content: application/json: schema: $ref: "#/components/schemas/NfeSyncOrgResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-nfes-sync parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/nfes/bulk: post: tags: - NF-e summary: Bulk update NF-e description: Updates multiple NF-e at once. Currently supports linking or unlinking an invoice (`invoice_id`) on up to 100 NF-e per request. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/NfeBulkUpdateRequest" responses: "200": description: Number of NF-e updated. content: application/json: schema: $ref: "#/components/schemas/NfeBulkUpdateResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-nfes-bulk parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/nfes/bulk-delete: post: tags: - NF-e summary: Bulk delete NF-e description: Deletes up to 100 NF-e at once. All must be in `draft` status and belong to the current organization. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/NfeBulkDeleteRequest" responses: "200": description: Number of NF-e deleted. content: application/json: schema: $ref: "#/components/schemas/NfeBulkDeleteResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-nfes-bulk-delete parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/nfes/request-tries: get: tags: - NF-e summary: List request retries (organization) description: Lists every NF-e provider request attempt for the organization, paginated and ordered by descending date. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of attempts. content: application/json: schema: $ref: "#/components/schemas/NfeRequestTryPaginatedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-nfes-request-tries /v1/nfes/fetch-from-sefaz: post: tags: - NF-e summary: Fetch NFS-e from ADN (SEFAZ) description: Fetches an NFS-e from the Ambiente de Dados Nacional (ADN) using a 50-digit access key and a previously registered digital certificate (mTLS authentication). security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/NfeFetchFromSefazRequest" responses: "200": description: ADN fetch result. content: application/json: schema: $ref: "#/components/schemas/NfeFetchFromSefazResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-nfes-fetch-from-sefaz parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/nfes/fetch-barueri: post: tags: - NF-e summary: Fetch NFS-e from Barueri description: Fetches an NFS-e from the Barueri municipal endpoint using the `codigo_autenticidade` printed on the DANFSE and the taker's CPF/CNPJ. Returns the raw XML and, when found, the NF-e already present in the organization. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/NfeFetchBarueriRequest" responses: "200": description: Fetch result with XML and reference to the existing NF-e, when present. content: application/json: schema: $ref: "#/components/schemas/NfeFetchBarueriResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-nfes-fetch-barueri parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/nfes/import-barueri: post: tags: - NF-e summary: Import Barueri NFS-e description: Imports a Barueri NFS-e into the database. Accepts a raw XML (returned by `POST /nfes/fetch-barueri`) or the `codigo_autenticidade` + `cnpj_tomador` to re-fetch before importing. Creates the taker `BillingAccount` when it does not yet exist. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/NfeImportBarueriRequest" responses: "200": description: Import result with `created`/`updated` flags and the persisted NF-e. content: application/json: schema: $ref: "#/components/schemas/NfeImportBarueriResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-nfes-import-barueri parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/nfes/{id}: get: tags: - NF-e summary: Get NF-e security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: NF-e UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: NF-e detail. content: application/json: schema: $ref: "#/components/schemas/NfeResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-nfes-id patch: tags: - NF-e summary: Update draft NF-e description: Updates NF-e fields. Only `draft` NF-e accept changes to amounts and fiscal codes. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: NF-e UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/NfeUpdateRequest" responses: "200": description: NF-e updated. content: application/json: schema: $ref: "#/components/schemas/NfeResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-nfes-id delete: tags: - NF-e summary: Delete NF-e description: Deletes an NF-e. Allowed only for `draft`, `pending`, `processing`, `error` or `canceled` statuses. `issued` NF-e must be canceled via `POST /nfes/{id}/cancel`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: NF-e UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: NF-e deleted. content: application/json: schema: $ref: "#/components/schemas/NfeDeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-nfes-id /v1/nfes/{id}/issue: post: tags: - NF-e summary: Issue NF-e description: Issues a draft (`draft`) NF-e or retries one in `pending`/`error`. Sends the request to the provider configured for the organization. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: NF-e UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: NF-e queued/issued. content: application/json: schema: $ref: "#/components/schemas/NfeResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-nfes-id-issue /v1/nfes/{id}/cancel: post: tags: - NF-e summary: Cancel NF-e description: Cancels an issued NF-e. Enqueues the cancellation asynchronously with the provider. The `reason` must be at least 15 characters and is recorded in the audit log. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: NF-e UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/NfeCancelRequest" responses: "200": description: Cancellation queued. content: application/json: schema: $ref: "#/components/schemas/NfeResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-nfes-id-cancel /v1/nfes/{id}/retry-cancel: post: tags: - NF-e summary: Retry NF-e cancellation description: Retries cancellation of an NF-e stuck in `pending_cancel`, `canceling` or `error`. Re-enqueues the cancellation job. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: NF-e UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Cancellation retry queued. content: application/json: schema: $ref: "#/components/schemas/NfeResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-nfes-id-retry-cancel /v1/nfes/{id}/sync: post: tags: - NF-e summary: Sync NF-e PDF/XML description: Downloads the NF-e PDF and XML from the provider and stores them in the database. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: NF-e UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: PDF/XML synced. content: application/json: schema: $ref: "#/components/schemas/NfeResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-nfes-id-sync /v1/nfes/{id}/pdf: get: tags: - NF-e summary: Download NF-e PDF description: Downloads the NF-e PDF (DANFE) as a binary attachment (`application/pdf`). Served from the database when available; otherwise fetched from the provider. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: NF-e UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: NF-e PDF. content: application/pdf: schema: type: string format: binary "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-nfes-id-pdf /v1/nfes/{id}/xml: get: tags: - NF-e summary: Download NF-e XML description: Downloads the NF-e XML as a binary attachment (`application/xml`). Served from the database when available; otherwise fetched from the provider. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: NF-e UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: NF-e XML. content: application/xml: schema: type: string format: binary "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-nfes-id-xml /v1/nfes/{id}/request-tries: get: tags: - NF-e summary: List NF-e request retries description: Lists the attempts (`NfeRequestTry`) made to the provider for this NF-e — one entry per call, with endpoint, HTTP status, duration and error messages. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: NF-e UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: List of attempts. content: application/json: schema: $ref: "#/components/schemas/NfeRequestTryListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-nfes-id-request-tries /v1/nfes/{id}/requests: get: tags: - NF-e summary: List NF-e external requests description: Lists captured HTTP requests for this NF-e (provider calls and incoming webhooks), paginated. Use `direction` to filter between `outbound` and `inbound`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: NF-e UUID. required: true name: id in: path - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - outbound - inbound description: "Filter requests by direction: `outbound` (outgoing calls) or `inbound` (incoming webhooks)." required: false name: direction in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of requests. content: application/json: schema: $ref: "#/components/schemas/NfeExternalRequestListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-nfes-id-requests /v1/nfes/{id}/requests/{request_id}: get: tags: - NF-e summary: Get external request security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: NF-e UUID. required: true name: id in: path - schema: type: string format: uuid description: External request UUID. required: true name: request_id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: External request detail, including headers and bodies. content: application/json: schema: $ref: "#/components/schemas/NfeExternalRequestResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-nfes-id-requests-request-id /v1/nfes/{id}/validate-barueri: post: tags: - NF-e summary: Validate Barueri NFS-e description: Re-fetches the NFS-e from the Barueri municipality and compares it to the local record, returning the diff list and the fresh XML for reapplication via `POST /nfes/import-barueri`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: NF-e UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Validation result with differences and current XML. content: application/json: schema: $ref: "#/components/schemas/NfeValidateBarueriResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-nfes-id-validate-barueri /v1/proposals: get: tags: - Proposals summary: List proposals description: Returns a paginated list of the current organization's commercial proposals. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Filter by associated person UUID. required: false name: person_id in: query - schema: type: string description: Filter by person CPF/CNPJ (exact match). required: false name: person_document_number in: query - schema: type: string description: Filter by person name (partial search, case-insensitive). required: false name: person_name_contains in: query - schema: type: string enum: - draft - sent - viewed - accepted - rejected - expired - canceled description: "Filter by status: `draft`, `sent`, `viewed`, `accepted`, `rejected`, `expired` or `canceled`." required: false name: status in: query - schema: type: string format: uuid description: Filter by linked `billing_account_id`. required: false name: billing_account_id in: query - schema: type: string format: uuid description: Filter by `prospect_id`. required: false name: prospect_id in: query - schema: type: string format: uuid description: Filter by linked `contact_id`. required: false name: contact_id in: query - schema: type: string format: uuid description: Filter by applied `coupon_id`. required: false name: coupon_id in: query - schema: type: string format: uuid description: Filter by issuing `company_id`. required: false name: company_id in: query - schema: type: string format: uuid description: Filter by `template_id` used to generate the PDF. required: false name: template_id in: query - schema: type: string description: "Filter by proposal short code (e.g.: `PROP-0001`)." required: false name: code in: query - schema: type: string description: Filter by external identifier. required: false name: external_id in: query - schema: type: string description: Free-text search. required: false name: search in: query - schema: type: string format: date description: Start of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_after in: query - schema: type: string format: date description: End of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_before in: query - schema: type: string format: date description: Filter by start `expires_at` (ISO 8601, inclusive). example: 2026-01-15 required: false name: expires_after in: query - schema: type: string format: date description: Filter by end `expires_at` (ISO 8601, inclusive). example: 2026-01-15 required: false name: expires_before in: query - schema: type: string format: date description: Filter by start `accepted_at` (ISO 8601, inclusive). example: 2026-01-15 required: false name: accepted_after in: query - schema: type: string format: date description: Filter by end `accepted_at` (ISO 8601, inclusive). example: 2026-01-15 required: false name: accepted_before in: query - schema: type: string format: date description: Filter by start `sent_at` (ISO 8601, inclusive). example: 2026-01-15 required: false name: sent_after in: query - schema: type: string format: date description: Filter by end `sent_at` (ISO 8601, inclusive). example: 2026-01-15 required: false name: sent_before in: query - schema: type: string format: date description: Filter by start `viewed_at` (ISO 8601, inclusive). example: 2026-01-15 required: false name: viewed_after in: query - schema: type: string format: date description: Filter by end `viewed_at` (ISO 8601, inclusive). example: 2026-01-15 required: false name: viewed_before in: query - schema: type: string format: date description: Filter by start `rejected_at` (ISO 8601, inclusive). example: 2026-01-15 required: false name: rejected_after in: query - schema: type: string format: date description: Filter by end `rejected_at` (ISO 8601, inclusive). example: 2026-01-15 required: false name: rejected_before in: query - schema: type: - number - "null" minimum: 0 description: Filter by minimum `setup_amount` (in BRL). example: 100 required: false name: setup_amount_min in: query - schema: type: - number - "null" minimum: 0 description: Filter by maximum `setup_amount` (in BRL). example: 100 required: false name: setup_amount_max in: query - schema: type: - number - "null" minimum: 0 description: Filter by minimum `monthly_amount` (in BRL). example: 100 required: false name: monthly_amount_min in: query - schema: type: - number - "null" minimum: 0 description: Filter by maximum `monthly_amount` (in BRL). example: 100 required: false name: monthly_amount_max in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of proposals. content: application/json: schema: $ref: "#/components/schemas/ProposalListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-proposals post: tags: - Proposals summary: Create proposal description: Creates a commercial proposal. You must provide `billing_account_id`, `prospect_id` or `prospect_data` (inline prospect creation). security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProposalCreateRequest" responses: "201": description: Proposal created. content: application/json: schema: $ref: "#/components/schemas/ProposalResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposals parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Proposals summary: Upsert proposal description: "Takes the same body as POST, plus `id` and `public_id`, and dedups on `id`, `public_id`, `external_id` and the resource's natural keys, in that order, stopping at the first key that finds a record. A match is updated and returns 200; otherwise the record is created and returns 201. The POST's required fields are required only when no record is found, and updates are partial: absent fields keep their stored value." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProposalUpsertRequest" responses: "200": description: Record updated. content: application/json: schema: $ref: "#/components/schemas/ProposalUpsertResponse" "201": description: Record created. content: application/json: schema: $ref: "#/components/schemas/ProposalUpsertResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-proposals parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/proposals/stats: get: tags: - Proposals summary: Get proposal statistics description: Returns proposal counts by status (`draft`, `sent`, `viewed`, `accepted`, `rejected`, `expired`, `canceled`) for the current organization. security: - bearerAuth: [] responses: "200": description: Proposal statistics. content: application/json: schema: $ref: "#/components/schemas/ProposalStatsResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-proposals-stats parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/proposals/bulk-cancel: post: tags: - Proposals summary: Bulk cancel proposals description: Cancels multiple proposals at once (up to 100). Returns success/failure counts and errors per id. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProposalBulkRequest" responses: "200": description: Bulk cancel result. content: application/json: schema: $ref: "#/components/schemas/ProposalBulkResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposals-bulk-cancel parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/proposals/bulk-delete: post: tags: - Proposals summary: Bulk delete proposals description: Deletes multiple proposals at once (up to 100). Returns success/failure counts and errors per id. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProposalBulkRequest" responses: "200": description: Bulk delete result. content: application/json: schema: $ref: "#/components/schemas/ProposalBulkResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposals-bulk-delete parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/proposals/bulk-send: post: tags: - Proposals summary: Bulk send proposals description: Sends multiple proposals at once (up to 100). Returns success/failure counts and errors per id. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProposalBulkRequest" responses: "200": description: Bulk send result. content: application/json: schema: $ref: "#/components/schemas/ProposalBulkResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposals-bulk-send parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/proposals/{id}: get: tags: - Proposals summary: Get proposal security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Proposal detail. content: application/json: schema: $ref: "#/components/schemas/ProposalResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-proposals-id patch: tags: - Proposals summary: Update proposal security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/ProposalUpdateRequest" responses: "200": description: Proposal updated. content: application/json: schema: $ref: "#/components/schemas/ProposalResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-proposals-id delete: tags: - Proposals summary: Delete proposal security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Proposal deleted. content: application/json: schema: $ref: "#/components/schemas/ProposalDeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-proposals-id /v1/proposals/{id}/accept: post: tags: - Proposals summary: Accept proposal description: Accepts the proposal and creates (or confirms) the corresponding subscription using the given cycle. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/ProposalAcceptRequest" responses: "200": description: Proposal accepted — returns the proposal, `subscription_id` and `invoice_id` when applicable. content: application/json: schema: $ref: "#/components/schemas/ProposalAcceptResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposals-id-accept /v1/proposals/{id}/cancel: post: tags: - Proposals summary: Cancel proposal description: Cancels the proposal (`status → canceled`). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Proposal canceled. content: application/json: schema: $ref: "#/components/schemas/ProposalResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposals-id-cancel /v1/proposals/{id}/duplicate: post: tags: - Proposals summary: Duplicate proposal description: Creates a new proposal from the original (as draft), preserving items and configuration. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "201": description: Proposal duplicated. content: application/json: schema: $ref: "#/components/schemas/ProposalResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposals-id-duplicate /v1/proposals/{id}/send: post: tags: - Proposals summary: Send proposal email description: "Sends (or resends) the proposal email to the recipient. Allowed statuses: `draft`, `sent` or `viewed`. Optionally customize `subject` and `message` (HTML)." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/ProposalSendRequest" responses: "200": description: Proposal sent. content: application/json: schema: $ref: "#/components/schemas/ProposalResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposals-id-send /v1/proposals/{id}/publish: post: tags: - Proposals summary: Publish proposal description: Publishes the proposal (`draft → sent`) without sending the email, making it available on the portal. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Proposal published. content: application/json: schema: $ref: "#/components/schemas/ProposalResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposals-id-publish /v1/proposals/{id}/unpublish: post: tags: - Proposals summary: Unpublish proposal description: Reverts the proposal to draft (`sent`/`viewed` → `draft`). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Proposal unpublished. content: application/json: schema: $ref: "#/components/schemas/ProposalResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposals-id-unpublish /v1/proposals/{id}/undo-accept: post: tags: - Proposals summary: Undo proposal acceptance description: "Reverts the acceptance: removes the linked subscription and returns status to `sent`." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Acceptance undone. content: application/json: schema: $ref: "#/components/schemas/ProposalResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposals-id-undo-accept /v1/proposals/{id}/generate-pdf: post: tags: - Proposals summary: Generate proposal PDF description: Generates (or regenerates) the proposal PDF via Google App Scripts. Requires a `template` with `app_script_url` configured. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: PDF generated — returns the updated proposal and document/PDF URLs. content: application/json: schema: $ref: "#/components/schemas/ProposalGeneratePdfResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposals-id-generate-pdf /v1/proposals/{id}/json: get: tags: - Proposals summary: Get proposal JSON snapshot description: Returns the full data snapshot used to render the PDF template (mirrors what AppScript receives). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Proposal JSON snapshot. content: application/json: schema: $ref: "#/components/schemas/ProposalJsonResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-proposals-id-json /v1/proposals/{id}/pricing: get: tags: - Proposals summary: Get proposal pricing breakdown description: Returns the pricing breakdown per billing cycle (monthly, quarterly, semiannual, annual), with setup and discounts applied. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Pricing breakdown. content: application/json: schema: $ref: "#/components/schemas/ProposalPricingResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-proposals-id-pricing /v1/proposals/{id}/items: get: tags: - Proposals summary: List proposal items security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: List of items. content: application/json: schema: $ref: "#/components/schemas/ProposalItemsListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-proposals-id-items post: tags: - Proposals summary: Add item to proposal security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/ProposalItemCreateRequest" responses: "201": description: Item created. content: application/json: schema: $ref: "#/components/schemas/ProposalItemResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposals-id-items /v1/proposals/{id}/items/{item_id}: get: tags: - Proposals summary: Get proposal item security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - schema: type: string format: uuid description: Proposal item UUID. required: true name: item_id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Item detail. content: application/json: schema: $ref: "#/components/schemas/ProposalItemResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-proposals-id-items-item-id patch: tags: - Proposals summary: Update proposal item description: Updates an item. Only allowed on draft (`status = draft`) proposals. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - schema: type: string format: uuid description: Proposal item UUID. required: true name: item_id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/ProposalItemUpdateRequest" responses: "200": description: Item updated. content: application/json: schema: $ref: "#/components/schemas/ProposalItemResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-proposals-id-items-item-id delete: tags: - Proposals summary: Delete proposal item description: Removes an item. Only allowed on draft (`status = draft`) proposals. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - schema: type: string format: uuid description: Proposal item UUID. required: true name: item_id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Item deleted. content: application/json: schema: $ref: "#/components/schemas/ProposalDeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-proposals-id-items-item-id /v1/proposal_templates: get: tags: - Proposal Templates summary: List proposal templates description: Returns a paginated list of the current organization's proposal templates. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string description: Text search by name or description. required: false name: search in: query - schema: type: boolean description: Filter by active (`true`) or deactivated (`false`) templates. required: false name: is_active in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of proposal templates. content: application/json: schema: $ref: "#/components/schemas/ProposalTemplateListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-proposal-templates post: tags: - Proposal Templates summary: Create proposal template description: Creates a proposal template linked to a Google Doc or Google Slides. The `google_doc_id` must be unique per organization. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProposalTemplateCreateRequest" responses: "201": description: Proposal template created. content: application/json: schema: $ref: "#/components/schemas/ProposalTemplateResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposal-templates parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Proposal Templates summary: Upsert proposal template description: "Takes the same body as POST, plus `id` and `public_id`, and dedups on `id`, `public_id`, `external_id` and the resource's natural keys, in that order, stopping at the first key that finds a record. A match is updated and returns 200; otherwise the record is created and returns 201. The POST's required fields are required only when no record is found, and updates are partial: absent fields keep their stored value." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProposalTemplateUpsertRequest" responses: "200": description: Record updated. content: application/json: schema: $ref: "#/components/schemas/ProposalTemplateUpsertResponse" "201": description: Record created. content: application/json: schema: $ref: "#/components/schemas/ProposalTemplateUpsertResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-proposal-templates parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/proposal_templates/{id}: get: tags: - Proposal Templates summary: Get proposal template security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal template UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Proposal template detail. content: application/json: schema: $ref: "#/components/schemas/ProposalTemplateResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-proposal-templates-id patch: tags: - Proposal Templates summary: Update proposal template security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal template UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/ProposalTemplateUpdateRequest" responses: "200": description: Proposal template updated. content: application/json: schema: $ref: "#/components/schemas/ProposalTemplateResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-proposal-templates-id delete: tags: - Proposal Templates summary: Delete proposal template security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal template UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Proposal template removed. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-proposal-templates-id /v1/proposal_templates/{id}/activate: post: tags: - Proposal Templates summary: Activate proposal template description: Activates a previously deactivated proposal template, making it available for use in new proposals. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal template UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Proposal template activated. content: application/json: schema: $ref: "#/components/schemas/ProposalTemplateResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposal-templates-id-activate /v1/proposal_templates/{id}/deactivate: post: tags: - Proposal Templates summary: Deactivate proposal template description: Deactivates a proposal template. Deactivated templates cannot be used in new proposals, but proposals already created remain unchanged. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal template UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Proposal template deactivated. content: application/json: schema: $ref: "#/components/schemas/ProposalTemplateResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposal-templates-id-deactivate /v1/proposal_templates/{id}/duplicate: post: tags: - Proposal Templates summary: Duplicate proposal template description: Creates a copy of the given template, keeping configuration and metadata. The new template gets a derived name. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal template UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "201": description: Proposal template duplicated. content: application/json: schema: $ref: "#/components/schemas/ProposalTemplateResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposal-templates-id-duplicate /v1/plan_changes: get: tags: - Plan Changes summary: List plan changes description: Returns the paginated history of plan changes (upgrades, downgrades and lateral) for the current organization. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Filter by associated person UUID. required: false name: person_id in: query - schema: type: string description: Filter by person CPF/CNPJ (exact match). required: false name: person_document_number in: query - schema: type: string description: Filter by person name (partial search, case-insensitive). required: false name: person_name_contains in: query - schema: type: string format: uuid description: Filter by changes of a subscription. required: false name: subscription_id in: query - schema: type: string format: uuid description: Filter by changes of a billing account. required: false name: billing_account_id in: query - schema: type: string format: uuid description: Filter by source plan (UUID). required: false name: from_plan_id in: query - schema: type: string format: uuid description: Filter by target plan (UUID). required: false name: to_plan_id in: query - schema: type: string enum: - upgrade - downgrade - lateral description: "Filter by type: `upgrade`, `downgrade` or `lateral`." required: false name: change_type in: query - schema: type: string enum: - pending - scheduled - completed - canceled - failed description: "Filter by status: `pending`, `scheduled`, `completed`, `canceled` or `failed`." required: false name: status in: query - schema: type: string enum: - immediate - end_of_period description: "Filter by timing: `immediate` or `end_of_period`." required: false name: timing in: query - schema: type: string description: Filter by proration method (e.g. `full_proration`, `no_proration`, `partial_proration`). required: false name: proration_method in: query - schema: type: - number - "null" minimum: 0 description: Minimum price difference in R$ (sub-cents ÷10000). E.g. `10.50`. example: 100 required: false name: price_difference_min in: query - schema: type: - number - "null" minimum: 0 description: Maximum price difference in R$ (sub-cents ÷10000). E.g. `500.00`. example: 100 required: false name: price_difference_max in: query - schema: type: - number - "null" minimum: 0 description: Minimum proration charge in R$ (sub-cents ÷10000). example: 100 required: false name: proration_charge_min in: query - schema: type: - number - "null" minimum: 0 description: Maximum proration charge in R$ (sub-cents ÷10000). example: 100 required: false name: proration_charge_max in: query - schema: type: - number - "null" minimum: 0 description: Minimum proration credit in R$ (sub-cents ÷10000). example: 100 required: false name: proration_credit_min in: query - schema: type: - number - "null" minimum: 0 description: Maximum proration credit in R$ (sub-cents ÷10000). example: 100 required: false name: proration_credit_max in: query - schema: type: string format: date description: "Effective date from (inclusive). Format: `YYYY-MM-DD`." example: 2026-01-15 required: false name: effective_date_from in: query - schema: type: string format: date description: "Effective date to (inclusive). Format: `YYYY-MM-DD`." example: 2026-01-15 required: false name: effective_date_to in: query - schema: type: string format: date description: "Scheduled date from (inclusive). Format: `YYYY-MM-DD`." example: 2026-01-15 required: false name: scheduled_date_from in: query - schema: type: string format: date description: "Scheduled date to (inclusive). Format: `YYYY-MM-DD`." example: 2026-01-15 required: false name: scheduled_date_to in: query - schema: type: string format: date description: "Completed from (inclusive). Format: `YYYY-MM-DD`." example: 2026-01-15 required: false name: completed_after in: query - schema: type: string format: date description: "Completed to (inclusive). Format: `YYYY-MM-DD`." example: 2026-01-15 required: false name: completed_before in: query - schema: type: string format: date description: Start of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_after in: query - schema: type: string format: date description: End of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_before in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of plan changes. content: application/json: schema: $ref: "#/components/schemas/PlanChangeListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-plan-changes post: tags: - Plan Changes summary: Execute plan change description: Executes a plan change for an existing subscription. `timing` controls whether the change applies immediately (with proration) or at the end of the current period. On success, returns the UUIDs of the `plan_change`, the proration invoice (if any) and the generated credit (if any). security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanChangeExecuteRequest" responses: "201": description: Plan change executed. content: application/json: schema: $ref: "#/components/schemas/PlanChangeExecuteResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-plan-changes parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/plan_changes/stats: get: tags: - Plan Changes summary: Plan change stats description: Returns plan change aggregates (totals by type, by status, proration credits and charges) for a window in days. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Window in days for the aggregates (default: `30`)." example: 30 required: false name: days in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Aggregated plan change stats. content: application/json: schema: $ref: "#/components/schemas/PlanChangeStatsResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-plan-changes-stats /v1/plan_changes/config: get: tags: - Plan Changes summary: Get plan change config description: Returns the organization's default configuration for upgrades and downgrades — proration behavior, timing and credit/refund generation. security: - bearerAuth: [] responses: "200": description: Current configuration. content: application/json: schema: $ref: "#/components/schemas/PlanChangeConfigResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-plan-changes-config parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier patch: tags: - Plan Changes summary: Update plan change config description: Partially updates (PATCH) the organization's plan change configuration. All fields are optional. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanChangeConfigUpdateRequest" responses: "200": description: Configuration updated. content: application/json: schema: $ref: "#/components/schemas/PlanChangeConfigResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-plan-changes-config parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/plan_changes/rules: get: tags: - Plan Changes summary: List plan change rules description: Lists custom rules that override the default behavior for specific plan-to-plan transitions. security: - bearerAuth: [] responses: "200": description: List of plan change rules. content: application/json: schema: $ref: "#/components/schemas/PlanChangeRuleListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-plan-changes-rules parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier post: tags: - Plan Changes summary: Create plan change rule description: Creates a new rule for a plan-to-plan transition. Lets you block/allow the transition, set timing, proration, discounts and bonus days. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanChangeRuleCreateRequest" responses: "201": description: Rule created. content: application/json: schema: $ref: "#/components/schemas/PlanChangeRuleResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-plan-changes-rules parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/plan_changes/rules/{id}: get: tags: - Plan Changes summary: Get plan change rule security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan change rule UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Rule detail. content: application/json: schema: $ref: "#/components/schemas/PlanChangeRuleResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-plan-changes-rules-id patch: tags: - Plan Changes summary: Update plan change rule security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan change rule UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanChangeRuleUpdateRequest" responses: "200": description: Rule updated. content: application/json: schema: $ref: "#/components/schemas/PlanChangeRuleResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-plan-changes-rules-id delete: tags: - Plan Changes summary: Delete plan change rule security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan change rule UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Rule removed. content: application/json: schema: $ref: "#/components/schemas/PlanChangeRuleDeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-plan-changes-rules-id /v1/plan_changes/{id}: get: tags: - Plan Changes summary: Get plan change security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan change UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Plan change detail. content: application/json: schema: $ref: "#/components/schemas/PlanChangeResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-plan-changes-id /v1/subscription_changes/config: get: tags: - Subscription Changes summary: Get subscription change settings description: Returns the organization settings for subscription item changes — allowed operations (add/remove/quantity change/price swap), proration method per operation, timing (`immediate` or `end_of_period`), refund/credit on remove and portal self-service. If not yet present, defaults are created on first read. security: - bearerAuth: [] responses: "200": description: Organization settings. content: application/json: schema: $ref: "#/components/schemas/SubscriptionChangeConfigResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-subscription-changes-config parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Subscription Changes summary: Update subscription change settings description: Partially updates the settings. Only supplied fields are changed. `refund_on_remove` requires `credit_on_remove` to also be enabled — refund is a variant of credit. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/SubscriptionChangeConfigUpdateRequest" responses: "200": description: Settings updated. content: application/json: schema: $ref: "#/components/schemas/SubscriptionChangeConfigResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-subscription-changes-config parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/subscription_item_changes: get: tags: - Subscription Changes summary: List subscription item changes description: Returns a paginated list of changes applied (or scheduled) to the organization's subscription items — additions, removals, quantity changes and price swaps. Each record includes the operations snapshot, proration amounts in BRL (float, up to 4 decimal places) and pointers to the resulting invoice/credit. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Filter by associated person UUID. required: false name: person_id in: query - schema: type: string description: Filter by person CPF/CNPJ (exact match). required: false name: person_document_number in: query - schema: type: string description: Filter by person name (partial search, case-insensitive). required: false name: person_name_contains in: query - schema: type: string format: uuid description: Filter by changes of a specific subscription. required: false name: subscription_id in: query - schema: type: string format: uuid description: Filter by changes of a specific billing account. required: false name: billing_account_id in: query - schema: type: string enum: - pending - scheduled - completed - canceled - failed description: "Filter by status: `pending`, `scheduled`, `completed`, `canceled` or `failed`." required: false name: status in: query - schema: type: string enum: - immediate - end_of_period description: "Filter by the timing of the change application: `immediate` or `end_of_period`." required: false name: timing in: query - schema: type: string enum: - dashboard - portal - api description: "Filter by the origin of the change: `dashboard`, `portal` or `api`." required: false name: initiated_by_role in: query - schema: type: - number - "null" minimum: 0 description: Minimum proration charge amount in BRL (R$). Internally stored in BRL (float, up to 4 decimal places). example: 100 required: false name: proration_charge_min in: query - schema: type: - number - "null" minimum: 0 description: Maximum proration charge amount in BRL (R$). Internally stored in BRL (float, up to 4 decimal places). example: 100 required: false name: proration_charge_max in: query - schema: type: - number - "null" minimum: 0 description: Minimum proration credit amount in BRL (R$). Internally stored in BRL (float, up to 4 decimal places). example: 100 required: false name: proration_credit_min in: query - schema: type: - number - "null" minimum: 0 description: Maximum proration credit amount in BRL (R$). Internally stored in BRL (float, up to 4 decimal places). example: 100 required: false name: proration_credit_max in: query - schema: type: string format: date description: Minimum effective date of the change (inclusive), in `YYYY-MM-DD` format. example: 2026-01-15 required: false name: effective_date_from in: query - schema: type: string format: date description: Maximum effective date of the change (inclusive), in `YYYY-MM-DD` format. example: 2026-01-15 required: false name: effective_date_to in: query - schema: type: string format: date description: Start of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_after in: query - schema: type: string format: date description: End of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_before in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of item changes. content: application/json: schema: $ref: "#/components/schemas/SubscriptionItemChangeListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-subscription-item-changes /v1/subscription_item_changes/{id}: get: tags: - Subscription Changes summary: Get subscription item change security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Item change UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Item change detail. content: application/json: schema: $ref: "#/components/schemas/SubscriptionItemChangeResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-subscription-item-changes-id delete: tags: - Subscription Changes summary: Cancel a scheduled change description: Cancels an item change that is still scheduled (`timing=end_of_period`). Changes already applied cannot be canceled. Returns the record with its new status. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Item change UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Change canceled. content: application/json: schema: $ref: "#/components/schemas/SubscriptionItemChangeResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-subscription-item-changes-id /v1/usage: get: tags: - Usage (Metered) summary: List usage records description: Returns metered usage records for a subscription item. Identify the item by `subscription_item_id` **or** by the `product_slug` + `customer_id` combination. Supports date-range filtering and `limit`/`offset` windowing. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription item UUID. Alternative to `product_slug` + `customer_id`. required: false name: subscription_item_id in: query - schema: type: string description: Product slug. Combine with `customer_id`. required: false name: product_slug in: query - schema: type: string description: Customer external identifier. Combine with `product_slug`. required: false name: customer_id in: query - schema: type: string description: Filter start date/time — ISO 8601 format. required: false name: start_date in: query - schema: type: string description: Filter end date/time — ISO 8601 format. required: false name: end_date in: query - schema: type: integer minimum: 1 maximum: 1000 description: "Items per page. Default: `100`. Maximum: `1000`." required: false name: limit in: query - schema: type: - integer - "null" minimum: 0 description: "Pagination offset. Default: `0`." required: false name: offset in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Usage records list with `total_quantity` aggregation in `meta`. content: application/json: schema: $ref: "#/components/schemas/UsageListResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-usage post: tags: - Usage (Metered) summary: Report usage (metered) description: "Reports usage for metered billing. Accepts a single record **or** a `{ records: [...] }` batch of up to **100** items. Each record must identify the subscription item by `subscription_item_id` **or** by `product_slug` + `customer_id` (recommended for external integrations). The price/product must be configured with `usage_type=metered` and the subscription must be `active` or `trialing`. Use `idempotency_key` to avoid duplicates — when a key was already seen the response is flagged with `duplicate: true`. Batches with partial failures return **207 Multi-Status**." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/UsageRecordCreateRequest" responses: "200": description: Processing result (single record or batch). content: application/json: schema: $ref: "#/components/schemas/UsageRecordCreateResponse" "207": description: Processing result (single record or batch). content: application/json: schema: $ref: "#/components/schemas/UsageRecordCreateResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-usage parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/usage/summary: get: tags: - Usage (Metered) summary: Usage summary for the period description: Returns the aggregated usage of a subscription item for the current billing period (or for an arbitrary period via `period_start`/`period_end`). Honors `set` records (which replace) and the sum of subsequent `increment` records. When the price is tiered or per-unit, computes an estimated cost in `estimated_cost` (float, up to 4 decimal places). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription item UUID. Alternative to `product_slug` + `customer_id`. required: false name: subscription_item_id in: query - schema: type: string description: Product slug. Combine with `customer_id`. required: false name: product_slug in: query - schema: type: string description: Customer external identifier. Combine with `product_slug`. required: false name: customer_id in: query - schema: type: string description: "Period start (ISO 8601). Default: subscription `current_period_start`." required: false name: period_start in: query - schema: type: string description: "Period end (ISO 8601). Default: subscription `current_period_end`." required: false name: period_end in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Usage summary, period and estimated cost. content: application/json: schema: $ref: "#/components/schemas/UsageSummaryResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-usage-summary /v1/usage/snapshots/daily: get: tags: - Usage (Metered) summary: List daily usage snapshots description: "Lists the organization's daily usage snapshots. Optional filters: `billing_account_id`, `product_id` and `start_date`/`end_date` window. Supports `limit`/`offset` pagination." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Filter snapshots by billing account UUID. required: false name: billing_account_id in: query - schema: type: string format: uuid description: Filter snapshots by product UUID. required: false name: product_id in: query - schema: type: string description: Filter start date/time — ISO 8601 format. required: false name: start_date in: query - schema: type: string description: Filter end date/time — ISO 8601 format. required: false name: end_date in: query - schema: type: integer minimum: 1 maximum: 1000 description: "Items per page. Default: `100`. Maximum: `1000`." required: false name: limit in: query - schema: type: - integer - "null" minimum: 0 description: "Pagination offset. Default: `0`." required: false name: offset in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Daily snapshots list with `meta` carrying `total`, `limit`, `offset`. content: application/json: schema: $ref: "#/components/schemas/UsageDailySnapshotListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-usage-snapshots-daily post: tags: - Usage (Metered) summary: Create daily usage snapshots description: "Creates daily usage snapshots, single record **or** `{ records: [...] }` batch up to **100** items. The natural key (organization, billing account, product, date) is unique: when present, the snapshot is overwritten (`overwritten: true`). Resolve the account by `billing_account_id` **or** `billing_account_public_id` and the product by `product_slug` **or** `product_id` within the supplied `product_group_slug`. Batches with partial failures return **207 Multi-Status**." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/UsageDailySnapshotCreateRequest" responses: "200": description: Processing result (single record or batch). content: application/json: schema: $ref: "#/components/schemas/UsageDailySnapshotCreateResponse" "207": description: Processing result (single record or batch). content: application/json: schema: $ref: "#/components/schemas/UsageDailySnapshotCreateResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-usage-snapshots-daily parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/usage/snapshots/monthly: get: tags: - Usage (Metered) summary: List monthly usage snapshots description: "Lists the organization's monthly usage snapshots. Optional filters: `billing_account_id`, `product_id` and `start_month`/`end_month` window. Supports `limit`/`offset` pagination." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Filter snapshots by billing account UUID. required: false name: billing_account_id in: query - schema: type: string format: uuid description: Filter snapshots by product UUID. required: false name: product_id in: query - schema: type: string description: Filter start month in `YYYY-MM-DD` format (first day of the month). required: false name: start_month in: query - schema: type: string description: Filter end month in `YYYY-MM-DD` format (first day of the month). required: false name: end_month in: query - schema: type: integer minimum: 1 maximum: 1000 description: "Items per page. Default: `100`. Maximum: `1000`." required: false name: limit in: query - schema: type: - integer - "null" minimum: 0 description: "Pagination offset. Default: `0`." required: false name: offset in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Monthly snapshots list with `meta` carrying `total`, `limit`, `offset`. content: application/json: schema: $ref: "#/components/schemas/UsageMonthlySnapshotListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-usage-snapshots-monthly post: tags: - Usage (Metered) summary: Create monthly usage snapshots description: "Creates monthly usage snapshots, single record **or** `{ records: [...] }` batch up to **100** items. The natural key (organization, billing account, product, month) is unique: when present, the snapshot is overwritten (`overwritten: true`). Resolve the account by `billing_account_id` **or** `billing_account_public_id` and the product by `product_slug` **or** `product_id` within `product_group_slug`. Batches with partial failures return **207 Multi-Status**." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/UsageMonthlySnapshotCreateRequest" responses: "200": description: Processing result (single record or batch). content: application/json: schema: $ref: "#/components/schemas/UsageMonthlySnapshotCreateResponse" "207": description: Processing result (single record or batch). content: application/json: schema: $ref: "#/components/schemas/UsageMonthlySnapshotCreateResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-usage-snapshots-monthly parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/usage/credits/daily: post: tags: - Usage (Metered) summary: Publish daily credit usage description: "Publishes prepaid credit usage (a `credits` product) per billing account × product × day, as a single record **or** a batch `{ records: [...] }` of up to **100** items. The key (account, product, `usage_date`) is unique: publishing the same day again **overwrites** the record (`overwritten: true`), it never adds up. Batches with partial failures return **207 Multi-Status**." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/CreditUsageDailyRequest" responses: "200": description: Records processed (`207` when part of the batch failed). content: application/json: schema: $ref: "#/components/schemas/CreditUsageDailyResponse" "207": description: Records processed (`207` when part of the batch failed). content: application/json: schema: $ref: "#/components/schemas/CreditUsageDailyResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-usage-credits-daily parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/usage/credits: get: tags: - Usage (Metered) summary: Get credit usage and balance description: Returns prepaid credit usage for the period (totals and daily series) and the current balance. Without `billing_account_id`, sums every account in the organization. Without dates, uses the current month (São Paulo time zone). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Filters by billing account. required: false name: billing_account_id in: query - schema: type: string format: uuid description: "Credits product. Default: the first active product." required: false name: product_id in: query - schema: type: string description: Period start (`YYYY-MM-DD`). required: false name: start_date in: query - schema: type: string description: Period end, inclusive (`YYYY-MM-DD`). required: false name: end_date in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Period usage and balance. content: application/json: schema: $ref: "#/components/schemas/CreditUsageReportResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-usage-credits /v1/credit_purchases: post: tags: - Usage (Metered) summary: Buy credits description: "Creates and finalizes a standalone invoice (`billing_reason = credit_purchase`) for a quantity of a `credits` product, independent of any subscription. The balance becomes available once the invoice is paid: the `invoice.paid` webhook carries `line_items[].product_type` and `quantity`." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/CreditPurchaseCreateRequest" responses: "201": description: Purchase invoice, with its line items. content: application/json: schema: $ref: "#/components/schemas/InvoiceResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-credit-purchases parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/tax_rules: get: tags: - Tax Rules summary: List tax rules description: Returns a paginated list of the current organization's tax rules. Use the `scope`, `company_id`, `service_item_id`, `billing_account_id` and `is_active` filters to narrow the result. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - global - organization - company - service - customer - municipality description: "Filter by scope: `global`, `organization`, `company`, `service`, `customer` or `municipality`." required: false name: scope in: query - schema: type: string format: uuid description: Filter by rules of a specific company. required: false name: company_id in: query - schema: type: string format: uuid description: Filter by rules of a specific service item. required: false name: service_item_id in: query - schema: type: string format: uuid description: Filter by rules of a specific billing account. required: false name: billing_account_id in: query - schema: type: string enum: - "true" - "false" description: When `true`, returns only active rules; when `false`, only inactive ones. required: false name: is_active in: query - schema: type: string description: Text search across `name` and `description`. required: false name: search in: query - schema: type: string description: "Filter by customer tax type: `pessoa_fisica`, `pessoa_juridica`, `mei`, `simples_optante` or `entidade_publica`." required: false name: customer_tax_type in: query - schema: type: string description: "Filter by operation type: `interno` (same municipality) or `externo` (different municipality)." required: false name: operation_type in: query - schema: type: string description: Filter by IBGE municipality code (7 digits). required: false name: municipality in: query - schema: type: - integer - "null" description: Minimum priority (inclusive) to filter rules. required: false name: priority_from in: query - schema: type: - integer - "null" description: Maximum priority (inclusive) to filter rules. required: false name: priority_to in: query - schema: type: string format: date description: Returns rules whose effective-from date is on or after this value (ISO 8601). example: 2026-01-15 required: false name: effective_from_from in: query - schema: type: string format: date description: Returns rules whose effective-from date is on or before this value (ISO 8601). example: 2026-01-15 required: false name: effective_from_to in: query - schema: type: string format: date description: Returns rules whose effective-to date is on or after this value (ISO 8601). example: 2026-01-15 required: false name: effective_to_from in: query - schema: type: string format: date description: Returns rules whose effective-to date is on or before this value (ISO 8601). example: 2026-01-15 required: false name: effective_to_to in: query - schema: type: string format: date description: Start of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_after in: query - schema: type: string format: date description: End of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_before in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of tax rules. content: application/json: schema: $ref: "#/components/schemas/TaxRuleListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-tax-rules post: tags: - Tax Rules summary: Create tax rule description: Creates a new tax rule along with its items (per-tax rates). The `scope` defines the applicability level and `priority` defines precedence — higher priority overrides lower. At least one entry in `items` is required. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/TaxRuleCreateRequest" responses: "201": description: Tax rule created. content: application/json: schema: $ref: "#/components/schemas/TaxRuleResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-tax-rules parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Tax Rules summary: Upsert tax rule description: "Takes the same body as POST, plus `id` and `public_id`, and dedups on `id`, `public_id`, `external_id` and the resource's natural keys, in that order, stopping at the first key that finds a record. A match is updated and returns 200; otherwise the record is created and returns 201. The POST's required fields are required only when no record is found, and updates are partial: absent fields keep their stored value." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/TaxRuleUpsertRequest" responses: "200": description: Record updated. content: application/json: schema: $ref: "#/components/schemas/TaxRuleUpsertResponse" "201": description: Record created. content: application/json: schema: $ref: "#/components/schemas/TaxRuleUpsertResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-tax-rules parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/tax_rules/{id}: get: tags: - Tax Rules summary: Get tax rule security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Tax rule UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Tax rule detail. content: application/json: schema: $ref: "#/components/schemas/TaxRuleResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-tax-rules-id patch: tags: - Tax Rules summary: Update tax rule description: Updates editable fields of the rule. When `items` is provided, it **fully replaces** the existing items list. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Tax rule UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/TaxRuleUpdateRequest" responses: "200": description: Tax rule updated. content: application/json: schema: $ref: "#/components/schemas/TaxRuleResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-tax-rules-id delete: tags: - Tax Rules summary: Delete tax rule security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Tax rule UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Tax rule removed. content: application/json: schema: $ref: "#/components/schemas/TaxRuleDeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-tax-rules-id /v1/late_fee_policies: get: tags: - Late Fees summary: List late fee policies description: 'Returns the organization late fee policies. The policy that applies to an invoice is resolved in cascade: invoice → subscription → billing account → organization default. A null level means inherit, never "no charges" — charging nothing is an explicit policy with both modes set to `none`.' security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - "true" - "false" description: Includes soft-deleted policies. required: false name: include_deleted in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of late fee policies. content: application/json: schema: $ref: "#/components/schemas/LateFeePolicyListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-late-fee-policies post: tags: - Late Fees summary: Create a late fee policy description: Creates a policy. Fine and interest above the legal ceilings (2% fine and 1% monthly interest, Brazilian Consumer Code art. 52) are refused unless `enforce_legal_caps` is `false` — which is audited separately, being a legal-risk decision. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/LateFeePolicyCreateRequest" responses: "201": description: Policy created. content: application/json: schema: $ref: "#/components/schemas/LateFeePolicyResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-late-fee-policies parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/late_fee_policies/simulate: post: tags: - Late Fees summary: Simulate late charges description: Computes what an outstanding balance owes in fine and interest on a given date, creating nothing. Pass either `policy_id` or an inline `policy`. Use it to reconcile the arithmetic before an invoice actually goes late. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/LateChargesSimulateRequest" responses: "200": description: Charges accrued at the given date. content: application/json: schema: $ref: "#/components/schemas/LateChargesSimulateResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-late-fee-policies-simulate parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/late_fee_policies/{id}: get: tags: - Late Fees summary: Get a late fee policy security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Late fee policy ID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Policy found. content: application/json: schema: $ref: "#/components/schemas/LateFeePolicyResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-late-fee-policies-id patch: tags: - Late Fees summary: Update a late fee policy description: "Updates the policy. Invoices already finalized are unaffected: each invoice freezes the policy in force at finalization, so a renegotiation cannot retroactively change what was already issued." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Late fee policy ID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/LateFeePolicyUpdateRequest" responses: "200": description: Policy updated. content: application/json: schema: $ref: "#/components/schemas/LateFeePolicyResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-late-fee-policies-id delete: tags: - Late Fees summary: Delete a late fee policy description: Soft delete. Invoices already issued keep working from the snapshot they carry. The default policy cannot be deleted — set another as default first. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Late fee policy ID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Policy deleted. content: application/json: schema: $ref: "#/components/schemas/LateFeePolicyDeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-late-fee-policies-id /v1/late_fee_policies/{id}/default: post: tags: - Late Fees summary: Set as the default policy description: Makes this the organization default — what an invoice inherits when neither it, its subscription nor its billing account names one. Exactly one policy holds the flag. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Late fee policy ID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Policy set as default. content: application/json: schema: $ref: "#/components/schemas/LateFeePolicyResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-late-fee-policies-id-default /v1/holidays: get: tags: - Holidays summary: List holidays description: Returns the organization holidays — the days business-day counting skips. A late fee policy with `day_count = business` reads exactly this table. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: integer minimum: 1900 maximum: 2199 description: Filters by calendar year. required: false name: year in: query - schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Start date, inclusive, as `YYYY-MM-DD`. required: false name: date_from in: query - schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: End date, inclusive, as `YYYY-MM-DD`. required: false name: date_to in: query - schema: type: string enum: - national - state - municipal - optional - custom description: Filters by the holiday scope. required: false name: type in: query - schema: type: string enum: - "true" - "false" description: Includes soft-deleted holidays. required: false name: include_deleted in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of holidays. content: application/json: schema: $ref: "#/components/schemas/HolidayListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-holidays post: tags: - Holidays summary: Create a holiday description: Creates a holiday. Use it for state and municipal holidays and optional days off — the national ones arrive through the automatic import. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/HolidayCreateRequest" responses: "201": description: Holiday created. content: application/json: schema: $ref: "#/components/schemas/HolidayResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-holidays parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/holidays/sync: post: tags: - Holidays summary: Import national holidays description: "Imports the Brazilian national holidays from BrasilAPI for the given years (default: the current one plus the next two). Idempotent: it imports only what is missing and never resurrects a holiday removed on purpose." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/HolidaySyncRequest" responses: "200": description: Import result. content: application/json: schema: $ref: "#/components/schemas/HolidaySyncResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-holidays-sync parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/holidays/{id}: get: tags: - Holidays summary: Get a holiday security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Holiday ID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Holiday found. content: application/json: schema: $ref: "#/components/schemas/HolidayResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-holidays-id patch: tags: - Holidays summary: Update a holiday security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Holiday ID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/HolidayUpdateRequest" responses: "200": description: Holiday updated. content: application/json: schema: $ref: "#/components/schemas/HolidayResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-holidays-id delete: tags: - Holidays summary: Delete a holiday description: "Soft delete. The row stays, and that is what makes the import respect the removal: a holiday taken out on purpose does not come back on the next sync." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Holiday ID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Holiday deleted. content: application/json: schema: $ref: "#/components/schemas/HolidayDeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-holidays-id /v1/banks: get: tags: - Banks summary: List banks description: Brazilian banks with a COMPE code (BACEN), used to register bank accounts. The list is the same for every organization and is refreshed weekly from BrasilAPI. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string description: Search by part of the name or code. required: false name: search in: query - schema: type: string description: Exact COMPE code (e.g. `341`). required: false name: code in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of banks. content: application/json: schema: $ref: "#/components/schemas/BankListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-banks /v1/bank_accounts: get: tags: - Bank accounts summary: List bank accounts description: The organization bank accounts customers transfer to on a `bank_transfer` charge (`POST /invoices/{id}/pay`). security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - "true" - "false" description: Filter by active (`true`) or inactive (`false`) accounts. required: false name: active in: query - schema: type: string format: uuid description: Filter by bank (UUID from `/banks`). required: false name: bank_id in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of bank accounts. content: application/json: schema: $ref: "#/components/schemas/BankAccountListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-bank-accounts post: tags: - Bank accounts summary: Create a bank account security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/BankAccountCreateRequest" responses: "201": description: Bank account created. content: application/json: schema: $ref: "#/components/schemas/BankAccountResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-bank-accounts parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/bank_accounts/{id}: get: tags: - Bank accounts summary: Get a bank account security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Bank account UUID or `public_id`. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Bank account found. content: application/json: schema: $ref: "#/components/schemas/BankAccountResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-bank-accounts-id patch: tags: - Bank accounts summary: Update a bank account security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Bank account UUID or `public_id`. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/BankAccountUpdateRequest" responses: "200": description: Bank account updated. content: application/json: schema: $ref: "#/components/schemas/BankAccountResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-bank-accounts-id delete: tags: - Bank accounts summary: Delete a bank account description: Soft delete. Charges already sent keep showing the details the customer received. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Bank account UUID or `public_id`. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Bank account deleted. content: application/json: schema: $ref: "#/components/schemas/TransferDestinationDeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-bank-accounts-id /v1/pix_keys: get: tags: - Pix keys summary: List Pix keys description: The organization Pix keys customers transfer to on a `bank_transfer` charge (`POST /invoices/{id}/pay`). security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - "true" - "false" description: Filter by active (`true`) or inactive (`false`) keys. required: false name: active in: query - schema: type: string enum: - cpf - cnpj - email - phone - random description: Filter by key type. required: false name: key_type in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of Pix keys. content: application/json: schema: $ref: "#/components/schemas/PixKeyListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-pix-keys post: tags: - Pix keys summary: Create a Pix key description: The type is detected from the key itself (CPF, CNPJ, email, phone with +55 or random); `key_type`, when sent, must match. The key is stored unmasked and is unique in the organization. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PixKeyCreateRequest" responses: "201": description: Pix key created. content: application/json: schema: $ref: "#/components/schemas/PixKeyResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-pix-keys parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/pix_keys/{id}: get: tags: - Pix keys summary: Get a Pix key security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Pix key UUID or `public_id`. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Pix key found. content: application/json: schema: $ref: "#/components/schemas/PixKeyResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-pix-keys-id patch: tags: - Pix keys summary: Update a Pix key security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Pix key UUID or `public_id`. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/PixKeyUpdateRequest" responses: "200": description: Pix key updated. content: application/json: schema: $ref: "#/components/schemas/PixKeyResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-pix-keys-id delete: tags: - Pix keys summary: Delete a Pix key description: Soft delete. Charges already sent keep showing the details the customer received, and the key can be registered again. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Pix key UUID or `public_id`. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Pix key deleted. content: application/json: schema: $ref: "#/components/schemas/TransferDestinationDeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-pix-keys-id /v1/tax_periods: get: tags: - Tax Periods summary: List tax periods description: Returns a paginated list of the organization tax periods (monthly or quarterly). Supports filtering by company, period type, year and status. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Filter by issuing company. required: false name: company_id in: query - schema: type: string enum: - monthly - quarterly description: "Filter by period type: `monthly` or `quarterly`." required: false name: period_type in: query - schema: type: string pattern: ^\d+$ description: "Filter by reference year (e.g.: `2026`)." required: false name: year in: query - schema: type: string enum: - open - calculated - closed description: "Filter by status: `open`, `calculated` or `closed`." required: false name: status in: query - schema: type: integer minimum: 1 maximum: 12 description: Filter by reference month (1 to 12). required: false name: month in: query - schema: type: integer minimum: 1 maximum: 4 description: Filter by reference quarter (1 to 4). required: false name: quarter in: query - schema: type: - number - "null" minimum: 0 description: "Minimum gross revenue for the period, in BRL (e.g.: `1000.00`)." example: 100 required: false name: gross_revenue_min in: query - schema: type: - number - "null" minimum: 0 description: "Maximum gross revenue for the period, in BRL (e.g.: `50000.00`)." example: 100 required: false name: gross_revenue_max in: query - schema: type: - number - "null" minimum: 0 description: "Minimum estimated DAS for the period, in BRL (e.g.: `100.00`)." example: 100 required: false name: das_estimated_min in: query - schema: type: - number - "null" minimum: 0 description: "Maximum estimated DAS for the period, in BRL (e.g.: `5000.00`)." example: 100 required: false name: das_estimated_max in: query - schema: type: string format: date description: Returns periods closed on or after this date (format `YYYY-MM-DD`). example: 2026-01-15 required: false name: closed_after in: query - schema: type: string format: date description: Returns periods closed on or before this date (format `YYYY-MM-DD`). example: 2026-01-15 required: false name: closed_before in: query - schema: type: string format: date description: Start of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_after in: query - schema: type: string format: date description: End of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_before in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of tax periods. content: application/json: schema: $ref: "#/components/schemas/TaxPeriodListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-tax-periods post: tags: - Tax Periods summary: Process monthly tax period description: Creates (or retrieves) the given monthly tax period and computes the taxes due (ISS, PIS, COFINS, IRPJ, CSLL, CBS, IBS) based on issued NFes and pending compensation. When `company_id` is omitted, uses the organization default company. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/TaxPeriodCreateRequest" responses: "201": description: Tax period processed. content: application/json: schema: $ref: "#/components/schemas/TaxPeriodResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-tax-periods parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/tax_periods/{id}: get: tags: - Tax Periods summary: Get tax period security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Tax period UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Tax period detail. content: application/json: schema: $ref: "#/components/schemas/TaxPeriodResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-tax-periods-id patch: tags: - Tax Periods summary: Run action on tax period description: "Applies an action to the period: `recalculate` recomputes taxes (monthly periods only), `close` closes the period and `reopen` reopens it." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Tax period UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/TaxPeriodUpdateRequest" responses: "200": description: Tax period updated. content: application/json: schema: $ref: "#/components/schemas/TaxPeriodResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-tax-periods-id delete: tags: - Tax Periods summary: Delete tax period description: Permanently removes the tax period. Use with caution — closed periods usually should not be deleted. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Tax period UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Tax period removed. content: application/json: schema: $ref: "#/components/schemas/TaxPeriodDeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-tax-periods-id /v1/withholdings: get: tags: - Withholdings summary: List withholdings description: Returns a paginated list of the current organization's tax withholdings. Supports filters by tax type, status, withholder, invoice, NF-e and competence period. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Filter by associated person UUID. required: false name: person_id in: query - schema: type: string description: Filter by person CPF/CNPJ (exact match). required: false name: person_document_number in: query - schema: type: string description: Filter by person name (partial search, case-insensitive). required: false name: person_name_contains in: query - schema: type: string enum: - iss - pis - cofins - csll - irpj - irrf - csrf - inss - cbs - ibs description: "Filter by tax type: `iss`, `pis`, `cofins`, `csll`, `irpj`, `irrf`, `csrf`, `inss`, `cbs` or `ibs`." required: false name: tax_type in: query - schema: type: string enum: - retained - compensated - partially_compensated description: "Filter by status: `retained`, `compensated` or `partially_compensated`." required: false name: status in: query - schema: type: string format: uuid description: Filter by withholdings of a specific withholder (billing account). required: false name: withholder_id in: query - schema: type: string format: uuid description: Filter by withholdings associated with an invoice. required: false name: invoice_id in: query - schema: type: string format: uuid description: Filter by withholdings associated with an NF-e. required: false name: nfe_id in: query - schema: type: integer minimum: 2000 maximum: 3000 description: Filter by competence year (2000–3000). required: false name: competence_year in: query - schema: type: integer minimum: 1 maximum: 12 description: Filter by competence month (1–12). required: false name: competence_month in: query - schema: type: - number - "null" minimum: 0 description: "Minimum withheld amount in BRL (e.g.: `10.5` for R$ 10.50)." example: 100 required: false name: amount_min in: query - schema: type: - number - "null" minimum: 0 description: "Maximum withheld amount in BRL (e.g.: `500.0` for R$ 500.00)." example: 100 required: false name: amount_max in: query - schema: type: - number - "null" minimum: 0 description: Minimum calculation base in BRL. example: 100 required: false name: base_min in: query - schema: type: - number - "null" minimum: 0 description: Maximum calculation base in BRL. example: 100 required: false name: base_max in: query - schema: type: - number - "null" minimum: 0 description: Minimum compensated amount in BRL. example: 100 required: false name: compensated_min in: query - schema: type: - number - "null" minimum: 0 description: Maximum compensated amount in BRL. example: 100 required: false name: compensated_max in: query - schema: type: string format: date description: Start of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_after in: query - schema: type: string format: date description: End of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_before in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of withholdings. content: application/json: schema: $ref: "#/components/schemas/WithholdingListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-withholdings post: tags: - Withholdings summary: Create a withholding description: Records a withholding at source for the given withholder. `base` and `amount` are values in BRL (float, up to 4 decimal places). security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/WithholdingCreateRequest" responses: "201": description: Withholding created. content: application/json: schema: $ref: "#/components/schemas/WithholdingResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-withholdings parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Withholdings summary: Create or update a withholding description: "Looks the withholding up by `id`, `public_id` or `external_id`. If it is not found, creates it from the full body and returns `201`. **If it is found, only `competence_month`, `competence_year`, `metadata`, `external_id` and `custom_metadata` are applied**: `base`, `rate`, `amount` and `withholder_id` are immutable once recorded and are ignored in the update body." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/WithholdingUpsertRequest" responses: "200": description: Record updated. content: application/json: schema: $ref: "#/components/schemas/WithholdingUpsertResponse" "201": description: Record created. content: application/json: schema: $ref: "#/components/schemas/WithholdingUpsertResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-withholdings parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/withholdings/convert-to-credits: post: tags: - Withholdings summary: Convert pending withholdings to credits (bulk) description: Converts all of the organization's pending withholdings — optionally narrowed by `tax_type` and/or competence period — into credits. Returns the list of generated credits, the total count converted and the total amount in BRL. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/WithholdingBulkConvertRequest" responses: "200": description: Batch of withholdings converted to credits. content: application/json: schema: $ref: "#/components/schemas/WithholdingBulkConvertResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-withholdings-convert-to-credits parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/withholdings/{id}: get: tags: - Withholdings summary: Get withholding security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Withholding UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Withholding detail. content: application/json: schema: $ref: "#/components/schemas/WithholdingResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-withholdings-id patch: tags: - Withholdings summary: Update a withholding description: "Only the competence period and the metadata are editable: base, rate and amount are immutable once recorded." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Withholding UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/WithholdingUpdateRequest" responses: "200": description: Withholding updated. content: application/json: schema: $ref: "#/components/schemas/WithholdingResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-withholdings-id delete: tags: - Withholdings summary: Delete a withholding description: Refuses the deletion when the withholding has already been compensated, in full or in part. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Withholding UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Withholding deleted. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-withholdings-id /v1/withholdings/{id}/convert-to-credit: post: tags: - Withholdings summary: Convert withholding to credit description: Converts a withholding (fully or partially) into a credit on the billing account derived from the associated invoice — or, when absent, from the withholder itself. When `amount` is omitted, converts the withholding's pending balance. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Withholding UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/WithholdingConvertToCreditRequest" responses: "201": description: Credit generated from the withholding. content: application/json: schema: $ref: "#/components/schemas/WithholdingConvertToCreditResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-withholdings-id-convert-to-credit /v1/service_items: get: tags: - Service Items (LC 116) summary: List service items description: Returns a paginated list of the current organization's service items (LC 116/2003 catalog). Use the filters to narrow by company, LC 116 code, NBS, tax classification, operation indicator, or Simples annex. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Filter by UUID of the issuing company associated with the item. required: false name: company_id in: query - schema: type: string description: Free-text search across `name`, `internal_code` and `description`. required: false name: search in: query - schema: type: string enum: - "true" - "false" description: "Filter by status: `true` returns only active items; `false`, only inactive." required: false name: is_active in: query - schema: type: string description: Filter by LC 116/2003 code (e.g. `01.05`). required: false name: lc116_code in: query - schema: type: string description: Filter by NBS code (Brazilian Service Nomenclature). required: false name: nbs_code in: query - schema: type: string description: Filter by IBS/CBS tax classification (`c_class_trib`). required: false name: c_class_trib in: query - schema: type: string description: Filter by Operation Indicator (`indop_code`) used in SNNFSE NFS-e. required: false name: indop_code in: query - schema: type: string enum: - annex_iii - annex_iv - annex_v description: "Filter by applicable Simples Nacional annex: `annex_iii`, `annex_iv` or `annex_v`." required: false name: simples_annex in: query - schema: type: string description: Filter by CNAE code related to the service. required: false name: cnae_code in: query - schema: type: string description: Filter by municipal service code. required: false name: municipal_code in: query - schema: type: string description: Filter by internal item code. required: false name: internal_code in: query - schema: type: string description: Filter by CBS/IBS category for the item per the tax reform. required: false name: cbs_ibs_category in: query - schema: type: string format: date description: Start of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_after in: query - schema: type: string format: date description: End of creation date range (YYYY-MM-DD). example: 2026-01-15 required: false name: created_before in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of service items. content: application/json: schema: $ref: "#/components/schemas/ServiceItemListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-service-items post: tags: - Service Items (LC 116) summary: Create service item description: Creates a service item in the LC 116/2003 catalog. `internal_code` is the internal identifier and `lc116_code` must follow the Complementary Law 116/2003 catalog (e.g. `01.05`). When `company_id` is provided, the company must belong to the authenticated organization. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ServiceItemCreateRequest" responses: "201": description: Service item created. content: application/json: schema: $ref: "#/components/schemas/ServiceItemResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-service-items parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Service Items (LC 116) summary: Upsert service item description: "Takes the same body as POST, plus `id` and `public_id`, and dedups on `id`, `public_id`, `external_id` and the resource's natural keys, in that order, stopping at the first key that finds a record. A match is updated and returns 200; otherwise the record is created and returns 201. The POST's required fields are required only when no record is found, and updates are partial: absent fields keep their stored value." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ServiceItemUpsertRequest" responses: "200": description: Record updated. content: application/json: schema: $ref: "#/components/schemas/ServiceItemUpsertResponse" "201": description: Record created. content: application/json: schema: $ref: "#/components/schemas/ServiceItemUpsertResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-service-items parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/service_items/{id}: get: tags: - Service Items (LC 116) summary: Get service item security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Service item UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Service item detail. content: application/json: schema: $ref: "#/components/schemas/ServiceItemResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-service-items-id patch: tags: - Service Items (LC 116) summary: Update service item description: Updates editable fields of the service item. `internal_code` is immutable after creation. Use `is_active=false` to deactivate the item without deleting it. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Service item UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/ServiceItemUpdateRequest" responses: "200": description: Service item updated. content: application/json: schema: $ref: "#/components/schemas/ServiceItemResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-service-items-id delete: tags: - Service Items (LC 116) summary: Delete service item description: Deletes the service item permanently. To preserve history on already-issued invoices or NFS-e, prefer deactivating the item (`PATCH` with `is_active=false`). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Service item UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Service item deleted. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-service-items-id /v1/dashboard_users: get: tags: - Account Administration summary: List dashboard users description: Returns a paginated list of dashboard users (team members) for the current organization. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string description: Text search by name or email. required: false name: search in: query - schema: type: string enum: - all - active - pending_invitation - suspended description: "Filter by status: `all` (default), `active`, `pending_invitation` or `suspended`." required: false name: status in: query - schema: type: string description: Filter by users that have the given role (role slug). required: false name: role in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of dashboard users. content: application/json: schema: $ref: "#/components/schemas/DashboardUserListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-dashboard-users post: tags: - Account Administration summary: Invite dashboard user description: Invites a new member to the organization team. `email` and at least one role in `role_ids` are required. The user receives an email invite and starts with `pending_invitation` status. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/DashboardUserCreateRequest" responses: "201": description: User invited. content: application/json: schema: $ref: "#/components/schemas/DashboardUserResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-dashboard-users parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Account Administration summary: Create or update a dashboard user description: Looks the user up by `id`, `public_id`, `external_id` or `email` — the last one is unique per organization. If found, updates it; otherwise creates it and returns `201`. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/DashboardUserUpsertRequest" responses: "200": description: Record updated. content: application/json: schema: $ref: "#/components/schemas/DashboardUserUpsertResponse" "201": description: Record created. content: application/json: schema: $ref: "#/components/schemas/DashboardUserUpsertResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-dashboard-users parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/dashboard_users/{id}: get: tags: - Account Administration summary: Get dashboard user security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Dashboard user UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Dashboard user detail. content: application/json: schema: $ref: "#/components/schemas/DashboardUserResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-dashboard-users-id patch: tags: - Account Administration summary: Update dashboard user description: Updates the user’s name, picture, status, permissions and/or roles. Only the fields sent are changed. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Dashboard user UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/DashboardUserUpdateRequest" responses: "200": description: User updated. content: application/json: schema: $ref: "#/components/schemas/DashboardUserResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-dashboard-users-id delete: tags: - Account Administration summary: Remove dashboard user description: Removes the dashboard user from the organization. Irreversible — the user must be invited again to regain access. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Dashboard user UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: User removed. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-dashboard-users-id /v1/team_roles: get: tags: - Account Administration summary: List team roles description: Returns the paginated list of roles configured for the organization team. Includes both system roles (`is_system = true`) and custom roles. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string description: Text search by name or slug. required: false name: search in: query - schema: type: - boolean - "null" description: Filter by active (`true`) or inactive (`false`) roles. required: false name: is_active in: query - schema: type: - boolean - "null" description: Filter by system (`true`) or custom (`false`) roles. required: false name: is_system in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of roles. content: application/json: schema: $ref: "#/components/schemas/TeamRoleListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-team-roles post: tags: - Account Administration summary: Create custom role description: Creates a custom role. `slug` must start with a lowercase letter and contain only lowercase letters, digits and `_`. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/TeamRoleCreateRequest" responses: "201": description: Role created. content: application/json: schema: $ref: "#/components/schemas/TeamRoleResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-team-roles parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Account Administration summary: Create or update a team role description: Looks the role up by `id`, `public_id` or `external_id`. The `slug` carries no unique constraint and therefore does **not** identify a row. If found, updates it; otherwise creates it and returns `201`. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/TeamRoleUpsertRequest" responses: "200": description: Record updated. content: application/json: schema: $ref: "#/components/schemas/TeamRoleUpsertResponse" "201": description: Record created. content: application/json: schema: $ref: "#/components/schemas/TeamRoleUpsertResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-team-roles parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/team_roles/{id}: get: tags: - Account Administration summary: Get role security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Role UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Role detail. content: application/json: schema: $ref: "#/components/schemas/TeamRoleResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-team-roles-id patch: tags: - Account Administration summary: Update role description: Updates the role fields. Only the fields sent are changed. System roles have additional restrictions. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Role UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/TeamRoleUpdateRequest" responses: "200": description: Role updated. content: application/json: schema: $ref: "#/components/schemas/TeamRoleResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-team-roles-id delete: tags: - Account Administration summary: Remove role description: Soft-deletes the role. System roles (`is_system = true`) cannot be removed. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Role UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Role removed. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-team-roles-id /v1/portal_users: get: tags: - Account Administration summary: List portal users description: Returns the customer portal users in the authenticated organization, paginated. Sensitive fields (password, tokens) are never exposed. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Scope to a specific billing account. required: false name: billing_account_id in: query - schema: type: string description: Scope to every billing account of a customer. Accepts the customer's `id` or its `external_id`. required: false name: customer_id in: query - schema: type: string enum: - active - pending_invitation - pending_verification - suspended - locked description: "Filter by status: `active`, `pending_invitation`, `pending_verification`, `suspended` or `locked`." required: false name: status in: query - schema: type: string description: Substring match on the email. required: false name: email in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of portal users. content: application/json: schema: $ref: "#/components/schemas/CustomerPortalUserListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-portal-users webhooks: {}