Request/Response Structure

Every Azotte endpoint responds with the same predictable JSON envelope so that client teams can reuse logging, retry, and UI logic across features. This page explains the integration lanes (M2M, P2M, T2M, W2M), the required headers, and how to interpret the diagnostics, status, and payload blocks that wrap every response.

Integration lanes at a glance

Lane	Best for	Base path	Auth method	Typical caller
M2M (Machine-to-Machine)	Checkout services, backend automations, partner storefronts needing bundles, artifacts, or subscription state.	`/api/m2m/*`	Service token issued via client credentials	Storefront backends, cron jobs, internal services
P2M (Portal-to-Moneti)	Admin Portal UI and analytics widgets that the Moneti console already surfaces.	`/api/p2m/*`	User session token (PKCE) with portal scopes	Moneti Portal SPA, Azotte dashboards
T2M (Third party to Moneti)	Integrations brought by affiliate storefronts or channel partners selling Azotte SKUs.	`/api/t2m/*`	Scoped partner key + shared secret	Shopify apps, third-party checkout flows
W2M (Webhook-to-Moneti)	Event notifications Moneti sends to your systems (subscriptions, invoices, payment updates).	`/api/w2m/*` (outbound)	Signed payload + `X-Moneti-Signature`	Your webhook receivers

All lanes reuse the same envelope. Only scopes, hosts, and rate limits differ.

Standard request pattern

Base hosts

Production https://api.azotte.cloud
Staging https://api.preview.azotte.cloud
Local emulation http://localhost:5210 (when running the developer gateway)

Each lane hangs off the same host; the path prefix communicates the contract (e.g., /api/m2m/offer/bundles).

Required headers

Header	PresentationType
`Authorization: Bearer <token>`	All lanes require JWT or HMAC tokens. Service tokens for M2M/T2M, user tokens for P2M, webhook signatures for W2M.
`Content-Type: application/json`	Every request body is JSON encoded.
`X-Correlation-Id`	Pass a UUID so diagnostics can be traced across services. Moneti will generate one if omitted, but providing your own simplifies log joins.
`X-Moneti-Tenant`	Tenant URN (`tn.xx.xxx`). Required when a caller can access multiple tenants.

Optional but recommended headers

Header	Why it matters
`Idempotency-Key`	Guarantees a single write for payment or provisioning requests even if the caller retries. Retained for 24 hours.
`X-Region-Override`	Forces a geo when testing compliance scenarios (staging only).

Common body contract

While each endpoint defines its own payload, most POST/PUT calls wrap business input under a context or payload node so Moneti can enrich it with risk, geo, and campaign metadata without mutating the root.

Node	Description
`context`	Who/where the request comes from (customer URNs, storefront URNs, IP address, interaction type).
`payload`	The domain-specific part (bundle filters, payment instrument details, entitlement overrides, etc.).

Example request

POST /api/m2m/offer/bundles HTTP/1.1
Host: api.azotte.cloud
Authorization: Bearer <service-token>
X-Correlation-Id: cdbb5e0d-1f46-4a13-8bc9-8d71b4a98211
Content-Type: application/json

{
    "context": {
        "customerUrn": "sb.00.060",
        "storefrontUrn": "st.00.001",
        "interactionType": 10,
        "channel": 101,
        "customerIpAddress": "203.0.113.24"
    }
}

Response envelope overview

Every endpoint responds with a predictable envelope. The domain payload (offer, subscription, invoice, etc.) sits beside diagnostic and status metadata.

JSON blueprint

{
    "diagnostics": {
        "correlationId": "cdbb5e0d-1f46-4a13-8bc9-8d71b4a98211",
        "effectiveRegionCode": "EU",
        "createdAt": "2025-11-18T12:21:53.762051Z",
        "nodeId": "gw-prod-eu-01"
    },
    "data": { /* resource-specific block such as offer, subscription, invoice */ },
    "status": {
        "severity": "SUCCESS",
        "messageCode": "MNT-000-00",
        "message": "Success",
        "source": "Moneti",
        "success": true,
        "warnings": []
    },
    "statusCode": "MNT-000-00",
    "links": {
        "self": "https://api.azotte.cloud/api/m2m/offer/bundles",
        "next": null
    }
}

Top-level keys

Key	Description	Always present
`diagnostics`	Trace info emitted by the gateway. Mirrors headers such as `X-Correlation-Id`.	✅
`data` / domain key	The business payload. Some endpoints name the node (`offer`, `subscription`, `invoice`).	✅
`status`	Machine- and human-readable outcome.	✅
`statusCode`	Canonical Moneti status code, duplicated for convenience.	✅
`links`	`self`, pagination, retries.	⛔ optional
`warnings` / `errors`	Arrays surfaced when something non-blocking/blocking occurred.	⛔ optional

