> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data reference

> Metrics, breakdowns, refresh cadence, and limits for the WooCommerce data source in Adriel.

## Introduction

WooCommerce is a WordPress plugin for self-hosted online stores. The connector fetches orders and products from a WooCommerce installation via the WooCommerce REST API v3, exposing order, revenue, and product datasets for analytics. Authentication uses a per-store consumer key/secret pair generated inside the WooCommerce admin.

Because WooCommerce runs on the merchant's own infrastructure, currency, tax behavior, and order-status semantics follow the store's local configuration rather than a marketplace standard. Multi-currency support depends on the plugins installed on the WordPress site.

As an e-commerce connector, order, revenue, and product breakdowns are standardized so widgets can aggregate alongside ad-platform sources without additional configuration.

To connect this data source, see [How to connect WooCommerce to Adriel](/data-sources/o-z/woocommerce/how-to-connect).

## Data refresh strategy

### Architecture data

Architecture covers the store catalog and products. Products are fully refreshed **once per day**. The catalog snapshot includes product names, SKUs, prices, status, and categories. Newly added or deleted products appear after the next daily refresh.

### Reports data

Reports include order-level financial and status data. Orders are refreshed **hourly** on a rolling **1-day lookback window**: at every refresh, orders created or modified in the last 1 day are updated. This short window reflects the high frequency of order-status changes on WooCommerce stores. Revenue is reconstructed from the raw order payload, with currency taken from the shop's WooCommerce settings.

## Architecture levels

Store → Catalog / Product → Order → Order line.

## Date range limits

Historical backfill is capped at **90 days**: the connector's `maxFromDate` is 90 days ago, so orders older than 90 days from today cannot be retrieved. Date breakdowns (daily, weekly, monthly, and longer) are all bounded by this same 90-day historical window.

## Metrics

<Note>
  **How to read the columns**

  The **Data type** column uses this vocabulary: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean.

  The **API Key** column uses code style like `order_price_amount` for the field key Adriel exposes for the value. An italic tag such as *(Adriel-computed)* or *(Adriel-derived)* marks a value that Adriel reconstructs or derives rather than reading directly from a single WooCommerce field.
</Note>

### Orders

| Metric             | Description                       | Data type | API Key              |
| ------------------ | --------------------------------- | --------- | -------------------- |
| Order Count        | Number of distinct orders.        | Number    | `order_count`        |
| Order Buyer Count  | Number of distinct buyers.        | Number    | `order_buyer_count`  |
| Order Currency     | Currency the order was placed in. | Text      | `order_currency`     |
| Order Date         | Date the order was placed.        | Date      | `order_date`         |
| Order Payment Date | Date the order was paid.          | Date      | `order_payment_date` |
| Order Updated Date | Date the order was last modified. | Date      | `order_updated_date` |

### Revenue & sales

<Note>
  **Net sales and refund handling.** Order Net Sales reflects order total minus shipping and tax for active orders, zero for cancelled or on-hold orders, and a negative value on refund rows. Order Refund Amount carries the positive refund total tied to an order. Reports that need true net revenue should rely on Order Net Sales rather than the gross order amount.
</Note>

| Metric                | Description                                                                                                | Data type | API Key                                   |
| --------------------- | ---------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------- |
| Order Price Amount    | Total order value including tax and shipping.                                                              | Currency  | `order_price_amount`                      |
| Order Payment Amount  | Captured payment amount.                                                                                   | Currency  | `order_payment_amount`                    |
| Order Amount Due      | Outstanding amount on the order.                                                                           | Currency  | `order_amount_due`                        |
| Order Net Sales       | Order total minus shipping and tax for active orders; zero for cancelled/on-hold; negative on refund rows. | Currency  | `order_net_sales` *(Adriel-computed)*     |
| Order Refund Amount   | Refund total tied to an order.                                                                             | Currency  | `order_refund_amount` *(Adriel-computed)* |
| Order Discount Amount | Discount applied to the order.                                                                             | Currency  | `order_discount_amount`                   |
| Order Tax Amount      | Tax applied to the order.                                                                                  | Currency  | `order_tax_amount`                        |
| Order Shipping Fee    | Shipping charged on the order.                                                                             | Currency  | `order_shipping_fee`                      |

### Products

<Note>
  **Product Order metrics link products with their orders.** When a Product Order metric is used with a product filter, only the portion of the order tied to that product is included, and only orders containing at least one matching product are shown. If a product has been deleted from the catalog, the related orders may not appear — use Product Order metrics only when necessary.
</Note>

