WooCommerce Reports API

openapi: 3.1.0
info:
  title: WooCommerce REST Cart Reports 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: 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:
  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
  responses:
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    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: {}
    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/