> ## 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 Kakao Shopping data source in Adriel.

## Introduction

Kakao Shopping is the e-commerce surface of Kakao Commerce, covering two distinct Korean retail channels: KakaoTalk Gift (선물하기) and Kakao Store (톡스토어). Merchants list products in one of these channels and fulfil orders through Kakao's commerce APIs. The connector retrieves order and product data from `kapi.kakao.com` using static Kakao app keys — no OAuth token refresh is involved.

A single data source covers exactly one channel: Gift or Store. Available metrics, breakdowns, and product fetch logic differ between the two channels because each is backed by a separate Kakao Commerce API surface. Kakao does not expose pre-aggregated sales analytics, so sales metrics are reconstructed from raw orders and products. All monetary values are reported in South Korean Won (KRW).

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 Kakao Shopping to Adriel](/data-sources/g-n/kakao-shopping/how-to-connect).

## Data refresh strategy

### Architecture data

Products are fully refreshed once per day. Product records carry name, status, stock quantity, delivery fees, and brand. Some fields are channel-specific: the Store channel provides created and updated timestamps and a brand attribute, while the Gift channel does not expose product created/updated dates. Product SKU is not populated on either channel.

### Reports data

Orders are refreshed hourly. On each refresh the connector re-fetches orders made or modified in the last 2 days to capture status transitions (paid, shipped, cancelled, refunded); this wider window reflects Kakao Commerce's settlement and cancellation cycle. The current day is excluded from the sync window because Kakao's API can return incomplete data for today, so the most recent complete day is the latest reported. Revenue is reported in KRW and no currency conversion is applied at refresh time.

## Architecture levels

Channel (Gift or Store) → Product catalog → Order → Product order line.

## 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 `orderAmount` for the literal field the connector exposes. *Italic text* describes how a value is produced when it is derived on Adriel's side rather than read from a single Kakao field.

  Some metrics are available on only one channel (Gift or Store), because each channel is backed by a separate Kakao Commerce API surface. Channel availability is noted in the description.
</Note>

### Orders

| Metric             | Description                                        | Data type | API Key             |
| ------------------ | -------------------------------------------------- | --------- | ------------------- |
| Order Count        | Distinct number of orders.                         | Number    | `orderCount`        |
| Cancellation Count | Number of orders transitioned to cancelled status. | Number    | `cancellationCount` |
| Refund Count       | Number of orders transitioned to refunded status.  | Number    | `refundCount`       |

### Revenue & sales

| Metric                 | Description                                                                                        | Data type | API Key                                |
| ---------------------- | -------------------------------------------------------------------------------------------------- | --------- | -------------------------------------- |
| Order Amount           | Total revenue from confirmed orders, in KRW.                                                       | Currency  | `orderAmount`                          |
| Average Order Value    | Order amount divided by order count.                                                               | Currency  | *Computed:* `orderAmount / orderCount` |
| Product Order Amount   | Portion of order amount tied to a filtered product. Without a product filter, equals order amount. | Currency  | `productOrderAmount`                   |
| Product Order Count    | Count of orders containing at least one matching product.                                          | Number    | `productOrderCount`                    |
| Product Order Quantity | Total units of the matching product across orders.                                                 | Number    | `productOrderQuantity`                 |

<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 cannot be retrieved from the API (for example, it has been deleted), the related orders may not appear — use Product Order metrics only when necessary.
</Note>

### Products

| Metric               | Description                                                      | Data type | API Key              |
| -------------------- | ---------------------------------------------------------------- | --------- | -------------------- |
| Gift Stock Quantity  | Available stock for a Gift-channel product. Gift channel only.   | Number    | `giftStockQuantity`  |
| Store Stock Quantity | Available stock for a Store-channel product. Store channel only. | Number    | `storeStockQuantity` |

### Fulfillment & delivery