| Metric                     | Description                                         | Data type | API Key                      |
| -------------------------- | --------------------------------------------------- | --------- | ---------------------------- |
| Product Price              | Listed product price.                               | Currency  | `product_price`              |
| Product Retail Price       | Retail price before discount.                       | Currency  | `product_retail_price`       |
| Product Currency           | Currency code for the product price.                | Text      | `product_currency`           |
| Product Image              | Product image asset URL.                            | URL       | `product_image`              |
| Product Created Date       | Date the product was created.                       | Date      | `product_created_date`       |
| Product Updated Date       | Date the product was last updated.                  | Date      | `product_updated_date`       |
| Product Order Price Amount | Revenue tied to a specific product within an order. | Currency  | `product_order_price_amount` |
| Product Order Quantity     | Units of a specific product within an order.        | Number    | `product_order_quantity`     |

## Breakdowns

### Store & product hierarchy

| Breakdown             | Description                                         | API Key                                     |
| --------------------- | --------------------------------------------------- | ------------------------------------------- |
| Product ID            | WooCommerce product identifier.                     | `product_id`                                |
| Product Name          | Product display name.                               | `product_name`                              |
| Product Detailed Name | Extended product name including variant attributes. | `product_detailled_name` *(Adriel-derived)* |
| Product SKU           | Stock keeping unit.                                 | `product_sku`                               |
| Product Status        | WooCommerce product status.                         | `product_status`                            |

### Order details

| Breakdown            | Description                                                                                                 | API Key                |
| -------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------- |
| Order Status         | One of WooCommerce's order statuses (pending, processing, on-hold, completed, cancelled, refunded, failed). | `order_status`         |
| Order Payment Method | Payment method used on the order.                                                                           | `order_payment_method` |
| Order Source         | Origin attributed to the order.                                                                             | `order_source`         |

### Marketing attribution

<Note>
  These breakdowns are provided by Adriel, extracted from the order data so orders can be grouped by acquisition channel and device.
</Note>

| Breakdown    | Description                           |
| ------------ | ------------------------------------- |
| UTM Source   | `utm_source` recorded on the order.   |
| UTM Medium   | `utm_medium` recorded on the order.   |
| UTM Campaign | `utm_campaign` recorded on the order. |
| Device Type  | Device type attributed to the order.  |

### Time & date grouping

<Note>
  These breakdowns are provided by Adriel, grouping the same underlying order data into time buckets for reporting.
</Note>

| Breakdown           | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| Auto Time Breakdown | Automatically picks the best granularity for the date range. |
| Daily               | Split reports by day.                                        |
| Weekly (Start: Mon) | Split reports by week starting Monday.                       |
| Weekly (Start: Sun) | Split reports by week starting Sunday.                       |
| Monthly             | Split reports by calendar month.                             |
| Quarterly           | Split reports by calendar quarter.                           |
| Yearly              | Split reports by calendar year.                              |

### Overview

<Note>
  These breakdowns are provided by Adriel for aggregate and datasource-level views.
</Note>

| Breakdown       | Description                                   |
| --------------- | --------------------------------------------- |
| No Grouping     | Do not break down; return one aggregated row. |
| Datasource Name | Group by Adriel datasource name.              |

## Limitations

Based on the current connector, WooCommerce has:

* **A 90-day historical limit** (`maxFromDate` = 90 days ago). Orders older than 90 days from today cannot be back-filled.
* **An hourly refresh on a 1-day lookback window.** Orders created or modified more than 1 day before a refresh are not re-checked until they fall inside a later window.
* **HTTPS is required.** Credentials are transmitted as HTTP Basic Auth; without HTTPS the integration cannot complete authentication.
* **Currency follows the store.** Order and product currency come from the shop's WooCommerce settings. Multi-currency support depends on store plugins; without one, all values are reported in the shop's base currency.
* **Cancelled and on-hold orders contribute zero to net sales.** Revenue reconstruction typically treats `processing` and `completed` orders as confirmed.
* **Deleted products can hide their orders.** If a product cannot be retrieved from the API (e.g. it has been deleted), orders referencing it may not appear under Product Order metrics.
* **A 100,000-row query result cap** applies as the ecommerce overflow boundary; very large result sets are truncated at this limit.

## API references

* [WooCommerce REST API v3 reference](https://woocommerce.github.io/woocommerce-rest-api-docs/)
* [Authentication (HTTP Basic Auth)](https://woocommerce.github.io/woocommerce-rest-api-docs/#authentication)
* [Orders endpoint](https://woocommerce.github.io/woocommerce-rest-api-docs/#orders)
* [Order refunds endpoint](https://woocommerce.github.io/woocommerce-rest-api-docs/#order-refunds)
* [Products endpoint](https://woocommerce.github.io/woocommerce-rest-api-docs/#products)

## See also

* [How to connect WooCommerce](/data-sources/o-z/woocommerce/how-to-connect) (paired how-to)
* [Shopify data reference](/data-sources/o-z/shopify/data-reference) — hosted direct-to-consumer commerce platform