CStoreOffice® Support & Learning

Fuel Invoices

The Fuel Invoice API is a RESTful service that provides access to CStoreOffice® fuel invoices in XML format:

  • Incoming fuel invoices received through EDI;
  • Generated based on Fuel Central sale invoices;
  • Added manually in CStoreOffice®.

The information is automatically published as an XML document immediately after an invoice is manually or automatically added to CStoreOffice®.

Prerequisites

The generation and publishing of fuel invoice 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 Invoices in CStoreOffice®

Fuel invoice business document data is based on the information from CStoreOffice® Fuel Invoices form. This form can be opened from the Vendors > Bills > Fuel Invoices.

A separate business document is generated for each invoice.

If any changes are made to the original invoice, the system will automatically replace the existing business document with an updated version containing the revised information.

Fuel invoice export via the Business Documents API

The fuel invoice business documents are available through the /business-unit-level-resources endpoint of the Business Documents PULL API. To export XML files with the fuel invoice data, specify the following parameters:

  • Document type identifier (documentType): fuel-invoice
  • 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 invoice data is exported as XML files, placed in the Amazon Web Services (AWS) bucket and made available through the Business Documents API.

You can also access the files via the standard AWS REST API, the AWS SDK, or manually through the AWS Management Console. When the data is changed, an event is triggered. Event notifications are available through AWS Simple Notification Service or Simple Queue Service.

A separate file is generated for each invoice. 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>T0000-V<Document version>-<Interchange document ID>.xml

  • Document Type: FUEL-INV
  • Date: fuel invoice date in ISO 8601 format
  • Fuel invoice date in CStoreOffice® does not include the time. Therefore, the date portion of the file name contains only the date in <year><month><date> format.

  • Document version: sequential number
  • Interchange document ID: unique identifier

For example: FUEL-INV-20250506T0000-V1-f8067938-9d1d-5ca2-9820-da9225bdc545.xml

If the invoice is updated, the new business document is generated and replaces the existing file. If the invoice is deleted, the corresponding business document is removed.

Fuel invoice data mapping

Fuel invoice data from CStoreOffice® is converted to XML format mapped to a Conexxus NAXML-FuelInvoice15 schema (Conexxus Fuel Invoice part of Motor Fuel Interface.)

<NAXML-FuelsDoc
    xmlns="http://www.naxml.org/Retail-EDI/Vocabulary/2003-10-16"
    version=""
    xmlns:xsi="/conexxus/motor-fuels-interface-V1.5.12-3/Schemas/NAXML-FuelInvoice15.xsd">

The following data mapping is used:

Transmission header

Key Description
/NAXML-FuelsDoc/TransmissionHeader/TransmissionId Internal identifier of the invoice document
/NAXML-FuelsDoc/TransmissionHeader/TransmissionDate The date when the business document was generated
/NAXML-FuelsDoc/TransmissionHeader/TransmissionTime The time the business document was generated, with second-level precision
/NAXML-FuelsDoc/TransmissionHeader/TransmissionStatus

Business document status:

  • original – initial document upload
  • resend – updated document

Invoice parties

Contains information about the vendor and the customer.

<Parties>
    ...
</Parties>

The fields that are not filled in CStoreOffice® are not included to the document.

Vendor details are obtained from CStoreOffice®vendor settings.

Key Description

/NAXML-FuelsDoc/Parties/Supplier/Name

The name of the fuel vendor the invoice was received from

/NAXML-BusDoc/Parties/Supplier/OrganizationId@identType Always equal to GL
/NAXML-BusDoc/Parties/Supplier/OrganizationId@ident GL Number configured for the vendor

/NAXML- FuelsDoc/Parties/Supplier/Address

Vendor’s address

/NAXML- FuelsDoc/Parties/Supplier/City

Vendor’s city

/NAXML- FuelsDoc/Parties/Supplier/County

Vendor's county

/NAXML- FuelsDoc/Parties/Supplier/State

Vendor’s state

/NAXML- FuelsDoc/Parties/Supplier/PostalCode

Vendor’s postal code

/NAXML-BusDoc/Parties/Supplier/CountryCode@code Vendor’s country code in ISO-3166 format
/NAXML-FuelsDoc/Parties/Supplier/Fax Vendor's fax number
/NAXML-FuelsDoc/Parties/Supplier/Email Vendor's email
/NAXML-FuelsDoc/Parties/Supplier/Phone Vendor's phone number
/NAXML-BusDoc/Parties/Supplier/OrganizationId@identType Always equal to VendorId
/NAXML-BusDoc/Parties/Supplier/OrganizationId@ident

Internal Vendor ID from CStoreOffice®, which can be found in vendors list:

