WooCommerce · Schema

WooCommerce Order

A WooCommerce customer order created via the storefront, checkout API, or REST API. Orders track the complete lifecycle of a purchase from cart submission through payment, fulfillment, and optional refunds. Monetary amounts are represented as decimal strings with two decimal places.

eCommerceOpen SourceOrdersProductsWordPress

Properties

Name Type Description
id integer Order unique identifier assigned by WooCommerce.
parent_id integer Parent order ID. Used for refund orders and child orders.
number string Order number displayed to customers on confirmation pages and emails.
order_key string Unique key used to verify order ownership in public-facing URLs.
created_via string How the order was created (e.g. checkout, rest-api, admin).
version string WooCommerce version when the order was created.
status string Current order status.
currency string ISO 4217 currency code used for the order (e.g. USD, GBP, EUR).
date_created string Date the order was created in site timezone (ISO8601 format).
date_created_gmt string Date the order was created in UTC (ISO8601 format).
date_modified string Date the order was last modified in site timezone.
date_modified_gmt string Date the order was last modified in UTC.
date_completed stringnull Date the order was marked as completed. Null if not completed.
date_paid stringnull Date the order was paid. Null if not paid.
discount_total string Total discount amount applied by coupons, as a decimal string.
discount_tax string Tax amount on discounts as a decimal string.
shipping_total string Total shipping cost as a decimal string.
shipping_tax string Tax on shipping cost as a decimal string.
cart_tax string Total cart item taxes before shipping as a decimal string.
total string Grand total including taxes and shipping as a decimal string.
total_tax string Total tax amount as a decimal string.
prices_include_tax boolean Whether the store's product prices include tax.
customer_id integer Customer ID associated with this order. 0 for guest orders.
customer_ip_address string Customer IP address at time of order placement.
customer_user_agent string Customer browser user agent string at time of order placement.
customer_note string Note entered by the customer at checkout.
billing object Billing address for the order.
shipping object Shipping address for the order.
payment_method string Payment method ID (e.g. stripe, paypal, bacs).
payment_method_title string Human-readable payment method name shown to the customer.
transaction_id string Unique transaction ID from the payment gateway.
payment_url string URL for the customer to complete pending payment.
line_items array Products purchased in this order.
tax_lines array Tax lines applied to the order.
shipping_lines array Shipping methods applied to the order.
fee_lines array Extra fees applied to the order.
coupon_lines array Coupons applied to the order.
refunds array Refunds associated with this order.
meta_data array Custom metadata key-value pairs attached to the order.
View JSON Schema on GitHub

JSON Schema

