Cozzix API Documentation

Overview

Built for server-to-server billing events

Each product or subsidiary receives its own Business Line and API key. The key identifies the Cozzix workspace and revenue attribution automatically, so callers never send an internal business ID.

Source of truth

Your product remains the source of truth for the processor action. Cozzix becomes the centralized record for CRM customers, invoices, payments, refunds, business-line reporting, and audit history.

Authentication

One private key per Business Line

Send the live key as a Bearer token from your backend only. Keys begin with czx_live_ and must never be included in browser or mobile code.

Authorization: Bearer czx_live_REPLACE_WITH_SECRET
Content-Type: application/json
Idempotency-Key: stable-provider-event-id

Quickstart

Create a paid invoice

Call this endpoint only after the payment provider confirms that the charge succeeded. Monetary values use major currency units, so USD 79.99 is sent as 79.99, not 7999.

curl --request POST \
  --url https://api.cozzix.com/api/external/v1/invoices \
  --header "Authorization: Bearer $COZZIX_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: evt_1ExampleSucceeded" \
  --data '{
    "externalInvoiceId": "in_123",
    "paidAt": "2026-10-20T14:25:03.000Z",
    "currency": "USD",
    "customer": {
      "externalId": "cus_123",
      "name": "Example Customer",
      "email": "[email protected]",
      "country": "US",
      "timezone": "America/New_York"
    },
    "items": [{
      "description": "Monthly subscription",
      "quantity": 1,
      "unitAmount": 79.99,
      "taxPercent": 0
    }],
    "payment": {
      "provider": "stripe",
      "method": "card",
      "accountId": "acct_123",
      "paymentId": "pi_123",
      "chargeId": "ch_123",
      "card": { "brand": "visa", "last4": "4242" }
    }
  }'

Endpoints

API surface

GET/api/external/v1/status

Connection status

Verify credentials, enabled currencies, delivery health, and recent activity.

POST/api/external/v1/invoices

Create paid invoice

Create or match a client, issue a paid invoice, record its payment, and attribute revenue.

POST/api/external/v1/transactions

Sync transaction

Synchronize payment failures, cancellations, disputes, partial refunds, and full refunds.

Request schemas, response schemas, status codes, and field limits are available in the OpenAPI specification.

Customer matching

One client can belong to several products

Match customer.externalId within the authenticated Business Line.
Fall back to the customer email in the Cozzix workspace.
Create a new CRM client when neither value matches.

Always send a stable external customer ID. Email addresses can change and should remain a fallback.

Reliability

Safe retries without duplicate invoices

Every POST requires an Idempotency-Key. Use the immutable Stripe event ID or your billing system’s event ID and reuse the same key with the exact same body for every retry.

2xx

Accepted. Do not retry.

409

Inspect retryable; retry dependencies with backoff.

422

Fix the payload or account configuration.

5xx

Retry with exponential backoff and the same key.

Duplicate protection

Cozzix also checks external invoice IDs and provider payment IDs. A retried event cannot create a second invoice or payment.

Security

Send safe payment details only

You may send card brand, last four digits, expiration month/year, funding type, wallet type, and the provider receipt URL. Never send a full card number, CVC/CVV, PIN, track data, or raw payment secrets.