Standardized Transactional Format
📦 Standardized Transactional Format
This page defines the standard structure used by Fyre to represent transactional data across partners and markets.
The structure described here builds on the data requirements defined during the preparation phase and ensures that transactional data can be interpreted, enriched, and analyzed consistently.
Details about the required fields for the initial one-month sample are described in Transactional Data Requirements. Supported delivery mechanisms are covered in Data Delivery Models, and API implementation details are explained in API-Based Delivery.
🤝 Why a Standardized Format Exists
POS systems can represent transactional data in many different ways. Even when the underlying information is similar, field names, structures, and data granularity often differ.
The standardized transactional format provides a common structure that:
⚡ Reduces onboarding and mapping effort
🌍 Ensures consistent interpretation across partners and markets
🧠 Simplifies enrichment, segmentation, and analytics
🛠️ Improves long-term maintainability of integrations
Partners who align with this format usually experience faster onboarding and fewer follow-up adjustments.
📍 Where This Format Is Used
The standardized transactional format can be applied with multiple delivery models.
🔌 API-Based Delivery
This is the primary and most strictly defined use case. API request payloads are expected to closely follow this format.
📁 File-Based Delivery
The same structure can also be reused for file uploads or data transfers. During onboarding, alternative structures may still be supported when necessary.
The delivery mechanism itself is documented separately and does not affect the structure defined on this page.
📊 Format Scope and Granularity
The standardized format operates at order-item level.
This means:
Each record represents a single product sold within an order
Orders containing multiple products are represented by multiple records
These records share the same order identifier
This level of granularity is required for:
Product normalization
Category mapping
Brand identification
Accurate basket-level analytics
🔑 Identifier Conventions
The standardized format relies on stable and consistent identifiers.
location_ref
Identifies the outlet and must match the identifier used in the outlet list
order_id
Uniquely identifies an order within a single outlet
source_id
Uniquely identifies an individual order item within a single outlet
Important rules:
Identifiers must remain stable over time
They must be reused consistently across all API requests
⏱️ Timestamp Conventions
The standardized transactional format currently requires one mandatory timestamp.
Each record must include:
Order Creation Timestamp
This represents when the order was created or opened in the POS system.
When using the standardized format:
Timestamp must be in ISO 8601 format
Timestamp must be expressed in UTC
The field must be clearly identifiable
It must be consistently populated
This timestamp acts as the primary temporal reference for transactional analysis.
Standardized fields
The table below describes the core fields of the standardized transactional format. Fields are marked as required or optional.
location_ref
string
✅
Unique identifier for a location in the external system
order_id
string
✅
Unique identifier for a order in the external system. Must be unique when combined with location_ref
source_id
string
✅
Unique identifier of the individual order item. Must be unique when combined with location_ref
parent_source_id
string
❌
If the item is part of a combo (e.g., meal deals, topings, modifiers, cocktails), this field holds the source_id of the parent item
product_ref
string
✅
Product identifier in the external system
product_name
string
✅
Product name
category_ref
string
❌
Category identifier in an external system
category_name
string
❌
Category name
cost
number
❌
Purchase price of the product in the order, if available
quantity
number
✅
Quantity of ordered items
price
number
✅
Price of individual item
options_price
number
❌
Total price of child items that share the same parent_source_id
subtotal
number
✅
Cost of an order item including options:
(price + options_price) * quantity
currency
string
❌
Currency in ISO 4217 format. If not provided it will use the location currency
tax_price
number
❌
Total tax amount for the ordered item, rounded to two decimal places.
tax_rate
number
❌
The tax rate for an ordered item is a percentage between 0 and 100.
guests_count
number
❌
Number of guests. If not provided it will default to 1
timezone
string
❌
Timezone name in ISO-8601 format. If not provided it will use the location timezone
created_at
string
✅
Order creation date in ISO 8601 format, expressed in UTC.
Below is a sample CSV file that follows the specified standard.
🍔 Combos, Modifiers, and Item Hierarchies
The standardized format supports item hierarchies, including:
Meal deals
Modifiers
Toppings
Bundled products
Child items reference their parent using parent_source_id, allowing Fyre to reconstruct complete baskets and pricing relationships during processing.
🔄 Using Other Formats
Using the standardized transactional format is not mandatory.
If a partner already has an existing export structure, Fyre can adapt to alternative formats during onboarding, provided that:
All required information is available
Fields can be reliably identified and mapped
For API-based integrations, aligning with the standardized format is strongly recommended to ensure long-term stability and minimize future changes.
Last updated