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 property. Property-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": "Guest 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 property:

{
  "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": [],
  "hasMore": false,
  "nextCursor": null
}

Read a Sale

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

Requires commerce:sales:read.

{
  "sale": {}
}

Sale objects include payment status, fulfillment status, transfer/refund fields, captured checkout fields, linked conversation fields when available, and reservation details for reservation deposit purchases.

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