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

# List commerce sales

> Requires `commerce:sales:read`.



## OpenAPI

````yaml /openapi.json get /commerce/sales
openapi: 3.0.3
info:
  title: Visito M2M API
  version: 1.0.0
  description: >-
    Tenant-scoped server-to-server API for channels, conversations, commerce,
    custom AI tools, and WhatsApp templates. Send operations are asynchronous
    and return queued acknowledgements. Expansion adds conversation controls,
    knowledge, sales opportunities, delivery status, reporting, and signed
    webhooks.
servers:
  - url: https://platform-api.visitoai.com/m2m/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Channels
  - name: Conversations
  - name: Commerce
  - name: Custom tools
  - name: WhatsApp templates
  - name: Properties
  - name: Knowledge
  - name: Sales CRM
  - name: Delivery
  - name: Reporting
  - name: Webhooks
paths:
  /commerce/sales:
    get:
      tags:
        - Commerce
      summary: List commerce sales
      description: Requires `commerce:sales:read`.
      operationId: listCommerceSales
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
        - name: cursor
          in: query
          schema:
            type: string
          description: Opaque cursor from the previous response.
        - name: status
          in: query
          schema:
            type: string
            enum:
              - pending
              - paid
              - payment_failed
              - refunded
              - canceled
        - name: fulfillmentStatus
          in: query
          schema:
            type: string
            enum:
              - unfulfilled
              - fulfilled
      responses:
        '200':
          description: Commerce sales page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommerceSalesResponse'
        default:
          $ref: '#/components/responses/Error'
components:
  schemas:
    CommerceSalesResponse:
      type: object
      required:
        - sales
        - hasMore
        - nextCursor
      properties:
        sales:
          type: array
          items:
            $ref: '#/components/schemas/CommerceSale'
        hasMore:
          type: boolean
        nextCursor:
          type: string
          nullable: true
      additionalProperties: false
    CommerceSale:
      type: object
      required:
        - purchaseId
        - tenantId
        - itemId
        - itemName
        - scope
        - quantity
        - unitAmountMinor
        - totalAmountMinor
        - amountMinor
        - currency
        - status
        - transferStatus
        - refundStatus
        - capturedFields
      properties:
        purchaseId:
          type: string
          description: Sale identifier. Use this as saleId in Commerce API routes.
        tenantId:
          type: string
        stripeMode:
          type: string
          enum:
            - test
            - live
        purchaseKind:
          type: string
          enum:
            - catalog_item
            - hospitality_reservation
        conversationId:
          type: string
        conversationKey:
          type: string
        itemId:
          type: string
        itemName:
          type: string
        scope:
          type: string
          enum:
            - global
            - property
        propertyId:
          type: string
        quantity:
          type: integer
          minimum: 1
        unitAmountMinor:
          type: integer
          minimum: 1
        totalAmountMinor:
          type: integer
          minimum: 1
        amountMinor:
          type: integer
          minimum: 1
        currency:
          type: string
        status:
          type: string
          enum:
            - pending
            - paid
            - payment_failed
            - refunded
            - canceled
        fulfillmentStatus:
          type: string
          enum:
            - unfulfilled
            - fulfilled
        fulfilledAt:
          type: string
          format: date-time
        fulfilledBy:
          type: string
        transferStatus:
          type: string
          enum:
            - not_ready
            - pending
            - transferred
            - failed
            - skipped
        checkoutSessionId:
          type: string
        checkoutUrl:
          type: string
          format: uri
        paymentIntentId:
          type: string
        connectedAccountId:
          type: string
        platformFeeBps:
          type: integer
          minimum: 0
          description: Platform fee in basis points.
        transferId:
          type: string
        transferError:
          type: string
        refundStatus:
          type: string
          enum:
            - none
            - pending
            - succeeded
            - failed
            - reversal_failed
        refundId:
          type: string
        refundAmountMinor:
          type: integer
          minimum: 0
        refundCurrency:
          type: string
        refundReason:
          type: string
          enum:
            - requested_by_customer
            - duplicate
            - fraudulent
            - other
        refundRequestedBy:
          type: string
        refundRequestedAt:
          type: string
          format: date-time
        refundError:
          type: string
        transferReversalId:
          type: string
        transferReversalStatus:
          type: string
          enum:
            - not_required
            - pending
            - succeeded
            - failed
        transferReversalError:
          type: string
        capturedFields:
          type: object
          additionalProperties: true
        balance:
          type: object
          required:
            - amount
            - fee
            - net
            - currency
            - originalPrice
            - platformCommission
            - providerNet
          properties:
            amount:
              type: integer
            fee:
              type: integer
            net:
              type: integer
            currency:
              type: string
            exchangeRate:
              type: number
            balanceTransactionId:
              type: string
            status:
              type: string
              enum:
                - available
                - pending
            availableOn:
              type: string
              format: date-time
            originalPrice:
              type: integer
            platformCommission:
              type: integer
            providerNet:
              type: integer
          additionalProperties: false
        proofUrl:
          type: string
          format: uri
        reservation:
          type: object
          additionalProperties: true
        paidAt:
          type: string
          format: date-time
        refundedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      additionalProperties: true
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              example: M2M_AUTH_INSUFFICIENT_SCOPE
            message:
              type: string
            details:
              type: object
              additionalProperties: true
      example:
        error:
          code: M2M_AUTH_INSUFFICIENT_SCOPE
          message: M2M credential does not have required scope.
          details:
            requiredScopes:
              - conversations:write
            missingScopes:
              - conversations:write
  responses:
    Error:
      description: Structured error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Visito M2M API key
      description: Server-side tenant-scoped credential created from Build > API Keys.

````