Enhance Reporting Documentation: Add Package Pricing Fields and add offline file delivery report example (#179)

* Doc: update schema for reporting, add offline file delivery examples

* fix wrong report file extension in the offline delivery example path

* feat: add csv example, remove naming convension on files

Author: BaiyuScope3

.changeset/enhance-reporting-docs.md

@@ -0,0 +1,15 @@
+---
+"adcontextprotocol": minor
+---
+
+- Enhanced `get_media_buy_delivery` response to include package-level pricing information: `pricing_model`, `rate`, and `currency` fields added to `by_package` section.
+- Added offline file delivery examples for JSON Lines (JSONL), CSV, and Parquet formats.
+- Added tab structure to list different formats of offline delivery files in optimization reporting documentation.
+- Updated all delivery reporting examples to include new pricing fields.
+- Added comprehensive JSONL, CSV, and Parquet format examples with schema documentation.
+
+**Impact:**
+- Buyers can now see pricing information directly in delivery reports for better cost analysis.
+- Publishers have clearer guidance on structured batch reporting formats that maintain nested data.
+- Documentation provides a detailed examples for implementing offline file delivery.
+

docs/media-buy/media-buys/optimization-reporting.mdx

@@ -74,7 +74,7 @@ Publishers can proactively push reporting data to buyers through webhook notific
 **Example: Offline Delivery**
 Publisher pushes daily report files to buyer's cloud storage:
 ```
-s3://buyer-reports/publisher_name/2024/02/05/media_buy_delivery.json.gz
+s3://buyer-reports/publisher_name/2024/02/05/media_buy_delivery.jsonl.gz
 ```
 
 File contains same structure as webhook payload but aggregated across all campaigns. Buyer processes files on their schedule.
@@ -174,7 +174,7 @@ When a reporting webhook is configured, publishers commit to sending:
 - One final notification when the campaign completes
 - If reporting data is delayed beyond the expected delay window, a `"delayed"` notification will be sent
 
-### Webhook Payload
+### Webhook Payload (Real-time)
 
 Reporting webhooks use the same payload structure as [`get_media_buy_delivery`](/docs/media-buy/task-reference/get_media_buy_delivery) with additional metadata:
 
@@ -211,6 +211,123 @@ Reporting webhooks use the same payload structure as [`get_media_buy_delivery`](
 - **`next_expected_at`**: ISO 8601 timestamp for next notification (omitted for final notifications)
 - **`media_buy_deliveries`**: Array of media buy delivery data (may contain multiple media buys aggregated by publisher)
 
+### Offline File Delivery (Batch)
+
+For offline file delivery, publishers can provide reporting data in JSON Lines (JSONL), CSV, or Parquet format. All formats preserve the nested JSON structure from webhook payloads, making them ideal for batch processing.
+
+**Compression:**
+Files can be compressed with gzip (`.jsonl.gz`, `.csv.gz`, or `.parquet.gz`) for efficient storage and transfer. Compression is recommended for large files.
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs>
+<TabItem value="jsonl" label="JSONL" default>
+
+---
+
+**Structure:**
+
+Each line in the JSONL file contains a complete webhook payload object. Multiple reports can be included by having multiple lines in the file. The structure matches the [webhook payload structure](#webhook-payload-real-time).
+
+**Example:**
+
+```jsonl
+{"notification_type":"scheduled","sequence_number":5,"next_expected_at":"2024-02-06T08:00:00Z","reporting_period":{"start":"2024-02-05T00:00:00Z","end":"2024-02-05T23:59:59Z"},"currency":"USD","media_buy_deliveries":[{"media_buy_id":"mb_001","buyer_ref":"campaign_a","status":"active","totals":{"impressions":125000,"spend":5625.00,"clicks":250,"ctr":0.002,"video_completions":87500,"completion_rate":0.70},"by_package":[{"package_id":"pkg_001","buyer_ref":"ctv_package","impressions":75000,"spend":3375.00,"clicks":150,"video_completions":52500,"pacing_index":0.95,"pricing_model":"cpcv","rate":0.045,"currency":"USD"},{"package_id":"pkg_002","buyer_ref":"audio_package","impressions":50000,"spend":2250.00,"clicks":100,"video_completions":35000,"pacing_index":0.93,"pricing_model":"cpm","rate":45.00,"currency":"USD"}]}]}
+{"notification_type":"scheduled","sequence_number":6,"next_expected_at":"2024-02-07T08:00:00Z","reporting_period":{"start":"2024-02-06T00:00:00Z","end":"2024-02-06T23:59:59Z"},"currency":"USD","media_buy_deliveries":[{"media_buy_id":"mb_002","buyer_ref":"campaign_b","status":"active","totals":{"impressions":200000,"spend":9000.00,"clicks":400,"ctr":0.002,"video_completions":140000,"completion_rate":0.70},"by_package":[{"package_id":"pkg_003","buyer_ref":"display_package","impressions":200000,"spend":9000.00,"clicks":400,"video_completions":140000,"pacing_index":1.02,"pricing_model":"cpm","rate":45.00,"currency":"USD"}]}]}
+```
+
+**File Format:**
+- File extension: `.jsonl` or `.jsonl.gz` (compressed)
+- Compression: Consider using `.gz` compression for large files to reduce storage and transfer costs
+
+---
+
+</TabItem>
+<TabItem value="csv" label="CSV">
+
+---
+
+**Structure:**
+
+CSV format flattens the nested JSON structure into rows. Since CSV cannot natively represent nested arrays, each child element (package) gets its own row with all parent-level data repeated. This is the standard approach for representing hierarchical data in CSV format.
+
+```csv
+reporting_period.start,reporting_period.end,notification_type,sequence_number,next_expected_at,currency,media_buy_deliveries.media_buy_id,media_buy_deliveries.buyer_ref,media_buy_deliveries.status,media_buy_deliveries.totals.impressions,media_buy_deliveries.totals.spend,media_buy_deliveries.totals.clicks,media_buy_deliveries.totals.ctr,media_buy_deliveries.totals.video_completions,media_buy_deliveries.totals.completion_rate,by_package.package_id,by_package.buyer_ref,by_package.impressions,by_package.spend,by_package.clicks,by_package.video_completions,by_package.pacing_index,by_package.pricing_model,by_package.rate,by_package.currency
+```
+
+**CSV Example:**
+
+Each row represents a package with its parent media buy context repeated. Parent-level data (reporting period, media buy totals) is included in every package row:
+
+```csv
+reporting_period.start,reporting_period.end,notification_type,sequence_number,next_expected_at,currency,media_buy_deliveries.media_buy_id,media_buy_deliveries.buyer_ref,media_buy_deliveries.status,media_buy_deliveries.totals.impressions,media_buy_deliveries.totals.spend,media_buy_deliveries.totals.clicks,media_buy_deliveries.totals.ctr,media_buy_deliveries.totals.video_completions,media_buy_deliveries.totals.completion_rate,by_package.package_id,by_package.buyer_ref,by_package.impressions,by_package.spend,by_package.clicks,by_package.video_completions,by_package.pacing_index,by_package.pricing_model,by_package.rate,by_package.currency
+2024-02-05T00:00:00Z,2024-02-05T23:59:59Z,scheduled,5,2024-02-06T08:00:00Z,USD,mb_001,campaign_a,active,125000,5625.00,250,0.002,87500,0.70,pkg_001,ctv_package,75000,3375.00,150,52500,0.95,cpcv,0.045,USD
+2024-02-05T00:00:00Z,2024-02-05T23:59:59Z,scheduled,5,2024-02-06T08:00:00Z,USD,mb_001,campaign_a,active,125000,5625.00,250,0.002,87500,0.70,pkg_002,audio_package,50000,2250.00,100,35000,0.93,cpm,45.00,USD
+2024-02-06T00:00:00Z,2024-02-06T23:59:59Z,scheduled,6,2024-02-07T08:00:00Z,USD,mb_002,campaign_b,active,200000,9000.00,400,0.002,140000,0.70,pkg_003,display_package,200000,9000.00,400,140000,1.02,cpm,45.00,USD
+```
+
+---
+
+</TabItem>
+<TabItem value="parquet" label="Parquet">
+
+---
+
+**Structure:**
+
+Parquet files preserve the nested structure through nested columns. The schema mirrors the JSON structure:
+
+**Schema Structure:**
+```
+reporting_period
+  ├── start (string)
+  └── end (string)
+notification_type (string)
+sequence_number (int64)
+next_expected_at (string)
+currency (string)
+media_buy_deliveries (list)
+  └── element (struct)
+      ├── media_buy_id (string)
+      ├── buyer_ref (string)
+      ├── status (string)
+      ├── totals (struct)
+      │   ├── impressions (int64)
+      │   ├── spend (double)
+      │   ├── clicks (int64)
+      │   ├── ctr (double)
+      │   ├── video_completions (int64)
+      │   └── completion_rate (double)
+      └── by_package (list)
+          └── element (struct)
+              ├── package_id (string)
+              ├── buyer_ref (string)
+              ├── impressions (int64)
+              ├── spend (double)
+              ├── clicks (int64)
+              ├── video_completions (int64)
+              ├── pacing_index (double)
+              ├── pricing_model (string)
+              ├── rate (double)
+              └── currency (string)
+```
+
+**Example Data Representation:**
+
+The Parquet file contains the same data as the JSONL format, but stored in columnar format. For example:
+
+| reporting_period.start | reporting_period.end | currency | media_buy_deliveries[0].media_buy_id | media_buy_deliveries[0].totals.impressions | media_buy_deliveries[0].by_package[0].package_id | media_buy_deliveries[0].by_package[0].pricing_model |
+|------------------------|----------------------|----------|---------------------------------------|-------------------------------------------|---------------------------------------------------|-----------------------------------------------------|
+| 2024-02-05T00:00:00Z   | 2024-02-05T23:59:59Z | USD      | mb_001                                | 125000                                    | pkg_001                                           | cpcv                                                |
+| 2024-02-05T00:00:00Z   | 2024-02-05T23:59:59Z | USD      | mb_001                                | 125000                                    | pkg_002                                           | cpm                                                 |
+| 2024-02-06T00:00:00Z   | 2024-02-06T23:59:59Z | USD      | mb_002                                | 200000                                    | pkg_003                                           | cpm                                                 |
+
+---
+
+</TabItem>
+</Tabs>
+
 ### Timezone Handling
 
 **All reporting MUST use UTC.** This eliminates DST complexity, simplifies reconciliation, and ensures consistent 24-hour reporting periods.

docs/media-buy/task-reference/get_media_buy_delivery.mdx

@@ -74,7 +74,10 @@ The message is returned differently in each protocol:
           "spend": "number",
           "clicks": "number",
           "video_completions": "number",
-          "pacing_index": "number"
+          "pacing_index": "number",
+          "pricing_model": "string",
+          "rate": "number",
+          "currency": "string"
         }
       ],
       "daily_breakdown": [
@@ -120,6 +123,9 @@ The message is returned differently in each protocol:
     - **clicks**: Package clicks
     - **video_completions**: Package video completions
     - **pacing_index**: Delivery pace (1.0 = on track, <1.0 = behind, >1.0 = ahead)
+    - **pricing_model**: The pricing model used for this package (e.g., `"cpm"`, `"cpcv"`, `"cpp"`, `"cpc"`, `"cpv"`, `"vcpm"`, `"flat_rate"`). This indicates how the package is billed and which metrics are most relevant for optimization. See [Pricing Models](/docs/media-buy/advanced-topics/pricing-models) for details on each model.
+    - **rate**: The pricing rate for this package in the specified currency. For fixed-rate pricing, this is the agreed rate (e.g., CPM rate of `12.50` means $12.50 per 1,000 impressions). For auction-based pricing, this represents the effective rate based on actual delivery. The rate helps calculate expected delivery and compare performance across different pricing models.
+    - **currency**: ISO 4217 currency code (e.g., `"USD"`, `"EUR"`, `"GBP"`) for this specific package's pricing. This indicates the currency in which the `rate` and `spend` values are denominated. Different packages within the same media buy can use different currencies when supported by the publisher.
   - **daily_breakdown**: Day-by-day delivery
     - **date**: Date (YYYY-MM-DD)
     - **impressions**: Daily impressions
@@ -176,7 +182,10 @@ The AdCP payload is identical across protocols. Only the request/response wrappe
           "spend": 22500,
           "clicks": 0,
           "video_completions": 525000,
-          "pacing_index": 0.95
+          "pacing_index": 0.95,
+          "pricing_model": "cpcv",
+          "rate": 0.03,
+          "currency": "USD"
         }
       ]
     }