Vendor details are obtained from CStoreOffice® company which the location mentioned in the invoice belongs to.

Key Description

/NAXML-FuelsDoc/Parties/Buyer/Name

The name of the buyer's company

/NAXML- FuelsDoc/Parties/Buyer/Address

Buyer’s address

/NAXML-FuelsDoc/Parties/Buyer/City

Buyer’s city

/NAXML-FuelsDoc/Parties/Buyer/State

Buyer’s state

/NAXML-FuelsDoc/Parties/Buyer/PostalCode

Buyer’s postal code

/NAXML-BusDoc/Parties/Buyer/CountryCode@code Buyer’s country code in ISO-3166 format
/NAXML-FuelsDoc/Parties/Buyer/Fax Buyer's fax number
/NAXML-FuelsDoc/Parties/Buyer/Phone Buyer's phone number
/NAXML-BusDoc/Parties/Supplier/OrganizationId@identType Always equal to CompanyId
/NAXML-BusDoc/Parties/Supplier/OrganizationId@ident

Internal Company ID from CStoreOffice®, which can be found in the companies list:

Ship to details are obtained from CStoreOffice® station (location) settings which is mentioned in the invoice.

Key Description

/NAXML-FuelsDoc/Parties/ShipTo/Name

Location name

/NAXML-BusDoc/Parties/Supplier/OrganizationId@identType Always equal to GL
/NAXML-BusDoc/Parties/Supplier/OrganizationId@ident GL Number configured for the location

/NAXML- FuelsDoc/Parties/ShipTo/Address

Location’s address

/NAXML-FuelsDoc/Parties/ShipTo/City

Location’s city

/NAXML-FuelsDoc/Parties/ShipTo/County Location's county

/NAXML-FuelsDoc/Parties/ShipTo/State

Location’s state

/NAXML-FuelsDoc/Parties/ShipTo/PostalCode

Location’s postal code

/NAXML-BusDoc/Parties/ShipTo/CountryCode@code Location’s country code in ISO-3166 format
/NAXML-FuelsDoc/Parties/ShipTo/Fax Location's fax number
/NAXML-FuelsDoc/Parties/Supplier/Email Location's email
/NAXML-FuelsDoc/Parties/ShipTo/Phone Location's phone number
/NAXML-BusDoc/Parties/ ShipTo/OrganizationId@identType Always equal to LocationId
/NAXML-BusDoc/Parties/ShipTo/OrganizationId@ident

Internal location ID from CStoreOffice®

Invoice

Contains invoice details.

Key Description

/NAXML-FuelsDoc/FuelInvoice/InvoiceNumber

Fuel invoice numberCStoreOffice®

/NAXML-FuelsDoc/FuelInvoice/InvoiceDate

Fuel invoice date (without time)

/NAXML-FuelsDoc/FuelInvoice/InvoiceDetail

Detailed information about purchased items, taxes and charges.

/NAXML-FuelsDoc/FuelInvoice/InvoiceSummary

Invoice summaries and additional charges.

/NAXML-FuelsDoc/FuelInvoice/Terms

Due date, method of payment, and other invoice terms.

Invoice details

Includes information about invoice line items and taxes applied.

All keys in the table below should be prefixed with /NAXML-FuelsDoc/FuelInvoice/InvoiceDetail/.

Key Description

BillOfLadingNumber

The bill of landing the invoice is associated with. Empty if there is no BOL.

LineItem[n]

Each LineItem block corresponds to the separate fuel product from the invoice.

LineItem[n]/@count Sequential line number.

LineItem[n]/BillOfLadingNumber

The bill of landing the invoice is associated with.

LineItem[n]/FuelProductId

The fuel product name, as mentioned in invoice.

LineItem[n]/FuelProductId/@identType

Type of the additional fuel product identifier.

Always GL, unless the fuel product's GL# is empty.

LineItem[n]/FuelProductId/@ident GL# configured for the fuel product. Can be found in Account Menu > General > Locations > UST System > Mix & Fuels

Omitted if GL# is empty for a fuel product.

LineItem[n]/FuelProductQty[m]

The number of gallons delivered (gross or net, depending on the value of @UOMBasis attribute, see below.)

LineItem[n]/FuelProductQty[m]/@UOMBasis

Indicates what quantity (gross or net) for fuel product is included in the document:

  • GrossGallons
  • GrossLiters
  • NetGallons
  • NetLiters

The choice between gallons or liters is based on your account settings.

LineItem[n]/FuelProductCost

Total product cost before taxes.

Corresponds to the Net Amount field in the invoice.

