Coming soon · Contract draft

Invoices, Payments & Disputes

Planned

A separately scoped billing contract for invoice drafts, lines, approvals, finalization, sending, payments, reversals, and disputes.

Reviewable specification — not callable

Documentation-first contract draft. The proposed additions on this page are not callable or available yet. Paths, payloads, scopes, names, and examples are intentionally concrete so customers can review the intended contract before and during implementation.

Canonical owner

Invoice, payment, dispute, and client-billing services

Contract posture

P2 · Documentation first · implementation follows approval

Contract metadata

Draft version

0.2 review draft

Review owner

Work/Finance + Developer Platform

Last reviewed

July 14, 2026

Target wave

Wave 5 · Financial operations

Contract dependencies

• Financial/privacy scope matrix
• Generic Operation resource
• Transactional audit and event contracts

What this unlocks

Integrate invoice lifecycle

Read a stable domain model for invoices, payments & disputes without depending on GUI routes or database shapes.

Explain billing state

Create a reviewable proposal and apply only the bounded commands the canonical owner permits.

Coordinate disputes safely

React to durable lifecycle facts and connect external systems with explicit direction and provenance.

Lifecycle and invariants

Invoices, Payments & Disputes exposes a bounded lifecycle with explicit commands and named authority at every transition.

draftapprovedfinalizedsentpaidvoideddisputed

From	To	Command	Authority
draft	approved	Approve invoice	Client invoice, payment, and dispute services
approved	finalized	Finalize invoice	Client invoice, payment, and dispute services
finalized	sent	Send invoice	Client invoice, payment, and dispute services
sent	paid	Record payment	Client invoice, payment, and dispute services
sent	disputed	Open dispute	Client invoice, payment, and dispute services

Lifecycle invariants

• This contract bills the customer’s clients, not the customer’s DigitalStack subscription.
• Finalize, send, void, payment, and reversal are named human actions.

Authority boundaries

The interfaces expose canonical capabilities; they do not become a second owner of domain rules or state.

DigitalStack owns

• DigitalStack invoice and dispute lifecycle
• Approval/finalization/send state
• Payment recording and reversal audit

Explicitly not building

• Agent finalization or payment recording
• Financial actions through generic write scopes
• DigitalStack plan, seat, subscription, purchase, or payment-method administration

Surface decisions

Deliberate additions, retained boundaries, and removals from the proposed external contract.

add

Client invoice drafts, lines, approval, finalize, send, payment, reversal, dispute, and comment resources

Agencies need to integrate their client-billing lifecycle.

keep

Separate scopes and REST commands for high-risk financial actions

Read, draft, finalize, send, and payment authority must not collapse into one write scope.

remove

DigitalStack subscription, seat, plan, purchase, or payment-method APIs

A customer manages its DigitalStack subscription in the authenticated product UI only.

Interface plan

REST API

Planned

Versioned invoices, payments & disputes resources, commands, idempotency, and operation status.

Reads + explicit commands

GraphQL

Planned

Composable Invoice reads with mutations delegated to the same canonical domain service.

Composable reads + bounded delegated mutations

MCP / Agent API

Planned

Bounded read, draft, and human-request tools with evidence and audit attribution.

Read + proposal/confirmed commands only

Webhooks

Planned

Past-tense invoice lifecycle facts with minimal payloads.

Past-tense durable facts only

Connected Apps

Planned

QuickBooks / Xero / NetSuite / Stripe plus consumer clients, with declared direction and authority.

Declared direction and field authority required

Cross-interface parity

Each surface delegates to the named canonical owner; a blank surface is an intentional denial of authority, not missing documentation.

Capability	REST	GraphQL	MCP	Webhook	Canonical owner
Primary read	GET /invoices	invoice(id: ID!): Invoice	get_invoices_payments	—	Invoice, payment, dispute, and client-billing services
Primary command	POST /invoices	draftInvoiceChange(input: DraftInvoiceChangeInput!): InvoiceChangeProposal!	draft_invoices_payments_change	invoice.created	Invoice, payment, dispute, and client-billing services

Proposed scopes

Proposed scopes are not grantable yet.

invoices:readplanned scope

Read governed invoices, payments & disputes resources.

invoices:writeplanned scope

Create and edit bounded invoices, payments & disputes fields.

invoices:operateplanned scope

Run explicit invoices, payments & disputes lifecycle commands.

Behavioral contract

Cross-cutting rules every implementation and interface must satisfy.

Canonical delegation

Every interface delegates to Invoice, payment, dispute, and client-billing services; no resolver, gateway, worker, or connector reimplements domain rules.

Least-privilege principals

Scopes are evaluated with tenant, role, field-visibility, and principal-type constraints before data is read or changed.

Safe writes

Mutations use explicit confirmation where required, optimistic concurrency, idempotency, and durable actor attribution.

Transactional facts

Webhook facts are emitted from the canonical commit path, versioned, minimal, and safe to redeliver.

Declared provider authority

Every Connected App declares direction, field authority, provenance, and conflict behavior before activation.

REST API

Proposed endpoints

Planned

GET/api/v1/invoices

List invoices, payments & disputes

Return an authorized, paginated collection with stable filters and provenance.

