> ## 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 Shopee e-commerce data source in Adriel.

## Introduction

Shopee is a marketplace e-commerce platform operating across Southeast Asia, Latin America, and other markets. The connector reads a seller's Shopee shop data — orders or products — through the Shopee Open Platform API (v2), reconstructing sales analytics from raw orders and building a product catalog from raw product data.

Each Shopee data source is created in one of two modes, **orders** or **products**, and the mode is fixed at creation. A single data source reports on only one mode; to report on both orders and products for the same shop, connect the shop twice — once in each mode.

As an e-commerce connector, order, sales, and product data are standardized so widgets can aggregate alongside other sources without additional configuration.

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

## Data refresh strategy

The two modes refresh on different schedules.

### Orders

Orders refresh **hourly**. Each refresh pulls a short rolling window (about the last one to two days by order creation date) so that recently created and recently modified orders stay current without a full re-sync.

The **current day is excluded** until it closes. Today's orders are not pulled into the sync window, so the most recent full day of data is the previous day; the current day fills in once it completes.

### Products

Products are **fully refreshed once per day**. Each refresh rebuilds the catalog, so product additions, price changes, and status changes are reflected on the next daily run.

### Initial import and historical coverage

On first connection, Adriel imports up to **90 days** of history for the selected mode. Because Adriel caches the data, the longer the data source stays connected, the more historical data is stored — coverage grows beyond the initial 90-day window over time.

## Architecture levels

* **Orders mode:** Shop → Order → Order item. Each order carries its line items (product, quantity, and item price) for product-linked reporting.
* **Products mode:** Shop → Product → Model (variant). Each product model or variant is stored as a separate product record.

## Date range limits

The initial import reaches back approximately **90 days** from the connection date. Earlier history is not back-filled retroactively; the cache instead accumulates going forward for as long as the data source stays connected.

## Metrics

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

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

  **API Key** in code style like `total_amount` is the literal field name delivered by the Shopee API. *Italic text* describes how a value is produced when it doesn't map cleanly to a single field — typically an aggregation across rows or a value computed by Adriel.
</Note>

Metrics available depend on the data source mode. Order metrics apply to orders-mode data sources; product metrics apply to products-mode data sources.

### Orders

<Note>
  Currency values are reported in each order's own currency, taken from the order's `currency` field (for example `PHP` or `BRL`). When an order has no currency, the connector falls back to `USD`. Because a shop's orders can span currencies and markets, cross-shop totals should account for currency normalization.
</Note>

| Metric               | Description                                                                                                         | Data type | API Key                      |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- | --------- | ---------------------------- |
| Order Count          | Distinct number of orders.                                                                                          | Number    | *Aggregated from order rows* |
| Order Buyer Count    | Distinct number of buyers on orders.                                                                                | Number    | *Aggregated from order rows* |
| Order Payment Amount | Total amount charged on the order.                                                                                  | Currency  | `total_amount`               |
| Order Shipping Fee   | Actual shipping fee on the order.                                                                                   | Currency  | `actual_shipping_fee`        |
| Order Status         | Order status, mapped to Adriel's canonical values (see below).                                                      | Text      | `order_status`               |
| Order Currency       | Currency the order was placed in.                                                                                   | Text      | `currency`                   |
| Order Buyer          | Buyer username on the order.                                                                                        | Text      | `buyer_username`             |
| Order Payment Method | Payment method used on the order.                                                                                   | Text      | `payment_method`             |
| Order Date           | Order creation timestamp.                                                                                           | Date      | `create_time`                |
| Order Payment Date   | Payment timestamp. Reported as `unknown` when Shopee returns no payment time (for example cash-on-delivery orders). | Date      | `pay_time`                   |
| Order Updated Date   | Timestamp the order was last updated.                                                                               | Date      | `update_time`                |

<Note>
  **Order status values.** Shopee's raw statuses are mapped to four canonical values: `opened` (`READY_TO_SHIP`, `UNPAID`, `SHIPPED`), `closed` (`PROCESSED`), `cancelled` (`CANCELLED`), and `unknown` (any other status).
</Note>

<Note>
  **Fields Shopee does not provide for orders.** Order price (before charges), discount amount, tax amount, amount due, and order source are not returned by Shopee's order API, so those metrics and the Order Source breakdown remain empty for this connector.
</Note>

### Product-order (orders mode)

<Note>
  **Product-order metrics link products to the orders that contain them.** When a product-order metric is used with a product filter, only the portion of each order tied to that product is included, and only orders containing at least one matching product are shown. If a product cannot be retrieved (for example it was deleted), its related orders may not appear — use product-order metrics only when necessary.
</Note>