@@ -262,7 +271,10 @@ A2A returns results as artifacts:
                     "spend": 22500,
                     "clicks": 0,
                     "video_completions": 525000,
-                    "pacing_index": 0.95
+                    "pacing_index": 0.95,
+                    "pricing_model": "cpcv",
+                    "rate": 0.03,
+                    "currency": "USD"
                   }
                 ]
               }
@@ -330,14 +342,20 @@ A2A returns results as artifacts:
           "spend": 11250.00,
           "clicks": 500,
           "video_completions": 175000,
-          "pacing_index": 0.93
+          "pacing_index": 0.93,
+          "pricing_model": "cpcv",
+          "rate": 0.0643,
+          "currency": "USD"
         },
         {
           "package_id": "pkg_audio_drive_ca_ny",
           "impressions": 200000,
           "spend": 5625.00,
           "clicks": 400,
-          "pacing_index": 0.88
+          "pacing_index": 0.88,
+          "pricing_model": "cpm",
+          "rate": 28.125,
+          "currency": "USD"
         }
       ],
       "daily_breakdown": [
@@ -410,7 +428,10 @@ A2A returns results as artifacts:
           "spend": 11250.00,
           "clicks": 500,
           "video_completions": 175000,
-          "pacing_index": 0.93
+          "pacing_index": 0.93,
+          "pricing_model": "cpcv",
+          "rate": 0.0643,
+          "currency": "USD"
         }
       ],
       "daily_breakdown": []
@@ -433,7 +454,10 @@ A2A returns results as artifacts:
           "spend": 5625.00,
           "clicks": 100,
           "video_completions": 56250,
-          "pacing_index": 0.75
+          "pacing_index": 0.75,
+          "pricing_model": "cpm",
+          "rate": 45.00,
+          "currency": "USD"
         }
       ],
       "daily_breakdown": []
@@ -456,7 +480,10 @@ A2A returns results as artifacts:
           "spend": 10000.00,
           "clicks": 400,
           "video_completions": 110000,
-          "pacing_index": 1.05
+          "pacing_index": 1.05,
+          "pricing_model": "cpm",
+          "rate": 33.33,
+          "currency": "USD"
         }
       ],
       "daily_breakdown": []