invoices:read

POST/api/v1/invoicesconfirmation

Create Invoice

Create one canonical resource with idempotency and actor attribution.

invoices:write

GET/api/v1/invoices/{id}

Retrieve Invoice

Return canonical detail, lifecycle state, permissions, and allowed actions.

invoices:read

PATCH/api/v1/invoices/{id}confirmation

Update Invoice

Update bounded editable fields using optimistic versioning.

invoices:write

POST/api/v1/invoices/{id}/finalizeconfirmation

finalize Invoice

Run one explicit domain command after validation and authorization.

invoices:operate

finalize a Invoice

Planned request

curl --request POST \
+  --url https://www.digitalstack360.com/api/v1/invoices/invoice_123/finalize \
+  --header "Authorization: Bearer $DSTACK_API_KEY" \
+  --header "Content-Type: application/json" \
+  --header "Idempotency-Key: invoices-payments-finalize-v2" \
+  --data '{
    "expected_version": 2,
    "reason": "Confirmed through the reviewed integration workflow"
  }'

Planned response

{
  "data": {
    "id": "invoice_123",
    "status": "finalized",
    "version": 3,
    "operation_id": "op_01k4..."
  }
}

GraphQL

Proposed graph

Planned

Types

Invoice

InvoiceConnection

InvoiceChangeProposal

Operation

Queries

invoice(id: ID!): Invoice

invoiceList(filter: InvoiceFilter, pagination: PaginationInput): InvoiceConnection!

Mutations

draftInvoiceChange(input: DraftInvoiceChangeInput!): InvoiceChangeProposal!

Planned GraphQL query

query InvoiceDetail($id: ID!) {
  invoice(id: $id) {
    id
    status
    version
    updatedAt
    allowedActions { id label requiresConfirmation }
    source { kind externalId }
  }
}

MCP / Agent API

Proposed tools

Planned

Get Invoices, Payments & Disputes

get_invoices_payments

Planned

Read the authorized invoices, payments & disputes state, provenance, and allowed actions.

Scope: invoices:read
Input: Resource id or a bounded filter.
Output: Canonical detail with source provenance and allowed actions.
Write boundary: Read only.

Draft Invoices, Payments & Disputes change

draft_invoices_payments_change

Planned

Build a reviewable proposal from explicit user intent and DigitalStack evidence.

Scope: invoices:write
Input: Target, requested outcome, expected version, and optional evidence references.
Output: A persisted proposal, validation results, and conflicts.
Write boundary: Creates a proposal; it does not mutate canonical state.

Request Invoices, Payments & Disputes action

request_invoices_payments_action

Planned

Prepare an authorized human action request without executing the high-risk command.

Scope: invoices:operate
Input: Proposal id, expected version, named decision maker, and reason.
Output: A pending human-action request and audit reference.
Write boundary: The agent cannot execute the final command.

Planned agent workflow

User: Review the proposed invoices, payments & disputes change and help me apply it.

1. Call get_invoices_payments to inspect current state, provenance, and allowed actions.
2. Call draft_invoices_payments_change to create a proposal without changing canonical state.
3. Show validation results, conflicts, and the exact command to the user.
4. Call request_invoices_payments_action so an authorized human can decide.

Never infer authority from access to the MCP client.

Webhooks

Proposed event catalog

Planned

Event types

invoice.createdplanned event

A canonical Invoice was created.

payload: invoice_id, status, created_at

invoice.updatedplanned event

Governed Invoice fields changed.

payload: invoice_id, changed_fields, version, occurred_at

invoice.finalizedplanned event

The finalize command completed.

payload: invoice_id, prior_status, status, occurred_at

Planned event example

{
  "event_id": "evt_01k4...",
  "type": "invoice.finalized",
  "event_version": 1,
  "occurred_at": "2026-07-16T14:22:04Z",
  "workspace_id": "ws_abc123",
  "resource": {
    "type": "invoice",
    "id": "invoice_123"
  },
  "actor": {
    "id": "user_123"
  },
  "payload": {
    "invoice_id": "invoice_123",
    "prior_status": "draft",
    "status": "finalized"
  },
  "source": null
}

Connected Apps

Proposed connection roles

Planned

Claude / ChatGPT / IDE clients

Consumer application

Read, explain, and submit bounded invoices, payments & disputes proposals through MCP.

Authority: Client access never implies domain approval or unrestricted mutation authority.

QuickBooks / Xero / NetSuite / Stripe

Synchronization provider

Exchange approved invoices and payment facts.

Authority: Direction and conflict rules are explicit; provider objects do not bypass DigitalStack approval.

Open contract decisions

Resolve before implementation approval

• Which payment providers may write payment facts versus submitting reconciliation evidence?

Proof obligations

Must remain true	Failure indicator
Invoice, payment, dispute, and client-billing services remains the singular canonical owner.	An interface or connector persists a second authoritative lifecycle state.
Draft and apply remain separate actions.	An agent or integration silently converts inferred intent into a canonical mutation.
Every write is attributable, versioned, and idempotent.	A retry duplicates work or stale state overwrites a newer human decision.
Connected App direction and field authority are explicit.	Provider data silently becomes canonical or conflicts are resolved without policy.