| Metric                     | Description                                         | Data type | API Key                          |
| -------------------------- | --------------------------------------------------- | --------- | -------------------------------- |
| Product Order Price Amount | Revenue tied to a specific product within an order. | Currency  | *Computed from order line items* |
| Product Order Quantity     | Units of a specific product within an order.        | Number    | *Computed from order line items* |

### Products

<Note>
  Each product model or variant is a separate record. The product name combines the item name and the model (variant) name. Product price and currency populate only when Shopee returns price information for the model.
</Note>

| Metric               | Description                                                      | Data type | API Key                                        |
| -------------------- | ---------------------------------------------------------------- | --------- | ---------------------------------------------- |
| Product Name         | Item name combined with the model (variant) name.                | Text      | *Composed from* `item_name` *and* `model_name` |
| Product SKU          | Stock keeping unit.                                              | Text      | `item_sku`                                     |
| Product Status       | Product status, mapped to Adriel's canonical values (see below). | Text      | `item_status`                                  |
| Product Image        | Primary product image URL.                                       | URL       | `image.image_url_list[0]`                      |
| Product Price        | Current listed price of the model.                               | Currency  | `price_info[0].current_price`                  |
| Product Currency     | Currency of the product price.                                   | Text      | `price_info[0].currency`                       |
| Product Created Date | Timestamp the product was created in Shopee.                     | Date      | `create_time`                                  |
| Product Updated Date | Timestamp the product was last updated in Shopee.                | Date      | `update_time`                                  |

<Note>
  **Product status values.** Shopee's raw statuses are mapped to `active` (`NORMAL`), `deleted` (`SELLER_DELETE`, `UNLIST`), and `unknown` (any other status). Retail (compare-at) price and a separate detailed product name are not provided by Shopee and remain empty.
</Note>

## Breakdowns

<Note>
  Breakdowns whose API Key is a Shopee field come directly from the Shopee API response. Breakdowns marked *Adriel-derived* are computed on top of the raw order or product data, including time groupings.
</Note>

### Order details (orders mode)

| Breakdown            | Description                                            | API Key          |
| -------------------- | ------------------------------------------------------ | ---------------- |
| Order ID             | Shopee order serial number.                            | `order_sn`       |
| Order Status         | Group by mapped order status.                          | `order_status`   |
| Order Payment Method | Group by payment method.                               | `payment_method` |
| Order Region         | Group by the order's market region (for example `PH`). | `region`         |

### Product details (products mode)

| Breakdown      | Description                     | API Key       |
| -------------- | ------------------------------- | ------------- |
| Product ID     | Model (variant) identifier.     | `model_id`    |
| Product Name   | Group by product name.          | `item_name`   |
| Product SKU    | Group by stock keeping unit.    | `item_sku`    |
| Product Status | Group by mapped product status. | `item_status` |

### Time & date grouping

<Note>
  Shopee returns records with timestamps; Adriel groups them into these views for reporting. Time groupings are Adriel-side aggregations of the same underlying data.
</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.                              |

## Limitations

* **Orders or products, fixed at creation** — a data source reports on one mode only, chosen when it is connected and not changeable afterward. Connect the shop twice to report on both orders and products.
* **90-day initial history** — the first import reaches back about 90 days. Coverage grows the longer the data source stays connected, as Adriel caches each refresh.
* **Current day excluded for orders** — today's orders are not included until the day closes, so the current day can read low or empty until the next day's sync.
* **Cancellations are separate records** — a cancelled order is written as its own record containing only the cancellation, rather than overwriting the original order record. Reporting a single order's full history needs to include both records.
* **Some order fields are not provided** — order price (before charges), discount, tax, amount due, and order source are not returned by Shopee's order API and stay empty.
* **Some product fields are not provided** — retail (compare-at) price and a separate detailed product name are not returned. Product price and currency populate only when Shopee returns price information for the model.
* **Products need model data** — products without model (variant) data are not synced.

## API references

* [Shopee Open Platform documentation](https://open.shopee.com/documents) — official Shopee Open Platform (v2) reference.
* Orders endpoints: `get_order_list` (order IDs), `get_order_detail` (order detail).
* Products endpoints: `get_item_list` (product IDs), `get_item_base_info` (product detail), `get_model_list` (variant/model detail).

## See also

* [How to connect Shopee to Adriel](/data-sources/o-z/shopee/how-to-connect) (paired how-to)
* [Shopee Ads data reference](/data-sources/o-z/shopee-ads/data-reference) — the separate Shopee advertising connector (campaign spend, GMV, and attribution)
* [Shopify data reference](/data-sources/o-z/shopify/data-reference) — direct-to-consumer commerce platform