Skip to main content

Orders

The orders API allows you to create, view, update, and delete individual, or a batch, of orders.

Order properties​

AttributeTypeDescription
idintegerUnique identifier for the resource. READ-ONLY
parent_idintegerParent order ID.
statusstringOrder status. Default is pending. Options (plugins may include new status): pending, processing, on-hold, completed, cancelled, refunded and failed.
order_keystringOrder key. READ-ONLY
numberstringOrder number. READ-ONLY
currencystringCurrency the order was created with, in ISO format, e.g USD. Default is the current store currency.
versionstringVersion of WooCommerce when the order was made. READ-ONLY
prices_include_taxbooleanShows if the prices included tax during checkout. READ-ONLY
date_createddate-timeThe date the order was created, in the site's timezone. READ-ONLY
date_modifieddate-timeThe date the order was last modified, in the site's timezone. READ-ONLY
customer_idintegerUser ID who owns the order. Use 0 for guests. Default is 0.
discount_totalstringTotal discount amount for the order. READ-ONLY
discount_taxstringTotal discount tax amount for the order. READ-ONLY
shipping_totalstringTotal shipping amount for the order. READ-ONLY
shipping_taxstringTotal shipping tax amount for the order. READ-ONLY
cart_taxstringSum of line item taxes only. READ-ONLY
totalstringGrand total. READ-ONLY
total_taxstringSum of all taxes. READ-ONLY
billingobjectBilling address. See Customer Billing Address properties.
shippingobjectShipping address. See Customer Shipping Address properties.
payment_methodstringPayment method ID.
payment_method_titlestringPayment method title.
set_paidbooleanDefine if the order is paid. It will set the status to processing and reduce stock items. Default is false. WRITE-ONLY
transaction_idstringUnique transaction ID. In write-mode only is available if set_paid is true.
customer_ip_addressstringCustomer's IP address. READ-ONLY
customer_user_agentstringUser agent of the customer. READ-ONLY
created_viastringShows where the order was created. READ-ONLY
customer_notestringNote left by customer during checkout.
date_completeddate-timeThe date the order was completed, in the site's timezone. READ-ONLY
date_paiddate-timeThe date the order has been paid, in the site's timezone. READ-ONLY
cart_hashstringMD5 hash of cart items to ensure orders are not modified. READ-ONLY
line_itemsarrayLine items data. See Line Items properties.
tax_linesarrayTax lines data. See Tax Lines properties. READ-ONLY
shipping_linesarrayShipping lines data. See Shipping Lines properties.
fee_linesarrayFee lines data. See Fee Lines Properties.
coupon_linesarrayCoupons line data. See Coupon Lines properties.
refundsarrayList of refunds. See Refund line properties. READ-ONLY

Billing address properties​

AttributeTypeDescription
first_namestringFirst name.
last_namestringLast name.
companystringCompany name.
address_1stringAddress line 1.
address_2stringAddress line 2.
citystringCity name.
statestringISO code or name of the state, province or district.
postcodestringPostal code.
countrystringISO code of the country.
emailstringEmail address.
phonestringPhone number.

Shipping address properties​

AttributeTypeDescription
first_namestringFirst name.
last_namestringLast name.
companystringCompany name.
address_1stringAddress line 1.
address_2stringAddress line 2.
citystringCity name.
statestringISO code or name of the state, province or district.
postcodestringPostal code.
countrystringISO code of the country.

Line item properties​

AttributeTypeDescription
idintegerItem ID. READ-ONLY
namestringProduct name. READ-ONLY
skustringProduct SKU. READ-ONLY
product_idintegerProduct ID.
variation_idintegerVariation ID, if applicable.
quantityintegerQuantity ordered.
tax_classstringTax class of product. READ-ONLY
pricestringProduct price. READ-ONLY
subtotalstringLine subtotal (before discounts).
subtotal_taxstringLine subtotal tax (before discounts).
totalstringLine total (after discounts).
total_taxstringLine total tax (after discounts).
taxesarrayLine taxes with id, total and subtotal. READ-ONLY
metaarrayLine item meta data with key, label and value. READ-ONLY

Tax line properties​

AttributeTypeDescription
idintegerItem ID. READ-ONLY
rate_codestringTax rate code. READ-ONLY
rate_idstringTax rate ID. READ-ONLY
labelstringTax rate label. READ-ONLY
compoundbooleanShow if is a compound tax rate. Compound tax rates are applied on top of other tax rates. READ-ONLY
tax_totalstringTax total (not including shipping taxes). READ-ONLY
shipping_tax_totalstringShipping tax total. READ-ONLY

Shipping line properties​

AttributeTypeDescription
idintegerItem ID. READ-ONLY
method_titlestringShipping method name.
method_idstringShipping method ID. REQUIRED
totalstringLine total (after discounts).
total_taxstringLine total tax (after discounts). READ-ONLY
taxesarrayLine taxes with id and total. READ-ONLY

Fee line properties​

AttributeTypeDescription
idintegerItem ID. READ-ONLY
namestringFee name. REQUIRED
tax_classstringTax class. REQUIRED IF THE FEE IS TAXABLE
tax_statusstringTax status of fee. Set to taxable if need apply taxes.
totalstringLine total (after discounts).
total_taxstringLine total tax (after discounts).
taxesarrayLine taxes with id, total and subtotal. READ-ONLY

