openapi-cocart-plus-v2-collection.yaml

openapi: 3.0.3
info:
  title: CoCart Plus - API v2
  version: 2.0.0
  description: |
    CoCart Plus extends the CoCart REST API v2 with additional cart endpoints (mini cart,
    coupons, fees, removing all items, setting shipping methods), product shipping rate
    calculation, customer account endpoints (including orders and subscriptions) and
    customer registration.

    Requires CoCart Starter v5.0+ to be installed and active.

    When the geolocation feature is enabled, responses include `Country`,
    `Country-Code`, `Region` and `Timezone` headers.
    When rate limiting is enabled, responses include `RateLimit-Limit`,
    `RateLimit-Remaining` and `RateLimit-Reset` headers (plus `RateLimit-Retry-After`
    on 429 responses).
  termsOfService: https://cocartapi.com/terms-of-conditions-polar/
  contact:
    email: support@cocartapi.com
  license:
    name: GNU General Public License v3.0
    url: http://www.gnu.org/licenses/gpl-3.0.html
externalDocs:
  description: Find out more about CoCart API
  url: https://docs.cocartapi.com
servers:
  - url: '{protocol}://{host}/wp-json/cocart/v2'
    description: API v2
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
      host:
        default: example-store.com
        description: Your store domain
tags:
  - name: mini-cart
    description: Operations for a lightweight mini cart response
  - name: coupons
    description: Operations for managing coupons applied to the cart
  - name: fees
    description: Operations for managing cart fees
  - name: cart-items
    description: Operations for managing cart items
  - name: shipping
    description: Operations for managing shipping on the cart
  - name: products
    description: Operations for product shipping calculations
  - name: my-account
    description: Operations for the customer account dashboard, downloads, orders and subscriptions
  - name: customers
    description: Operations for registering customers
