Commerce API

Use the Commerce API from your backend to manage sellable items and sync sales into your own systems. All endpoints use the M2M base URL:

https://platform-api.visitoai.com/m2m/v1

M2M credentials are server-side secrets. Do not call these endpoints from browser, mobile, or embedded widget code.

Scopes

Scope	Allows
`commerce:items:read`	List and inspect catalog items.
`commerce:items:write`	Create, update, scope, and delete catalog items.
`commerce:sales:read`	List and inspect sales.

Commerce routes use the tenant attached to the M2M credential. Do not send a tenant id in the path or query string.

Item Model

{
  "itemId": "item_123",
  "tenantId": "tenant_123",
  "name": "Late checkout",
  "description": "Extend checkout until 2pm",
  "amountMinor": 2500,
  "currency": "usd",
  "active": true,
  "scope": "global",
  "allowQuantity": false,
  "minQuantity": 1,
  "maxQuantity": 1,
  "fields": [],
  "createdAt": "2026-08-18T12:00:00.000Z",
  "updatedAt": "2026-08-18T12:00:00.000Z"
}

scope is global unless the item is assigned to a business. Business-scoped items include propertyId.

List Items

GET /m2m/v1/commerce/items HTTP/1.1
Authorization: Bearer visito_m2m_...

Requires commerce:items:read.

{
  "items": []
}

Create an Item

POST /m2m/v1/commerce/items HTTP/1.1
Authorization: Bearer visito_m2m_...
Content-Type: application/json

Requires commerce:items:write.

{
  "name": "Late checkout",
  "description": "Extend checkout until 2pm",
  "amountMinor": 2500,
  "currency": "usd",
  "active": true,
  "allowQuantity": false,
  "fields": [
    {
      "label": "Customer name",
      "type": "text",
      "required": true
    }
  ]
}

Response:

{
  "item": {}
}

Supported field types: text, number, email, phone, date, and select.

Read an Item

GET /m2m/v1/commerce/items/{itemId}
Authorization: Bearer visito_m2m_...

Requires commerce:items:read.

Update an Item

PATCH /m2m/v1/commerce/items/{itemId}
Authorization: Bearer visito_m2m_...
Content-Type: application/json

Requires commerce:items:write. Send only the fields you want to change.

{
  "name": "Late checkout plus",
  "amountMinor": 3000,
  "active": true
}

Assign Item Scope

PATCH /m2m/v1/commerce/items/{itemId}/property
Authorization: Bearer visito_m2m_...
Content-Type: application/json

Requires commerce:items:write. Assign the item to one active business:

{
  "propertyId": "property_123"
}

Make the item global:

{
  "propertyId": null
}

Response:

{
  "itemId": "item_123",
  "scope": "property",
  "propertyId": "property_123"
}

Delete an Item

DELETE /m2m/v1/commerce/items/{itemId}
Authorization: Bearer visito_m2m_...

Requires commerce:items:write.

{
  "deleted": true
}

Sales

Sales are commerce purchases exposed with sales-oriented route names for external systems.

List Sales

GET /m2m/v1/commerce/sales?status=paid&limit=50 HTTP/1.1
Authorization: Bearer visito_m2m_...

Requires commerce:sales:read. Query parameters:

Parameter	Values
`limit`	`1` to `200`, default `50`
`cursor`	Opaque cursor from the previous response
`status`	`pending`, `paid`, `payment_failed`, `refunded`, `canceled`
`fulfillmentStatus`	`unfulfilled`, `fulfilled`

Response:

