WooCommerce Customers API

openapi: 3.2.0
info:
  title: WooCommerce REST Customers 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: Customers
  description: Create, retrieve, update, and delete customer accounts
paths:
  /customers:
    get:
      operationId: listCustomers
      summary: WooCommerce List All Customers
      description: Returns a paginated list of customers. Can be filtered by role, email, search term, and order by various fields such as id, registered date, name, or total spent.
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/per_page'
      - $ref: '#/components/parameters/search'
      - name: role
        in: query
        description: Filter customers by WordPress user role. Default is customer.
        required: false
        schema:
          type: string
        example: string-value
      - name: email
        in: query
        description: Filter customers by email address.
        required: false
        schema:
          type: string
          format: email
        example: user@example.com
      responses:
        '200':
          description: List of customers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Customer'
              examples:
                listCustomers200Example:
                  summary: Default listCustomers 200 response
                  x-microcks-default: true
                  value:
                  - id: 1
                    date_created: '2026-05-03T14:30:00Z'
                    date_modified: '2026-05-03T14:30:00Z'
                    email: user@example.com
                    first_name: Example Name
                    last_name: Example Name
                    role: string-value
                    username: Example Name
                    billing:
                      first_name: {}
                      last_name: {}
                      company: {}
                      address_1: {}
                      address_2: {}
                      city: {}
                      state: {}
                      postcode: {}
                      country: {}
                      email: {}
                      phone: {}
                    shipping:
                      first_name: {}
                      last_name: {}
                      company: {}
                      address_1: {}
                      address_2: {}
                      city: {}
                      state: {}
                      postcode: {}
                      country: {}
                      email: {}
                      phone: {}
                    is_paying_customer: true
                    orders_count: 1
                    total_spent: string-value
                    avatar_url: https://example.com/path
                    meta_data:
                    - string-value
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createCustomer
      summary: WooCommerce Create a Customer
      description: Creates a new customer account. Requires at minimum an email address and username. Billing and shipping address details can be set at creation time.
      tags:
      - Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerInput'
      responses:
        '201':
          description: Customer created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
              examples:
                createCustomer201Example:
                  summary: Default createCustomer 201 response
                  x-microcks-default: true
                  value:
                    id: 1
                    date_created: '2026-05-03T14:30:00Z'
                    date_modified: '2026-05-03T14:30:00Z'
                    email: user@example.com
                    first_name: Example Name
                    last_name: Example Name
                    role: string-value
                    username: Example Name
                    billing:
                      first_name: Example Name
                      last_name: Example Name
                      company: string-value
                      address_1: string-value
                      address_2: string-value
                      city: string-value
                      state: string-value
                      postcode: string-value
                      country: string-value
                      email: user@example.com
                      phone: string-value
                    shipping:
                      first_name: Example Name
                      last_name: Example Name
                      company: string-value
                      address_1: string-value
                      address_2: string-value
                      city: string-value
                      state: string-value
                      postcode: string-value
                      country: string-value
                      email: user@example.com
                      phone: string-value
                    is_paying_customer: true
                    orders_count: 1
                    total_spent: string-value
                    avatar_url: https://example.com/path
                    meta_data:
                    - string-value
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /customers/{id}:
    get:
      operationId: getCustomer
      summary: WooCommerce Retrieve a Customer
      description: Returns a single customer by numeric ID including billing and shipping addresses and account metadata.
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Customer details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
              examples:
                getCustomer200Example:
                  summary: Default getCustomer 200 response
                  x-microcks-default: true
                  value:
                    id: 1
                    date_created: '2026-05-03T14:30:00Z'
                    date_modified: '2026-05-03T14:30:00Z'
                    email: user@example.com
                    first_name: Example Name
                    last_name: Example Name
                    role: string-value
                    username: Example Name
                    billing:
                      first_name: Example Name
                      last_name: Example Name
                      company: string-value
                      address_1: string-value
                      address_2: string-value
                      city: string-value
                      state: string-value
                      postcode: string-value
                      country: string-value
                      email: user@example.com
                      phone: string-value
                    shipping:
                      first_name: Example Name
                      last_name: Example Name
                      company: string-value
                      address_1: string-value
                      address_2: string-value
                      city: string-value
                      state: string-value
                      postcode: string-value
                      country: string-value
                      email: user@example.com
                      phone: string-value
                    is_paying_customer: true
                    orders_count: 1
                    total_spent: string-value
                    avatar_url: https://example.com/path
                    meta_data:
                    - string-value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateCustomer
      summary: WooCommerce Update a Customer
      description: Updates a customer record by numeric ID. Only provided fields are changed.
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerInput'
      responses:
        '200':
          description: Customer updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
              examples:
                updateCustomer200Example:
                  summary: Default updateCustomer 200 response
                  x-microcks-default: true
                  value:
                    id: 1
                    date_created: '2026-05-03T14:30:00Z'
                    date_modified: '2026-05-03T14:30:00Z'
                    email: user@example.com
                    first_name: Example Name
                    last_name: Example Name
                    role: string-value
                    username: Example Name
                    billing:
                      first_name: Example Name
                      last_name: Example Name
                      company: string-value
                      address_1: string-value
                      address_2: string-value
                      city: string-value
                      state: string-value
                      postcode: string-value
                      country: string-value
                      email: user@example.com
                      phone: string-value
                    shipping:
                      first_name: Example Name
                      last_name: Example Name
                      company: string-value
                      address_1: string-value
                      address_2: string-value
                      city: string-value
                      state: string-value
                      postcode: string-value
                      country: string-value
                      email: user@example.com
                      phone: string-value
                    is_paying_customer: true
                    orders_count: 1
                    total_spent: string-value
                    avatar_url: https://example.com/path
                    meta_data:
                    - string-value
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteCustomer
      summary: WooCommerce Delete a Customer
      description: Deletes a customer by numeric ID. Set force to true to permanently delete the WordPress user account. Optionally reassign the customer's orders to another customer ID.
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/force'
      - name: reassign
        in: query
        description: User ID to reassign posts and links to.
        required: false
        schema:
          type: integer
        example: 1
      responses:
        '200':
          description: Customer deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
              examples:
                deleteCustomer200Example:
                  summary: Default deleteCustomer 200 response
                  x-microcks-default: true
                  value:
                    id: 1
                    date_created: '2026-05-03T14:30:00Z'
                    date_modified: '2026-05-03T14:30:00Z'
                    email: user@example.com
                    first_name: Example Name
                    last_name: Example Name
                    role: string-value
                    username: Example Name
                    billing:
                      first_name: Example Name
                      last_name: Example Name
                      company: string-value
                      address_1: string-value
                      address_2: string-value
                      city: string-value
                      state: string-value
                      postcode: string-value
                      country: string-value
                      email: user@example.com
                      phone: string-value
                    shipping:
                      first_name: Example Name
                      last_name: Example Name
                      company: string-value
                      address_1: string-value
                      address_2: string-value
                      city: string-value
                      state: string-value
                      postcode: string-value
                      country: string-value
                      email: user@example.com
                      phone: string-value
                    is_paying_customer: true
                    orders_count: 1
                    total_spent: string-value
                    avatar_url: https://example.com/path
                    meta_data:
                    - string-value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /customers/{id}/downloads:
    get:
      operationId: getCustomerDownloads
      summary: WooCommerce Retrieve Customer Downloads
      description: Returns a list of digital downloads available to the customer, including download links, expiry dates, remaining download counts, and product information.
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Customer downloads list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomerDownload'
              examples:
                getCustomerDownloads200Example:
                  summary: Default getCustomerDownloads 200 response
                  x-microcks-default: true
                  value:
                  - download_id: '500123'
                    download_url: https://example.com/path
                    product_id: 1
                    product_name: Example Name
                    download_name: Example Name
                    order_id: 1
                    order_key: string-value
                    downloads_remaining: string-value
                    access_expires: '2026-05-03T14:30:00Z'
                    file:
                      name: Example Name
                      file: https://example.com/path
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    search:
      name: search
      in: query
      description: Limit results to those matching a string.
      required: false
      schema:
        type: string
    force:
      name: force
      in: query
      description: Set to true to permanently delete the resource, bypassing the trash.
      required: false
      schema:
        type: boolean
        default: false
    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
    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
  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
    CustomerDownload:
      type: object
      description: A downloadable file accessible to a customer.
      properties:
        download_id:
          type: string
          description: Download unique identifier.
          example: '500123'
        download_url:
          type: string
          format: uri
          description: URL where the customer can download the file.
          example: https://example.com/path
        product_id:
          type: integer
          description: Product ID associated with this download.
          example: 1
        product_name:
          type: string
          description: Product name at time of purchase.
          example: Example Name
        download_name:
          type: string
          description: Name of the downloadable file.
          example: Example Name
        order_id:
          type: integer
          description: Order ID for this download.
          example: 1
        order_key:
          type: string
          description: Order key for verification.
          example: string-value
        downloads_remaining:
          type: string
          description: Number of downloads remaining (empty string for unlimited).
          example: string-value
        access_expires:
          type: string
          format: date-time
          description: Date and time when download access expires.
          nullable: true
          example: '2026-05-03T14:30:00Z'
        file:
          type: object
          description: File information.
          properties:
            name:
              type: string
              description: File name.
            file:
              type: string
              format: uri
              description: File URL.
          example:
            name: Example Name
            file: https://example.com/path
    CustomerInput:
      type: object
      description: Input for creating or updating a customer.
      properties:
        email:
          type: string
          format: email
          description: Customer email address.
          example: user@example.com
        first_name:
          type: string
          description: Customer first name.
          example: Example Name
        last_name:
          type: string
          description: Customer last name.
          example: Example Name
        username:
          type: string
          description: Customer login username.
          example: Example Name
        password:
          type: string
          description: Customer account password (write only, not returned).
          example: string-value
        billing:
          $ref: '#/components/schemas/Address'
        shipping:
          $ref: '#/components/schemas/Address'
        meta_data:
          type: array
          description: Custom metadata.
          items:
            $ref: '#/components/schemas/MetaData'
          example:
          - string-value
    Customer:
      type: object
      description: A WooCommerce customer account.
      properties:
        id:
          type: integer
          description: Customer unique identifier.
          example: 1
        date_created:
          type: string
          format: date-time
          description: Date the customer was created.
          example: '2026-05-03T14:30:00Z'
        date_modified:
          type: string
          format: date-time
          description: Date the customer was last modified.
          example: '2026-05-03T14:30:00Z'
        email:
          type: string
          format: email
          description: Customer email address.
          example: user@example.com
        first_name:
          type: string
          description: Customer first name.
          example: Example Name
        last_name:
          type: string
          description: Customer last name.
          example: Example Name
        role:
          type: string
          description: Customer WordPress user role.
          example: string-value
        username:
          type: string
          description: Customer login username.
          example: Example Name
        billing:
          $ref: '#/components/schemas/Address'
        shipping:
          $ref: '#/components/schemas/Address'
        is_paying_customer:
          type: boolean
          description: Whether the customer has placed at least one order.
          example: true
        orders_count:
          type: integer
          description: Total number of orders placed by the customer.
          example: 1
        total_spent:
          type: string
          description: Total amount spent by the customer as a decimal string.
          example: string-value
        avatar_url:
          type: string
          format: uri
          description: URL of the customer's Gravatar image.
          example: https://example.com/path
        meta_data:
          type: array
          description: Custom metadata attached to the customer.
          items:
            $ref: '#/components/schemas/MetaData'
          example:
          - string-value
    Address:
      type: object
      description: Billing or shipping address associated with a customer or order.
      properties:
        first_name:
          type: string
          description: First name.
          example: Example Name
        last_name:
          type: string
          description: Last name.
          example: Example Name
        company:
          type: string
          description: Company name.
          example: string-value
        address_1:
          type: string
          description: Address line 1.
          example: string-value
        address_2:
          type: string
          description: Address line 2.
          example: string-value
        city:
          type: string
          description: City name.
          example: string-value
        state:
          type: string
          description: ISO code or name of the state, province, or district.
          example: string-value
        postcode:
          type: string
          description: Postal code.
          example: string-value
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code.
          example: string-value
        email:
          type: string
          format: email
          description: Email address (billing only).
          example: user@example.com
        phone:
          type: string
          description: Phone number (billing only).
          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
  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/