paths:
  /cart/mini:
    get:
      tags:
        - mini-cart
      summary: Get mini cart
      description: |
        Returns a lightweight version of the cart scoped to only the fields needed
        to render a mini cart: items, item count, currency and subtotal.
      parameters:
        - $ref: '#/components/parameters/CartKey'
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Thumb'
        - $ref: '#/components/parameters/DefaultCart'
        - $ref: '#/components/parameters/Formatted'
      responses:
        '200':
          description: Mini cart retrieved successfully.
          headers:
            Country:
              $ref: '#/components/headers/GeoCountry'
            Country-Code:
              $ref: '#/components/headers/GeoCountryCode'
            Region:
              $ref: '#/components/headers/GeoRegion'
            Timezone:
              $ref: '#/components/headers/GeoTimezone'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MiniCart'
              example:
                cart_hash: e629fa6598d732768f7c726b4b621285
                cart_key: cb7a23af96a3f23af3c28a8b4b8c6d5e
                currency:
                  currency_code: USD
                  currency_symbol: $
                  currency_symbol_pos: left
                  currency_minor_unit: 2
                  currency_decimal_separator: .
                  currency_thousand_separator: ','
                  currency_prefix: $
                  currency_suffix: ''
                item_count: 2
                items:
                  - item_key: 6364d3f0f495b6ab9dcf8d3b5c6e0b01
                    id: 123
                    name: Premium Quality T-Shirt
                    price: '1800'
                    quantity: 2
                    variation: []
                    cart_item_data: {}
                    featured_image: https://example-store.com/wp-content/uploads/2024/03/tshirt.jpg
                subtotal: '3600'
        '403':
          description: Forbidden - the minimum required version of CoCart is not installed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_minimum_version_required
                message: You do not have the minimum required version of CoCart installed to use this endpoint.
                data:
                  status: 403
  /cart/coupons:
    get:
      tags:
        - coupons
      summary: Get applied coupons
      description: |
        Returns the coupons applied to the cart with the discount totals for each coupon.
      parameters:
        - $ref: '#/components/parameters/CartKey'
      responses:
        '200':
          description: Applied coupons retrieved successfully.
          headers:
            Country:
              $ref: '#/components/headers/GeoCountry'
            Country-Code:
              $ref: '#/components/headers/GeoCountryCode'
            Region:
              $ref: '#/components/headers/GeoRegion'
            Timezone:
              $ref: '#/components/headers/GeoTimezone'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AppliedCouponDetailed'
              example:
                - coupon: summer10
                  label: 'Coupon: summer10'
                  discount_type: percent
                  totals:
                    discount: '360'
                    discount_tax: '0'
        '404':
          description: Not found - coupons are not enabled or no coupons are applied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                not_enabled:
                  summary: Coupons not enabled
                  value:
                    code: cocart_coupons_not_enabled
                    message: Coupons are not enabled for this store!
                    data:
                      status: 404
                none_applied:
                  summary: No coupons applied
                  value:
                    code: cocart_cart_no_coupons_applied
                    message: No coupons are applied to the cart!
                    data:
                      status: 404
    delete:
      tags:
        - coupons
      summary: Remove all coupons
      description: |
        Removes all coupons applied to the cart and returns the updated cart.
      parameters:
        - $ref: '#/components/parameters/CartKey'
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Thumb'
        - $ref: '#/components/parameters/DefaultCart'
        - $ref: '#/components/parameters/Formatted'
      responses:
        '200':
          description: All coupons removed. Returns the updated cart.
          headers:
            Country:
              $ref: '#/components/headers/GeoCountry'
            Country-Code:
              $ref: '#/components/headers/GeoCountryCode'
            Region:
              $ref: '#/components/headers/GeoRegion'
            Timezone:
              $ref: '#/components/headers/GeoTimezone'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartV2'
        '404':
          description: Not found - coupons are not enabled for this store.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_coupons_not_enabled
                message: Coupons are not enabled for this store!
                data:
                  status: 404
  /cart/coupons/validate:
    get:
      tags:
        - coupons
      summary: Validate applied coupons
      description: |
        Checks all coupons applied to the cart to see if they are still valid.
        Invalid or expired coupons are removed from the cart. Coupons with email
        restrictions are checked against the customers billing email. The updated
        cart is returned with notices describing the validation results.
      parameters:
        - $ref: '#/components/parameters/CartKey'
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Thumb'
        - $ref: '#/components/parameters/DefaultCart'
        - $ref: '#/components/parameters/Formatted'
        - name: email
          in: query
          description: Customers billing email address used to check coupons restricted to certain email addresses.
          schema:
            type: string
            format: email
          required: false
      responses:
        '200':
          description: Coupons validated. Returns the updated cart with validation notices.
          headers:
            Country:
              $ref: '#/components/headers/GeoCountry'
            Country-Code:
              $ref: '#/components/headers/GeoCountryCode'
            Region:
              $ref: '#/components/headers/GeoRegion'
            Timezone:
              $ref: '#/components/headers/GeoTimezone'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartV2'
        '404':
          description: Not found - coupons are not enabled for this store.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_coupons_not_enabled
                message: Coupons are not enabled for this store!
                data:
                  status: 404
  /cart/apply-coupon:
    post:
      tags:
        - coupons
      summary: Apply coupon to cart
      description: |
        Applies a coupon code to the cart and returns the updated cart. If the coupon
        is already applied, the cart is returned with an informational notice.
        Coupons with email restrictions are checked against the customers billing
        email when provided.
      parameters:
        - $ref: '#/components/parameters/CartKey'
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Thumb'
        - $ref: '#/components/parameters/DefaultCart'
        - $ref: '#/components/parameters/Formatted'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  description: Coupon code to apply to the cart.
                  type: string
                email:
                  description: Customers email address used to check coupons restricted to certain email addresses.
                  type: string
                  format: email
              required:
                - code
            example:
              code: summer10
      responses:
        '200':
          description: Coupon applied. Returns the updated cart.
          headers:
            Country:
              $ref: '#/components/headers/GeoCountry'
            Country-Code:
              $ref: '#/components/headers/GeoCountryCode'
            Region:
              $ref: '#/components/headers/GeoRegion'
            Timezone:
              $ref: '#/components/headers/GeoTimezone'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartV2'
        '404':
          description: Not found - coupons not enabled, no code provided, cart empty or coupon does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                coupons_not_enabled:
                  summary: Coupons are not enabled for this store
                  value:
                    code: cocart_coupons_not_enabled
                    message: Coupons are not enabled for this store!
                    data:
                      status: 404
                code_required:
                  summary: No coupon code provided
                  value:
                    code: cocart_coupon_code_required
                    message: No coupon code provided!
                    data:
                      status: 404
                not_exist:
                  summary: Coupon does not exist
                  value:
                    code: cocart_coupon_not_exist
                    message: Coupon "summer10" does not exist!
                    data:
                      status: 404
                cannot_add:
                  summary: Cart is empty
                  value:
                    code: cocart_coupon_cannot_add
                    message: Coupon cannot be applied to cart with no items.
                    data:
                      status: 404
  /cart/coupons/{code}:
    delete:
      tags:
        - coupons
      summary: Remove coupon by code
      description: |
        Removes a single coupon from the cart by its coupon code and returns the updated cart.
      parameters:
        - name: code
          in: path
          description: The coupon code to remove from the cart.
          required: true
          schema:
            type: string
            pattern: ^[\w-]+$
        - $ref: '#/components/parameters/CartKey'
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Thumb'
        - $ref: '#/components/parameters/DefaultCart'
        - $ref: '#/components/parameters/Formatted'
      responses:
        '200':
          description: Coupon removed. Returns the updated cart.
          headers:
            Country:
              $ref: '#/components/headers/GeoCountry'
            Country-Code:
              $ref: '#/components/headers/GeoCountryCode'
            Region:
              $ref: '#/components/headers/GeoRegion'
            Timezone:
              $ref: '#/components/headers/GeoTimezone'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartV2'
        '404':
          description: Not found - coupons are not enabled, no code provided, or the coupon is not applied to the cart.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                coupons_not_enabled:
                  summary: Coupons are not enabled for this store
                  value:
                    code: cocart_coupons_not_enabled
                    message: Coupons are not enabled for this store!
                    data:
                      status: 404
                code_required:
                  summary: No coupon code provided
                  value:
                    code: cocart_coupon_required
                    message: No coupon code provided!
                    data:
                      status: 404
                not_applied:
                  summary: Coupon is not applied to the cart
                  value:
                    code: cocart_cart_coupon_invalid_code
                    message: Coupon does not exist in the cart.
                    data:
                      status: 404
  /cart/add-fee:
    post:
      tags:
        - fees
      summary: Add fee to cart
      description: |
        Adds a fee to the cart. The fee is stored in session and applied when cart
        totals are calculated. Returns the updated cart. If the same fee was already
        added, the cart is returned with an informational notice.
      parameters:
        - $ref: '#/components/parameters/CartKey'
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Thumb'
        - $ref: '#/components/parameters/DefaultCart'
        - $ref: '#/components/parameters/Formatted'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Name of the fee.
                  type: string
                amount:
                  description: Amount for the fee as a decimal string (e.g. "10.00"). Use a negative amount for a discount.
                  type: string
                taxable:
                  description: Determines if the fee is taxable.
                  type: boolean
                  default: false
                tax_class:
                  description: The tax class the fee applies to.
                  type: string
              required:
                - name
                - amount
            example:
              name: Handling Fee
              amount: '10.00'
              taxable: true
      responses:
        '200':
          description: Fee added. Returns the updated cart.
          headers:
            Country:
              $ref: '#/components/headers/GeoCountry'
            Country-Code:
              $ref: '#/components/headers/GeoCountryCode'
            Region:
              $ref: '#/components/headers/GeoRegion'
            Timezone:
              $ref: '#/components/headers/GeoTimezone'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartV2'
        '404':
          description: Not found - fee name or amount missing, or cart is empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_name:
                  summary: Fee name missing
                  value:
                    code: cocart_fee_missing_name
                    message: Name of fee is missing!
                    data:
                      status: 404
                missing_amount:
                  summary: Fee amount missing
                  value:
                    code: cocart_fee_missing_amount
                    message: Fee amount is missing!
                    data:
                      status: 404
                cannot_add:
                  summary: Cart is empty
                  value:
                    code: cocart_fee_cannot_add
                    message: Fee cannot be applied to cart with no items.
                    data:
                      status: 404
  /cart/remove-fees:
    post:
      tags:
        - fees
      summary: Remove all fees
      description: |
        Removes all fees from the cart and returns the updated cart.
      parameters:
        - $ref: '#/components/parameters/CartKey'
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Thumb'
        - $ref: '#/components/parameters/DefaultCart'
        - $ref: '#/components/parameters/Formatted'
      responses:
        '200':
          description: All fees removed. Returns the updated cart.
          headers:
            Country:
              $ref: '#/components/headers/GeoCountry'
            Country-Code:
              $ref: '#/components/headers/GeoCountryCode'
            Region:
              $ref: '#/components/headers/GeoRegion'
            Timezone:
              $ref: '#/components/headers/GeoTimezone'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartV2'
  /cart/items:
    delete:
      tags:
        - cart-items
      summary: Remove all items
      description: |
        Removes all items from the cart and returns the updated (empty) cart.
      parameters:
        - $ref: '#/components/parameters/CartKey'
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Thumb'
        - $ref: '#/components/parameters/DefaultCart'
        - $ref: '#/components/parameters/Formatted'
        - $ref: '#/components/parameters/IfNoneMatch'
        - $ref: '#/components/parameters/SkipCache'
      responses:
        '200':
          description: All items removed. Returns the updated cart.
          headers:
            ETag:
              $ref: '#/components/headers/ETagHeader'
            CoCart-Cache:
              $ref: '#/components/headers/CoCartCacheHeader'
            Country:
              $ref: '#/components/headers/GeoCountry'
            Country-Code:
              $ref: '#/components/headers/GeoCountryCode'
            Region:
              $ref: '#/components/headers/GeoRegion'
            Timezone:
              $ref: '#/components/headers/GeoTimezone'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartV2'
        '304':
          description: Not Modified - cart unchanged since the ETag provided in If-None-Match.
          headers:
            ETag:
              $ref: '#/components/headers/ETagHeader'
            CoCart-Cache:
              $ref: '#/components/headers/CoCartCacheHeader'
  /cart/set-shipping-method:
    post:
      tags:
        - shipping
      summary: Set shipping method
      description: |
        Sets the chosen shipping method for a shipping package (or all packages when
        no package ID is provided) and returns the updated cart with recalculated totals.
      parameters:
        - $ref: '#/components/parameters/CartKey'
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Thumb'
        - $ref: '#/components/parameters/DefaultCart'
        - $ref: '#/components/parameters/Formatted'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                rate_id:
                  description: The chosen rate ID for the package (e.g. "flat_rate:1").
                  type: string
                package_id:
                  description: The ID of the package being shipped. Leave blank to apply to all packages.
                  oneOf:
                    - type: integer
                      nullable: true
                    - type: string
                      nullable: true
              required:
                - rate_id
            example:
              rate_id: flat_rate:1
              package_id: 0
      responses:
        '200':
          description: Shipping method set. Returns the updated cart.
          headers:
            Country:
              $ref: '#/components/headers/GeoCountry'
            Country-Code:
              $ref: '#/components/headers/GeoCountryCode'
            Region:
              $ref: '#/components/headers/GeoRegion'
            Timezone:
              $ref: '#/components/headers/GeoTimezone'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartV2'
        '404':
          description: Not found - shipping is disabled, no rate ID provided, or shipping hasn't been calculated yet for the cart.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                shipping_disabled:
                  summary: Shipping is disabled for this store
                  value:
                    code: cocart_shipping_disabled
                    message: Shipping is disabled.
                    data:
                      status: 404
                missing_rate_id:
                  summary: No rate ID provided
                  value:
                    code: cocart_missing_rate_id
                    message: Invalid Rate ID.
                    data:
                      status: 404
                not_calculated:
                  summary: Applying to all packages, but shipping hasn't been calculated yet
                  value:
                    code: cocart_shipping_not_calculated
                    message: Customer has not calculated shipping.
                    data:
                      status: 404
  /products/{id}/shipping-rates:
    get:
      tags:
        - products
      summary: Get product shipping rates
      description: |
        Calculates and returns the available shipping rates for a product before it
        is added to the cart. The product is temporarily added to a cart simulation
        so that quantity-dependent shipping prices calculate correctly, then removed.

        This endpoint is stateless: passing a `cart_key` is rejected with a 403 error
        because shipping rate calculation must not be associated with a specific cart.

        External and grouped product types cannot be calculated and return a 403 error.

        The `id` may also be a SKU, resolved to a product ID first.
      parameters:
        - name: id
          in: path
          description: Unique identifier for the product or variation ID.
          required: true
          schema:
            type: string
        - name: quantity
          in: query
          description: Quantity of this item to simulate adding to the cart.
          required: false
          schema:
            type: string
            default: '1'
        - name: variation
          in: query
          description: Variable attributes that identify the variation of the item.
          required: false
          style: deepObject
          explode: true
          schema:
            type: object
            additionalProperties:
              type: string
        - name: item_data
          in: query
          description: Additional item data passed to make item unique.
          required: false
          style: deepObject
          explode: true
          schema:
            type: object
            additionalProperties: true
      responses:
        '200':
          description: Shipping rates calculated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductShippingRates'
              example:
                item_key: 6364d3f0f495b6ab9dcf8d3b5c6e0b01
                id: 123
                parent_id: 0
                name: Premium Quality T-Shirt
                type: simple
                item_match: true
                packages:
                  '1':
                    rates:
                      flat_rate:1:
                        key: flat_rate:1
                        method_id: flat_rate
                        instance_id: 1
                        label: Flat rate
                        cost: '1000'
                        html: 'Flat rate: $10.00'
                        taxes: '0'
                        meta_data:
                          items: Premium Quality T-Shirt × 1
                    formatted_destination: Beverly Hills, CA 90210, United States (US)
        '403':
          description: Forbidden - product type cannot be calculated or a cart key was passed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                cart_key_denied:
                  summary: Cart key passed
                  value:
                    code: cocart_calculate_product_shipping_rates_cart_access_denied
                    message: DO NOT associate a cart when calculating shipping rates for a product!
                    data:
                      status: 403
                external_denied:
                  summary: External product
                  value:
                    code: cocart_calculate_product_shipping_external_types_denied
                    message: This product is external, therefore it cannot be calculated for shipping rates.
                    data:
                      status: 403
                grouped_denied:
                  summary: Grouped product
                  value:
                    code: cocart_calculate_product_shipping_grouped_types_denied
                    message: This product is a group of products, therefore it cannot be calculated for shipping rates.
                    data:
                      status: 403
        '404':
          description: Not found - the product ID, SKU or variation is invalid or missing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_product:
                  summary: Product is invalid (unpublished, or has no valid ID)
                  value:
                    code: cocart_invalid_product
                    message: This product is invalid.
                    data:
                      status: 404
                invalid_variation:
                  summary: Variation ID does not belong to the parent product
                  value:
                    code: cocart_variation_invalid_id
                    message: Invalid variation ID.
                    data:
                      status: 404
                product_id_required:
                  summary: No product ID or SKU provided
                  value:
                    code: cocart_product_id_required
                    message: Product ID number is required!
                    data:
                      status: 404
                unknown_product_id:
                  summary: Product ID or SKU does not match any product
                  value:
                    code: cocart_unknown_product_id
                    message: Product does not exist! Check that you have submitted a product ID or SKU ID correctly for a product that exists.
                    data:
                      status: 404
                not_loaded:
                  summary: CoCart core is not active
                  value:
                    code: cocart_not_loaded
                    message: Either the core of CoCart is not active or a specific class required does not exist.
                    data:
                      status: 404
        '405':
          description: Method not allowed - the resolved product ID is not numeric.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_product_id_not_numeric
                message: Product ID must be numeric!
                data:
                  status: 405
        '500':
          description: Internal server error - the product could not be added to the shipping calculation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_calculate_product_shipping_rates_failed
                message: Product could not be calculated!
                data:
                  status: 500
  /my-account:
    get:
      tags:
        - my-account
      summary: Get account details
      description: |
        Returns details of the authenticated customer's account including addresses,
        order count, total spent and the most recent order.
      responses:
        '200':
          description: Account details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
              example:
                user:
                  id: 42
                  date_registered: '2024-03-15T10:30:00Z'
                  email: john.doe@example.com
                  first_name: John
                  last_name: Doe
                  display_name: John Doe
                  addresses:
                    billing:
                      first_name: John
                      last_name: Doe
                      company: Acme Corporation
                      address_1: 123 Main Street
                      address_2: Suite 100
                      city: Beverly Hills
                      state: CA
                      postcode: '90210'
                      country: US
                      email: john.doe@example.com
                      phone: +1-555-123-4567
                    shipping:
                      first_name: John
                      last_name: Doe
                      company: ''
                      address_1: 123 Main Street
                      address_2: Suite 100
                      city: Beverly Hills
                      state: CA
                      postcode: '90210'
                      country: US
                  orders_count: 12
                  total_spent: $1,254.00
                  is_paying_customer: true
                  avatar_url: https://secure.gravatar.com/avatar/abc123
                recent_order:
                  order_id: 1234
                  order_date: March 12, 2026
                  order_data: https://example-store.com/wp-json/cocart/v2/my-account/orders/1234
                meta:
                  is_customer_outside_base: false
                  is_vat_exempt: false
                extensions:
                  email_verification:
                    verified: false
        '400':
          description: Bad request - the customer could not be retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_customer_error
                message: Unable to retrieve customer.
                data:
                  status: 400
        '403':
          description: Forbidden - you need to be logged in to view the account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_access_my_account_denied
                message: You need to be logged in to view account!
                data:
                  status: 403
      security:
        - basicAuth: []
        - bearerAuth: []
    post:
      tags:
        - my-account
      summary: Update account details
      description: |
        Updates the authenticated customer's account details. First name, last name,
        display name and email address are required (filterable via the
        `cocart_save_account_details_required_fields` filter). To change the password,
        provide the current password along with the new password entered twice.
        Changed name and email values are kept in sync with the billing address.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account_first_name:
                  description: First name.
                  type: string
                account_last_name:
                  description: Last name.
                  type: string
                account_display_name:
                  description: Display name. Cannot be an email address.
                  type: string
                account_email:
                  description: Email address.
                  type: string
                  format: email
                password_current:
                  description: Current password. Required when changing the password.
                  type: string
                password_1:
                  description: New password.
                  type: string
                password_2:
                  description: Confirm new password. Must match `password_1`.
                  type: string
              required:
                - account_first_name
                - account_last_name
                - account_display_name
                - account_email
            example:
              account_first_name: John
              account_last_name: Doe
              account_display_name: John Doe
              account_email: john.doe@example.com
      responses:
        '200':
          description: Account details updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountUpdateResult'
              examples:
                updated:
                  summary: Updated immediately
                  value:
                    success: true
                    email_verification_pending: false
                pending_verification:
                  summary: Email change pending verification
                  value:
                    success: true
                    email_verification_pending: true
        '400':
          description: Bad request - missing required field, invalid email or password validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_field:
                  summary: Missing required field
                  value:
                    code: cocart_account_missing_required_field
                    message: <strong>First name</strong> is a required field.
                    data:
                      status: 400
                      id: account_first_name
                invalid_email:
                  summary: Invalid email address
                  value:
                    code: cocart_account_provide_valid_email
                    message: Please provide a valid email address.
                    data:
                      status: 400
                fill_all_password_fields:
                  summary: Current password given but new password fields empty
                  value:
                    code: cocart_account_fill_all_password_fields
                    message: Please fill out all password fields.
                    data:
                      status: 400
                enter_current_password:
                  summary: New password given without current password
                  value:
                    code: cocart_account_enter_current_password
                    message: Please enter your current password.
                    data:
                      status: 400
                reenter_password:
                  summary: New password confirmation missing
                  value:
                    code: cocart_account_reenter_password
                    message: Please re-enter your password a second time.
                    data:
                      status: 400
                passwords_mismatch:
                  summary: New passwords do not match
                  value:
                    code: cocart_account_new_passwords_do_not_match
                    message: New passwords do not match.
                    data:
                      status: 400
                incorrect_current_password:
                  summary: Current password is incorrect
                  value:
                    code: cocart_account_incorrect_current_password
                    message: Your current password is incorrect.
                    data:
                      status: 400
        '403':
          description: Forbidden - not logged in, email already registered or display name set to an email address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                not_logged_in:
                  summary: Not logged in
                  value:
                    code: cocart_access_my_account_denied
                    message: You need to be logged in to view account!
                    data:
                      status: 403
                email_registered:
                  summary: Email already registered to another account
                  value:
                    code: cocart_account_email_already_registered
                    message: This email address is already registered.
                    data:
                      status: 403
                display_name_is_email:
                  summary: Display name set to an email address
                  value:
                    code: cocart_cannot_set_email_as_display_name
                    message: Display name cannot be changed to email address due to privacy concern.
                    data:
                      status: 403
      security:
        - basicAuth: []
        - bearerAuth: []
  /my-account/address:
    patch:
      tags:
        - my-account
      summary: Update account address
      description: |
        Updates the authenticated customer's saved billing and/or shipping address,
        independently of checkout. Unlike checkout's address handling, billing and
        shipping are updated independently - there is no "use shipping for billing"
        copying, and no shipping packages are recalculated since there's no active
        cart context involved. At least one of `billing_address` or
        `shipping_address` must be provided. Only the fields included are updated;
        omitted fields are left unchanged.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountAddressUpdateRequest'
            example:
              billing_address:
                first_name: John
                last_name: Doe
                address_1: 123 Main Street
                city: Beverly Hills
                state: CA
                postcode: '90210'
                country: US
      responses:
        '200':
          description: Address updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountAddressUpdateResult'
              example:
                addresses:
                  billing:
                    first_name: John
                    last_name: Doe
                    company: ''
                    address_1: 123 Main Street
                    address_2: ''
                    city: Beverly Hills
                    state: CA
                    postcode: '90210'
                    country: US
                    email: john.doe@example.com
                    phone: +1-555-123-4567
                  shipping:
                    first_name: John
                    last_name: Doe
                    company: ''
                    address_1: 123 Main Street
                    address_2: ''
                    city: Beverly Hills
                    state: CA
                    postcode: '90210'
                    country: US
        '400':
          description: Bad request - no address data provided, or a field failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                no_data:
                  summary: No address data provided
                  value:
                    code: cocart_no_address_data
                    message: No address data provided.
                    data:
                      status: 400
                invalid_fields:
                  summary: One or more fields failed validation
                  value:
                    code: cocart_invalid_address_fields
                    message: Please provide a valid email address.
                    data:
                      status: 400
                customer_error:
                  summary: The customer could not be retrieved
                  value:
                    code: cocart_customer_error
                    message: Unable to retrieve customer.
                    data:
                      status: 400
        '403':
          description: Forbidden - you need to be logged in to update the address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_access_my_account_denied
                message: You need to be logged in to view account!
                data:
                  status: 403
      security:
        - basicAuth: []
        - bearerAuth: []
  /my-account/downloads:
    get:
      tags:
        - my-account
      summary: Get customer downloads
      description: |
        Returns the downloadable products available to the authenticated customer.
        When no downloads are available, a plain message string is returned instead.
      responses:
        '200':
          description: Downloads retrieved successfully.
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    title: Downloads
                    description: List of available downloads.
                    items:
                      $ref: '#/components/schemas/CustomerDownload'
                  - type: string
                    title: No Downloads
                    description: Message returned when no downloads are available.
              examples:
                downloads:
                  summary: Available downloads
                  value:
                    - product_name: Music Album
                      download_name: Track One
                      file: https://example-store.com/?download_file=456&order=wc_order_abc123&uid=hash
                      downloads_remaining: '3'
                      download_expires: December 31st 2026
                empty:
                  summary: No downloads available
                  value: No downloads available yet on this account.
        '400':
          description: Bad request - the customer could not be retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_customer_error
                message: Unable to retrieve customer.
                data:
                  status: 400
        '403':
          description: Forbidden - you need to be logged in to view downloads.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_access_my_account_denied
                message: You need to be logged in to view account!
                data:
                  status: 403
      security:
        - basicAuth: []
        - bearerAuth: []
  /my-account/orders:
    get:
      tags:
        - my-account
      summary: Get customer orders
      description: |
        Returns a paginated list of the authenticated customer's orders with
        available order actions and pagination links.
      parameters:
        - name: page
          in: query
          description: The pagination of orders to return. Clamped server-side to a maximum of 100.
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
            maximum: 100
        - name: per_page
          in: query
          description: Limit amount of orders to return per page. Clamped server-side to a maximum of 50 per request, regardless of the value requested.
          required: false
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 50
        - name: order
          in: query
          description: Order sort attribute ascending or descending.
          required: false
          schema:
            type: string
            default: DESC
            enum:
              - ASC
              - DESC
      responses:
        '200':
          description: Orders retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerOrders'
              example:
                orders:
                  - order_id: 1234
                    order_status: Processing
                    order_date: March 12, 2026, 2:45 pm
                    item_count: 3
                    order_total: $125.00
                    order_actions:
                      view:
                        url: https://example-store.com/wp-json/cocart/v2/my-account/orders/1234
                        label: View
                pagination:
                  next: https://example-store.com/wp-json/cocart/v2/my-account/orders/?page=2&per_page=10
        '400':
          description: Bad request - the customer could not be retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_customer_error
                message: Unable to retrieve customer.
                data:
                  status: 400
        '403':
          description: Forbidden - you need to be logged in to view orders.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_access_my_account_denied
                message: You need to be logged in to view account!
                data:
                  status: 403
        '404':
          description: Not found - no orders have been made yet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_account_no_orders
                message: No order has been made yet.
                data:
                  status: 404
      security:
        - basicAuth: []
        - bearerAuth: []
  /my-account/orders/{id}:
    get:
      tags:
        - my-account
      summary: Get single order
      description: |
        Returns the details of a single order belonging to the authenticated customer.
        Guests may also view an order by providing the `email` query parameter matching
        the order's billing email address.
      parameters:
        - name: id
          in: path
          description: Unique identifier for the order.
          required: true
          schema:
            type: integer
        - name: email
          in: query
          description: The order's billing email address. Allows guest access to the order when it matches.
          required: false
          schema:
            type: string
            format: email
      responses:
        '200':
          description: Order retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerOrder'
              example:
                order_id: 1234
                order_key: wc_order_abc123
                order_number: '1234'
                order_parent: 0
                order_date: March 12, 2026, 2:45 pm
                order_status: Processing
                order_currency: USD
                billing_address: John Doe, 123 Main Street, Suite 100, Beverly Hills, CA 90210, United States (US)
                shipping_address: John Doe, 123 Main Street, Suite 100, Beverly Hills, CA 90210, United States (US)
                phone: +1-555-123-4567
                email: john.doe@example.com
                ship_to_billing: true
                items:
                  - item_id: 10
                    product_id: 123
                    variation_id: 0
                    product_image: https://example-store.com/wp-content/uploads/2024/03/tshirt.jpg
                    product_name: Premium Quality T-Shirt
                    product_title: Premium Quality T-Shirt
                    product_type: simple
                    sku: TSHIRT-001
                    quantity: '2'
                    subtotal: $36.00
                    purchase_note: ''
                    refunded_qty: '0'
                    meta: {}
                    link: https://example-store.com/wp-json/cocart/v2/products/123
                totals:
                  subtotal:
                    label: Subtotal
                    value: $36.00
                  shipping:
                    label: Shipping
                    value: $10.00
                  payment_method:
                    label: Payment method
                    value: Credit Card
                  total:
                    label: Total
                    value: $46.00
                order_note: ''
                order_notes: []
                downloads: []
                order_actions:
                  cancel:
                    url: https://example-store.com/wp-json/cocart/v2/my-account/orders/1234/cancel
                    label: Cancel
        '403':
          description: Forbidden - not logged in and no matching billing email provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_access_my_orders_denied
                message: You are not logged in! Cannot view order.
                data:
                  status: 403
        '404':
          description: Not found - the order does not exist or the billing email does not match.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_order_does_not_exist
                message: Order #1234 does not exist.
                data:
                  status: 404
      security:
        - basicAuth: []
        - bearerAuth: []
  /my-account/orders/{id}/cancel:
    post:
      tags:
        - my-account
      summary: Cancel an order
      description: |
        Cancels a pending or failed order belonging to the authenticated customer.
        Mirrors the classic My Account "Cancel order" action - order status is
        validated, an order note is added, and the `woocommerce_cancelled_order`
        action fires so stock restoration and any cancellation notifications hooked
        onto that action behave the same as cancelling from the classic My Account
        page. Only orders with a status of `pending` or `failed` can be cancelled
        by default (filterable via
        `cocart_get_account_orders_action_valid_statuses_for_cancel`).
      parameters:
        - name: id
          in: path
          description: Unique identifier for the order.
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Order cancelled successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelOrderResult'
              example:
                success: true
                order_id: 1234
                order_status: Cancelled
        '400':
          description: Bad request - the order's current status does not allow cancellation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_order_cannot_be_cancelled
                message: This order can no longer be cancelled. Please contact us if you need assistance.
                data:
                  status: 400
        '403':
          description: Forbidden - you need to be logged in to cancel an order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_access_my_orders_denied
                message: You are not logged in! Cannot cancel order.
                data:
                  status: 403
        '404':
          description: Not found - the order does not exist or does not belong to the authenticated customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_order_does_not_exist
                message: Order #1234 does not exist.
                data:
                  status: 404
      security:
        - basicAuth: []
        - bearerAuth: []
  /my-account/subscriptions:
    get:
      tags:
        - my-account
      summary: Get customer subscriptions
      description: |
        Returns a paginated list of the authenticated customer's subscriptions.
        Subscriptions are provided by whichever subscription-plugin extension is
        active (WooCommerce Subscriptions, Milo Subscriptions, etc) via the
        `cocart_my_account_get_subscriptions` filter, so results are the same
        regardless of which subscription plugin the store runs. Requires a
        subscription-plugin extension to be active; no subscriptions are
        returned otherwise.
      parameters:
        - name: page
          in: query
          description: The pagination of subscriptions to return. Clamped server-side to a maximum of 100.
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
            maximum: 100
        - name: per_page
          in: query
          description: Limit amount of subscriptions to return per page. Clamped server-side to a maximum of 50 per request, regardless of the value requested.
          required: false
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 50
        - name: order
          in: query
          description: Order sort attribute ascending or descending.
          required: false
          schema:
            type: string
            default: DESC
            enum:
              - ASC
              - DESC
      responses:
        '200':
          description: Subscriptions retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerSubscriptions'
              example:
                subscriptions:
                  - subscription_id: 89
                    subscription_number: '#89'
                    subscription_status: Active
                    next_payment: September 19, 2026
                    subscription_total: $29.99 / month
                    is_manual: false
                    view: https://example-store.com/wp-json/cocart/v2/my-account/subscriptions/89
                pagination:
                  next: https://example-store.com/wp-json/cocart/v2/my-account/subscriptions/?page=2&per_page=10
        '403':
          description: Forbidden - you need to be logged in to view subscriptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_access_my_account_denied
                message: You need to be logged in to view account!
                data:
                  status: 403
        '404':
          description: Not found - no subscriptions found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_account_no_subscriptions
                message: No subscriptions found.
                data:
                  status: 404
      security:
        - basicAuth: []
        - bearerAuth: []
  /my-account/subscriptions/{id}:
    get:
      tags:
        - my-account
      summary: Get single subscription
      description: |
        Returns the details of a single subscription belonging to the
        authenticated customer. Guests may also view a subscription by
        providing the `email` query parameter matching the subscription's
        billing email address. To avoid leaking which subscription IDs exist,
        a non-existent subscription and one the requester doesn't own both
        return the same 404 response.
      parameters:
        - name: id
          in: path
          description: Unique identifier for the subscription.
          required: true
          schema:
            type: integer
        - name: email
          in: query
          description: The subscription's billing email address. Allows guest access to the subscription when it matches.
          required: false
          schema:
            type: string
            format: email
      responses:
        '200':
          description: Subscription retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerSubscription'
              example:
                subscription_id: 89
                subscription_number: '#89'
                parent_order: 1234
                order: https://example-store.com/wp-json/cocart/v2/my-account/orders/1234
                subscription_status: Active
                subscription_total: $29.99 / month
                is_manual: false
                start_date:
                  title: Start date
                  value: August 19, 2026
                next_payment:
                  title: Next payment date
                  value: September 19, 2026
                end_date:
                  title: End date
                  value: ''
                trial_end:
                  title: Trial end date
                  value: ''
                payment:
                  title: Payment
                  value: Visa ending in 1234
                billing_address: John Doe, 123 Main Street, Suite 100, Beverly Hills, CA 90210, United States (US)
                shipping_address: John Doe, 123 Main Street, Suite 100, Beverly Hills, CA 90210, United States (US)
                notes:
                  - date: August 19th 2026, 02:45pm
                    note: Payment received. Next payment scheduled for September 19, 2026.
        '403':
          description: Forbidden - not logged in and no matching billing email provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_access_my_account_denied
                message: You need to be logged in to view account!
                data:
                  status: 403
        '404':
          description: Not found - the subscription does not exist or does not belong to the requester.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_subscription_does_not_exist
                message: Subscription #89 does not exist.
                data:
                  status: 404
      security:
        - basicAuth: []
        - bearerAuth: []
  /my-account/subscriptions/{id}/suspend:
    post:
      tags:
        - my-account
      summary: Suspend a subscription
      description: |
        Puts the authenticated customer's subscription on hold, via the
        `cocart_my_account_suspend_subscription` filter. Requires login - unlike
        the read-only single-subscription view, write actions never allow guest
        access by billing email. Whether a subscription can be suspended (e.g.
        suspension limits) is decided entirely by the owning subscription
        plugin - the exact error code, message and status for a rejected
        suspension vary accordingly (WooCommerce Subscriptions always uses the
        codes shown below; Milo Subscriptions surfaces its own manager error
        code, or a generic 400 when it declines without a specific reason).
      parameters:
        - name: id
          in: path
          description: Unique identifier for the subscription.
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Subscription suspended successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionActionResult'
              example:
                subscription_id: 89
                subscription_status: On hold
        '400':
          description: Bad request - the subscription plugin declined the action without a more specific reason (e.g. Milo Subscriptions).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_subscription_action_failed
                message: This action could not be completed for this subscription.
                data:
                  status: 400
        '403':
          description: Forbidden - not logged in, or the subscription cannot be suspended.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                not_logged_in:
                  summary: Not logged in
                  value:
                    code: cocart_access_my_account_denied
                    message: You need to be logged in to manage your subscription!
                    data:
                      status: 403
                cannot_suspend:
                  summary: Subscription cannot be suspended (WooCommerce Subscriptions)
                  value:
                    code: cocart_subscription_cannot_suspend
                    message: This subscription cannot be suspended.
                    data:
                      status: 403
        '404':
          description: Not found - the subscription does not exist or does not belong to the requester.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_subscription_does_not_exist
                message: Subscription #89 does not exist.
                data:
                  status: 404
      security:
        - basicAuth: []
        - bearerAuth: []
  /my-account/subscriptions/{id}/cancel:
    post:
      tags:
        - my-account
      summary: Cancel a subscription
      description: |
        Cancels the authenticated customer's subscription, via the
        `cocart_my_account_cancel_subscription` filter. Requires login - unlike
        the read-only single-subscription view, write actions never allow guest
        access by billing email. The exact error code, message and status for a
        rejected cancellation depend on the owning subscription plugin
        (WooCommerce Subscriptions always uses the codes shown below; Milo
        Subscriptions surfaces its own manager error code, or a generic 400
        when it declines without a specific reason).
      parameters:
        - name: id
          in: path
          description: Unique identifier for the subscription.
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Subscription cancelled successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionActionResult'
              example:
                subscription_id: 89
                subscription_status: Cancelled
        '400':
          description: Bad request - the subscription plugin declined the action without a more specific reason (e.g. Milo Subscriptions).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_subscription_action_failed
                message: This action could not be completed for this subscription.
                data:
                  status: 400
        '403':
          description: Forbidden - not logged in, or the subscription cannot be cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                not_logged_in:
                  summary: Not logged in
                  value:
                    code: cocart_access_my_account_denied
                    message: You need to be logged in to manage your subscription!
                    data:
                      status: 403
                cannot_cancel:
                  summary: Subscription cannot be cancelled (WooCommerce Subscriptions)
                  value:
                    code: cocart_subscription_cannot_cancel
                    message: This subscription cannot be cancelled.
                    data:
                      status: 403
        '404':
          description: Not found - the subscription does not exist or does not belong to the requester.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_subscription_does_not_exist
                message: Subscription #89 does not exist.
                data:
                  status: 404
      security:
        - basicAuth: []
        - bearerAuth: []
  /my-account/subscriptions/{id}/reactivate:
    post:
      tags:
        - my-account
      summary: Reactivate a subscription
      description: |
        Reactivates the authenticated customer's subscription, via the
        `cocart_my_account_reactivate_subscription` filter. Requires login -
        unlike the read-only single-subscription view, write actions never
        allow guest access by billing email. A subscription that needs a
        renewal payment first is rejected rather than reactivated, matching
        WooCommerce Subscriptions' own My Account behavior; other subscription
        plugins may reject for different reasons (see the 400 and 403
        examples below).
      parameters:
        - name: id
          in: path
          description: Unique identifier for the subscription.
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Subscription reactivated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionActionResult'
              example:
                subscription_id: 89
                subscription_status: Active
        '400':
          description: Bad request - the subscription cannot be reactivated as-is.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                needs_payment:
                  summary: Needs a renewal payment first (WooCommerce Subscriptions)
                  value:
                    code: cocart_subscription_needs_payment
                    message: This subscription needs a renewal payment before it can be reactivated.
                    data:
                      status: 400
                action_failed:
                  summary: Declined without a more specific reason (e.g. Milo Subscriptions)
                  value:
                    code: cocart_subscription_action_failed
                    message: This action could not be completed for this subscription.
                    data:
                      status: 400
        '403':
          description: Forbidden - not logged in, or the subscription cannot be reactivated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                not_logged_in:
                  summary: Not logged in
                  value:
                    code: cocart_access_my_account_denied
                    message: You need to be logged in to manage your subscription!
                    data:
                      status: 403
                cannot_reactivate:
                  summary: Subscription cannot be reactivated (WooCommerce Subscriptions)
                  value:
                    code: cocart_subscription_cannot_reactivate
                    message: This subscription cannot be reactivated.
                    data:
                      status: 403
        '404':
          description: Not found - the subscription does not exist or does not belong to the requester.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_subscription_does_not_exist
                message: Subscription #89 does not exist.
                data:
                  status: 404
      security:
        - basicAuth: []
        - bearerAuth: []
  /my-account/subscriptions/{id}/auto-renew:
    post:
      tags:
        - my-account
      summary: Toggle subscription auto-renewal
      description: |
        Enables or disables auto-renewal (manual renewal) for the authenticated
        customer's subscription, via the
        `cocart_my_account_toggle_subscription_auto_renewal` filter. Requires
        login. Not every subscription plugin exposes this to customers (e.g.
        Milo Subscriptions has no customer-facing auto-renewal toggle), in
        which case the request 404s rather than pretending to succeed.
      parameters:
        - name: id
          in: path
          description: Unique identifier for the subscription.
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                enabled:
                  description: Whether auto-renewal should be enabled.
                  type: boolean
              required:
                - enabled
            example:
              enabled: false
      responses:
        '200':
          description: Auto-renewal setting updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionAutoRenewResult'
              example:
                subscription_id: 89
                is_manual: true
        '403':
          description: Forbidden - not logged in, or auto-renewal cannot be changed for this subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                not_logged_in:
                  summary: Not logged in
                  value:
                    code: cocart_access_my_account_denied
                    message: You need to be logged in to manage your subscription!
                    data:
                      status: 403
                cannot_toggle:
                  summary: Auto-renewal cannot be changed
                  value:
                    code: cocart_subscription_cannot_toggle_auto_renewal
                    message: Auto-renewal cannot be changed for this subscription.
                    data:
                      status: 403
        '404':
          description: Not found - the subscription does not exist, does not belong to the requester, or the active subscription plugin does not support this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_subscription_does_not_exist
                message: Subscription #89 does not exist.
                data:
                  status: 404
      security:
        - basicAuth: []
        - bearerAuth: []
  /my-account/subscriptions/{id}/payment-method:
    post:
      tags:
        - my-account
      summary: Update subscription payment method
      description: |
        Changes the payment method for the authenticated customer's
        subscription, via the
        `cocart_my_account_update_subscription_payment_method` filter.
        Requires login. What actually happens differs by subscription plugin -
        WooCommerce Subscriptions accepts any valid gateway ID and runs a real
        $0 validation charge against the new method before accepting it
        (mirroring its own change-payment-method flow), while Milo
        Subscriptions requires `token_id` (it identifies the gateway from the
        saved token itself, so `payment_method` is otherwise unused) and does
        a pure saved-token swap with no charge - it may also veto a token that
        was never validated for off-session use.
      parameters:
        - name: id
          in: path
          description: Unique identifier for the subscription.
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                payment_method:
                  description: Payment method (gateway) ID.
                  type: string
                token_id:
                  description: Saved payment token ID to use. Required for Milo Subscriptions; optional for WooCommerce Subscriptions.
                  type: integer
              required:
                - payment_method
            example:
              payment_method: stripe
              token_id: 42
      responses:
        '200':
          description: Payment method updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionPaymentMethodResult'
              example:
                subscription_id: 89
                payment_method: Visa ending in 1234
                is_manual: false
        '400':
          description: Bad request - the payment method or saved token is invalid, disabled, unavailable, or unsupported for this subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_payment_method:
                  summary: Payment method does not exist (WooCommerce Subscriptions)
                  value:
                    code: cocart_invalid_payment_method
                    message: Invalid payment method.
                    data:
                      status: 400
                payment_method_disabled:
                  summary: Payment method is disabled (WooCommerce Subscriptions)
                  value:
                    code: cocart_payment_method_disabled
                    message: This payment method is currently disabled.
                    data:
                      status: 400
                payment_method_no_subscription_support:
                  summary: Payment method does not support subscriptions (WooCommerce Subscriptions)
                  value:
                    code: cocart_payment_method_no_subscription_support
                    message: The payment method "Stripe" does not support subscriptions. Please choose a different payment method.
                    data:
                      status: 400
                payment_method_not_available:
                  summary: Payment method not available (WooCommerce Subscriptions)
                  value:
                    code: cocart_payment_method_not_available
                    message: This payment method is not available for your order.
                    data:
                      status: 400
                payment_method_not_supported:
                  summary: Subscription plugin does not support changing payment method (WooCommerce Subscriptions)
                  value:
                    code: cocart_subscription_payment_method_not_supported
                    message: Changing payment method is not supported for this subscription.
                    data:
                      status: 400
                payment_token_required:
                  summary: No saved token provided (Milo Subscriptions)
                  value:
                    code: cocart_subscription_payment_token_required
                    message: A saved payment token is required to change this subscription's payment method.
                    data:
                      status: 400
                invalid_payment_token:
                  summary: Saved token does not exist or belongs to another customer (Milo Subscriptions)
                  value:
                    code: cocart_subscription_invalid_payment_token
                    message: Invalid payment method.
                    data:
                      status: 400
                payment_token_needs_confirmation:
                  summary: Saved token needs re-confirmation before recurring use (Milo Subscriptions)
                  value:
                    code: cocart_subscription_payment_token_needs_confirmation
                    message: This payment method needs to be re-confirmed before it can be used for recurring payments.
                    data:
                      status: 400
        '402':
          description: Payment required - the validation charge on the new payment method failed (WooCommerce Subscriptions only; Milo Subscriptions never charges to change payment method).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_payment_failed
                message: Payment method could not be updated.
                data:
                  status: 402
        '403':
          description: Forbidden - you need to be logged in to manage your subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_access_my_account_denied
                message: You need to be logged in to manage your subscription!
                data:
                  status: 403
        '404':
          description: Not found - the subscription does not exist or does not belong to the requester.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_subscription_does_not_exist
                message: Subscription #89 does not exist.
                data:
                  status: 404
      security:
        - basicAuth: []
        - bearerAuth: []
  /my-account/subscriptions/{id}/resubscribe:
    post:
      tags:
        - my-account
      summary: Seed cart to resubscribe
      description: |
        Resubscribing isn't a single atomic action in either WooCommerce
        Subscriptions or Milo Subscriptions - both re-add the old
        subscription's items to the cart and send the customer through
        checkout, where the plugin's own order-creation hooks link the new
        order back to the old subscription. This endpoint only seeds the
        active cart the same way, via the
        `cocart_my_account_seed_resubscribe_cart` filter; the client then
        completes the purchase through CoCart's existing checkout endpoints.
        No payment is processed here. Seeding empties whatever the customer
        already had in their cart, so a non-empty cart is snapshotted into the
        session first - `DELETE` on this same route restores that snapshot and
        discards the in-progress resubscribe attempt. Eligibility (e.g. only
        cancelled/expired subscriptions) and the exact error message are
        decided by the owning subscription plugin; the codes below are shared
        by both providers, but message wording can differ.
      parameters:
        - name: id
          in: path
          description: Unique identifier for the subscription.
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Cart seeded with the subscription's items successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResubscribeResult'
              example:
                subscription_id: 89
                cart_items_added: 1
                cart_item_count: 1
                cart_total: $29.99
                saved_cart_item_count: 2
        '400':
          description: Bad request - none of the subscription's items could be added to the cart (e.g. the products are no longer available).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_subscription_resubscribe_failed
                message: None of this subscription's items could be added to the cart.
                data:
                  status: 400
        '403':
          description: Forbidden - not logged in, or you cannot resubscribe to this subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                not_logged_in:
                  summary: Not logged in
                  value:
                    code: cocart_access_my_account_denied
                    message: You need to be logged in to manage your subscription!
                    data:
                      status: 403
                cannot_resubscribe:
                  summary: Cannot resubscribe to this subscription
                  value:
                    code: cocart_subscription_cannot_resubscribe
                    message: You cannot resubscribe to this subscription.
                    data:
                      status: 403
        '404':
          description: Not found - the subscription does not exist or does not belong to the requester.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_subscription_does_not_exist
                message: Subscription #89 does not exist.
                data:
                  status: 404
      security:
        - basicAuth: []
        - bearerAuth: []
    delete:
      tags:
        - my-account
      summary: Restore cart before resubscribing
      description: |
        Restores the cart snapshot taken before a `POST` to this same route,
        discarding whatever resubscribe items are currently in the cart. Use
        this to abandon an in-progress resubscribe attempt and give the
        customer back what they had in their cart beforehand.
      parameters:
        - name: id
          in: path
          description: Unique identifier for the subscription.
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Saved cart restored successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResubscribeRestoreResult'
              example:
                restored: true
                cart_item_count: 2
                restored_item_count: 2
        '403':
          description: Forbidden - you need to be logged in to manage your subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_access_my_account_denied
                message: You need to be logged in to manage your subscription!
                data:
                  status: 403
        '404':
          description: Not found - the subscription does not exist or does not belong to the requester, or there is no saved cart to restore.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                subscription_does_not_exist:
                  summary: Subscription does not exist
                  value:
                    code: cocart_subscription_does_not_exist
                    message: Subscription #89 does not exist.
                    data:
                      status: 404
                no_saved_cart:
                  summary: No saved cart to restore
                  value:
                    code: cocart_subscription_no_saved_cart
                    message: There is no saved cart to restore.
                    data:
                      status: 404
      security:
        - basicAuth: []
        - bearerAuth: []
  /my-account/verify-email:
    get:
      tags:
        - my-account
      summary: Verify pending email change
      description: |
        Confirms a pending email address change initiated via
        `POST /my-account` and applies the new email to the user account and
        billing address. This endpoint is intentionally public (no
        authentication required) since the confirmation link is opened from an
        email client that may not share a session with the requester -
        possession of the emailed `key` is the proof of ownership. The link
        expires after 24 hours by default.
      parameters:
        - name: key
          in: query
          description: The verification key sent to the pending new email address.
          required: true
          schema:
            type: string
        - name: user_id
          in: query
          description: The user ID the pending email change belongs to.
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Email address verified and updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyEmailResult'
              example:
                success: true
                email: john.doe@example.com
        '400':
          description: Bad request - the verification key is invalid, expired, or does not match.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_invalid_or_expired_key
                message: This confirmation link is invalid or has expired.
                data:
                  status: 400
        '403':
          description: Forbidden - the pending email address is already registered to a different user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_account_email_already_registered
                message: This email address is already registered.
                data:
                  status: 403
      security: []
  /my-account/verify-order-email:
    post:
      tags:
        - my-account
      summary: Send order email verification
      description: |
        Sends (or resends) a confirmation email to the authenticated customer's
        account email address, proving they own it so WooCommerce can link any
        past guest orders placed with the same billing email to the account.
        The customer confirms via `GET /my-account/verify-order-email`, using
        the `key` and `user_id` carried in the emailed link. Resending is
        throttled to once every 60 seconds - a request within that window
        returns `status: throttled` rather than sending a new email or minting
        a new key. Requires WooCommerce 11.0+.
      responses:
        '200':
          description: Request processed. Check `status` to tell a new email from a throttled resend.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendOrderEmailVerificationResult'
              examples:
                sent:
                  summary: Verification email sent
                  value:
                    success: true
                    status: sent
                throttled:
                  summary: Resent within the 60 second rate limit
                  value:
                    success: true
                    status: throttled
        '400':
          description: Bad request - the account email address is already verified.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_email_already_verified
                message: Your account email address is already verified.
                data:
                  status: 400
        '403':
          description: Forbidden - you need to be logged in to verify your email.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_access_my_account_denied
                message: You need to be logged in to view account!
                data:
                  status: 403
        '501':
          description: Not implemented - requires WooCommerce 11.0 or higher.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_woocommerce_feature_unavailable
                message: This feature requires WooCommerce 11.0 or higher.
                data:
                  status: 501
      security:
        - basicAuth: []
        - bearerAuth: []
    get:
      tags:
        - my-account
      summary: Confirm order email verification
      description: |
        Confirms the verification key emailed via
        `POST /my-account/verify-order-email`, marking the account email
        address verified and letting WooCommerce link any matching guest
        orders to the account. Unlike `GET /my-account/verify-email`, this
        endpoint requires the request be authenticated as the key's target
        user - matching WooCommerce core's own rule that only a request
        authenticated as the link's target user can complete verification, so
        a leaked key with no session behind it (or a session for a different
        account) can never link orders to the wrong customer. Requires
        WooCommerce 11.0+.
      parameters:
        - name: key
          in: query
          description: The verification key emailed to confirm ownership of the account email address.
          required: true
          schema:
            type: string
        - name: user_id
          in: query
          description: The WordPress user ID the verification belongs to.
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Email address verified successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyOrderEmailResult'
              example:
                success: true
                email: john.doe@example.com
        '400':
          description: Bad request - the verification key is invalid or has expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_invalid_or_expired_key
                message: This confirmation link is invalid or has expired.
                data:
                  status: 400
        '403':
          description: Forbidden - not logged in, or logged in as a different account than the key's target user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_access_my_account_denied
                message: You need to be logged in to view account!
                data:
                  status: 403
        '501':
          description: Not implemented - requires WooCommerce 11.0 or higher.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: cocart_woocommerce_feature_unavailable
                message: This feature requires WooCommerce 11.0 or higher.
                data:
                  status: 501
      security:
        - basicAuth: []
        - bearerAuth: []
  /register:
    post:
      tags:
        - customers
      summary: Register customer
      description: |
        Registers a new customer account. A valid email address is required.

        When the WooCommerce setting "generate username from email" is enabled, the
        username may be omitted and is generated automatically. When the WooCommerce
        setting "generate password" is enabled, the password may be omitted and a
        generated password is emailed to the customer.

        A blocklist of reserved usernames (admin, root, support, etc.) cannot be
        registered (filterable via the `cocart_reserved_usernames` filter).

        Passwords provided by the customer must be at least 8 characters
        (filterable via `cocart_minimum_password_length`), must not match the
        username or email address, must not be a common weak password
        (filterable via `cocart_common_weak_passwords`), and must mix at
        least three of: lowercase, uppercase, digit, symbol. This check is
        skipped for a generated password.

        The username/password fields are named `requested_username` /
        `requested_password` rather than `username`/`password` deliberately:
        CoCart Starter's authentication layer treats any request containing
        non-empty `username`/`password` fields as a Basic Auth attempt, which
        would collide with (and reject) this endpoint's own registration fields.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  description: Customers email address. Required and must not already be registered.
                  type: string
                  format: email
                requested_username:
                  description: Customers requested username. Optional when WooCommerce is set to generate usernames from the email address.
                  type: string
                requested_password:
                  description: Customers requested password. Optional when WooCommerce is set to generate passwords automatically.
                  type: string
              required:
                - email
            example:
              email: jane.doe@example.com
              requested_username: janedoe
              requested_password: hunter2-Str0ng!
      responses:
        '200':
          description: Customer registered successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisteredCustomer'
              examples:
                password_provided:
                  summary: Password provided
                  value:
                    user_id: 43
                    username: janedoe
                    message: Your account was created successfully. Your login details have been sent to your email address.
                password_generated:
                  summary: Password generated
                  value:
                    user_id: 43
                    username: janedoe
                    message: Your account was created successfully and a password has been sent to your email address.
        '400':
          description: Bad request - reserved username, weak password, or account creation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                reserved_username:
                  summary: Username is reserved
                  value:
                    code: cocart_registration_error_reserved_username
                    message: This username cannot be registered. Please choose another.
                    data:
                      status: 400
                weak_password:
                  summary: Password is too weak
                  value:
                    code: cocart_registration_error_weak_password
                    message: This password is too weak. Please choose a stronger password.
                    data:
                      status: 400
                creation_failed:
                  summary: Account creation failed (message varies)
                  value:
                    code: cocart_registration_error_failed_creation
                    message: Registration is currently not allowed.
                    data:
                      status: 400
        '404':
          description: Not found - invalid email, invalid username or missing password.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_email:
                  summary: Invalid email
                  value:
                    code: cocart_registration_invalid_email
                    message: A valid email address is required!
                    data:
                      status: 404
                invalid_username:
                  summary: Invalid username
                  value:
                    code: cocart_registration_error_invalid_username
                    message: Please provide a valid username.
                    data:
                      status: 404
                missing_password:
                  summary: Missing password
                  value:
                    code: registration-error-missing-password
                    message: Please enter an account password.
                    data:
                      status: 404
        '405':
          description: Not allowed - the email address or username is already registered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                email_exists:
                  summary: Email already registered
                  value:
                    code: cocart_registration_error_email_exists
                    message: An account is already registered with your email address.
                    data:
                      status: 405
                username_exists:
                  summary: Username already registered
                  value:
                    code: cocart_registration_error_username_exists
                    message: An account is already registered with that username. Please choose another.
                    data:
                      status: 405