woocommerce-order-schema.json Raw ↑ 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://developer.woocommerce.com/schemas/order.json",
  "title": "WooCommerce Order",
  "description": "A WooCommerce customer order created via the storefront, checkout API, or REST API. Orders track the complete lifecycle of a purchase from cart submission through payment, fulfillment, and optional refunds. Monetary amounts are represented as decimal strings with two decimal places.",
  "type": "object",
  "required": ["id", "status", "currency", "total", "line_items"],
  "properties": {
    "id": {
      "type": "integer",
      "description": "Order unique identifier assigned by WooCommerce."
    },
    "parent_id": {
      "type": "integer",
      "description": "Parent order ID. Used for refund orders and child orders."
    },
    "number": {
      "type": "string",
      "description": "Order number displayed to customers on confirmation pages and emails."
    },
    "order_key": {
      "type": "string",
      "description": "Unique key used to verify order ownership in public-facing URLs."
    },
    "created_via": {
      "type": "string",
      "description": "How the order was created (e.g. checkout, rest-api, admin)."
    },
    "version": {
      "type": "string",
      "description": "WooCommerce version when the order was created."
    },
    "status": {
      "type": "string",
      "description": "Current order status.",
      "enum": ["pending", "processing", "on-hold", "completed", "cancelled", "refunded", "failed", "trash"]
    },
    "currency": {
      "type": "string",
      "description": "ISO 4217 currency code used for the order (e.g. USD, GBP, EUR).",
      "pattern": "^[A-Z]{3}$"
    },
    "date_created": {
      "type": "string",
      "format": "date-time",
      "description": "Date the order was created in site timezone (ISO8601 format)."
    },
    "date_created_gmt": {
      "type": "string",
      "format": "date-time",
      "description": "Date the order was created in UTC (ISO8601 format)."
    },
    "date_modified": {
      "type": "string",
      "format": "date-time",
      "description": "Date the order was last modified in site timezone."
    },
    "date_modified_gmt": {
      "type": "string",
      "format": "date-time",
      "description": "Date the order was last modified in UTC."
    },
    "date_completed": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "Date the order was marked as completed. Null if not completed."
    },
    "date_paid": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "Date the order was paid. Null if not paid."
    },
    "discount_total": {
      "type": "string",
      "description": "Total discount amount applied by coupons, as a decimal string.",
      "pattern": "^\\d+\\.\\d{2}$"
    },
    "discount_tax": {
      "type": "string",
      "description": "Tax amount on discounts as a decimal string.",
      "pattern": "^\\d+\\.\\d{2}$"
    },
    "shipping_total": {
      "type": "string",
      "description": "Total shipping cost as a decimal string.",
      "pattern": "^\\d+\\.\\d{2}$"
    },
    "shipping_tax": {
      "type": "string",
      "description": "Tax on shipping cost as a decimal string.",
      "pattern": "^\\d+\\.\\d{2}$"
    },
    "cart_tax": {
      "type": "string",
      "description": "Total cart item taxes before shipping as a decimal string.",
      "pattern": "^\\d+\\.\\d{2}$"
    },
    "total": {
      "type": "string",
      "description": "Grand total including taxes and shipping as a decimal string.",
      "pattern": "^\\d+\\.\\d{2}$"
    },
    "total_tax": {
      "type": "string",
      "description": "Total tax amount as a decimal string.",
      "pattern": "^\\d+\\.\\d{2}$"
    },
    "prices_include_tax": {
      "type": "boolean",
      "description": "Whether the store's product prices include tax."
    },
    "customer_id": {
      "type": "integer",
      "description": "Customer ID associated with this order. 0 for guest orders."
    },
    "customer_ip_address": {
      "type": "string",
      "description": "Customer IP address at time of order placement."
    },
    "customer_user_agent": {
      "type": "string",
      "description": "Customer browser user agent string at time of order placement."
    },
    "customer_note": {
      "type": "string",
      "description": "Note entered by the customer at checkout."
    },
    "billing": {
      "$ref": "#/$defs/Address",
      "description": "Billing address for the order."
    },
    "shipping": {
      "$ref": "#/$defs/Address",
      "description": "Shipping address for the order."
    },
    "payment_method": {
      "type": "string",
      "description": "Payment method ID (e.g. stripe, paypal, bacs)."
    },
    "payment_method_title": {
      "type": "string",
      "description": "Human-readable payment method name shown to the customer."
    },
    "transaction_id": {
      "type": "string",
      "description": "Unique transaction ID from the payment gateway."
    },
    "payment_url": {
      "type": "string",
      "format": "uri",
      "description": "URL for the customer to complete pending payment."
    },
    "line_items": {
      "type": "array",
      "description": "Products purchased in this order.",
      "items": {
        "$ref": "#/$defs/LineItem"
      }
    },
    "tax_lines": {
      "type": "array",
      "description": "Tax lines applied to the order.",
      "items": {
        "$ref": "#/$defs/TaxLine"
      }
    },
    "shipping_lines": {
      "type": "array",
      "description": "Shipping methods applied to the order.",
      "items": {
        "$ref": "#/$defs/ShippingLine"
      }
    },
    "fee_lines": {
      "type": "array",
      "description": "Extra fees applied to the order.",
      "items": {
        "$ref": "#/$defs/FeeLine"
      }
    },
    "coupon_lines": {
      "type": "array",
      "description": "Coupons applied to the order.",
      "items": {
        "$ref": "#/$defs/CouponLine"
      }
    },
    "refunds": {
      "type": "array",
      "description": "Refunds associated with this order.",
      "items": {
        "$ref": "#/$defs/OrderRefundSummary"
      }
    },
    "meta_data": {
      "type": "array",
      "description": "Custom metadata key-value pairs attached to the order.",
      "items": {
        "$ref": "#/$defs/MetaData"
      }
    }
  },
  "$defs": {
    "Address": {
      "type": "object",
      "description": "A postal address used for billing or shipping.",
      "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": "Street address line 1."
        },
        "address_2": {
          "type": "string",
          "description": "Street address line 2."
        },
        "city": {
          "type": "string",
          "description": "City or town name."
        },
        "state": {
          "type": "string",
          "description": "State, province, or region code."
        },
        "postcode": {
          "type": "string",
          "description": "Postal or ZIP code."
        },
        "country": {
          "type": "string",
          "description": "ISO 3166-1 alpha-2 country code.",
          "pattern": "^[A-Z]{2}$"
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "Email address (billing address only)."
        },
        "phone": {
          "type": "string",
          "description": "Phone number (billing address only)."
        }
      }
    },
    "MetaData": {
      "type": "object",
      "description": "A custom metadata key-value entry.",
      "required": ["key"],
      "properties": {
        "id": {
          "type": "integer",
          "description": "Metadata entry unique identifier."
        },
        "key": {
          "type": "string",
          "description": "Metadata key name."
        },
        "value": {
          "description": "Metadata value. May be a string, number, or object depending on the key."
        }
      }
    },
    "LineItem": {
      "type": "object",
      "description": "A product purchased as part of an order.",
      "properties": {
        "id": {
          "type": "integer",
          "description": "Line item unique identifier."
        },
        "name": {
          "type": "string",
          "description": "Product name at the time of purchase."
        },
        "product_id": {
          "type": "integer",
          "description": "ID of the parent product."
        },
        "variation_id": {
          "type": "integer",
          "description": "ID of the product variation. 0 for simple products."
        },
        "quantity": {
          "type": "integer",
          "description": "Quantity ordered.",
          "minimum": 1
        },
        "tax_class": {
          "type": "string",
          "description": "Tax class slug applied to this line item."
        },
        "subtotal": {
          "type": "string",
          "description": "Line item subtotal before discounts as a decimal string."
        },
        "subtotal_tax": {
          "type": "string",
          "description": "Subtotal tax as a decimal string."
        },
        "total": {
          "type": "string",
          "description": "Line item total after discounts as a decimal string."
        },
        "total_tax": {
          "type": "string",
          "description": "Total tax for the line item as a decimal string."
        },
        "taxes": {
          "type": "array",
          "description": "Tax breakdown per rate for this line item.",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "description": "Tax rate ID."
              },
              "total": {
                "type": "string",
                "description": "Tax amount for this rate."
              },
              "subtotal": {
                "type": "string",
                "description": "Subtotal tax for this rate."
              }
            }
          }
        },
        "sku": {
          "type": "string",
          "description": "Product SKU at time of purchase."
        },
        "price": {
          "type": "number",
          "description": "Unit price of the product at time of purchase."
        },
        "meta_data": {
          "type": "array",
          "description": "Custom metadata for the line item (e.g. selected variation attributes).",
          "items": {
            "$ref": "#/$defs/MetaData"
          }
        }
      }
    },
    "TaxLine": {
      "type": "object",
      "description": "A tax rate line applied to the order.",
      "properties": {
        "id": {
          "type": "integer",
          "description": "Tax line unique identifier."
        },
        "rate_code": {
          "type": "string",
          "description": "Tax rate code slug."
        },
        "rate_id": {
          "type": "integer",
          "description": "Tax rate ID."
        },
        "label": {
          "type": "string",
          "description": "Tax rate display label."
        },
        "compound": {
          "type": "boolean",
          "description": "Whether this is a compound tax rate."
        },
        "tax_total": {
          "type": "string",
          "description": "Tax amount on cart items for this rate."
        },
        "shipping_tax_total": {
          "type": "string",
          "description": "Tax amount on shipping for this rate."
        }
      }
    },
    "ShippingLine": {
      "type": "object",
      "description": "A shipping method applied to the order.",
      "properties": {
        "id": {
          "type": "integer",
          "description": "Shipping line unique identifier."
        },
        "method_title": {
          "type": "string",
          "description": "Shipping method display name."
        },
        "method_id": {
          "type": "string",
          "description": "Shipping method ID slug."
        },
        "total": {
          "type": "string",
          "description": "Shipping cost as a decimal string."
        },
        "total_tax": {
          "type": "string",
          "description": "Shipping tax as a decimal string."
        },
        "meta_data": {
          "type": "array",
          "description": "Shipping line metadata.",
          "items": {
            "$ref": "#/$defs/MetaData"
          }
        }
      }
    },
    "FeeLine": {
      "type": "object",
      "description": "An additional fee applied to the order.",
      "properties": {
        "id": {
          "type": "integer",
          "description": "Fee line unique identifier."
        },
        "name": {
          "type": "string",
          "description": "Fee display name."
        },
        "tax_class": {
          "type": "string",
          "description": "Tax class applied to this fee."
        },
        "tax_status": {
          "type": "string",
          "description": "Whether the fee is taxable. Options: taxable, none.",
          "enum": ["taxable", "none"]
        },
        "total": {
          "type": "string",
          "description": "Fee amount as a decimal string."
        },
        "total_tax": {
          "type": "string",
          "description": "Tax on the fee as a decimal string."
        }
      }
    },
    "CouponLine": {
      "type": "object",
      "description": "A coupon applied to the order.",
      "properties": {
        "id": {
          "type": "integer",
          "description": "Coupon line unique identifier."
        },
        "code": {
          "type": "string",
          "description": "Coupon code used."
        },
        "discount": {
          "type": "string",
          "description": "Discount amount applied by this coupon."
        },
        "discount_tax": {
          "type": "string",
          "description": "Tax amount on the discount."
        },
        "meta_data": {
          "type": "array",
          "description": "Coupon line metadata.",
          "items": {
            "$ref": "#/$defs/MetaData"
          }
        }
      }
    },
    "OrderRefundSummary": {
      "type": "object",
      "description": "A summary of a refund associated with the order.",
      "properties": {
        "id": {
          "type": "integer",
          "description": "Refund unique identifier."
        },
        "reason": {
          "type": "string",
          "description": "Reason for the refund."
        },
        "total": {
          "type": "string",
          "description": "Refund amount as a negative decimal string."
        }
      }
    }
  }
}