The Fuel Products Cost of Goods Sold API is a RESTful service that provides access to the consolidated fuel sales information in JSON format. The API provides daily summaries for each station, including:
- Fuel products;
- Sales volume;
- Net cost;
- Taxes and services;
- Profit;
- Fuel pool margin;
- Average retail price.
The information is automatically aggregated and published as JSON documents after the day is completed in CStoreOffice® Cash Reconciliation daily data.
Prerequisites
The aggregation and publishing of the Fuel Products COGS business documents for the specific location become available once you purchase and activate the Business Documents API subscription.
Any active CStoreOffice® user account, regardless of role or permissions, can be used to authorize access to the Business Documents API. However, we recommend creating a dedicated service account specifically for API access, rather than using your existing account for the CStoreOffice® console.
Fuel Products COGS in CStoreOffice®
Fuel Products COGS business document data is based on the information from CStoreOffice® Consolidated Fuel Sales report.
This form can be opened from the Reports > Fuel > Sales.
The business document includes all information from the report at the specific date for a particular station (location).
Fuel Products COGS export via the Business Documents API
The business document is available through the /business-unit-level-resources endpoint of the Business Documents PULL API. To export the JSON files with the Fuel Products COGS data, specify the following parameters:
- Document type identifier (
documentType): fuel-products-cost-of-goods-sold - Business unit ID (
businessUnitId): Unique identifier of your company or station.
For more information, see Calling the Business Documents API at the Business Unit Level and Preparing the input parameters for API request.
File naming conventions
Fuel Products COGS report data is exported as JSON files, placed in the Amazon Web Services (AWS) bucket and made available through the Business Documents API.
One file is created per station per date and saved to the separate directory on the AWS S3 storage:
<Station ID>/fuel-sales/<Export date>
- Station ID: The numeric identifier of the location (station)
- Export date: The date the report was generated for, formatted as <year><month><day>. The year is four digits, and the month and day are two digits each, padded with a leading zero if necessary.
For example: 64373/fuel-sales/20250429/
Exported file names follow ANSI ASC X12 naming conventions and EASI standards, ensuring reliable electronic document interchange. The file naming format is as follows:
<Document type>-<Date and time>-V<Document version>-<Interchange document ID>.json
- Document Type: FUEL-COGS
- Date and time: original document timestamp in ISO 8601 format
- Document version: sequential number
- Interchange document ID: unique identifier
For example: FUEL-COGS-20210629T1850-V1-305f9f24-d9d6-11eb-b8bc-0242ac130003.json
Fuel Products COGS data mapping
All data from the Consolidated Fuel Sales report is mapped to a Conexxus protocol and converted to JSON format. The conversion is based on the Conexxus Fuel Grade Movement part of the POS Activity Reporting API. We use the native Conexxus extension mechanism to add data elements not defined within the standard.
The following data mapping is used:
General information
JSON Example
"version": "3.4",
"release": "0.1",| Key | Type | Description |
|---|---|---|
| version | String | Version of the Conexxus standard |
| release | String | Version of the Petrosoft API |
Transmission header
JSON Example
"transmissionHeader": {
"organizationID": "8735",
"storeLocationID": "33084",
"vendorName": "CStoreOffice",
"vendorModelVersion": "API1.0"
},| Key | Type | Description |
|---|---|---|
| organizationID | String | CStoreOffice® account ID |
| storeLocationID | String | CStoreOffice® station ID |
| vendorName | String | Permanently set to "CStoreOffice" |
| vendorModelVersion | String | Permanently set to "API1.0" |
POS movement header
Contains information about the reported period.
JSON Example
"posMovementReport": {
"posMovementReportHeader": {
"reportSequenceNumber": 997,
"primaryReportPeriod": {
"interval": "day",
"value": "2025-03-01"
},
"beginDateTime": "2025-03-01T08:00:00Z",
"endDateTime": "2025-03-01T23:59:59Z",
"businessDate": "2025-03-01"
},
}| Key | Type | Description |
|---|---|---|
| posMovementReportHeader | ||
| reportSequenceNumber | Number | Unique report number for future reference |
| beginDateTime | Date and time | Start of the data collection period for the report in ISO 8601 format. The time is always 00:00:00 for automatic data export. |
| endDateTime | Date and time | End of the data collection period for the report in ISO 8601 format. The time is always 23:59:59 for automatic data export. |
| businessDate | Date | Date in ISO 8601 format when the report was generated. Equals to the value of “Generated on” in the report. |
| primaryReportPeriod | ||
| interval | String | Permanently set to "Day", since the report is generated daily and contains information for one day |
| value | Date | Report date in ISO 8601 format |
Fuel grade movement
Contains information about fuel sales, costs, and profits. Each line of Consolidated Fuel Sales report is represented as separate element of the fgmDetail array.
JSON Example
"posMovementReportGroup": [
{
"fuelGradeMovement": {
"fgmDetail": [
{
"fuelGradeID": {
"value": "1"
},
"fgmSalesTotals": [
{
"fuelGradeSalesVolume": {
"value": "42105",
"uom": "LTR"
},
"fuelGradeSalesAmount": {
"value": "61131.62",
"currency": "USD"
}
}
],
"fgmDetailExtension": [
{
"fuelGradeDescription": "Regular",
"fuelGradeNetCost": {
"value": "36715.16",
"currency": "USD"
},
"fuelGradeTaxes": {
"value": "22784.75",
"currency": "USD"
},
"fuelGradeSalesTax": {
"value": "0",
"currency": "USD"
},
"fuelGradeProfit": {
"value": "1631.70",
"currency": "USD"
},
"fuelGradeAvgRetail": {
"value": "1.452",
"currency": "USD"
},
"fuelGradePoolMargin": {
"value": "0.039"
}
}
]
},
{...}
]
}
}
]| Key | Type | Description |
|---|---|---|
| posMovementReportGroup | Array | Array of report groups objects |
| fuelGradeMovement | ||
| fgmDetail | Array | Each item represents a separate fuel grade in the Consolidated Fuel Sales report. |
| fuelGradeID / value | String | Identifier of the fuel grade. Corresponds to the Id column from the Consolidated Fuel Sales report. |
| fgmSalesTotals | Object | Aggregated information on fuel sales. |
| fuelGradeSalesVolume / value | String | Sales volume of the fuel grade, calculated in liters. Corresponds to the Gallons column from the Consolidated Fuel Sales report. |
| fuelGradeSalesVolume / uom | String | Units of measure for the sales volume. Permanently set to liters (LTR). |
| fuelGradeSalesAmount / value | String | Sales amount of the fuel grade. Corresponds to the Sales, $ column from the Consolidated Fuel Sales report. |
| fuelGradeSalesAmount / currency | String | Sales amount currency. Permanently set to USD. |
| fgmDetailExtension | Array | Petrosoft extension to the Conexxus format to accommodate report data. |
| fuelGradeDescription | String | Human readable fuel grade. Corresponds to the Description column from the Consolidated Fuel Sales report. |
| fuelGradeNetCost / value | String | Net cost of the fuel grade. Corresponds to the Net Cost, $ column from the Consolidated Fuel Sales report. |
| fuelGradeNetCost / currency | String | Net cost amount currency. Permanently set to USD. |
| fuelGradeTaxes / value | String | Fuel grade taxes and services amount. Corresponds to the Taxes & Services, $ column from the Consolidated Fuel Sales report. |
| fuelGradeTaxes / currency | String | Tax amount currency. Permanently set to USD. |
| fuelGradeSalesTax / value | String | Fuel grade sales tax. Corresponds to the Sales Tax, $ column from the Consolidated Fuel Sales report. |
| fuelGradeSalesTax / currency | String | Sales tax currency. Permanently set to USD. |
| fuelGradeProfit / value | String | Profit from the fuel sales. Corresponds to the Profit, $ column from the Consolidated Fuel Sales report. |
| fuelGradeProfit / currency | String | Profit currency. Permanently set to USD. |
| fuelGradeAvgRetail/ value | String | Average retail price of the fuel grade. Corresponds to the Average Retail, $ column from the Consolidated Fuel Sales report. |
| fuelGradeAvgRetail/ currency | String | Average retail price currency. Permanently set to USD. |
| fuelGradePoolMargin / value | String | Fuel grade pool margin. Corresponds to the Pool Margin column from the Consolidated Fuel Sales report. |
Sample data
The example below is taken from the testing environment with testing data. No association with any real company, product, event, or data is intended or should be inferred.
JSON Example
{
"version": "3.4",
"release": "0.1",
"transmissionHeader": {
"organizationID": "8735",
"storeLocationID": "33084",
"vendorName": "CStoreOffice",
"vendorModelVersion": "API1.0"
},
"posMovementReport": {
"posMovementReportHeader": {
"reportSequenceNumber": 997,
"primaryReportPeriod": {
"interval": "day",
"value": "2025-03-01"
},
"beginDateTime": "2025-03-01T08:00:00Z",
"endDateTime": "2025-03-01T23:59:59Z",
"businessDate": "2025-03-01"
},
"posMovementReportGroup": [
{
"fuelGradeMovement": {
"fgmDetail": [
{
"fuelGradeID": {
"value": "1"
},
"fgmSalesTotals": [
{
"fuelGradeSalesVolume": {
"value": "42105",
"uom": "LTR"
},
"fuelGradeSalesAmount": {
"value": "61131.62",
"currency": "USD"
}
}
],
"fgmDetailExtension": [
{
"fuelGradeDescription": "Regular",
"fuelGradeNetCost": {
"value": "36715.16",
"currency": "USD"
},
"fuelGradeTaxes": {
"value": "22784.75",
"currency": "USD"
},
"fuelGradeSalesTax": {
"value": "0",
"currency": "USD"
},
"fuelGradeProfit": {
"value": "1631.70",
"currency": "USD"
},
"fuelGradeAvgRetail": {
"value": "1.452",
"currency": "USD"
},
"fuelGradePoolMargin": {
"value": "0.039"
}
}
]
},
{
"fuelGradeID": {
"value": "6"
},
"fgmSalesTotals": [
{
"fuelGradeSalesVolume": {
"value": "13583",
"uom": "LTR"
},
"fuelGradeSalesAmount": {
"value": "22398.66",
"currency": "USD"
}
}
],
"fgmDetailExtension": [
{
"fuelGradeDescription": "Diesel",
"fuelGradeNetCost": {
"value": "14091.86",
"currency": "USD"
},
"fuelGradeTaxes": {
"value": "7048.99",
"currency": "USD"
},
"fuelGradeSalesTax": {
"value": "0",
"currency": "USD"
},
"fuelGradeProfit": {
"value": "1257.81",
"currency": "USD"
},
"fuelGradeAvgRetail": {
"value": "1.649",
"currency": "USD"
},
"fuelGradePoolMargin": {
"value": "0.093"
}
}
]
}
]
}
}
]
}
}
