WooCommerce Reports API

openapi: 3.2.0
info:
  title: WooCommerce REST Reports 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: Reports
  description: Retrieve aggregated sales, product, and customer report data
paths:
  /reports/sales:
    get:
      operationId: getSalesReport
      summary: WooCommerce Retrieve a Sales Report
      description: Returns aggregate sales data for a given date period. Includes totals for orders, items, discounts, shipping, refunds, taxes, and net sales. Supports period shortcuts (week, month, last_month, year) and custom date ranges.
      tags:
      - Reports
      parameters:
      - name: period
        in: query
        description: 'Report period shortcut. Options: week, month, last_month, year.'
        required: false
        schema:
          type: string
          enum:
          - week
          - month
          - last_month
          - year
        example: week
      - $ref: '#/components/parameters/after'
      - $ref: '#/components/parameters/before'
      responses:
        '200':
          description: Sales report data
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SalesReport'
              examples:
                getSalesReport200Example:
                  summary: Default getSalesReport 200 response
                  x-microcks-default: true
                  value:
                  - total_sales: string-value
                    net_revenue: string-value
                    average_sales: string-value
                    total_orders: 1
                    total_items: 1
                    total_tax: string-value
                    total_shipping: string-value
                    total_refunds: 10.5
                    total_discount: 10.5
                    totals_grouped_by: string-value
                    totals: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  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
    SalesReport:
      type: object
      description: Aggregated sales report data for a time period.
      properties:
        total_sales:
          type: string
          description: Total gross sales for the period.
          example: string-value
        net_revenue:
          type: string
          description: Net revenue (gross sales minus refunds).
          example: string-value
        average_sales:
          type: string
          description: Average daily sales for the period.
          example: string-value
        total_orders:
          type: integer
          description: Total number of orders in the period.
          example: 1
        total_items:
          type: integer
          description: Total number of items sold.
          example: 1
        total_tax:
          type: string
          description: Total tax collected.
          example: string-value
        total_shipping:
          type: string
          description: Total shipping revenue.
          example: string-value
        total_refunds:
          type: number
          description: Total refund amount.
          example: 10.5
        total_discount:
          type: number
          description: Total discount amount.
          example: 10.5
        totals_grouped_by:
          type: string
          description: Grouping interval for totals_by_date (day, week, month, year).
          example: string-value
        totals:
          type: object
          description: Sales totals grouped by the totals_grouped_by interval.
          additionalProperties: true
          example: {}
  responses:
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    after:
      name: after
      in: query
      description: Limit response to resources created after a given ISO8601 compliant date.
      required: false
      schema:
        type: string
        format: date-time
    before:
      name: before
      in: query
      description: Limit response to resources created before a given ISO8601 compliant date.
      required: false
      schema:
        type: string
        format: date-time
  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/