components:
  headers:
    ETagHeader:
      description: |
        Weak ETag cache validation token. Format: W/"<md5hash>". Use in If-None-Match on subsequent requests for conditional requests.
      schema:
        type: string
        pattern: ^W/"[a-f0-9]{32}"$
        example: W/"d41d8cd98f00b204e9800998ecf8427e"
    CoCartCacheHeader:
      description: |
        ETag cache status: HIT (304 returned), MISS (fresh response), SKIP (_skip_cache used).
      schema:
        type: string
        enum:
          - HIT
          - MISS
          - SKIP
        example: MISS
    GeoCountry:
      description: The geolocated country name of the customer. Only sent when the geolocation feature is enabled.
      schema:
        type: string
        example: United States
    GeoCountryCode:
      description: The geolocated two-letter country code of the customer. Only sent when the geolocation feature is enabled.
      schema:
        type: string
        example: US
    GeoRegion:
      description: The geolocated region of the customer. Only sent when the geolocation feature is enabled.
      schema:
        type: string
        example: California
    GeoTimezone:
      description: The geolocated timezone of the customer. Only sent when the geolocation feature is enabled.
      schema:
        type: string
        example: America/Los_Angeles
    RateLimitLimit:
      description: The maximum number of requests allowed in the current rate limit window. Only sent when rate limiting is enabled.
      schema:
        type: integer
        example: 25
    RateLimitRemaining:
      description: The number of requests remaining in the current rate limit window. Only sent when rate limiting is enabled.
      schema:
        type: integer
        example: 24
    RateLimitReset:
      description: Unix timestamp when the current rate limit window resets. Only sent when rate limiting is enabled.
      schema:
        type: integer
        example: 1767225600
  parameters:
    CartKey:
      name: cart_key
      in: query
      description: Unique identifier for the cart/customer.
      required: false
      schema:
        type: string
    Fields:
      name: fields
      in: query
      description: Specify each parent field you want to request separated by (,) in the response before the data is fetched.
      required: false
      schema:
        type: string
    Thumb:
      name: thumb
      in: query
      description: True if you want to return the URL of the featured product image for each item in the cart.
      required: false
      schema:
        type: boolean
        default: true
    DefaultCart:
      name: default
      in: query
      description: Return the default cart data if set to true.
      required: false
      schema:
        type: boolean
        default: false
    Formatted:
      name: formatted
      in: query
      description: Returns price values as a formatted string (e.g. "$18.00") when true. Defaults to false, returning raw numeric values (e.g. 1800).
      required: false
      schema:
        type: boolean
        default: false
    IfNoneMatch:
      name: If-None-Match
      in: header
      description: |
        Conditional request header. Send previous ETag value; server returns 304 Not Modified if resource unchanged.
      required: false
      schema:
        type: string
        example: W/"d41d8cd98f00b204e9800998ecf8427e"
    SkipCache:
      name: _skip_cache
      in: query
      description: |
        Set to true or 1 to bypass ETag checking. Forces full response with CoCart-Cache: SKIP header.
      required: false
      schema:
        type: string
        enum:
          - 'true'
          - '1'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: |
        Basic authentication with username and password.

        Since CoCart v4.9.0, if an `X-HTTP-Method-Override` header is present, it is honored
        when determining the request method during authentication (e.g. credentials sent in a
        JSON body are still detected when the original method is tunneled through POST).
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Bearer token authentication (JWT). Optional for cart endpoints.
        When provided by customers, enables enhanced functionality like persistent carts and user-specific data.
  schemas:
    MiniCart:
      type: object
      description: Lightweight cart object scoped to the fields needed to render a mini cart.
      properties:
        cart_hash:
          type: string
          nullable: true
          description: A unique hash key of the cart contents.
        cart_key:
          type: string
          description: The cart key identifying the cart in session.
        currency:
          $ref: '#/components/schemas/Currency'
        item_count:
          type: integer
          description: The number of items in the cart.
        items:
          type: array
          description: The items in the cart.
          items:
            $ref: '#/components/schemas/MiniCartItem'
        subtotal:
          type: string
          description: The cart subtotal. Raw numeric string (e.g. "3600") by default; formatted string (e.g. "$36.00") when `formatted=true`.
    MiniCartItem:
      type: object
      properties:
        item_key:
          type: string
          description: Unique identifier for the item within the cart.
        id:
          type: integer
          description: Product ID.
        name:
          type: string
          description: Product name.
        price:
          type: string
          description: Product price. Raw numeric string (e.g. "1800") by default; formatted string (e.g. "$18.00") when `formatted=true`.
        quantity:
          type: number
          description: Quantity of the item in the cart.
        variation:
          description: Variation attributes for the item.
          oneOf:
            - type: object
              additionalProperties:
                type: string
            - type: array
              items:
                type: string
        cart_item_data:
          type: object
          description: Additional cart item data.
          additionalProperties: true
        featured_image:
          type: string
          format: uri
          description: Product featured image URL.
    AppliedCouponDetailed:
      type: object
      description: A coupon applied to the cart with its discount totals.
      properties:
        coupon:
          type: string
          description: Coupon code.
        label:
          type: string
          description: Human-readable coupon label.
        discount_type:
          type: string
          description: Type of discount applied (e.g. percent, fixed_cart, fixed_product).
        totals:
          type: object
          properties:
            discount:
              type: string
              description: Total discounted by this coupon as a raw numeric string (e.g. "360").
            discount_tax:
              type: string
              description: Total discounted tax by this coupon as a raw numeric string.
    CartV2:
      type: object
      description: Complete cart object with enhanced v2 structure. CoCart Plus adds the `meta` property.
      properties:
        cart_hash:
          type: string
          description: Unique cart hash.
        cart_key:
          type: string
          description: Unique cart key for the customer.
        currency:
          $ref: '#/components/schemas/Currency'
        customer:
          $ref: '#/components/schemas/Customer'
        items:
          type: object
          description: Cart items indexed by item key.
          additionalProperties:
            $ref: '#/components/schemas/CartItem'
        item_count:
          type: integer
          description: Total number of items in cart.
        items_weight:
          type: number
          description: Total weight of all items.
        coupons:
          type: array
          description: Applied coupons.
          items:
            $ref: '#/components/schemas/AppliedCoupon'
        needs_payment:
          type: boolean
          description: Whether the cart needs payment.
        needs_shipping:
          type: boolean
          description: Whether the cart needs shipping.
        shipping:
          $ref: '#/components/schemas/Shipping'
        fees:
          type: array
          description: Cart fees.
          items:
            $ref: '#/components/schemas/CartFee'
        taxes:
          type: array
          description: Cart taxes.
          items:
            $ref: '#/components/schemas/CartTax'
        totals:
          $ref: '#/components/schemas/CartTotals'
        removed_items:
          type: array
          description: Recently removed items that can be restored.
          items:
            $ref: '#/components/schemas/RemovedItem'
        cross_sells:
          type: array
          description: Cross-sell products.
          items:
            $ref: '#/components/schemas/CrossSellItem'
        notices:
          type: object
          description: Cart notices and messages.
          additionalProperties: true
        meta:
          type: object
          description: Cart meta data stored in session. Added by CoCart Plus.
          additionalProperties: true
        extensions:
          type: object
          description: Additional data added by third-party extensions via the `cocart_cart_extensions` filter. Only present when at least one extension hooks this filter.
          additionalProperties: true
    CartItem:
      type: object
      properties:
        item_key:
          type: string
          description: Unique identifier for the item within the cart.
        id:
          type: integer
          description: Product ID.
        name:
          type: string
          description: Product name.
        title:
          type: string
          description: Product title.
        price:
          type: string
          description: Current product price. Raw numeric value (e.g. "1800") by default; formatted string (e.g. "$18.00") when the `formatted` query parameter is true.
        quantity:
          type: object
          description: Quantity information for this item.
          properties:
            value:
              type: number
              description: Current quantity of the item in the cart.
            minimum:
              type: number
              description: The minimum purchase amount required.
            maximum:
              type: number
              description: The maximum purchase amount allowed. If -1 the item has an unlimited purchase amount.
            multiple_of:
              type: number
              description: The quantity must be a multiple of this value.
            editable:
              type: boolean
              description: Whether the quantity of the item is editable.
        totals:
          type: object
          description: Item totals. All values are raw numeric strings (e.g. "3600") by default; formatted strings (e.g. "$36.00") when `formatted=true`.
          properties:
            subtotal:
              type: string
              description: Line subtotal (before discounts).
            subtotal_tax:
              type: string
              description: Line subtotal tax.
            total:
              type: string
              description: Line total (after discounts).
            tax:
              type: string
              description: Line total tax.
        slug:
          type: string
          description: Product slug.
        meta:
          type: object
          description: Item metadata.
          properties:
            product_type:
              type: string
              description: Product type.
            sku:
              type: string
              description: Product SKU.
            dimensions:
              type: object
              description: Product dimensions.
              properties:
                length:
                  type: string
                  description: Product length.
                width:
                  type: string
                  description: Product width.
                height:
                  type: string
                  description: Product height.
                unit:
                  type: string
                  description: Dimension unit.
            weight:
              type: string
              description: Product weight.
            variation:
              description: Chosen attributes (for variations).
              oneOf:
                - type: object
                  additionalProperties:
                    type: string
                - type: array
                  items:
                    type: string
          additionalProperties: true
        backorders:
          type: string
          description: Backorder status.
        cart_item_data:
          type: object
          description: Custom cart item data.
          additionalProperties: true
        featured_image:
          type: string
          description: Product featured image URL.
        extensions:
          type: object
          description: Additional data added by third-party extensions via the `cocart_cart_item_extensions` filter. Empty object when no extensions hook this filter.
          additionalProperties: true
    Currency:
      type: object
      properties:
        currency_code:
          type: string
          description: Currency code.
        currency_symbol:
          type: string
          description: Currency symbol.
        currency_symbol_pos:
          type: string
          description: Currency symbol position.
        currency_minor_unit:
          type: integer
          description: Currency minor unit.
        currency_decimal_separator:
          type: string
          description: Currency decimal separator.
        currency_thousand_separator:
          type: string
          description: Currency thousand separator.
        currency_prefix:
          type: string
          description: Currency prefix.
        currency_suffix:
          type: string
          description: Currency suffix.
    Customer:
      type: object
      properties:
        billing_address:
          $ref: '#/components/schemas/BillingAddress'
        shipping_address:
          $ref: '#/components/schemas/ShippingAddress'
    BillingAddress:
      type: object
      properties:
        billing_first_name:
          type: string
        billing_last_name:
          type: string
        billing_company:
          type: string
        billing_country:
          type: string
        billing_address_1:
          type: string
        billing_address_2:
          type: string
        billing_postcode:
          type: string
        billing_city:
          type: string
        billing_state:
          type: string
        billing_phone:
          type: string
        billing_email:
          type: string
    ShippingAddress:
      type: object
      properties:
        shipping_first_name:
          type: string
        shipping_last_name:
          type: string
        shipping_company:
          type: string
        shipping_country:
          type: string
        shipping_address_1:
          type: string
        shipping_address_2:
          type: string
        shipping_postcode:
          type: string
        shipping_city:
          type: string
        shipping_state:
          type: string
    Shipping:
      type: object
      properties:
        total_packages:
          type: integer
          description: Number of shipping packages.
        show_package_details:
          type: boolean
          description: Whether to show package details.
        has_calculated_shipping:
          type: boolean
          description: Whether shipping has been calculated.
        packages:
          type: object
          description: Shipping packages.
          additionalProperties:
            $ref: '#/components/schemas/ShippingPackage'
    ShippingPackage:
      type: object
      properties:
        package_name:
          type: string
          description: Package name.
        rates:
          type: object
          description: Available shipping rates.
          additionalProperties:
            $ref: '#/components/schemas/ShippingRate'
        package_details:
          type: string
          description: Package details.
        index:
          type: integer
          description: Package index.
        chosen_method:
          type: string
          description: Chosen shipping method.
        formatted_destination:
          type: string
          description: Formatted destination address.
    ShippingRate:
      type: object
      properties:
        key:
          type: string
        method_id:
          type: string
        instance_id:
          type: integer
        label:
          type: string
        cost:
          type: string
        html:
          type: string
        taxes:
          type: string
        chosen_method:
          type: boolean
    CartTotals:
      type: object
      description: All monetary values are raw numeric strings (e.g. "1800") by default. Pass `formatted=true` to receive formatted strings (e.g. "$18.00").
      properties:
        subtotal:
          type: string
          description: Cart subtotal.
        subtotal_tax:
          type: string
          description: Cart subtotal tax.
        shipping_total:
          type: string
          description: Shipping total.
        shipping_tax:
          type: string
          description: Shipping tax.
        shipping_taxes:
          type: array
          items:
            type: number
        discount_total:
          type: string
          description: Discount total.
        discount_tax:
          type: string
          description: Discount tax.
        cart_contents_total:
          type: string
          description: Cart contents total.
        cart_contents_tax:
          type: string
          description: Cart contents tax.
        cart_contents_taxes:
          type: array
          items:
            type: number
        fee_total:
          type: string
          description: Fee total.
        fee_tax:
          type: string
          description: Fee tax.
        fee_taxes:
          type: array
          items:
            type: number
        total:
          type: string
          description: Cart total.
        total_tax:
          type: string
          description: Total tax.
    CartFee:
      type: object
      properties:
        name:
          type: string
        amount:
          type: number
        taxable:
          type: boolean
        tax_class:
          type: string
        total:
          type: number
        tax:
          type: number
    CartTax:
      type: object
      description: |
        Tax entry. Structure depends on the WooCommerce tax display setting:
        - Non-itemized: `{ label, total }` — a single combined tax line.
        - Itemized: `{ name, price }` — one entry per tax rate.
      properties:
        label:
          type: string
          description: Tax label (non-itemized mode).
        total:
          type: string
          description: Combined tax total as raw numeric string, e.g. "1310" (non-itemized mode). Formatted string when `formatted=true`.
        name:
          type: string
          description: Tax rate name (itemized mode).
        price:
          type: string
          description: Tax amount as raw numeric string (itemized mode). Formatted string when `formatted=true`.
    AppliedCoupon:
      type: object
      properties:
        coupon:
          type: string
          description: Coupon code.
        label:
          type: string
          description: Human-readable coupon label.
        discount_type:
          type: string
          description: Type of discount applied (e.g. percent, fixed_cart, fixed_product).
        saving:
          type: string
          description: Amount saved by this coupon, formatted without HTML.
        saving_html:
          type: string
          description: Amount saved by this coupon, formatted as HTML.
    RemovedItem:
      type: object
      properties:
        key:
          type: string
        product_id:
          type: integer
        quantity:
          type: integer
        name:
          type: string
    CrossSellItem:
      type: object
      properties:
        id:
          type: integer
        product_name:
          type: string
        product_title:
          type: string
        price:
          type: string
          description: Current price. Raw numeric string (e.g. "1800") by default; formatted string (e.g. "$18.00") when `formatted=true`.
        regular_price:
          type: string
          description: Regular price. Raw numeric string by default; formatted when `formatted=true`.
        sale_price:
          type: string
          description: Sale price if on sale, otherwise empty string. Raw numeric string by default; formatted when `formatted=true`.
        product_image:
          type: string
    ErrorResponse:
      type: object
      description: Standard error response structure.
      properties:
        code:
          type: string
          description: Machine-readable error code.
          example: cocart_invalid_parameter
        message:
          type: string
          description: Human-readable error message.
          example: Invalid parameter provided.
        data:
          type: object
          description: Additional error data.
          properties:
            status:
              type: integer
              description: HTTP status code.
              example: 400
          additionalProperties: true
    ProductShippingRates:
      type: object
      description: Shipping rates calculated for a product.
      properties:
        item_key:
          type: string
          description: The cart item key generated from the product, variation and item data.
        id:
          type: integer
          description: Product ID.
        parent_id:
          type: integer
          description: Parent product ID. 0 when the product has no parent.
        name:
          type: string
          description: Product name.
        type:
          type: string
          description: Product type (e.g. simple, variable, variation).
        item_match:
          type: boolean
          description: Whether the generated item key matched the cart item key during simulation.
        packages:
          type: object
          description: Shipping packages keyed by package number, each containing the available rates.
          additionalProperties:
            $ref: '#/components/schemas/ShippingRatesPackage'
    ShippingRatesPackage:
      type: object
      properties:
        rates:
          type: object
          description: Available shipping rates keyed by rate key.
          additionalProperties:
            $ref: '#/components/schemas/ProductShippingRate'
        formatted_destination:
          type: string
          description: Formatted destination address the rates were calculated for.
    ProductShippingRate:
      type: object
      properties:
        key:
          type: string
          description: Rate key (e.g. "flat_rate:1").
        method_id:
          type: string
          description: Shipping method ID.
        instance_id:
          type: integer
          description: Shipping method instance ID.
        label:
          type: string
          description: Shipping method label.
        cost:
          type: string
          description: Shipping cost as a raw numeric string in the currency's smallest unit (e.g. "1000" = $10.00).
        html:
          type: string
          description: Shipping method label with cost, formatted without HTML tags.
        taxes:
          type: string
          description: Shipping tax amount as a raw numeric string. Empty string when no tax applies.
        meta_data:
          type: object
          description: Rate meta data (e.g. the items included in the package).
          additionalProperties: true
    Account:
      type: object
      description: The customer's account details.
      properties:
        user:
          type: object
          description: User account information.
          properties:
            id:
              type: integer
              description: Unique identifier for the user.
            date_registered:
              type: string
              format: date-time
              description: User registration date.
            email:
              type: string
              format: email
              description: Email address used when registered. May differ from the billing email address.
            first_name:
              type: string
              description: First name.
            last_name:
              type: string
              description: Last name.
            display_name:
              type: string
              description: Display name.
            addresses:
              type: object
              description: Customer addresses. The `shipping` address is only included when the store ships to an address other than billing.
              additionalProperties:
                $ref: '#/components/schemas/AccountAddress'
            orders_count:
              type: integer
              description: Total number of orders.
            total_spent:
              type: string
              description: Total amount spent, formatted without HTML.
            is_paying_customer:
              type: boolean
              description: Whether the customer has made any purchase.
            avatar_url:
              type: string
              format: uri
              description: Avatar URL.
        recent_order:
          type: object
          description: Most recent order information.
          properties:
            order_id:
              type: integer
              nullable: true
              description: Most recent order ID. Null when no order has been made.
            order_date:
              type: string
              nullable: true
              description: Most recent order date. Null when no order has been made.
            order_data:
              type: string
              format: uri
              description: Link to the order details endpoint. Empty string when no order has been made.
        meta:
          type: object
          description: Additional customer metadata.
          properties:
            is_customer_outside_base:
              type: boolean
              description: Whether the customer is outside the base location.
            is_vat_exempt:
              type: boolean
              description: Whether the customer is VAT exempt.
        extensions:
          type: object
          description: |
            Additional data added by third-party extensions via the
            `cocart_get_account_extensions` filter. Includes
            `email_verification.verified` (WooCommerce 11.0+ only) - whether
            the account email address has been confirmed via
            `POST /my-account/verify-order-email`.
          additionalProperties: true
    AccountUpdateResult:
      type: object
      description: The result of updating the customer's account details.
      properties:
        success:
          type: boolean
          description: Whether the account details were saved.
        email_verification_pending:
          type: boolean
          description: |
            True when an email address change was requested and is awaiting
            confirmation via `GET /my-account/verify-email` - the account's
            email address has not changed yet. False when there was no email
            change, or verification is disabled and the email updated immediately.
      required:
        - success
        - email_verification_pending
    VerifyEmailResult:
      type: object
      description: The result of confirming a pending email address change.
      properties:
        success:
          type: boolean
        email:
          type: string
          format: email
          description: The email address that was applied to the account.
      required:
        - success
        - email
    SendOrderEmailVerificationResult:
      type: object
      description: The result of requesting an order email verification.
      properties:
        success:
          type: boolean
        status:
          type: string
          description: |
            `sent` when a new verification email was minted and sent,
            `throttled` when a resend was requested within the 60 second
            rate-limit window and no new email was sent.
          enum:
            - sent
            - throttled
      required:
        - success
        - status
    VerifyOrderEmailResult:
      type: object
      description: The result of confirming ownership of the account email address.
      properties:
        success:
          type: boolean
        email:
          type: string
          format: email
          description: The account email address that was verified.
      required:
        - success
        - email
    AccountAddress:
      type: object
      properties:
        first_name:
          type: string
          description: First name.
        last_name:
          type: string
          description: Last name.
        company:
          type: string
          description: Company name.
        address_1:
          type: string
          description: Address line 1.
        address_2:
          type: string
          description: Address line 2.
        city:
          type: string
          description: City.
        state:
          type: string
          description: State/Province.
        postcode:
          type: string
          description: Postcode/ZIP.
        country:
          type: string
          description: Country code.
        email:
          type: string
          format: email
          description: Email address (billing only).
        phone:
          type: string
          description: Phone number (billing only).
    AccountAddressUpdateRequest:
      type: object
      description: |
        At least one of `billing_address` or `shipping_address` must be provided.
        Only the fields included in each address object are updated; omitted
        fields are left unchanged.
      properties:
        billing_address:
          type: object
          description: Billing address fields to update.
          additionalProperties: true
        shipping_address:
          type: object
          description: Shipping address fields to update.
          additionalProperties: true
    AccountAddressUpdateResult:
      type: object
      description: The result of updating the customer's saved address(es).
      properties:
        addresses:
          type: object
          description: The customer addresses after the update.
          additionalProperties:
            $ref: '#/components/schemas/AccountAddress'
      required:
        - addresses
    CancelOrderResult:
      type: object
      description: The result of cancelling an order.
      properties:
        success:
          type: boolean
          description: Whether the order was cancelled.
        order_id:
          type: integer
          description: Unique identifier for the order.
        order_status:
          type: string
          description: Order status after cancellation.
      required:
        - success
        - order_id
        - order_status
    CustomerDownload:
      type: object
      properties:
        product_name:
          type: string
          description: Product name.
        download_name:
          type: string
          description: Download name.
        file:
          type: string
          format: uri
          description: Download URL.
        downloads_remaining:
          type: string
          description: Number of downloads remaining, or the infinity symbol when unlimited.
        download_expires:
          type: string
          description: Download expiration date, or "Never".
    CustomerOrders:
      type: object
      description: Paginated list of customer orders.
      properties:
        orders:
          type: array
          description: List of customer orders.
          items:
            type: object
            properties:
              order_id:
                type: integer
                description: Unique identifier for the order.
              order_status:
                type: string
                description: Order status.
              order_date:
                type: string
                description: Order date.
              item_count:
                type: integer
                description: Number of items in the order (excluding refunded items).
              order_total:
                type: string
                description: Order total amount, formatted without HTML.
              order_actions:
                type: object
                description: Available actions for the order (e.g. view), each with a `url` and `label`.
                additionalProperties:
                  $ref: '#/components/schemas/OrderAction'
        pagination:
          type: object
          description: Pagination information. Links are only present when more pages are available.
          properties:
            previous:
              type: string
              format: uri
              description: Link to previous page.
            next:
              type: string
              format: uri
              description: Link to next page.
    OrderAction:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: URL to perform the action.
        label:
          type: string
          description: Human-readable action label.
    CustomerOrder:
      type: object
      description: A single customer order. Extendable via the `cocart_add_additional_single_order_fields` filter.
      properties:
        order_id:
          type: integer
          description: Unique identifier for the order.
        order_key:
          type: string
          description: Order key for verification, required to pay for the order.
        order_number:
          type: string
          description: Order number.
        order_parent:
          type: integer
          description: Parent order ID. 0 when the order has no parent.
        order_date:
          type: string
          description: Order date.
        order_status:
          type: string
          description: Order status.
        order_currency:
          type: string
          description: Order currency code.
        billing_address:
          type: string
          description: Formatted billing address as a single line.
        shipping_address:
          type: string
          description: Formatted shipping address as a single line.
        phone:
          type: string
          description: Billing phone number.
        email:
          type: string
          format: email
          description: Billing email address.
        ship_to_billing:
          type: boolean
          description: Whether the order needs a shipping address.
        items:
          type: array
          description: Order items.
          items:
            $ref: '#/components/schemas/OrderItem'
        totals:
          type: object
          description: Order totals rows keyed by total type (e.g. subtotal, shipping, payment_method, total), each with a `label` and `value`.
          additionalProperties:
            type: object
            properties:
              label:
                type: string
                description: Total row label.
              value:
                type: string
                description: Total row value, formatted without HTML.
        order_note:
          type: string
          description: Customer note left on the order.
        order_notes:
          type: array
          description: Order notes shared with the customer.
          items:
            type: object
            properties:
              date:
                type: string
                description: Note date.
              note:
                type: string
                description: Note content.
        downloads:
          type: array
          description: Downloadable items for the order. Empty when the order has no permitted downloads.
          items:
            $ref: '#/components/schemas/CustomerDownload'
        order_actions:
          type: object
          description: Available actions for the order (e.g. pay, cancel), each with a `url` and `label`.
          additionalProperties:
            $ref: '#/components/schemas/OrderAction'
    OrderItem:
      type: object
      properties:
        item_id:
          type: integer
          description: Order item ID.
        product_id:
          type: integer
          description: Product ID. Empty when the product no longer exists.
        variation_id:
          type: integer
          description: Variation ID. 0 when the item is not a variation.
        product_image:
          type: string
          format: uri
          description: Product featured image URL.
        product_name:
          type: string
          description: Product name.
        product_title:
          type: string
          description: Product title.
        product_type:
          type: string
          description: Product type.
        sku:
          type: string
          description: Product SKU.
        quantity:
          type: string
          description: Quantity ordered.
        subtotal:
          type: string
          description: Line subtotal, formatted without HTML.
        purchase_note:
          type: string
          description: Product purchase note. Only shown for completed and processing orders.
        refunded_qty:
          type: string
          description: Quantity refunded for this item.
        meta:
          type: object
          description: Formatted item meta data keyed by meta ID.
          additionalProperties: true
        link:
          type: string
          format: uri
          description: Link to the product endpoint. Empty when the product no longer exists.
    CustomerSubscriptions:
      type: object
      description: Paginated list of customer subscriptions.
      properties:
        subscriptions:
          type: array
          description: List of customer subscriptions.
          items:
            type: object
            properties:
              subscription_id:
                type: integer
                description: Unique identifier for the subscription.
              subscription_number:
                type: string
                description: Subscription number.
              subscription_status:
                type: string
                description: Subscription status.
              next_payment:
                type: string
                description: Next payment date. Empty when no future payment is scheduled.
              subscription_total:
                type: string
                description: Subscription total, formatted without HTML.
              is_manual:
                type: boolean
                description: Whether the subscription requires manual renewal.
              view:
                type: string
                format: uri
                description: Link to view the subscription.
        pagination:
          type: object
          description: Pagination information. Links are only present when more pages are available.
          properties:
            previous:
              type: string
              format: uri
              description: Link to previous page.
            next:
              type: string
              format: uri
              description: Link to next page.
    CustomerSubscription:
      type: object
      description: A single customer subscription.
      properties:
        subscription_id:
          type: integer
          description: Unique identifier for the subscription.
        subscription_number:
          type: string
          description: Subscription number.
        parent_order:
          type: integer
          description: Parent order ID.
        order:
          type: string
          format: uri
          description: Link to the parent order.
        subscription_status:
          type: string
          description: Subscription status.
        subscription_total:
          type: string
          description: Subscription total, formatted without HTML.
        is_manual:
          type: boolean
          description: Whether the subscription requires manual renewal.
        start_date:
          $ref: '#/components/schemas/SubscriptionTitledValue'
        next_payment:
          $ref: '#/components/schemas/SubscriptionTitledValue'
        end_date:
          $ref: '#/components/schemas/SubscriptionTitledValue'
        trial_end:
          $ref: '#/components/schemas/SubscriptionTitledValue'
        payment:
          $ref: '#/components/schemas/SubscriptionTitledValue'
        billing_address:
          type: string
          description: Formatted billing address as a single line.
        shipping_address:
          type: string
          description: Formatted shipping address as a single line.
        notes:
          type: array
          description: Subscription notes shared with the customer.
          items:
            type: object
            properties:
              date:
                type: string
                description: Note date.
              note:
                type: string
                description: Note content.
    SubscriptionTitledValue:
      type: object
      description: A labelled subscription detail row, e.g. a date or the payment method.
      properties:
        title:
          type: string
          description: Field title.
        value:
          type: string
          description: Field value. Empty when not applicable to this subscription.
    SubscriptionActionResult:
      type: object
      description: Result of a subscription status action (suspend, cancel, reactivate).
      properties:
        subscription_id:
          type: integer
          description: Unique identifier for the subscription.
        subscription_status:
          type: string
          description: Subscription status after the action.
    SubscriptionAutoRenewResult:
      type: object
      description: Result of toggling subscription auto-renewal.
      properties:
        subscription_id:
          type: integer
          description: Unique identifier for the subscription.
        is_manual:
          type: boolean
          description: Whether the subscription now requires manual renewal.
    SubscriptionPaymentMethodResult:
      type: object
      description: Result of updating a subscription's payment method.
      properties:
        subscription_id:
          type: integer
          description: Unique identifier for the subscription.
        payment_method:
          type: string
          description: Payment method display name after the change.
        is_manual:
          type: boolean
          description: Whether the subscription requires manual renewal.
    SubscriptionResubscribeResult:
      type: object
      description: Result of seeding the cart to resubscribe.
      properties:
        subscription_id:
          type: integer
          description: Unique identifier for the subscription.
        cart_items_added:
          type: integer
          description: Number of line items added to the cart.
        cart_item_count:
          type: integer
          description: Total items now in the cart.
        cart_total:
          type: string
          description: Formatted cart total.
        saved_cart_item_count:
          type: integer
          description: Number of items from the customer's previous cart that were snapshotted before it was replaced (0 if the cart was already empty).
    SubscriptionResubscribeRestoreResult:
      type: object
      description: Result of restoring the cart snapshot taken before a resubscribe attempt.
      properties:
        restored:
          type: boolean
          description: Whether a saved cart snapshot was restored.
        cart_item_count:
          type: integer
          description: Total items now in the cart.
        restored_item_count:
          type: integer
          description: Number of items restored from the saved cart snapshot.
    RegisteredCustomer:
      type: object
      description: The newly registered customer.
      properties:
        user_id:
          type: integer
          description: Unique identifier for the new user.
        username:
          type: string
          description: The username registered for the new user.
        message:
          type: string
          description: Human-readable confirmation message.
security:
  - {}
  - basicAuth: []
  - bearerAuth: []