Diagnostics object

Field	Type	Notes
`correlationId`	`string`	Echoes the incoming header or a generated UUID. Use it to search distributed traces.
`effectiveRegionCode`	`string`	Region derived from IP/tenant (e.g., `EU`, `US`, `APAC`). Helps reason about tax and compliance flows.
`createdAt`	`string (ISO8601)`	Timestamp of when the gateway processed the request.
`nodeId`	`string`	Hostname of the edge node. Useful when contacting support.

Status object

Field	Description
`severity`	`SUCCESS`, `WARNING`, or `ERROR`. Drives retry/rollback logic.
`messageCode`	Canonical code (e.g., `MNT-000-00`, `MNT-409-02`). Maps 1:1 with `statusCode`.
`source`	Component that produced the response (e.g., `Moneti`, `OfferEngine`, `WebhookDelivery`).
`message`	Human-friendly summary safe to log or bubble to UI.
`details`	Structured info about failures (validation errors, risk reasons).
`success`	Boolean helper (true when `severity === "SUCCESS"`).
`warnings` / `warning`	Optional array describing recoverable issues (fallback pricing, partial syncs).

Data/resource block

M2M responses usually expose named nodes (offer, customer, options).
P2M uses the same pattern but payloads skew toward grid/list shapes with items + pageInfo.
T2M payloads omit confidential fields and add partnerTags when the caller belongs to a reseller.

Treat everything inside the domain node as authoritative for the operation you requested—Moneti never mutates your input in place.

Pagination & collections

List endpoints embed pagination metadata beside items:

{
    "data": {
        "items": [ ... ],
        "pageInfo": {
            "page": 1,
            "pageSize": 25,
            "total": 240,
            "hasNext": true
        }
    }
}

When pagination applies, the links.next and links.previous fields mirror the cursor URLs.

Status codes & severity map

Severity	Example codes	HTTP status	Caller guidance
`SUCCESS`	`MNT-000-00`	`2xx`	Proceed. Cache payloads that include `expiresAt`.
`WARNING`	`MNT-206-01` (partial success), `MNT-299-05` (fallback geo)	`2xx`	Action completed but inspect `warnings`. Show banner or schedule reconciliation if data was skipped.
`ERROR`	`MNT-400-01` (validation), `MNT-401-01` (auth), `MNT-409-02` (conflict), `MNT-500-00` (server)	`4xx/5xx`	Do not retry blindly. Use `messageCode`, `details`, and `diagnostics` to determine fix or backoff.

Error payload example

{
    "diagnostics": {
        "correlationId": "7a6cc75a-3a74-4ec1-bd86-0b0a684d8531",
        "createdAt": "2025-11-18T10:02:12.004Z",
        "nodeId": "gw-prod-us-03"
    },
    "errors": [
        {
            "code": "MNT-401-01",
            "field": "Authorization",
            "message": "Token expired",
            "help": "Request a fresh client-credential token."
        }
    ],
    "status": {
        "severity": "ERROR",
        "messageCode": "MNT-401-01",
        "source": "Gateway",
        "message": "Unauthorized",
        "success": false
    },
    "statusCode": "MNT-401-01"
}

Channel-specific notes

M2M

Best for backends that act on behalf of customers without human interaction.
Long-lived service tokens (15 minutes) are scoped via client credentials. Refresh proactively and reuse until expiry to minimize login churn.
Respect offer.expiresAt and subscription.version to avoid conflicting writes.

P2M

Tied to human operators in the Moneti console. Tokens carry user identity for auditing.
Responses frequently include permissions blocks so the UI can hide disabled features.
Rate limits are lower than M2M; debounce portal widgets when filtering.

T2M

Adds partnerId, partnerTags, or channelReference to diagnostics.
Sign each request with the shared secret; the gateway validates both the Bearer token and HMAC signature.
Payloads redact sensitive customer identifiers unless explicitly whitelisted.

W2M

Moneti calls your webhook. Expect the same diagnostics and status envelope, plus an event payload under event.
Verify the X-Moneti-Signature header (HMAC SHA-256 of the raw body). Reject if the timestamp is older than 5 minutes to prevent replay.
Return 2xx to acknowledge receipt. Any other code will trigger exponential backoff retries (max 12 attempts).

Integration lanes at a glance​

Standard request pattern​

Base hosts​

Required headers​

Optional but recommended headers​

Common body contract​

Example request​

Response envelope overview​

JSON blueprint​

Top-level keys​

Diagnostics object​

Status object​

Data/resource block​

Pagination & collections​

Status codes & severity map​

Error payload example​

Channel-specific notes​

M2M​

P2M​

T2M​

W2M​

What to read next​