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

# List refunds

> Lists the refunds made for the stores you can reach in the mode of your API key, newest first. Filter by payment, store or status, and page through the results with the cursor parameters.

> [!WARNING]
>
> Payments and refunds are in beta. Contact Vori Support to enable them for your account. Until they are enabled, these endpoints answer `403 Forbidden`.


## OpenAPI

````yaml api/openapi.json GET /v1/refunds
openapi: 3.0.0
info:
  title: Vori API
  description: ''
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.vori.com
    description: production
security: []
tags: []
paths:
  /v1/refunds:
    get:
      tags:
        - Refunds
      summary: List refunds
      description: >-
        Lists the refunds made for the stores you can reach in the mode of your
        API key, newest first. Filter by payment, store or status, and page
        through the results with the cursor parameters.
      operationId: listRefunds
      parameters:
        - name: ending_before
          required: false
          in: query
          description: Return records that precede the record with this ID, in list order.
          schema:
            type: string
        - name: limit
          required: false
          in: query
          description: Maximum number of records to return.
          schema:
            minimum: 1
            maximum: 100
            default: 20
            type: integer
        - name: payment_id
          required: false
          in: query
          style: form
          explode: true
          description: >-
            ID of the payment being refunded. Accepts a TypeID or a UUID. Repeat
            to match any of up to 20 values.
          schema:
            type: array
            items:
              type: string
        - name: starting_after
          required: false
          in: query
          description: Return records that follow the record with this ID, in list order.
          schema:
            type: string
        - name: status
          required: false
          in: query
          style: form
          explode: true
          description: >-
            Where the refund stands: `captured` once the money was given back,
            and `failed` when the processor refused it. A refund is never
            `authorized`. A refund the processor has not answered for yet is not
            served at all, and goes on holding that part of the payment until
            its outcome is known. Repeat to match any of up to 20 values.
          schema:
            type: array
            items:
              type: string
              enum:
                - authorized
                - captured
                - failed
        - name: store_id
          required: false
          in: query
          style: form
          explode: true
          description: >-
            ID of the store the refund was made for. Repeat to match any of up
            to 20 values.
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRefundList'
        '400':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ConflictingListParametersError'
                  - $ref: '#/components/schemas/InvalidListCursorError'
        '403':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/InsufficientPermissionsError'
                  - $ref: '#/components/schemas/NoBannerAssociationError'
      security:
        - bearer: []
