WooCommerce Order Refunds API

openapi: 3.1.0
info:
  title: WooCommerce REST Cart Order Refunds API
  description: The WooCommerce REST API is the primary server-side interface for reading and writing WooCommerce store data programmatically. It follows REST conventions, uses JSON for all requests and responses, and is fully integrated with the WordPress REST API under the /wp-json/wc/v3/ namespace. The API covers products, product variations, product categories, product attributes, orders, order notes, order refunds, customers, coupons, tax rates, shipping zones, payment gateways, settings, webhooks, reports, and system status. Authentication uses Consumer Key and Consumer Secret pairs generated in the WooCommerce admin, transmitted over HTTPS via HTTP Basic Auth or OAuth 1.0a over plain HTTP.
  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:
    page:
      name: page
      in: query
      description: Current page of the collection. Defaults to 1.
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
    id:
      name: id
      in: path
      description: Unique identifier for the resource.
      required: true
      schema:
        type: integer
    order_id:
      name: order_id
      in: path
      description: Unique identifier of the parent order.
      required: true
      schema:
        type: integer
    force:
      name: force
      in: query
      description: Set to true to permanently delete the resource, bypassing the trash.
      required: false
      schema:
        type: boolean
        default: false
    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
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request body contains invalid or missing parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    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
    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
    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
  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/