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.

E-CommerceOpen-SourceOrderProductWordPress

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."
        }
      }
    }
  }
}