components:
  schemas:
    PaymentRefundList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PaymentRefund'
        has_more:
          type: boolean
          description: Whether more records follow this page.
      required:
        - data
        - has_more
    ConflictingListParametersError:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - conflicting_list_parameters
      required:
        - error_code
    InvalidListCursorError:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - invalid_list_cursor
      required:
        - error_code
    InsufficientPermissionsError:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - insufficient_permissions
        error_details:
          $ref: '#/components/schemas/InsufficientPermissionsErrorDetails'
      required:
        - error_code
        - error_details
    NoBannerAssociationError:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - no_banner_association
      required:
        - error_code
    PaymentRefund:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the record.
        amount:
          type: string
          description: Amount returned to the card, in dollars.
          format: positive-monetary
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '199.99'
        created_at:
          type: string
          description: When the record was created.
          format: date-time
        idempotency_key:
          type: string
          description: >-
            Your own key for the refund, unique within the banner and mode.
            Sending the same key again returns the refund already made rather
            than refunding twice. Up to 255 characters.
        metadata:
          type: object
          maxProperties: 50
          additionalProperties:
            type: string
            maxLength: 500
          example:
            order_source: shopify
            fulfillment_id: '88213'
          nullable: true
          description: >-
            Your own key/value pairs, exactly as supplied when the refund was
            made.
        mode:
          description: >-
            Whether money moves for real or not: `test` refunds in the payment
            processor's test environment and never moves money, and `live` makes
            an actual refund. It is always the `mode` of the payment being
            refunded.
          allOf:
            - $ref: '#/components/schemas/PaymentMode'
        payment_id:
          type: string
          description: ID of the payment being refunded.
        processor:
          description: >-
            The payment processor that handled the refund, which is the one that
            took the payment.
          allOf:
            - $ref: '#/components/schemas/PaymentProcessor'
        status:
          description: >-
            Where the refund stands: `captured` once the money was given back,
            and `failed` when the processor refused it. A refund is never
            `authorized`. A refund the processor has not answered for yet is not
            served at all, and goes on holding that part of the payment until
            its outcome is known.
          allOf:
            - $ref: '#/components/schemas/PaymentStatus'
        store_id:
          type: string
          description: ID of the store the refund was made for.
          pattern: ^[0-9]+$
        type:
          description: >-
            How the money was given back: `void` cancels the charge before it
            settles, and `return` sends money back to the card. Vori picks
            whichever the payment still allows.
          allOf:
            - $ref: '#/components/schemas/PaymentRefundType'
        updated_at:
          type: string
          description: When the record was last changed.
          format: date-time
      description: >-
        A refund of a card payment taken through the Vori API. One refund is one
        attempt to give money back, and a refund is never edited once the
        processor has answered.
      required:
        - id
        - amount
        - created_at
        - idempotency_key
        - metadata
        - mode
        - payment_id
        - processor
        - status
        - store_id
        - type
        - updated_at
    InsufficientPermissionsErrorDetails:
      type: object
      properties:
        action:
          allOf:
            - $ref: '#/components/schemas/Action'
        resource:
          allOf:
            - $ref: '#/components/schemas/Resource'
      required:
        - action
        - resource
    PaymentMode:
      type: string
      enum:
        - live
        - test
      description: Live or test. A test payment moves no money.
    PaymentProcessor:
      type: string
      enum:
        - datacap
      description: >-
        The payment processor that handled the charge, which is the one
        configured for the store.
    PaymentStatus:
      type: string
      enum:
        - authorized
        - captured
        - failed
      description: >-
        Where the payment stands: `captured` once the amount was taken from the
        card, `authorized` while the processor only holds it, and `failed` when
        the card was refused. A payment the processor has not answered for yet
        is not served at all: sending the same request again with the same
        `idempotency_key` and the same `token` settles it.
    PaymentRefundType:
      type: string
      enum:
        - return
        - void
      description: >-
        How the money was given back: `void` cancels the charge before it
        settles, and `return` sends money back to the card. Vori picks whichever
        the payment still allows.
    Action:
      type: string
      enum:
        - '*'
        - cancel
        - check_in
        - create
        - delete
        - read
        - read_credentials
        - record_events
        - refund
        - restart
        - update
        - void
    Resource:
      type: string
      enum:
        - '*'
        - accounting_integration
        - agent_chats
        - agent_job_settings
        - agent_tasks
        - agents
        - api_clients
        - asynchronous_tasks
        - banners
        - billing
        - blackhawk_transactions
        - business_entities
        - capabilities
        - coupons
        - custom_quick_actions
        - datacap_transactions
        - departments
        - discounts
        - ditto_auth_tokens
        - doordash_enrollments
        - edge_agents
        - electronic_shelf_labels
        - employees
        - feature_orientations
        - files
        - food_modifiers
        - gift_cards
        - gl_code_mappings
        - house_account_payment_links
        - house_account_payments
        - house_accounts
        - inventory
        - inventory_sessions
        - inventory_settings
        - invoices
        - item_modifiers
        - label_dimension_sets
        - label_sheet_profiles
        - label_stock_products
        - lanes
        - loyalty_bonuses
        - loyalty_campaigns
        - loyalty_rewards
        - notification_templates
        - offers
        - order_guides
        - orders
        - payments
        - people
        - pos_banner_configurations
        - pos_orders
        - pos_tills
        - price_settings
        - price_tags
        - product_attributes
        - product_ranges
        - products
        - promotions
        - purchase_orders
        - receiving
        - reporting
        - revision_sessions
        - revisions
        - roles
        - shopper_tags
        - shoppers
        - store_product_inventory_counts
        - store_product_lots
        - store_product_rules
        - store_product_tag_templates
        - store_snap_incentive_program_coupons
        - store_vendor_merge_requests
        - store_vendor_product_merge_requests
        - store_vendor_products
        - store_vendors
        - stores
        - tag_printings
        - tag_template_presets
        - tag_templates
        - tax_rates
        - users
        - variable_weights
        - vendor_data_requests
        - vendor_merge_requests
        - vendor_product_merge_requests
        - vendor_products
        - vendor_store_department_accounts
        - vendors
        - wallet_payments
        - wic_products
  securitySchemes:
    bearer:
      type: http
      scheme: bearer

````

## Related topics

- [Accept card payments online](https://help.vori.com/api/accept-card-payments-online.md)
- [List payments](https://help.vori.com/api/payments/list.md)
- [List transactions](https://help.vori.com/api-reference/transactions/list-transactions.md)
