WooCommerce Customers API

openapi: 3.1.0
info:
  title: WooCommerce REST Cart Customers 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: 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:
  schemas:
    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
    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
    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
    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
    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
    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
  parameters:
    id:
      name: id
      in: path
      description: Unique identifier for the resource.
      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
    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
    search:
      name: search
      in: query
      description: Limit results to those matching a string.
      required: false
      schema:
        type: string
  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'
  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/