| Metric                     | Description                                                                       | Data type | API Key                   |
| -------------------------- | --------------------------------------------------------------------------------- | --------- | ------------------------- |
| Gift Base Fee              | Base fee applied to a Gift-channel product. Gift channel only.                    | Currency  | `giftBaseFee`             |
| Gift Return Delivery Fee   | Delivery fee charged when a Gift-channel product is returned. Gift channel only.  | Currency  | `giftReturnDeliveryFee`   |
| Gift Exchange Delivery Fee | Delivery fee charged when a Gift-channel product is exchanged. Gift channel only. | Currency  | `giftExchangeDeliveryFee` |
| Store Delivery Base Fee    | Base delivery fee applied to a Store-channel product. Store channel only.         | Currency  | `storeDeliveryBaseFee`    |

## Breakdowns

### Order details

| Breakdown    | Description                                      | API Key       |
| ------------ | ------------------------------------------------ | ------------- |
| Order date   | Date the order was placed.                       | `orderDate`   |
| Order status | Kakao Commerce order status code.                | `orderStatus` |
| Channel      | Gift or Store — matches the data source channel. | `channelType` |

### Product

| Breakdown    | Description                                                         | API Key       |
| ------------ | ------------------------------------------------------------------- | ------------- |
| Product name | Product display name.                                               | `productName` |
| Brand        | Brand attributed to the ordered product.                            | `brandName`   |
| Store brand  | Brand attribute from the Store product catalog. Store channel only. | `storeBrand`  |

### Time & date grouping

<Note>
  Time-grouping breakdowns are Adriel-side aggregations of the same underlying order 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.                              |

### Overview & status

<Note>
  These grouping options are provided by Adriel and do not map to a Kakao field.
</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, Kakao Shopping has:

* **A 60-day historical limit.** Orders older than 60 days from today cannot be back-filled (`maxFromDate` = 60 days ago).
* **The current day is excluded** from the order sync window. Kakao's API can return incomplete data for today, so the latest reported day is the most recent complete day.
* **One channel per data source.** A data source's channel (Gift or Store) is fixed when the asset is created and cannot be switched later. Reporting across both channels requires two separate data sources.
* **Sales metrics are reconstructed from raw orders.** Kakao does not expose a pre-aggregated sales analytics API, so order amount, cancellation and refund counts, and product-level metrics are reconstructed from raw orders and products. Discrepancies versus Kakao's own merchant dashboards can be raised with Adriel support.
* **KRW-only currency.** Revenue is reported in KRW with no currency conversion applied. Cross-currency dashboards that combine Kakao Shopping with non-KRW sources require external normalization.
* **No OAuth token refresh.** Authentication uses static Kakao app keys rather than OAuth, so no token refresh runs. Re-issuing either app key in Kakao Commerce invalidates the existing connection and requires the credentials to be re-entered.
* **Product SKU is not populated** on either channel. The Gift channel additionally does not expose product created or updated dates.
* **Channel-specific metrics and breakdowns.** Stock, delivery-fee, and brand fields differ between Gift and Store; a metric or breakdown flagged for one channel is unavailable on the other.
* **Group-level API rate limit of 3 requests per second**, which paces large product and order fetches.

## API references

* Kakao Commerce / Kakao Business API, host `kapi.kakao.com`.
* Orders: `GET v1/shopping/orders/bulk`.
* Gift products: `v1/gift/products/sale-status/search` (list by sale status) and `v1/gift/products/search` (detail by ID).
* Store products: `v1/store/products` (paginated list).
* Authentication uses dual `KakaoAK` app-key headers: the admin app key on `Authorization` and the seller app key on `Target-Authorization`.

## See also

* [How to connect Kakao Shopping](/data-sources/g-n/kakao-shopping/how-to-connect) (paired how-to)
* [Naver Smart Store data reference](/data-sources/g-n/naver-smart-store/data-reference) — alternative Korean e-commerce marketplace
* [Cafe24 data reference](/data-sources/a-f/cafe24/data-reference) — alternative Korean DTC commerce platform
* [Coupang data reference](/data-sources/a-f/coupang/data-reference) — Korean marketplace commerce