Surfaces

Interactive API Explorer: Explorer

The authoritative surface is the OpenAPI spec:

• /accounting/openapi.yaml

Additional surfaces are available: MCP (/accounting/mcp.html) and CLI (g3n accounting ...; see cli/README.md).

Surface Types (explicit)

API Gateway

• Status: Available.
• Base: https://api.g3nretailstack.com/accounting
• Notes: Primary tenant surface for accounting exports, usage, reconciliation, AR tracking, commissions, and financial rollups.

Direct Lambda

• Status: Available (operator-only).
• Notes: Usage rollup admin endpoints are direct Lambda (IAM-gated).

CLI

• Status: Available.
• Command: g3n accounting ... (API Gateway + operator direct Lambdas).
• Notes: See cli/README.md for admin rollup commands.

MCP

• Status: Available.
• Canonical protocol: https://mcp.g3nretailstack.com/accounting/PROTOCOL.md
• Mirror: https://doc.g3nretailstack.com/accounting/PROTOCOL.md

Auth + tenancy

• Required headers: x-orgcode and x-session-guid (user session) or x-api-key (org-bound service account).
• Header auth is canonical; body auth is accepted where documented. See /common/headers-identity.html.
• Optional cost attribution: x-cccode (or request field cccode) where supported; see OpenAPI.
• Non-associated callers receive 404 not-found (anti-enumeration).
• Facility context: x-logical-guid (required for operational actions; see OpenAPI per-path). x-channel-code (required where documented; see OpenAPI per-path).

Identifier policy

• Direct get/update/status calls require GUID/ID fields (*_id or legacy *_guid where that is the canonical field name). Code-based lookups are resolve/search only.
• Responses never include both *_id and *_guid for the same record (no dual-field output).
• Exceptions (email-based UAS, PVM resolve, MRS container+record_id) are listed in /common/ids-codes.html.

Request builder (API Gateway)

Headers (canonical)

-H "x-orgcode: $ORGCODE"
-H "x-session-guid: $SESSION_GUID" # or: -H "x-api-key: $API_KEY"
-H "content-type: application/json"

Template

curl -sS -X POST "https://api.g3nretailstack.com/accounting/<endpoint>" \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{"...": "..."}'

Notes

• Replace <endpoint> with a route from the OpenAPI inventory.
• Header auth is canonical; body session_guid / api_key is accepted where documented.

Tax audit export surfaces

• Export create supports export_kind=tax_audit with optional tax filters (jurisdiction codes, policy versions, basis, liability trigger).

Accounts Receivable surfaces

• POST /accounting/invoice/set|get|list|status/set — invoice lifecycle (create, read, list, status transition)
• POST /accounting/invoice/payment/apply|list — apply payment against invoice, list payments
• POST /accounting/ar/aging/report — on-demand aging buckets (current, 1-30, 31-60, 61-90, 91-120, 120+)
• POST /accounting/ar/balance — per-customer outstanding balance
• POST /accounting/ar/statement — customer statement (invoices + payments for date range)
• Auto-invoice: SCM order-placed events with payment_terms auto-create invoices via EventBridge ingest.
• Auto-payment: SCM tender-captured events auto-apply payments to matching invoices.

Financial rollup surfaces

• POST /accounting/rollup/financial/get|list — read pre-BI daily financial rollups
• Dimensions: sales, tender, tax, ar_aging — each with dimension_value breakdown
• Scheduled job runs daily at 02:00 UTC; idempotent and re-runnable

Commission surfaces

• POST /accounting/commission/get|list — read commission records (by ID, associate via GSI1, or order via GSI3)
• POST /accounting/commission/adjust — manual adjustment (bonus, chargeback, correction)
• POST /accounting/commission/split/set — multi-associate split allocation (must sum to 10000 bps)
• POST /accounting/commission/statement — period statement for an associate (aggregated totals)
• POST /accounting/commission/payout/create|get|list|status/set — payout lifecycle (pending → approved → paid)
• Auto-commission: SCM order-placed events with associate_ref auto-create commission records via EventBridge ingest.
• Rule cache: PPM commission-rule-set / commission-rule-status-set events are cached locally for commission calculation.
• Auto-void: SCM order-cancelled events void the associated commission record.

Comments and inbox surfaces

• POST /accounting/comment|comment/get|comment/list|comment/revise|comment/status|comment/report
• POST /accounting/inbox/create|get|list|status|state

Endpoint inventory (OpenAPI parity)

Request/response schema names reference OpenAPI component schemas.

