DATA DICTIONARY · VERSION 1.3.3
What is inside your restaurant export?
CSV is a table. JSON keeps nested source context. ZIP groups locally generated files. None of those extensions tells you whether a row is an item, an order or a payout—check the module and fields first.
Recognise the file before opening it
A locally generated Zomato dataset uses the pattern Partner-Data-{outlet ID}-{module}-{From}-to-{To}.csv or .json. Swiggy adds Swiggy after Partner-Data. A multi-file archive additionally includes the version. The filenames can contain a private outlet ID; redact it before sharing screenshots publicly.
| File label | What it represents | What not to infer |
|---|---|---|
| Order-Level-Items | Recovered Zomato dishes within individual orders | Row count is not order count. |
| Order-Level-Finance | Swiggy order-level amounts and payout context | Not dish, variant or add-on sales. |
| Menu-Catalogue-and-Add-ons / Menu-Categories-and-Opening-Hours | A current menu snapshot for the selected platform | Not the menu as it existed at every date in the selected period. |
| Settlement-and-Payout-Breakup / Settlements-and-Payout-Breakups | Discovered payout cycles and accessible detailed responses | A breakdown row is not another payout. |
| Export-Index | Job scope, selected modules, results, warnings and queued local filenames | Completion of attempted modules is not proof of completeness. |
CSV headers are formed from keys actually present in the generated rows. Some diagnostic datasets flatten data to source, path and value. These are useful for inspection but are not a normalised payout table. An empty result may contain a “No records returned” marker: it is not a transaction.
Zomato order-level item fields
One row represents one dish line within a recovered order. The current mapper emits these field groups; upstream values can be blank, textual or differently formatted. Confirm currency, units and timestamp interpretation against the official record before converting.
| Fields | Use | Check first |
|---|---|---|
order_id, order_created_at, order_state, order_type | Group dishes into an order and apply the intended date/state filter. | Count distinct order IDs, not rows; retain timestamp context. |
item_index, item_name, variant, catalogue_id | Identify a dish line and match it to a recipe or catalogue. | Do not merge similarly named variants without checking IDs and portions. |
quantity, unit_price, line_total | Understand units and the amount shown for a dish. | Do not automatically add unit price and line total, or multiply a line total by quantity again. |
addons_and_details, addons_and_details_v2, customisations_json | Retain available add-on/customisation context. | Text descriptions are not necessarily separate priced units. |
discounts_json, metadata_json, raw_item_json | Keep source detail for an authorised audit or technical mapping. | Nested data needs inspection, not blind addition to sales totals. |
customer_id, customer_name, item_instruction_json | Fields potentially returned by the authorised account. | Private or free-text information: remove when it is unnecessary for your analysis. |
In the synthetic sample below, one order has two dish lines: two meal portions at ₹150 each and one snack at ₹120. There are two rows, three portions and one order. The illustrative item amounts total ₹420; this does not define that order's tax, delivery charge, discount or settlement amount.
For incomplete order detail retrieval, inspect the JSON's counts and failures plus any Order-Detail-Errors CSV. Recovered dish quantities may understate the selected period if some orders could not be retrieved.
Swiggy order-level finance fields
This module deduplicates returned records by restaurant ID plus order ID. It does not invent a dish list from money values. The exported CSV includes:
| Field | Meaning in the export | Safe interpretation |
|---|---|---|
restaurant_id, order_id | Outlet and order identifiers returned for the selected scope. | Keep identifiers as text so spreadsheet conversion does not alter them. |
order_timestamp, order_status | Upstream order time and state. | Preserve raw representation; confirm time zone/units before making daily totals. |
customer_paid_amount | The customer-paid amount returned by order-level finance. | Not automatically tax-exclusive restaurant revenue. |
restaurant_payout_amount | Restaurant payout amount returned for that order. | Not proof of a bank transfer by itself, and not net profit. |
payout_state, payout_message | Available payout status/context. | Match the settlement cycle and bank evidence before treating it as cash received. |
payment_utrs | Available UTR references joined by a vertical bar. | Sensitive cash-matching references; do not post publicly. |
The accompanying JSON preserves module, range, returned pages and deduplicated records. Two amounts that differ do not prove a mistake: there may be taxes, platform charges, refunds or other defined adjustments. Use the supporting settlement evidence to explain the difference.
Which files can the settlement analyser read?
The settlement analyser currently reads supported exporter settlement JSON, recognised settlement CSV structures, or a ZIP containing matching settlement-payout JSON. It is not a universal invoice, PDF, Excel or arbitrary CSV importer.
- Zomato JSON: accessible payout rows appear in
pages; detailed payout responses appear indetails. The parser maps recognised summary labels rather than treating every nested number as money to add. - Swiggy JSON: the supported structure has
discovery.payoutsand adetailsarray containing payout responses and their summaries. - Swiggy CSV: recognised records use
record_typeandpayout_id, including payout metadata and summary/breakdown rows. Keep those headers unchanged. - Diagnostic CSV: a file with
sourceorpathcolumns is deliberately rejected when it cannot provide a reliable payout breakup. Choose the matching settlement JSON or full exporter ZIP instead. - Current file limits: free analysis accepts one selected file with a 15 MB limit; activated subscription analysis allows batch selection with a combined 100 MB limit. ZIP decompression is also bounded.
Upload only the settlement scope you need. Exclude customer information and unnecessary modules from your working copy. If the upstream structure changes, do not rename unrelated headers just to force acceptance.
Download privacy-safe sample files
Open the item CSV using your spreadsheet's text/CSV import function and keep IDs as text. Find the two rows with the same order ID, sum quantity to 3, then sum the two line totals to ₹420. In your own exports, first check whether line amounts already include add-ons or discounts before repeating that calculation.
Five checks before making a chart
- Grain: label each dataset as item line, order, current catalogue entry, payout cycle or payout component.
- Scope: keep platform, outlet, period, state and date basis attached to every result.
- Units: check currency, price representation, quantities and timestamp units against a known record.
- Completeness: read warnings and count recovered details; absence is not zero.
- Privacy: remove unneeded customer, instruction and bank-reference fields from analysis copies and support attachments.
Spreadsheet files from any source can contain formula-like text. Import free-text columns as text and do not enable macros, external links or remote content. The extension's CSV writer guards formula-like cell content, but that does not make arbitrary files from elsewhere trustworthy.