Coupon line properties​

AttributeTypeDescription
idintegerItem ID. READ-ONLY
codestringCoupon code. REQUIRED
discountstringDiscount total. REQUIRED
discount_taxstringDiscount total tax. READ-ONLY

Refund line properties​

AttributeTypeDescription
idintegerRefund ID. READ-ONLY
reasonstringRefund reason. READ-ONLY
totalstringRefund total. READ-ONLY

Create an order​

This API helps you to create a new order.

POST /wp-json/wc/v1/orders

Example of create a paid order:

curl -X POST https://example.com/wp-json/wc/v1/orders \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "payment_method": "bacs",
  "payment_method_title": "Direct Bank Transfer",
  "set_paid": true,
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  },
  "line_items": [
    {
      "product_id": 93,
      "quantity": 2
    },
    {
      "product_id": 22,
      "variation_id": 23,
      "quantity": 1
    }
  ],
  "shipping_lines": [
    {
      "method_id": "flat_rate",
      "method_title": "Flat Rate",
      "total": "10.00"
    }
  ]
}'

Retrieve an order​

This API lets you retrieve and view a specific order.

GET /wp-json/wc/v1/orders/<id>
curl https://example.com/wp-json/wc/v1/orders/154 \
	-u consumer_key:consumer_secret

Available parameters​

ParameterTypeDescription
dpstringNumber of decimal points to use in each resource.

List all orders​

This API helps you to view all the orders.

GET /wp-json/wc/v1/orders
curl https://example.com/wp-json/wc/v1/orders \
	-u consumer_key:consumer_secret

Available parameters​

ParameterTypeDescription
contextstringScope under which the request is made; determines fields present in response. Options: view and edit.
pageintegerCurrent page of the collection.
per_pageintegerMaximum number of items to be returned in result set.
searchstringLimit results to those matching a string.
afterstringLimit response to resources published after a given ISO8601 compliant date.
beforestringLimit response to resources published before a given ISO8601 compliant date.
dates_are_gmtbooleanInterpret after and before as UTC dates when true.
excludestringEnsure result set excludes specific ids.
includestringLimit result set to specific ids.
offsetintegerOffset the result set by a specific number of items.
orderstringOrder sort attribute ascending or descending. Default is asc. Options: asc and desc.
orderbystringSort collection by object attribute. Default is date, Options: date, id, include, title and slug.
statusstringLimit result set to orders assigned a specific status. Default is any. Options (plugins may add new status): any, pending, processing, on-hold, completed, cancelled, refunded and failed.
customerstringLimit result set to orders assigned a specific customer.
productstringLimit result set to orders assigned a specific product.
dpstringNumber of decimal points to use in each resource.

Update an Order​

This API lets you make changes to an order.

HTTP Request​

PUT /wp-json/wc/v1/orders/<id>
curl -X PUT https://example.com/wp-json/wc/v1/orders/154 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "status": "completed"
}'

Delete an order​

This API helps you delete an order.

DELETE /wp-json/wc/v1/orders/<id>
curl -X DELETE https://example.com/wp-json/wc/v1/orders/154?force=true \
	-u consumer_key:consumer_secret

Available parameters​

ParameterTypeDescription
forcebooleanUse true to permanently delete the order. Default is false.

Batch update orders​

This API helps you to batch create, update and delete multiple orders.

note

Note: By default it's limited to up to 100 objects to be created, updated or deleted.

POST /wp-json/wc/v1/orders/batch
curl -X POST https://example.com/wp-json/wc/v1/orders/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "payment_method": "bacs",
      "payment_method_title": "Direct Bank Transfer",
      "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
      },
      "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
      },
      "line_items": [
        {
          "product_id": 79,
          "quantity": 1
        },
        {
          "product_id": 93,
          "quantity": 1
        },
        {
          "product_id": 22,
          "variation_id": 23,
          "quantity": 1
        }
      ],
      "shipping_lines": [
        {
          "method_id": "flat_rate",
          "method_title": "Flat Rate",
          "total": "30.00"
        }
      ]
    },
    {
      "payment_method": "bacs",
      "payment_method_title": "Direct Bank Transfer",
      "set_paid": true,
      "billing": {
        "first_name": "John",
        "last_name": "Doe",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
      },
      "shipping": {
        "first_name": "John",
        "last_name": "Doe",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
      },
      "line_items": [
        {
          "product_id": 22,
          "variation_id": 23,
          "quantity": 1
        },
        {
          "product_id": 22,
          "variation_id": 24,
          "quantity": 1
        }
      ],
      "shipping_lines": [
        {
          "method_id": "flat_rate",
          "method_title": "Flat Rate",
          "total": "20.00"
        }
      ]
    }
  ],
  "update": [
    {
      "id": 154,
      "shipping_methods": "Local Delivery"
    }
  ],
  "delete": [
    154
  ]
}'

Use of your personal data

We and our partners process your personal data (such as browsing data, IP Addresses, cookie information, and other unique identifiers) based on your consent and/or our legitimate interest to optimize our website, marketing activities, and your user experience.