Transactions API

The Transactions API lets you track and manage commerce transactions that occur through agent interactions on the Cresva platform.

Scope: transactions:read transactions:write

Management API preview

The Storefront-side transaction lifecycle (create, confirm, escrow) is live. The brand-facing Transactions list and external-recording API documented here ship with the public Management API release.

GET/transactions

List transactions. Supports pagination and filtering by status and date range.

Pagination: All list endpoints support page (default 1), perPage (default 20, max 100), sort, order (asc/desc), since and until (ISO 8601). See Rate Limits for usage best practices.

Query Parameters

sincestringISO 8601 start date

untilstringISO 8601 end date

statusstringFilter by status: pending, completed, failed, refunded

bash

curl "https://api.cresva.ai/api/storefront/[brandId]/transactions?status=completed&since=2026-03-01T00:00:00Z" \
  -H "Authorization: Bearer cresva_ak_a1b2c3d4e5f6..."

javascript

const response = await fetch(
  "https://api.cresva.ai/api/storefront/[brandId]/transactions?status=completed&since=2026-03-01T00:00:00Z",
  {
    headers: {
      Authorization: "Bearer " + process.env.CRESVA_API_KEY,
    },
  }
);

const { data } = await response.json();

POST/transactions

Record an external transaction. Use this to track transactions that occurred outside the Cresva platform.

Request Body

productIdstringProduct ID (required)

amountnumberTransaction amount in smallest currency unit (required)

currencystringISO 4217 currency code (required)

platformstringPlatform where the transaction occurred

sessionIdstringAgent session ID for attribution

metadataobjectArbitrary key-value metadata

bash

curl -X POST https://api.cresva.ai/api/storefront/[brandId]/transactions \
  -H "Authorization: Bearer cresva_ak_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "prod_a1b2c3d4",
    "amount": 19999,
    "currency": "USD",
    "platform": "chatgpt",
    "sessionId": "sess_m4n5o6p7",
    "metadata": { "source": "external" }
  }'

javascript

const response = await fetch("https://api.cresva.ai/api/storefront/[brandId]/transactions", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.CRESVA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    productId: "prod_a1b2c3d4",
    amount: 19999,
    currency: "USD",
    platform: "chatgpt",
    sessionId: "sess_m4n5o6p7",
    metadata: { source: "external" },
  }),
});

const { data } = await response.json();

Transaction object

json

{
  "id": "txn_x9y8z7w6",
  "productId": "prod_a1b2c3d4",
  "amount": 19999,
  "currency": "USD",
  "platform": "chatgpt",
  "status": "completed",
  "createdAt": "2026-03-25T16:45:00Z"
}