> ## Documentation Index
> Fetch the complete documentation index at: https://docs.visitoai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Commerce API

> Manage commerce catalog items and read sales through the Visito M2M 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:

```bash theme={null}
https://platform-api.visitoai.com/m2m/v1
```

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

## 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

```json theme={null}
{
  "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

```http theme={null}
GET /m2m/v1/commerce/items HTTP/1.1
Authorization: Bearer visito_m2m_...
```

Requires `commerce:items:read`.

```json theme={null}
{
  "items": []
}
```

## Create an Item

```http theme={null}
POST /m2m/v1/commerce/items HTTP/1.1
Authorization: Bearer visito_m2m_...
Content-Type: application/json
```

Requires `commerce:items:write`.

```json theme={null}
{
  "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:

```json theme={null}
{
  "item": {}
}
```

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

## Read an Item

```http theme={null}
GET /m2m/v1/commerce/items/{itemId}
Authorization: Bearer visito_m2m_...
```

Requires `commerce:items:read`.

## Update an Item

```http theme={null}
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.

```json theme={null}
{
  "name": "Late checkout plus",
  "amountMinor": 3000,
  "active": true
}
```

## Assign Item Scope

```http theme={null}
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:

```json theme={null}
{
  "propertyId": "property_123"
}
```

Make the item global:

```json theme={null}
{
  "propertyId": null
}
```

Response:

```json theme={null}
{
  "itemId": "item_123",
  "scope": "property",
  "propertyId": "property_123"
}
```

## Delete an Item

```http theme={null}
DELETE /m2m/v1/commerce/items/{itemId}
Authorization: Bearer visito_m2m_...
```

Requires `commerce:items:write`.

```json theme={null}
{
  "deleted": true
}
```

## Sales

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

### List Sales

```http theme={null}
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:

```json theme={null}
{
  "sales": [],
  "hasMore": false,
  "nextCursor": null
}
```

### Read a Sale

```http theme={null}
GET /m2m/v1/commerce/sales/{saleId}
Authorization: Bearer visito_m2m_...
```

Requires `commerce:sales:read`.

```json theme={null}
{
  "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.