WooCommerce Order Refunds API

openapi: 3.2.0
info:
  title: WooCommerce REST Order Refunds API
  description: The WooCommerce REST API is the primary server-side interface for reading and writing WooCommerce store data programmatically.
  version: v3
  contact:
    name: WooCommerce Developer Support
    url: https://developer.woocommerce.com/docs/apis/rest-api/
  termsOfService: https://woocommerce.com/terms-conditions/
servers:
- url: https://example.com/wp-json/wc/v3
  description: Production Server (replace example.com with your store domain)
security:
- basicAuth: []
tags:
- name: Order Refunds
  description: Create and retrieve refunds associated with orders
paths:
  /orders/{order_id}/refunds:
    get:
      operationId: listOrderRefunds
      summary: WooCommerce List All Order Refunds
      description: Returns all refunds associated with a specific order.
      tags:
      - Order Refunds
      parameters:
      - $ref: '#/components/parameters/order_id'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/per_page'
      responses:
        '200':
          description: List of order refunds
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderRefund'
              examples:
                listOrderRefunds200Example:
                  summary: Default listOrderRefunds 200 response
                  x-microcks-default: true
                  value:
                  - id: 1
                    date_created: '2026-05-03T14:30:00Z'
                    amount: string-value
                    reason: string-value
                    refunded_by: 1
                    line_items:
                    - string-value
                    meta_data:
                    - string-value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createOrderRefund
      summary: WooCommerce Create an Order Refund
      description: Creates a refund for a specific order. The refund amount, line item quantities to refund, whether to restock items, and reason can all be specified. Automatic gateway refunds are attempted when supported.
      tags:
      - Order Refunds
      parameters:
      - $ref: '#/components/parameters/order_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRefundInput'
      responses:
        '201':
          description: Refund created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderRefund'
              examples:
                createOrderRefund201Example:
                  summary: Default createOrderRefund 201 response
                  x-microcks-default: true
                  value:
                    id: 1
                    date_created: '2026-05-03T14:30:00Z'
                    amount: string-value
                    reason: string-value
                    refunded_by: 1
                    line_items:
                    - string-value
                    meta_data:
                    - string-value
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orders/{order_id}/refunds/{id}:
    get:
      operationId: getOrderRefund
      summary: WooCommerce Retrieve an Order Refund
      description: Returns a single refund by its ID for a specific order.
      tags:
      - Order Refunds
      parameters:
      - $ref: '#/components/parameters/order_id'
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Order refund details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderRefund'
              examples:
                getOrderRefund200Example:
                  summary: Default getOrderRefund 200 response
                  x-microcks-default: true
                  value:
                    id: 1
                    date_created: '2026-05-03T14:30:00Z'
                    amount: string-value
                    reason: string-value
                    refunded_by: 1
                    line_items:
                    - string-value
                    meta_data:
                    - string-value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteOrderRefund
      summary: WooCommerce Delete an Order Refund
      description: Permanently deletes a refund from an order.
      tags:
      - Order Refunds
      parameters:
      - $ref: '#/components/parameters/order_id'
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/force'
      responses:
        '200':
          description: Refund deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderRefund'
              examples:
                deleteOrderRefund200Example:
                  summary: Default deleteOrderRefund 200 response
                  x-microcks-default: true
                  value:
                    id: 1
                    date_created: '2026-05-03T14:30:00Z'
                    amount: string-value
                    reason: string-value
                    refunded_by: 1
                    line_items:
                    - string-value
                    meta_data:
                    - string-value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    force:
      name: force
      in: query
      description: Set to true to permanently delete the resource, bypassing the trash.
      required: false
      schema:
        type: boolean
        default: false
    id:
      name: id
      in: path
      description: Unique identifier for the resource.
      required: true
      schema:
        type: integer
    page:
      name: page
      in: query
      description: Current page of the collection. Defaults to 1.
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
    per_page:
      name: per_page
      in: query
      description: Maximum number of items per page. Defaults to 10, maximum 100.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
    order_id:
      name: order_id
      in: path
      description: Unique identifier of the parent order.
      required: true
      schema:
        type: integer
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code.
          example: string-value
        message:
          type: string
          description: Human-readable error message.
          example: string-value
        data:
          type: object
          description: Additional error context including HTTP status code.
          properties:
            status:
              type: integer
              description: HTTP status code associated with the error.
          example:
            status: 1
    MetaData:
      type: object
      description: Custom metadata key-value entry.
      properties:
        id:
          type: integer
          description: Metadata unique identifier.
          example: 1
        key:
          type: string
          description: Metadata key.
          example: string-value
        value:
          type: string
          description: Metadata value.
          example: string-value
    LineItem:
      type: object
      description: A product line item within an order.
      properties:
        id:
          type: integer
          description: Line item unique identifier.
          example: 1
        name:
          type: string
          description: Product name at time of purchase.
          example: Example Name
        product_id:
          type: integer
          description: Product ID.
          example: 1
        variation_id:
          type: integer
          description: Variation ID (0 if not a variation).
          example: 1
        quantity:
          type: integer
          description: Quantity ordered.
          example: 1
        tax_class:
          type: string
          description: Tax class used for this line item.
          example: string-value
        subtotal:
          type: string
          description: Line subtotal (before discounts) as a decimal string.
          example: string-value
        subtotal_tax:
          type: string
          description: Line subtotal tax as a decimal string.
          example: string-value
        total:
          type: string
          description: Line total (after discounts) as a decimal string.
          example: string-value
        total_tax:
          type: string
          description: Line total tax as a decimal string.
          example: string-value
        sku:
          type: string
          description: Product SKU.
          example: string-value
        price:
          type: number
          description: Product price at time of purchase.
          example: 10.5
        meta_data:
          type: array
          description: Metadata for the line item (e.g. variation attributes).
          items:
            $ref: '#/components/schemas/MetaData'
          example:
          - string-value
    OrderRefund:
      type: object
      description: A refund associated with an order.
      properties:
        id:
          type: integer
          description: Refund unique identifier.
          example: 1
        date_created:
          type: string
          format: date-time
          description: Date the refund was created.
          example: '2026-05-03T14:30:00Z'
        amount:
          type: string
          description: Refund amount as a decimal string.
          example: string-value
        reason:
          type: string
          description: Reason for the refund.
          example: string-value
        refunded_by:
          type: integer
          description: User ID of the person who issued the refund.
          example: 1
        line_items:
          type: array
          description: Line items included in the refund.
          items:
            $ref: '#/components/schemas/LineItem'
          example:
          - string-value
        meta_data:
          type: array
          description: Custom metadata.
          items:
            $ref: '#/components/schemas/MetaData'
          example:
          - string-value
    OrderRefundInput:
      type: object
      description: Input for creating an order refund.
      properties:
        amount:
          type: string
          description: Refund amount as a decimal string.
          example: string-value
        reason:
          type: string
          description: Reason for the refund.
          example: string-value
        refunded_by:
          type: integer
          description: User ID issuing the refund.
          example: 1
        api_refund:
          type: boolean
          description: Whether to attempt an automatic payment gateway refund.
          default: true
          example: true
        line_items:
          type: array
          description: Line items to refund with quantities and amounts.
          items:
            $ref: '#/components/schemas/LineItem'
          example:
          - string-value
  responses:
    BadRequest:
      description: The request body contains invalid or missing parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Auth using the WooCommerce Consumer Key as the username and Consumer Secret as the password over HTTPS. Over plain HTTP use OAuth 1.0a one-legged authentication instead.
externalDocs:
  description: WooCommerce REST API Documentation
  url: https://woocommerce.github.io/woocommerce-rest-api-docs/