WooCommerce Cart API

openapi: 3.1.0
info:
  title: WooCommerce REST Cart 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: Cart
  description: Manage the current shopper's cart session including items, coupons, and shipping
paths:
  /cart:
    get:
      operationId: getCart
      summary: WooCommerce Get the Current Cart
      description: Returns the current customer's cart contents including items, coupons, fees, totals, and available shipping rates. The response also includes a nonce token in the X-WC-Store-API-Nonce header (and body) required for write operations.
      tags:
      - Cart
      responses:
        '200':
          description: Cart contents and totals
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
              examples:
                getCart200Example:
                  summary: Default getCart 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - string-value
                    coupons:
                    - code: string-value
                      discount_type: standard
                      totals: {}
                    fees:
                    - id: '500123'
                      name: Example Name
                      totals: {}
                    totals:
                      total_items: string-value
                      total_items_tax: string-value
                      total_fees: string-value
                      total_fees_tax: string-value
                      total_discount: string-value
                      total_discount_tax: string-value
                      total_shipping: string-value
                      total_shipping_tax: string-value
                      total_price: string-value
                      total_tax: string-value
                      tax_lines:
                      - name: Example Name
                        price: string-value
                        rate: string-value
                    shipping_rates:
                    - 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
                    has_calculated_shipping: true
                    needs_payment: true
                    needs_shipping: true
                    items_count: 1
                    items_weight: 10.5
                    cross_sells:
                    - string-value
                    errors:
                    - code: string-value
                      message: string-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /cart/add-item:
    post:
      operationId: addCartItem
      summary: WooCommerce Add an Item to the Cart
      description: Adds a product or variation to the cart. Requires a product_id, an optional variation_id, and quantity. Custom item data can be passed via the item_data array. Requires the Nonce header from a prior cart GET.
      tags:
      - Cart
      parameters:
      - $ref: '#/components/parameters/nonce'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddCartItemInput'
      responses:
        '200':
          description: Updated cart after adding item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
              examples:
                addCartItem200Example:
                  summary: Default addCartItem 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - string-value
                    coupons:
                    - code: string-value
                      discount_type: standard
                      totals: {}
                    fees:
                    - id: '500123'
                      name: Example Name
                      totals: {}
                    totals:
                      total_items: string-value
                      total_items_tax: string-value
                      total_fees: string-value
                      total_fees_tax: string-value
                      total_discount: string-value
                      total_discount_tax: string-value
                      total_shipping: string-value
                      total_shipping_tax: string-value
                      total_price: string-value
                      total_tax: string-value
                      tax_lines:
                      - name: Example Name
                        price: string-value
                        rate: string-value
                    shipping_rates:
                    - 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
                    has_calculated_shipping: true
                    needs_payment: true
                    needs_shipping: true
                    items_count: 1
                    items_weight: 10.5
                    cross_sells:
                    - string-value
                    errors:
                    - code: string-value
                      message: string-value
        '400':
          $ref: '#/components/responses/BadRequest'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /cart/remove-item:
    post:
      operationId: removeCartItem
      summary: WooCommerce Remove an Item from the Cart
      description: Removes a cart item identified by its unique cart item key. Requires the Nonce header.
      tags:
      - Cart
      parameters:
      - $ref: '#/components/parameters/nonce'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - key
              properties:
                key:
                  type: string
                  description: The unique cart item key to remove.
      responses:
        '200':
          description: Updated cart after removing item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
              examples:
                removeCartItem200Example:
                  summary: Default removeCartItem 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - string-value
                    coupons:
                    - code: string-value
                      discount_type: standard
                      totals: {}
                    fees:
                    - id: '500123'
                      name: Example Name
                      totals: {}
                    totals:
                      total_items: string-value
                      total_items_tax: string-value
                      total_fees: string-value
                      total_fees_tax: string-value
                      total_discount: string-value
                      total_discount_tax: string-value
                      total_shipping: string-value
                      total_shipping_tax: string-value
                      total_price: string-value
                      total_tax: string-value
                      tax_lines:
                      - name: Example Name
                        price: string-value
                        rate: string-value
                    shipping_rates:
                    - 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
                    has_calculated_shipping: true
                    needs_payment: true
                    needs_shipping: true
                    items_count: 1
                    items_weight: 10.5
                    cross_sells:
                    - string-value
                    errors:
                    - code: string-value
                      message: string-value
        '400':
          $ref: '#/components/responses/BadRequest'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /cart/update-item:
    post:
      operationId: updateCartItem
      summary: WooCommerce Update a Cart Item Quantity
      description: Updates the quantity of a cart item identified by its key. Set quantity to 0 to remove the item. Requires the Nonce header.
      tags:
      - Cart
      parameters:
      - $ref: '#/components/parameters/nonce'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - key
              - quantity
              properties:
                key:
                  type: string
                  description: Cart item key to update.
                quantity:
                  type: integer
                  description: New quantity. Set to 0 to remove the item.
                  minimum: 0
      responses:
        '200':
          description: Updated cart
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
              examples:
                updateCartItem200Example:
                  summary: Default updateCartItem 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - string-value
                    coupons:
                    - code: string-value
                      discount_type: standard
                      totals: {}
                    fees:
                    - id: '500123'
                      name: Example Name
                      totals: {}
                    totals:
                      total_items: string-value
                      total_items_tax: string-value
                      total_fees: string-value
                      total_fees_tax: string-value
                      total_discount: string-value
                      total_discount_tax: string-value
                      total_shipping: string-value
                      total_shipping_tax: string-value
                      total_price: string-value
                      total_tax: string-value
                      tax_lines:
                      - name: Example Name
                        price: string-value
                        rate: string-value
                    shipping_rates:
                    - 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
                    has_calculated_shipping: true
                    needs_payment: true
                    needs_shipping: true
                    items_count: 1
                    items_weight: 10.5
                    cross_sells:
                    - string-value
                    errors:
                    - code: string-value
                      message: string-value
        '400':
          $ref: '#/components/responses/BadRequest'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /cart/apply-coupon:
    post:
      operationId: applyCartCoupon
      summary: WooCommerce Apply a Coupon to the Cart
      description: Applies a coupon code to the current cart session. Returns an error if the coupon is invalid, expired, or does not meet usage conditions. Requires the Nonce header.
      tags:
      - Cart
      parameters:
      - $ref: '#/components/parameters/nonce'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - code
              properties:
                code:
                  type: string
                  description: Coupon code to apply to the cart.
      responses:
        '200':
          description: Updated cart with coupon applied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
              examples:
                applyCartCoupon200Example:
                  summary: Default applyCartCoupon 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - string-value
                    coupons:
                    - code: string-value
                      discount_type: standard
                      totals: {}
                    fees:
                    - id: '500123'
                      name: Example Name
                      totals: {}
                    totals:
                      total_items: string-value
                      total_items_tax: string-value
                      total_fees: string-value
                      total_fees_tax: string-value
                      total_discount: string-value
                      total_discount_tax: string-value
                      total_shipping: string-value
                      total_shipping_tax: string-value
                      total_price: string-value
                      total_tax: string-value
                      tax_lines:
                      - name: Example Name
                        price: string-value
                        rate: string-value
                    shipping_rates:
                    - 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
                    has_calculated_shipping: true
                    needs_payment: true
                    needs_shipping: true
                    items_count: 1
                    items_weight: 10.5
                    cross_sells:
                    - string-value
                    errors:
                    - code: string-value
                      message: string-value
        '400':
          $ref: '#/components/responses/BadRequest'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /cart/remove-coupon:
    post:
      operationId: removeCartCoupon
      summary: WooCommerce Remove a Coupon from the Cart
      description: Removes a previously applied coupon code from the cart. Requires the Nonce header.
      tags:
      - Cart
      parameters:
      - $ref: '#/components/parameters/nonce'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - code
              properties:
                code:
                  type: string
                  description: Coupon code to remove from the cart.
      responses:
        '200':
          description: Updated cart with coupon removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
              examples:
                removeCartCoupon200Example:
                  summary: Default removeCartCoupon 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - string-value
                    coupons:
                    - code: string-value
                      discount_type: standard
                      totals: {}
                    fees:
                    - id: '500123'
                      name: Example Name
                      totals: {}
                    totals:
                      total_items: string-value
                      total_items_tax: string-value
                      total_fees: string-value
                      total_fees_tax: string-value
                      total_discount: string-value
                      total_discount_tax: string-value
                      total_shipping: string-value
                      total_shipping_tax: string-value
                      total_price: string-value
                      total_tax: string-value
                      tax_lines:
                      - name: Example Name
                        price: string-value
                        rate: string-value
                    shipping_rates:
                    - 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
                    has_calculated_shipping: true
                    needs_payment: true
                    needs_shipping: true
                    items_count: 1
                    items_weight: 10.5
                    cross_sells:
                    - string-value
                    errors:
                    - code: string-value
                      message: string-value
        '400':
          $ref: '#/components/responses/BadRequest'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /cart/update-customer:
    post:
      operationId: updateCartCustomer
      summary: WooCommerce Update Cart Customer Data
      description: Updates billing and/or shipping address information for the current cart session. Used to recalculate shipping rates and taxes based on the customer's location. Requires the Nonce header.
      tags:
      - Cart
      parameters:
      - $ref: '#/components/parameters/nonce'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartCustomerInput'
      responses:
        '200':
          description: Updated cart with recalculated rates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
              examples:
                updateCartCustomer200Example:
                  summary: Default updateCartCustomer 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - string-value
                    coupons:
                    - code: string-value
                      discount_type: standard
                      totals: {}
                    fees:
                    - id: '500123'
                      name: Example Name
                      totals: {}
                    totals:
                      total_items: string-value
                      total_items_tax: string-value
                      total_fees: string-value
                      total_fees_tax: string-value
                      total_discount: string-value
                      total_discount_tax: string-value
                      total_shipping: string-value
                      total_shipping_tax: string-value
                      total_price: string-value
                      total_tax: string-value
                      tax_lines:
                      - name: Example Name
                        price: string-value
                        rate: string-value
                    shipping_rates:
                    - 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
                    has_calculated_shipping: true
                    needs_payment: true
                    needs_shipping: true
                    items_count: 1
                    items_weight: 10.5
                    cross_sells:
                    - string-value
                    errors:
                    - code: string-value
                      message: string-value
        '400':
          $ref: '#/components/responses/BadRequest'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /cart/select-shipping-rate:
    post:
      operationId: selectCartShippingRate
      summary: WooCommerce Select a Shipping Rate for the Cart
      description: Selects a specific shipping rate from those available for the customer's shipping address. Requires the Nonce header.
      tags:
      - Cart
      parameters:
      - $ref: '#/components/parameters/nonce'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - package_id
              - rate_id
              properties:
                package_id:
                  type: integer
                  description: The shipping package index to update.
                rate_id:
                  type: string
                  description: The ID of the shipping rate to select.
      responses:
        '200':
          description: Updated cart with selected shipping rate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
              examples:
                selectCartShippingRate200Example:
                  summary: Default selectCartShippingRate 200 response
                  x-microcks-default: true
                  value:
                    items:
                    - string-value
                    coupons:
                    - code: string-value
                      discount_type: standard
                      totals: {}
                    fees:
                    - id: '500123'
                      name: Example Name
                      totals: {}
                    totals:
                      total_items: string-value
                      total_items_tax: string-value
                      total_fees: string-value
                      total_fees_tax: string-value
                      total_discount: string-value
                      total_discount_tax: string-value
                      total_shipping: string-value
                      total_shipping_tax: string-value
                      total_price: string-value
                      total_tax: string-value
                      tax_lines:
                      - name: Example Name
                        price: string-value
                        rate: string-value
                    shipping_rates:
                    - 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
                    has_calculated_shipping: true
                    needs_payment: true
                    needs_shipping: true
                    items_count: 1
                    items_weight: 10.5
                    cross_sells:
                    - string-value
                    errors:
                    - code: string-value
                      message: string-value
        '400':
          $ref: '#/components/responses/BadRequest'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /cart/items:
    get:
      operationId: listCartItems
      summary: WooCommerce List Cart Items
      description: Returns a list of all items currently in the cart session.
      tags:
      - Cart
      responses:
        '200':
          description: List of cart items
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CartItem'
              examples:
                listCartItems200Example:
                  summary: Default listCartItems 200 response
                  x-microcks-default: true
                  value:
                  - key: string-value
                    id: 1
                    quantity: 1
                    variation_id: 1
                    item_data:
                    - name: Example Name
                      value: string-value
                      display: string-value
                    prices:
                      price: {}
                      regular_price: {}
                      sale_price: {}
                      price_range: {}
                      currency_code: {}
                      currency_symbol: {}
                      currency_decimal_separator: {}
                      currency_thousand_separator: {}
                      currency_prefix: {}
                      currency_suffix: {}
                    name: Example Name
                    short_description: A sample description
                    images:
                    - string-value
                    

# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/woocommerce/refs/heads/main/openapi/woocommerce-cart-api-openapi.yml