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 is designed to ensure 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. The supported mechanisms for delivering this data are covered in Data Delivery Models. How this structure is applied in practice for API integrations is described in API-Based Delivery.
Why a standardized format exists
POS systems differ significantly in how they represent orders, items, categories, and prices. Even when the underlying data is similar, field naming, structure, and granularity often vary.
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 API integrations
Partners that align with this format typically experience faster onboarding and fewer follow-up adjustments.
Where this format is used
The standardized transactional format can be used with multiple delivery models:
API-Based Delivery This is the primary and most strictly defined use case. API request payloads are expected to align closely with this format.
File-Based Delivery The same structure can be reused for file uploads or transfers when convenient. Alternative structures may also be supported during onboarding.
The delivery mechanism itself is documented separately and does not affect the structure defined on this page.
Format scope and granularity
The standardized transactional format is defined at order-item level.
Each record represents a single product sold within an order. Orders containing multiple products are represented by multiple records that share the same order identifier.
This granularity is required for product normalization, category mapping, brand identification, and 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
Identifiers must remain stable over time and be reused consistently across all API requests.
Timestamp conventions
The standardized transactional format currently requires a single timestamp.
Each record must include an order creation timestamp, representing when the order was created or opened in the POS system.
When using the standardized format
The timestamp must be provided in ISO 8601 format
The timestamp must be expressed in UTC
The field must be clearly identifiable and consistently populated
This timestamp serves 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 such as meal deals, modifiers, toppings, and bundled products.
Child items reference their parent using parent_source_id, allowing Fyre to correctly reconstruct baskets and pricing relationships during processing.
Using other formats
Using the standardized transactional format is not mandatory.
If an existing export structure is already in place, Fyre can adapt to alternative formats during onboarding, as long as all required information can be identified and mapped reliably.
For API-based integrations, aligning with the standardized format is strongly recommended to ensure long-term stability and minimize future changes.
Last updated