Method	Path	Request schema	Response schema
POST	/comment	CommentAddRequest	CommentEnvelope
POST	/comment/get	CommentGetRequest	CommentEnvelope
POST	/comment/list	CommentListRequest	CommentListEnvelope
POST	/comment/report	CommentReportRequest	CommentReportEnvelope
POST	/comment/revise	CommentReviseRequest	CommentEnvelope
POST	/comment/status	CommentStatusRequest	CommentEnvelope
POST	/event/get	EventGetRequest	EventEnvelope
POST	/event/list	EventListRequest	EventListEnvelope
POST	/event/record	EventRecordRequest	EventEnvelope
POST	/export/batch/create	ExportBatchCreateRequest	ExportBatchEnvelope
POST	/export/batch/get	ExportBatchGetRequest	ExportBatchEnvelope
POST	/export/batch/list	ExportBatchListRequest	ExportBatchListEnvelope
POST	/export/batch/repair	ExportBatchRepairRequest	ExportBatchEnvelope
POST	/export/batch/status/set	ExportBatchStatusSetRequest	ExportBatchEnvelope
POST	/export/create	ExportCreateRequest	ExportEnvelope
POST	/export/get	ExportGetRequest	ExportEnvelope
POST	/export/list	ExportListRequest	ExportListEnvelope
POST	/export/schedule/create	ExportScheduleCreateRequest	ExportScheduleEnvelope
POST	/export/schedule/get	ExportScheduleGetRequest	ExportScheduleEnvelope
POST	/export/schedule/list	ExportScheduleListRequest	ExportScheduleListEnvelope
POST	/export/schedule/status/set	ExportScheduleStatusSetRequest	ExportScheduleEnvelope
POST	/inbox/create	InboxCreateRequest	InboxEnvelope
POST	/inbox/get	InboxGetRequest	InboxEnvelope
POST	/inbox/list	InboxListRequest	InboxListEnvelope
POST	/inbox/state	InboxStateRequest	InboxEnvelope
POST	/inbox/status	InboxStatusRequest	InboxEnvelope
POST	/lineage/list	LineageListRequest	LineageListEnvelope
POST	/reconcile/report	ReconcileReportRequest	ReconcileReportEnvelope
POST	/storage/usage/get	StorageUsageGetRequest	StorageUsageEnvelope
POST	/storage/usage/list	StorageUsageListRequest	StorageUsageListEnvelope
POST	/storage/usage/reconcile	StorageUsageReconcileRequest	StorageUsageReconcileEnvelope
POST	/storage/usage/record	StorageUsageRecordRequest	StorageUsageEnvelope
POST	/usage/rollup/get	UsageRollupGetRequest	UsageRollupEnvelope
POST	/usage/rollup/list	UsageRollupListRequest	UsageRollupListEnvelope
POST	/invoice/set	InvoiceSetRequest	InvoiceEnvelope
POST	/invoice/get	InvoiceGetRequest	InvoiceEnvelope
POST	/invoice/list	InvoiceListRequest	InvoiceListEnvelope
POST	/invoice/status/set	InvoiceStatusSetRequest	InvoiceEnvelope
POST	/invoice/payment/apply	InvoicePaymentApplyRequest	ArPaymentEnvelope
POST	/invoice/payment/list	InvoicePaymentListRequest	ArPaymentListEnvelope
POST	/ar/aging/report	ArAgingReportRequest	ArAgingReportEnvelope
POST	/ar/balance	ArBalanceRequest	ArBalanceEnvelope
POST	/ar/statement	ArStatementRequest	ArStatementEnvelope
POST	/commission/get	CommissionGetRequest	Envelope
POST	/commission/list	CommissionListRequest	Envelope
POST	/commission/adjust	CommissionAdjustRequest	Envelope
POST	/commission/split/set	CommissionSplitSetRequest	Envelope
POST	/commission/statement	CommissionStatementRequest	Envelope
POST	/commission/payout/create	CommissionPayoutCreateRequest	Envelope
POST	/commission/payout/get	CommissionPayoutGetRequest	Envelope
POST	/commission/payout/list	CommissionPayoutListRequest	Envelope
POST	/commission/payout/status/set	CommissionPayoutStatusSetRequest	Envelope
POST	/rollup/financial/get	FinancialRollupGetRequest	FinancialRollupEnvelope
POST	/rollup/financial/list	FinancialRollupListRequest	FinancialRollupListEnvelope

Error tags

Common tags (see /common/error-tags.html for definitions): validation-error, unauthorized, forbidden, not-found, expected-revision-required, conflict, invalid-state, throttled, internal-error.

Example envelopes

Success envelope (shape-only):

{
  "success": true,
  "data": { "example": "see schema for fields" },
  "build": { "build_major": "MONDAY", "build_minor": "0000000000", "build_id": "MONDAY-0000000000" },
  "stats": { "call": "example", "service": "accounting", "timestamp_utc": "2026-01-21T00:00:00Z" }
}

Error envelope (shape-only):

{
  "success": false,
  "error": {
    "error_code": "accounting.conflict_revision",
    "http_status": 409,
    "retryable": false,
    "request_id": "req-123",
    "trace_id": "trace-abc",
    "major": { "tag": "conflict", "message": { "en_US": "Expected revision does not match the current record." } },
    "details": { "expected_revision": "3", "current_revision": "4" },
    "conflict_snapshot": { "revision": 4 }
  },
  "build": { "...": "..." },
  "stats": { "call": "example", "service": "accounting", "timestamp_utc": "2026-01-21T00:00:00Z", "request_id": "req-123" }
}

Role requirements (by endpoint family)

• Read/list: acct_view (or owner).
• Export create/repair: acct_export_admin (or owner).
• AR write (invoice set/status, payment apply): ar_admin, acct_export_admin, or finance_audit.
• Commission write (adjust, split/set, payout create/status): commission_admin, ar_admin, acct_export_admin, or finance_audit.
• Financial rollup read: acct_view, acct_export_admin, or finance_audit.
• Audit: finance_audit (org-wide) where applicable.

Idempotency & retries

• Export create is not idempotent; use export get to check before retrying.
• Batch status updates require expected_revision where documented.
• Invoice set is idempotent on order_guid (auto-dedup). Invoice status/set and payment/apply require expected_revision.
• Financial rollup job is idempotent; re-running overwrites the same date partition.

Common pitfalls

• Exports are asynchronous; poll export/get for readiness.
• Large windows may be split into multiple batches.

Examples (core families)

Export create

{ "export_kind": "financial_events", "reason": "erp-sync" }

Response (shape):

{ "success": true, "data": { "export_id": "EXPORT_ID" }, "build": { "...": "..." }, "stats": { "...": "..." } }

Export get

{ "export_id": "EXPORT_ID" }

Response (shape):

{ "success": true, "data": { "export": { "status": "ready" } }, "build": { "...": "..." }, "stats": { "...": "..." } }