WooCommerce Checkout API

openapi: 3.1.0
info:
  title: WooCommerce REST Cart Checkout 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: Checkout
  description: Submit and manage the checkout process for the current shopper
paths:
  /checkout:
    get:
      operationId: getCheckout
      summary: WooCommerce Get Checkout Data
      description: Returns the current checkout state including the cart contents, available payment methods, and pre-filled billing and shipping fields from the customer's account.
      tags:
      - Checkout
      responses:
        '200':
          description: Checkout data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout'
              examples:
                getCheckout200Example:
                  summary: Default getCheckout 200 response
                  x-microcks-default: true
                  value:
                    order_id: 1
                    billing_address:
                      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_address:
                      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
                    payment_methods:
                    - id: '500123'
                      title: Example Name
                      description: A sample description
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: processCheckout
      summary: WooCommerce Process Checkout and Place Order
      description: Submits the checkout form to create an order and process payment. Requires billing address, payment method, and optional shipping data. Requires the Nonce header. Returns the created order on success or redirects to the payment gateway for hosted gateways.
      tags:
      - Checkout
      parameters:
      - $ref: '#/components/parameters/nonce'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutInput'
      responses:
        '200':
          description: Order created and payment initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutOrder'
              examples:
                processCheckout200Example:
                  summary: Default processCheckout 200 response
                  x-microcks-default: true
                  value:
                    id: 1
                    status: active
                    order_key: string-value
                    order_number: string-value
                    customer_note: string-value
                    billing_address:
                      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_address:
                      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
                    payment_method: string-value
                    payment_result:
                      payment_status: active
                      payment_details:
                      - {}
                      redirect_url: https://example.com/path
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          description: Payment required or payment processing failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                processCheckout402Example:
                  summary: Default processCheckout 402 response
                  x-microcks-default: true
                  value:
                    code: string-value
                    message: string-value
                    data:
                      status: 1
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /checkout/{id}:
    get:
      operationId: getCheckoutOrder
      summary: WooCommerce Get a Checkout Order
      description: Returns an order placed via checkout identified by its numeric ID. Only accessible for the order owner or a store administrator.
      tags:
      - Checkout
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Checkout order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutOrder'
              examples:
                getCheckoutOrder200Example:
                  summary: Default getCheckoutOrder 200 response
                  x-microcks-default: true
                  value:
                    id: 1
                    status: active
                    order_key: string-value
                    order_number: string-value
                    customer_note: string-value
                    billing_address:
                      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_address:
                      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
                    payment_method: string-value
                    payment_result:
                      payment_status: active
                      payment_details:
                      - {}
                      redirect_url: https://example.com/path
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateCheckoutOrder
      summary: WooCommerce Update a Pending Checkout Order
      description: Updates billing, shipping, or payment method on a pending order before payment is confirmed. Requires the Nonce header.
      tags:
      - Checkout
      parameters:
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/nonce'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutInput'
      responses:
        '200':
          description: Updated checkout order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutOrder'
              examples:
                updateCheckoutOrder200Example:
                  summary: Default updateCheckoutOrder 200 response
                  x-microcks-default: true
                  value:
                    id: 1
                    status: active
                    order_key: string-value
                    order_number: string-value
                    customer_note: string-value
                    billing_address:
                      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_address:
                      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
                    payment_method: string-value
                    payment_result:
                      payment_status: active
                      payment_details:
                      - {}
                      redirect_url: https://example.com/path
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    id:
      name: id
      in: path
      description: Unique identifier for the resource.
      required: true
      schema:
        type: integer
    nonce:
      name: Nonce
      in: header
      description: Store API nonce token obtained from the X-WC-Store-API-Nonce response header of a prior cart GET request. Required for all cart and checkout write operations to prevent CSRF.
      required: true
      schema:
        type: string
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request contains invalid or missing parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    CheckoutOrder:
      type: object
      description: An order created or retrieved via the Store API checkout flow.
      properties:
        id:
          type: integer
          description: Order unique identifier.
          example: 1
        status:
          type: string
          description: Order status.
          example: active
        order_key:
          type: string
          description: Order key for ownership verification.
          example: string-value
        order_number:
          type: string
          description: Human-readable order number.
          example: string-value
        customer_note:
          type: string
          description: Customer note on the order.
          example: string-value
        billing_address:
          $ref: '#/components/schemas/StoreAddress'
        shipping_address:
          $ref: '#/components/schemas/StoreAddress'
        payment_method:
          type: string
          description: Payment method ID.
          example: string-value
        payment_result:
          type: object
          description: Result of payment processing.
          properties:
            payment_status:
              type: string
              description: Payment result status (success, pending, failure).
            payment_details:
              type: array
              description: Gateway-specific payment result details.
              items:
                type: object
            redirect_url:
              type: string
              format: uri
              description: URL to redirect the customer to after checkout.
          example:
            payment_status: active
            payment_details:
            - {}
            redirect_url: https://example.com/path
    Checkout:
      type: object
      description: Current checkout state.
      properties:
        order_id:
          type: integer
          description: Pending order ID if one exists.
          example: 1
        billing_address:
          $ref: '#/components/schemas/StoreAddress'
        shipping_address:
          $ref: '#/components/schemas/StoreAddress'
        payment_methods:
          type: array
          description: Available payment methods at checkout.
          items:
            type: object
            properties:
              id:
                type: string
                description: Payment method ID.
              title:
                type: string
                description: Payment method display title.
              description:
                type: string
                description: Payment method description shown at checkout.
          example:
          - id: '500123'
            title: Example Name
            description: A sample description
    StoreAddress:
      type: object
      description: A customer billing or shipping address in the Store API context.
      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.
          example: string-value
        state:
          type: string
          description: State or province code.
          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.
          example: string-value
    CheckoutInput:
      type: object
      description: Input payload for submitting or updating a checkout.
      required:
      - billing_address
      - payment_method
      properties:
        billing_address:
          $ref: '#/components/schemas/StoreAddress'
        shipping_address:
          $ref: '#/components/schemas/StoreAddress'
        customer_note:
          type: string
          description: Optional note from the customer.
          example: string-value
        create_account:
          type: boolean
          description: Whether to create a new customer account on checkout.
          example: true
        payment_method:
          type: string
          description: Payment method ID to use for this order.
          example: string-value
        payment_data:
          type: array
          description: Additional payment gateway data (e.g. token, nonce).
          items:
            type: object
            properties:
              key:
                type: string
                description: Payment data key.
              value:
                type: string
                description: Payment data value.
          example:
          - key: string-value
            value: string-value
    Error:
      type: object
      description: Error response returned when a request fails.
      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 context including HTTP status.
          properties:
            status:
              type: integer
              description: HTTP status code.
          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/