{
  "sales": [
    {
      "purchaseId": "purchase_01JY8Q4W9F3C2M7N6K5H1G0D8A",
      "tenantId": "tenant_123",
      "purchaseKind": "catalog_item",
      "itemId": "item_123",
      "itemName": "Initial consultation",
      "scope": "global",
      "quantity": 1,
      "unitAmountMinor": 5000,
      "totalAmountMinor": 5000,
      "amountMinor": 5000,
      "currency": "usd",
      "status": "paid",
      "fulfillmentStatus": "unfulfilled",
      "transferStatus": "transferred",
      "refundStatus": "none",
      "capturedFields": {
        "customer_name": "Sofia Reyes",
        "customer_email": "sofia@example.com"
      },
      "paidAt": "2026-08-31T18:42:17.000Z",
      "createdAt": "2026-08-31T18:40:02.000Z",
      "updatedAt": "2026-08-31T18:42:18.000Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA4LTMxVDE4OjQwOjAyLjAwMFoifQ"
}

Read a Sale

GET /m2m/v1/commerce/sales/{saleId}
Authorization: Bearer visito_m2m_...

Requires commerce:sales:read.

{
  "sale": {
    "purchaseId": "purchase_01JY8Q4W9F3C2M7N6K5H1G0D8A",
    "tenantId": "tenant_123",
    "stripeMode": "live",
    "purchaseKind": "catalog_item",
    "conversationId": "conversation_123",
    "conversationKey": "whatsapp:+525512345678",
    "itemId": "item_123",
    "itemName": "Initial consultation",
    "scope": "global",
    "quantity": 1,
    "unitAmountMinor": 5000,
    "totalAmountMinor": 5000,
    "amountMinor": 5000,
    "currency": "usd",
    "status": "paid",
    "fulfillmentStatus": "unfulfilled",
    "transferStatus": "transferred",
    "refundStatus": "none",
    "capturedFields": {
      "customer_name": "Sofia Reyes",
      "customer_email": "sofia@example.com"
    },
    "checkoutSessionId": "cs_live_123",
    "paymentIntentId": "pi_123",
    "connectedAccountId": "acct_123",
    "platformFeeBps": 1000,
    "transferId": "tr_123",
    "proofUrl": "https://example.com/commerce/proof/purchase_01JY8Q4W9F3C2M7N6K5H1G0D8A",
    "paidAt": "2026-08-31T18:42:17.000Z",
    "createdAt": "2026-08-31T18:40:02.000Z",
    "updatedAt": "2026-08-31T18:42:18.000Z"
  }
}

The list and detail endpoints return the same sale shape. Optional fields are omitted when they do not apply or are not yet available.

Field group	Fields
Identity	`purchaseId` (also used as `{saleId}`), `tenantId`, `purchaseKind`
Conversation	`conversationId`, `conversationKey`
Item and scope	`itemId`, `itemName`, `scope`, `propertyId`
Amounts	`quantity`, `unitAmountMinor`, `totalAmountMinor`, `amountMinor`, `currency`
State	`status`, `fulfillmentStatus`, `fulfilledAt`, `fulfilledBy`
Checkout	`capturedFields`, `checkoutSessionId`, `checkoutUrl`, `paymentIntentId`
Transfers	`connectedAccountId`, `platformFeeBps`, `transferStatus`, `transferId`, `transferError`, `balance`
Refunds	`refundStatus`, `refundId`, `refundAmountMinor`, `refundCurrency`, `refundReason`, `refundRequestedBy`, `refundRequestedAt`, `refundError`, transfer-reversal fields, `refundedAt`
Type-specific details	`reservation` is present only for supported reservation-deposit sales
Audit	`proofUrl`, `paidAt`, `createdAt`, `updatedAt`

All monetary fields ending in Minor use the currency’s minor unit. For example, 5000 with currency: "usd" means USD 50.00. capturedFields contains the values collected from the item fields configured at checkout.

Build With Visito

AI Coding Assistants

Scopes

Item Model

List Items

Create an Item

Read an Item

Update an Item

Assign Item Scope

Delete an Item

Sales

List Sales

Read a Sale

​Scopes

​Item Model

​List Items

​Create an Item

​Read an Item

​Update an Item

​Assign Item Scope

​Delete an Item

​Sales

​List Sales

​Read a Sale

Scopes

Item Model

List Items

Create an Item

Read an Item

Update an Item

Assign Item Scope

Delete an Item

Sales

List Sales

Read a Sale