LineItem[n]/FuelProductCost/@billingRate Net cost per gallon of the fuel product.
LineItem[n]/FuelProductCost/@billingUOM Unit of measurement used for billing. Based on the account settings, it can be Dollars-Gallon ($ per gallon) or Dollars-Liter ($ per liter.)
LineItem[n]/FuelProductCost/@exTax Whether the cost is reported before or after taxes. Always Yes.
/NAXML-FuelsDoc/FuelInvoice/InvoiceDetail/LineItem[n]/FuelTaxes The list of taxes applied to fuel product.
/NAXML-FuelsDoc/FuelInvoice/InvoiceDetail/LineItem[n]/FuelTaxes/@taxable Always Yes.
/NAXML-FuelsDoc/FuelInvoice/InvoiceDetail/LineItem[n]/FuelTaxes/TaxType[m] Tax details.
LineItem[n]/FuelTaxes/TaxType[m]/@ident

Tax name, as mentioned in the invoice.

LineItem[n]/FuelTaxes/TaxType[m]/TaxMethod/@billingBasis Indicates which quantity (Net or Gross) is used for tax calculation. Based on location settings.
LineItem[n]/FuelTaxes/TaxType[m]/TaxMethod/@billingUOM Always Dollars-Gallon.
LineItem[n]/FuelTaxes/TaxType[m]/TaxRate Tax rate.
LineItem[n]/FuelTaxes/TaxType[m]/TaxAmount

Total tax amount for the fuel product. Calculated by multiplying tax rate by the fuel product quality.

This value is only provided through Business Documents API. It is not shown in CStoreOffice® invoice.

LineItem[n]/TotalLineItemAllowanceOrCharge Always empty.
LineItem[n]/TotalLineItemAllowanceOrCharge/@identType Always credit.
LineItem[n]/TotalLineItemGrossTaxAmt The sum of all taxes amounts for the fuel product.
LineItem[n]/TotalLineItemGrossTaxAmt/@identType Always credit.
LineItem[n]/TotalLineItemNetDueAmt Fuel product cost, including taxes.
LineItem[n]/TotalLineItemNetDueAmt/@identType Always credit.

Invoice summary

Includes invoice totals and information about additional charges and taxes that are not directly associated with any fuel product.

All keys in the table below should be prefixed with /NAXML-FuelsDoc/FuelInvoice/InvoiceSummary/.

Key Description

InvoiceTotals

Invoice totals details.

InvoiceTotals/LineItems/@count

Total count of fuel products in the invoice.

InvoiceTotals/AdditionalAllowancesAndCharges Any additional charges listed in Other charges section, if available.

InvoiceTotals/AdditionalAllowancesAndCharges/AllowanceOrCharge[n]

Each entry from Other Charges section.

InvoiceTotals/AdditionalAllowancesAndCharges/AllowanceOrCharge[n]/AllowanceOrChargeReason

Charge name.

InvoiceTotals/AdditionalAllowancesAndCharges/AllowanceOrCharge[n]/AllowanceOrChargeReason/@quantity

Charge quantity (QTY column.)

InvoiceTotals/AdditionalAllowancesAndCharges/AllowanceOrCharge[n]/ChargeAmt Charge Amount.
InvoiceTotals/AdditionalAllowancesAndCharges/TotalAdditionalAllowancesAndChargesNetAmt

The sum of all charges amount from Other charges section (Other Charges Total field of the invoice.)

InvoiceTotals/AdditionalFuelTaxes

Taxes not directly linked to any fuel product. Included in Taxes and Services invoice section.

InvoiceTotals/AdditionalFuelTaxes/TaxType Detaild of each additional tax applied.
AdditionalFuelTaxes/TaxType/@ident

Tax name, as mentioned in the invoice.

InvoiceTotals/AdditionalFuelTaxes/TaxType/TaxRate Tax rate that corresponds to the Rate column of the invoice.
InvoiceTotals/AdditionalFuelTaxes/TaxType/TaxAmount Tax amount that corresponds to the Amount column of the invoice.
InvoiceTotals/TotalInvoiceDueAmt

Total invoice amount including all taxes and charges.

Corresponds to the Total Invoice value.

InvoiceTotals/TotalInvoiceDueAmt/@identType Always credit.

Invoice terms

Includes invoice terms: due date, method of payment, and the like.

Key Description

/NAXML-FuelsDoc/FuelInvoice/Terms

Invoice term list.

/NAXML-FuelsDoc/FuelInvoice/Terms/TermsType[n]

Term value based on @ident attribute:

  • Due date
  • Method of payment:
  • EFT
  • Credit
  • Check
/NAXML-FuelsDoc/FuelInvoice/Terms/TermsType[n]/@ident

Type of term:

  • MOP - the TermsType contains the method of payment.
  • Due - the TermsType contains the due date.

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.