The Generic EDI Invoice Import supports delimited text files (CSV, TSV, pipe-delimited, etc.) that are interpreted according to a JSON configuration. A full sample configuration can be found at the bottom of this page.
This allows almost any vendor invoice export to be imported without modifying code. The JSON configuration tells the importer:
- Whether the file contains a header row
- Which delimiter is used
- Which columns contain each field
- Whether columns are identified by index or column name
- Which vendor each invoice belongs to, when one file contains invoices from more than one vendor
- How dates are formatted
- Whether prices require normalization
- How expense lines are detected
The settings shown in the partial examples on this page belong in the InvoiceConfiguration section of the configuration. See Full Configuration Example.
Building a new export? Use the Standard Configuration for New Vendors. It uses every column, UTC dates and standard expense codes, and needs no custom configuration.
Checking a file? Use the Developer Tool. It validates your file against your configuration and prepares your certification submission. See Validation Rules for what it checks.
The configuration is submitted once for Certification and is then used for every future file.
Yellow Dog provides a free Windows tool that checks an invoice file against its JSON configuration before you send it. It builds the configuration for you, lists every problem by line, and prepares the certification email. Use it to get to a passing file before you submit. See Validation Rules for what it checks and Certification for how to submit.
Download GenericEdiDevTool-win-x64.zip
- Windows 10 or 11.
- The Microsoft Edge WebView2 Runtime. Windows 11 includes it. On Windows 10, download the runtime from Microsoft if the tool does not start.
- Unzip the download.
- Run
GenericEdiDevTool.exe.
Nothing is installed. The build is not code-signed, so Windows SmartScreen may show a warning. Choose More info, then Run anyway.
The tool works offline. Nothing leaves your computer. It does not send your files or configuration anywhere; you send them yourself by email.
Follow the Start here tab. It has five steps:
- Read the file specification (this page).
- Get a starting configuration. Use the standard layout if you are building a new export, or load a sample file from an existing export and the tool drafts a configuration.
- Make a test file that covers the cases in the Test file checklist.
- Validate the file and fix what is reported. Change the configuration or the file and repeat.
- Stop when every test file passes.
The other tabs:
- Start here: the five steps above, with the status of your last validation.
- Validate: checks a file against a configuration and lists problems by line, with a preview of the invoices and the test file checklist.
- Build config: a form that builds the configuration JSON. You can start from a sample file, the standard configuration or an existing JSON.
- Starter files: saves the standard configuration and a sample file.
- Submit for certification: prepares the email and zip for Yellow Dog.
A file passes when the tool reports no errors. Errors must be fixed. Review every warning and fix it unless you are sure it is correct for your export.
A passing validation is required before you can submit. The Submit for certification tab then:
- Asks for your company, contact and export details.
- Fills in an email to integrationsdev@yellowdogsoftware.com. The subject starts with
[GenericInvoiceSubmission]. - Saves a zip that contains the test file,
configuration.json, the validation report and the email text.
The tool does not send anything. Attach the zip to the email and send it yourself.
The Developer Tool checks the file and the configuration with the importer's own row parser, plus extra checks. It is stricter than the importer. Where the importer would quietly substitute a value or skip a line, the tool reports an error. A file that passes the tool imports correctly.
Errors must be fixed before you can submit. Warnings do not block submission but should be reviewed.
Configuration:
- The configuration is not valid JSON, or is not a JSON object.
- A setting name is not recognized. The importer ignores unknown settings, so a misspelled setting would have no effect. The tool suggests the closest name.
KeyorNameis missing or empty.InvoiceConfigurationis missing.- A setting has a value of the wrong type, so the configuration cannot be read.
UseNameMappingis true butHasHeaderis false, orNameMappingis missing.UseNameMappingis false andIndexMappingis missing.- With index mapping,
InvoiceIdentifier,ItemIdentifier,ItemDescription,ItemQuantityorItemPriceis not set. Set each one, using0when it is the first column. - A column index is negative, or is beyond the number of columns in the file.
- With name mapping, a required column is not in the header row (
InvoiceIdentifier,ItemIdentifier,ItemDescription,ItemQuantity,ItemPrice). - With name mapping, the
VendorIdentifiercolumn, or a column listed inExpenseColumns, is not in the header row. - No store column is mapped.
- No invoice date column is mapped.
File:
- A row has a different number of fields than the header row (or the first row when there is no header). This usually means a missing or extra delimiter, or text that contains the delimiter and is not in double quotes.
- The file cannot be read, for example because of an unclosed double quote.
- The file has no invoice lines.
- A line has no invoice identifier or no item identifier. The importer skips these lines.
- The vendor column is mapped but empty on a line.
- The item description is empty.
- The store is empty on the first line of an invoice.
- The invoice date is empty, or does not match
DateFormatexactly. Without aDateFormat, it is not a valid date. A due date that is present is checked the same way. - A header field differs from the first line of the same invoice: store, invoice date, due date, account or purchase order. Only the first line is used, so the other values would be ignored.
QuantityorPriceis empty.- A number is not a number. This applies to
Quantity,Price,ItemWeightedAmount,InvoiceTotalAmountand expense columns. Use digits with.as the decimal point. - A number contains a comma. The importer reads a comma as a thousands separator, so
1,50would import as 150. Send no thousands separators. IsWeightedorIsExpenseis nottrue,false,0or1.IsWeightedis true butItemWeightedAmountis empty. The weight is used as the quantity.- A time zone selected in the tool is not found.
Versionis missing from the configuration. Add"Version": 1.- No size column is mapped and
ItemSizeDefaultis not set, so items have no size. - No pack size column is mapped.
- The size or pack size is empty on a line.
ItemSizeDefaultis not applied to blank cells in a mapped size column. - A number has more than 8 decimal places.
- The same item appears on more than one line of an invoice. Send multiples of one item as a single line with the total quantity.
InvoiceTotalAmountdiffers from the lines plus expenses by more than 0.01. Yellow Dog uses the total from the file, so check that it is right.ExpenseColumnsDuplicatedistrueand the lines of one invoice have different amounts in the same expense column. Only the first amount is used.- A date is not in an ISO format and no
DateFormatis set, so it is read only by the importer's fallback date parse. SetDateFormatto make it exact.
These rules are explained where they apply:
- Discounts: see Discounts.
- Several vendors in one file: see Multiple Vendors.
- Multiples of the same item: see Processing Rules and Requirements.
- Returns: see Processing Rules and Requirements.
- Dates and times: see UTC Dates.
- Quoting text: see Quoting text.
- Item order: see Processing Rules and Requirements.
- Combining expense methods: see Combining expense methods.
The tool looks for these six cases in your test file and shows which it found. Send one test file that covers all of them.
- Typical expenses. Fuel, shipping and fees, with quantity 1 and the charge as the price. See Standard Expenses.
- Multiples of the same item on one line. One line with the total quantity, never the same item repeated on separate lines.
- A return. A negative quantity.
- Weighted items, if you sell by weight. Set
IsWeightedandItemWeightedAmount. - Multiple invoices in one file, if your export does that. Include at least two invoices.
- Items in the same order every time. The tool cannot check this. Keep the lines of each invoice in the order of the physical invoice.
- Each row represents one invoice line item.
- Multiple rows with the same Invoice Identifier are combined into a single invoice. When a Vendor Identifier column is mapped, rows are combined by vendor identifier plus invoice identifier (see Multiple Vendors).
- Name mapping allows columns to appear in any order.
- Index mapping requires columns to exactly match the configured positions.
- All required fields must be present for every line item, including expense lines.
- Optional fields may be omitted.
- A line without an invoice identifier or an item identifier is skipped by the importer. The Developer Tool reports it as an error.
- Expense detection is evaluated before the line is imported as inventory. The
IsExpensecolumn, exact keywords, item identifiers and contains keywords can be used together (see Combining expense methods). - Any unused optional columns should be omitted from the configuration.
- All number columns support up to 8 decimal places.
- Bool columns support "true", "false", 0 and 1.
- Returns should be provided with a negative quantity.
- Send multiples of the same item on one line with the total quantity. Do not repeat the item on separate lines of the same invoice. The Developer Tool warns about repeated items.
- Send the items of an invoice in the same order every time, matching the order on the physical invoice.
- Send a discount as an expense line with a negative price (see Discounts).
- Wrap text fields in double quotes (see Quoting text).
- Every row must have the same number of columns as the header row.
- Numbers use
.as the decimal separator and no thousands separators. - The header fields of an invoice (store, invoice date, due date, account and purchase order) must be the same on every line of that invoice. The importer reads them from the first line only.
Example:
| Vendor | InvoiceNumber | InvoiceDate | Store | Item | Description | Quantity | Price | Size | PackSize |
|---|---|---|---|---|---|---|---|---|---|
| SAMPLEFOODS | 10001 | 2026-01-01 | 9875 | ABC123 | Item 1 | 2 | 5.00 | CASE | "12x 1oz" |
| SAMPLEFOODS | 10001 | 2026-01-01 | 9875 | XYZ200 | Item 2 | 1 | 10.50 | EA | 1 ct |
| DEMOPRODUCE | 10002 | 2026-01-02 | 9875 | AAA500 | Item 3 | 4 | 2.25 | EA | 1 lb |
The importer supports any standard delimited text format. But this character must not be included in any field unless wrapped in double quotes.
Common delimiters include:
| Delimiter | Configuration Value |
|---|---|
| Comma | , |
| Tab | \t |
| Pipe | | |
| Semicolon | ; |
Example configuration:
{
"ColumnDelimiter": ","
}Wrap text fields in double quotes so delimiters, quotes and other special characters cannot break the row. Escape a double quote inside a field by doubling it.
SAMPLEFOODS,10003,2026-01-03,9875,ABC124,"Pickles, dill, 5 gal",1,18.00,EA,"1x 5 gal"
SAMPLEFOODS,10003,2026-01-03,9875,ABC125,"Tray, 12"" round",2,6.50,EA,"1 ct"The second line has the description Tray, 12" round.
Vendor,InvoiceNumber,InvoiceDate,Store,Item,Description,Quantity,Price,Size,PackSize
SAMPLEFOODS,10001,2026-01-01,9875,ABC123,Item 1,2,5.00,CASE,"12x 1oz"
DEMOPRODUCE,10002,2026-01-02,9875,AAA500,Item 3,4,2.25,EA,1 lbConfiguration:
{
"HasHeader": true
}SAMPLEFOODS,10001,2026-01-01,9875,ABC123,Item 1,2,5.00,CASE,"12x 1oz"
DEMOPRODUCE,10002,2026-01-02,9875,AAA500,Item 3,4,2.25,EA,1 lbConfiguration:
{
"HasHeader": false
}The importer supports two mapping methods. Only one is supported at a time.
When the file contains column headers, enable name mapping. Name mapping requires HasHeader to be true.
{
"UseNameMapping": true
}The configuration below lists every NameMapping property. Follow the default column names if possible. The right hand value should be updated to match the column names from your file. Any property left out of NameMapping uses its default column name. VendorIdentifier is the exception: it has no default name and is only used when it is set. The value Vendor below is an example.
{
"NameMapping": {
"InvoiceIdentifier": "InvoiceNumber",
"VendorIdentifier": "Vendor",
"StoreIdentifier": "Store",
"AccountIdentifier": "Account",
"InvoiceDate": "InvoiceDate",
"InvoiceDueDate": "InvoiceDueDate",
"PurchaseOrderIdentifier": "PurchaseOrderNumber",
"InvoiceTotalAmount": "InvoiceTotalAmount",
"ItemQuantity": "Quantity",
"ItemPrice": "Price",
"ItemSizeIdentifier": "Size",
"ItemIdentifier": "Item",
"ItemDescription": "Description",
"ItemPackSize": "PackSize",
"AdditionalInformation": "AdditionalInformation",
"IsWeighted": "IsWeighted",
"ItemWeightedAmount": "ItemWeightedAmount",
"ItemUpc": "UPC",
"IsExpense": "IsExpense"
}
}With name mapping, the order of the columns does not matter. If InvoiceIdentifier, ItemIdentifier, ItemDescription, ItemQuantity or ItemPrice is not found in the header row, the file fails to import. Other columns that are not found in the header row are ignored by the importer. The Developer Tool reports a missing store, invoice date, vendor or expense column as an error.
Index mapping identifies columns by their zero-based position. It is required when the file has no header row, and can also be used with a header row (the header row is skipped). The right hand value should be updated to match the column index from your file.
{
"UseNameMapping": false
}Example file:
SAMPLEFOODS,10001,2026-01-01,9875,ABC123,Item 1,2,5.00,CASE,"12x 1oz"
DEMOPRODUCE,10002,2026-01-02,9875,AAA500,Item 3,4,2.25,EA,1 lbConfiguration:
{
"IndexMapping": {
"VendorIdentifier": 0,
"InvoiceIdentifier": 1,
"InvoiceDate": 2,
"StoreIdentifier": 3,
"ItemIdentifier": 4,
"ItemDescription": 5,
"ItemQuantity": 6,
"ItemPrice": 7,
"ItemSizeIdentifier": 8,
"ItemPackSize": 9
}
}Set InvoiceIdentifier, ItemIdentifier, ItemDescription, ItemQuantity and ItemPrice explicitly. If one is left out, the importer reads column 0. Use 0 only when the first column is meant. VendorIdentifier has no default and is only used when it is set.
All IndexMapping properties:
{
"IndexMapping": {
"InvoiceIdentifier": 0,
"StoreIdentifier": 1,
"AccountIdentifier": 2,
"InvoiceDate": 3,
"InvoiceDueDate": 4,
"PurchaseOrderIdentifier": 5,
"InvoiceTotalAmount": 6,
"ItemQuantity": 7,
"ItemPrice": 8,
"ItemSizeIdentifier": 9,
"ItemIdentifier": 10,
"ItemDescription": 11,
"ItemPackSize": 12,
"AdditionalInformation": 13,
"IsWeighted": 14,
"ItemWeightedAmount": 15,
"ItemUpc": 16,
"IsExpense": 17,
"VendorIdentifier": 18
}
}The following fields are required.
| Configuration Property | Description |
|---|---|
| InvoiceIdentifier | Unique invoice number |
| ItemIdentifier | Vendor item number or SKU |
| ItemDescription | Product description |
| ItemQuantity | Quantity purchased |
| ItemPrice | Unit Price for the item or line excluding any tax or fees |
| StoreIdentifier | Store receiving the invoice |
| InvoiceDate | Invoice date |
These fields are strongly recommended:
| Configuration Property | Description |
|---|---|
| ItemSizeIdentifier | Item size such as each or case |
| ItemPackSize | Pack size such as "10 x 4lb rolls" this helps identify the unique item to the customer |
The importer fails the file if the invoice, item, description, quantity or price column cannot be found. For the other fields it substitutes a placeholder so the rest of the invoice can still be reviewed. These invoices need manual correction, so do not rely on the placeholders:
- A missing store becomes
NO_STORE. - A missing invoice date becomes the date the file is processed.
- A missing description becomes
NO_DESCRIPTION. - A missing size column uses
ItemSizeDefault(see Default Item Size).
The Developer Tool reports a missing store or invoice date as an error. A missing size or pack size is a warning. The standard configuration requires size and pack size.
The following fields may be included if available.
| Configuration Property | Description |
|---|---|
| VendorIdentifier | Vendor code or name for the invoice. It has no default column name and is only used when it is set. Used when one file contains invoices from more than one vendor. See Multiple Vendors |
| AccountIdentifier | Vendor account number |
| InvoiceDueDate | Due date. If present, it must match DateFormat |
| PurchaseOrderIdentifier | Purchase order number |
| InvoiceTotalAmount | Invoice total. When it is provided, Yellow Dog uses it as the invoice total. When it is empty or not mapped, the total is calculated from the lines plus expenses. Send the same value on every line of the invoice; the first value found is used. The Developer Tool warns when it does not match the lines plus expenses |
| AdditionalInformation | Additional notes |
| ItemUpc | UPC barcode |
| IsWeighted | Indicates weighted item |
| ItemWeightedAmount | Weight of item. If IsWeighted is true, this will be used in place of Quantity and is required |
| IsExpense | Explicitly identifies an expense line where the description is used as the expense name and quantity and price are multiplied to get the total expense amount |
A single file can contain invoices from more than one vendor, for example a distributor or aggregator export. Map the column that holds the vendor on each line to VendorIdentifier.
- The vendor identifier on each invoice is mapped to a Yellow Dog vendor during invoice processing, so the value must be consistent for a vendor across every file (a vendor code is preferred over a free-text name).
- If
VendorIdentifieris not mapped, or a line has an empty value in the mapped column, the configurationNameis used as the vendor identifier. Single-vendor files do not need this column. VendorIdentifierhas no default column name. With name mapping, set it to the vendor column name. With index mapping, set it to the column index.- Include the vendor on every line. The Developer Tool reports an empty vendor in a mapped column as an error, and a mapped vendor column that is not in the header as an error.
- Invoice numbers only need to be unique per vendor. Rows are combined into invoices by vendor identifier plus invoice identifier, so two vendors may use the same invoice number in one file.
Example:
| Vendor | InvoiceNumber | InvoiceDate | Store | Item | Description | Quantity | Price | Size | PackSize |
|---|---|---|---|---|---|---|---|---|---|
| SAMPLEFOODS | 10001 | 2026-01-01 | 9875 | ABC123 | Item 1 | 2 | 5.00 | CASE | "12x 1oz" |
| SAMPLEFOODS | 10001 | 2026-01-01 | 9875 | XYZ200 | Item 2 | 1 | 10.50 | EA | 1 ct |
| DEMOPRODUCE | 10001 | 2026-01-01 | 9875 | K-500 | Item 3 | 4 | 2.25 | EA | 1 lb |
This file produces two invoices: 10001 for SAMPLEFOODS with two lines and 10001 for DEMOPRODUCE with one line.
Name mapping:
{
"UseNameMapping": true,
"NameMapping": {
"VendorIdentifier": "Vendor",
"InvoiceIdentifier": "InvoiceNumber",
"InvoiceDate": "InvoiceDate",
"StoreIdentifier": "Store",
"ItemIdentifier": "Item",
"ItemDescription": "Description",
"ItemQuantity": "Quantity",
"ItemPrice": "Price",
"ItemSizeIdentifier": "Size",
"ItemPackSize": "PackSize"
}
}Index mapping:
{
"UseNameMapping": false,
"IndexMapping": {
"VendorIdentifier": 0,
"InvoiceIdentifier": 1,
"InvoiceDate": 2,
"StoreIdentifier": 3,
"ItemIdentifier": 4,
"ItemDescription": 5,
"ItemQuantity": 6,
"ItemPrice": 7,
"ItemSizeIdentifier": 8,
"ItemPackSize": 9
}
}If dates are not in a standard format, specify the expected .NET date format. If a date does not match DateFormat, the importer tries a standard date parse before falling back to the processing date. The Developer Tool reports a date that does not match DateFormat as an error.
Example:
{
"DateFormat": "MM/dd/yyyy"
}Examples:
| File Value | Format |
|---|---|
| 01/31/2026 | MM/dd/yyyy |
| 31-Jan-2026 | dd-MMM-yyyy |
| 2026-01-31 | yyyy-MM-dd |
Send dates and times in UTC for consistency, with IsUtc set to true. Use an ISO format: yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss.
If dates should be interpreted as UTC use the below configuration. IsUtc defaults to true. When a time zone is configured for the integration, dates are converted to that time zone after they are read.
{
"IsUtc": true
}Otherwise:
{
"IsUtc": false
}Some invoice exports provide the extended line total rather than the unit price.
Example:
| Quantity | Price |
|---|---|
| 4 | 20.00 |
Enable automatic calculation of unit price:
{
"DividePriceByQuantity": true
}The importer calculates:
20.00 / 4 = 5.00The division is only applied when both price and quantity are greater than zero.
If the file does not include a size column (no ItemSizeIdentifier is mapped):
{
"ItemSizeDefault": "EA"
}Every imported item will use:
EAItemSizeDefault is not applied to blank cells in a mapped size column.
Invoice rows can be imported as expenses instead of inventory items. It is highly recommended to supply a configuration for standard expense data to avoid the need for configuration for each implementation.
Several expense methods can be used together in one configuration. Each line is checked in this order, and the first match wins:
- The
IsExpensecolumn - Exact keyword matching
- Item identifier matching
- Contains keyword matching
These four methods turn a whole line into an expense. Additional Expense Columns work differently: they add expenses from extra columns on a line that is imported as a normal item.
The expense amount is quantity multiplied by price. A blank quantity is treated as 1, and an expense with a total of zero is not imported. Expense lines must still include an item identifier, or the line is skipped.
{
"ExpenseExactKeywords": {
"Freight": "Freight",
"Tax": "Sales Tax"
}
}If the description matches one of the configured keys (ignoring case), the row is treated as an expense and the right hand value is used as the expense name.
Example:
Freight{
"ExpenseItemIdentifiers": {
"FRT": "Freight",
"TAX": "Sales Tax"
}
}If the item identifier matches one of the configured keys (ignoring case), the row is treated as an expense and the right hand value is used as the expense name.
Example:
FRT{
"ExpenseContainsKeywords": {
"fuel": "Fuel Surcharge",
"delivery": "Delivery Fee"
}
}If the description contains one of the configured keywords (ignoring case), it is imported as an expense and the right hand value is used as the expense name.
Example:
Fuel surcharge Julycontains:
fuelIf a description contains more than one keyword, each match adds its own expense.
Use whichever methods fit your export, in the same configuration. A line is checked against the whole-line methods in the order above. A line that matches none of them is imported as an item, and any ExpenseColumns on it add expenses.
{
"NameMapping": {
"IsExpense": "IsExpense",
"ExpenseColumns": {
"Handling": "Handling"
}
},
"ExpenseExactKeywords": {
"Freight": "Freight"
},
"ExpenseItemIdentifiers": {
"FUEL": "Fuel",
"FEE": "Fee"
},
"ExpenseContainsKeywords": {
"surcharge": "Surcharge"
}
}With this configuration:
- A line with
IsExpensetrue is an expense named by its description. - A line with the description
Freightis a Freight expense. - A line with the item code
FUELis a Fuel expense. - A line with a description such as
Energy surchargeis a Surcharge expense. - Any other line is an item. A
Handlingamount greater than zero on it adds a Handling expense.
Send a discount as an expense line with a quantity of 1 and a negative price. Identify the line in one of two ways:
- An expense item code, such as
DISCOUNT, mapped inExpenseItemIdentifiers. IsExpenseset totrue. The description is the expense name.
SAMPLEFOODS,10001,2026-01-05,9875,DISCOUNT,Volume Discount,1,-5.00,EA,1 ctThe expense amount is quantity multiplied by price, so this line is a -5.00 expense. A line with an amount of zero is skipped.
A discount cannot be sent in an expense column. ExpenseColumns only import amounts greater than zero, so a negative amount is ignored.
Additional columns may be used as expense records while the item data on the same line is imported as a standard line item. ExpenseColumns is set inside IndexMapping or NameMapping, and the right hand value is the expense name. The value of the column should be a decimal amount. Only amounts greater than zero are imported, so these columns cannot carry a discount (see Discounts). They are not read on lines that are whole-line expenses.
Expense columns are added up across all lines of an invoice. An expense that applies to the whole invoice, such as freight, must be on one line only. Leave the column empty or 0 on the other lines of that invoice. If the same amount is repeated on every line, it is counted once for each line, unless ExpenseColumnsDuplicated is set (see Repeated expense amounts).
In this example, Freight is mapped as an expense column. Invoice 10001 gets one Freight expense of 12.50:
InvoiceNumber,InvoiceDate,Store,Item,Description,Quantity,Price,Freight
10001,2026-01-05,9875,ABC123,"Item 1",2,5.00,12.50
10001,2026-01-05,9875,XYZ200,"Item 2",1,10.50,
10001,2026-01-05,9875,AAA500,"Item 3",4,2.25,Repeating 12.50 on all three lines would import a Freight expense of 37.50.
If your export repeats the invoice-level amount on every line of the invoice, set ExpenseColumnsDuplicated to true. Each expense column is then read once per invoice, from the first line of the invoice that has a value, and the column is ignored on the other lines. With this setting, repeating 12.50 on all three lines in the example above imports one Freight expense of 12.50. The Developer Tool warns when the lines of one invoice have different amounts in the same expense column, because only the first is used.
{
"InvoiceConfiguration": {
"ExpenseColumnsDuplicated": true
}
}ExpenseColumnsDuplicated defaults to false. It does not affect whole-line expenses.
The left hand key is the column index.
{
"IndexMapping": {
"ExpenseColumns": {
"10": "Department",
"11": "CostCenter"
}
}
}The left hand key is the column name.
{
"NameMapping": {
"ExpenseColumns": {
"Department": "Department",
"CostCenter": "CostCenter"
}
}
}This file uses the Example NameMapping Configuration below. It contains invoices from two vendors, including a freight expense line.
Vendor,InvoiceNumber,Store,InvoiceDate,Item,Description,Quantity,Price,Size,PackSize,UPC
SAMPLEFOODS,10001,001,2026-01-01,ABC123,Hamburger Patty,2,12.50,CASE,"40x 4oz",123456789012
SAMPLEFOODS,10001,001,2026-01-01,FRT,Freight,1,15.00,EA,1 ct,
DEMOPRODUCE,10002,002,2026-01-02,XYZ500,French Fries,5,4.25,CASE,"6x 5lb",999888777666
DEMOPRODUCE,10002,002,2026-01-02,FRT,Freight,1,10.00,EA,1 ct,This file produces two invoices: 10001 for SAMPLEFOODS with one item and a 15.00 freight expense, and 10002 for DEMOPRODUCE with one item and a 10.00 freight expense.
{
"HasHeader": true,
"UseNameMapping": true,
"ColumnDelimiter": ",",
"DateFormat": "yyyy-MM-dd",
"IsUtc": true,
"DividePriceByQuantity": false,
"ItemSizeDefault": "EA",
"NameMapping": {
"VendorIdentifier": "Vendor",
"InvoiceIdentifier": "InvoiceNumber",
"StoreIdentifier": "Store",
"InvoiceDate": "InvoiceDate",
"ItemIdentifier": "Item",
"ItemDescription": "Description",
"ItemQuantity": "Quantity",
"ItemPrice": "Price",
"ItemSizeIdentifier": "Size",
"ItemPackSize": "PackSize",
"ItemUpc": "UPC"
},
"ExpenseItemIdentifiers": {
"FRT": "Freight"
}
}This configuration reads the same file without its header row.
{
"HasHeader": false,
"UseNameMapping": false,
"ColumnDelimiter": ",",
"DateFormat": "yyyy-MM-dd",
"IsUtc": false,
"DividePriceByQuantity": false,
"ItemSizeDefault": "EA",
"IndexMapping": {
"VendorIdentifier": 0,
"InvoiceIdentifier": 1,
"StoreIdentifier": 2,
"InvoiceDate": 3,
"ItemIdentifier": 4,
"ItemDescription": 5,
"ItemQuantity": 6,
"ItemPrice": 7,
"ItemSizeIdentifier": 8,
"ItemPackSize": 9,
"ItemUpc": 10
},
"ExpenseItemIdentifiers": {
"FRT": "Freight"
}
}Vendors developing a new export should follow this standard. It uses every supported column with the default column names, a header row, comma delimiters, UTC dates and a standard set of expense codes. An export that follows it can be certified with the configuration below; only Key and Name change.
- The file has a header row with the column names below. Columns may be in any order.
- Only the required columns must be in the file. Optional columns that a vendor does not have can be left out of the file entirely; the standard configuration does not need to change.
- Every line includes all required columns:
InvoiceNumber,InvoiceDate,Store,Item,Description,Quantity,Price,SizeandPackSize. Vendoris included on every line, even when the file only contains one vendor (see Multiple Vendors).- Dates are UTC calendar dates in the format
yyyy-MM-dd. - Text fields are wrapped in double quotes (see Quoting text).
Priceis the unit price. For weighted items, setIsWeightedtotrueand put the weight inItemWeightedAmount; the price is per unit of weight.- Bool columns use
trueorfalse.
Fuel, shipping and fee charges are sent as their own lines with one of these item codes. The expense amount is Quantity x Price, so send a quantity of 1 and the charge as the price.
| Item | Expense | Use for |
|---|---|---|
FUEL | Fuel | Fuel surcharges |
SHIPPING | Shipping | Freight, delivery and shipping charges |
FEE | Fee | Service, small order and other fees |
Leave IsExpense as false on these lines. IsExpense set to true is only for any other expense, which is then named by its Description. This includes a discount, which uses a quantity of 1 and a negative price (see Discounts).
| Column | Configuration Property | Required |
|---|---|---|
| Vendor | VendorIdentifier | Yes (standard). Not needed for a single vendor, but the standard configuration maps it |
| InvoiceNumber | InvoiceIdentifier | Yes |
| InvoiceDate | InvoiceDate | Yes |
| InvoiceDueDate | InvoiceDueDate | No |
| PurchaseOrderNumber | PurchaseOrderIdentifier | No |
| Account | AccountIdentifier | No |
| Store | StoreIdentifier | Yes |
| InvoiceTotalAmount | InvoiceTotalAmount | No |
| Item | ItemIdentifier | Yes |
| Description | ItemDescription | Yes |
| Quantity | ItemQuantity | Yes |
| Price | ItemPrice | Yes |
| Size | ItemSizeIdentifier | Yes (standard) |
| PackSize | ItemPackSize | Yes (standard) |
| UPC | ItemUpc | No |
| IsWeighted | IsWeighted | No |
| ItemWeightedAmount | ItemWeightedAmount | No |
| AdditionalInformation | AdditionalInformation | No |
| IsExpense | IsExpense | No |
Vendor,InvoiceNumber,InvoiceDate,InvoiceDueDate,PurchaseOrderNumber,Account,Store,InvoiceTotalAmount,Item,Description,Quantity,Price,Size,PackSize,UPC,IsWeighted,ItemWeightedAmount,AdditionalInformation,IsExpense
SAMPLEFOODS,10001,2026-01-05,2026-02-04,PO-5512,ACCT-77,9875,90.75,ABC123,Hamburger Patty,2,25.00,CASE,"40x 4oz",123456789012,false,,,false
SAMPLEFOODS,10001,2026-01-05,2026-02-04,PO-5512,ACCT-77,9875,90.75,BEEF01,Beef Brisket,1,6.25,LB,"1x 12lb avg",,true,3.4,,false
SAMPLEFOODS,10001,2026-01-05,2026-02-04,PO-5512,ACCT-77,9875,90.75,FUEL,Fuel Surcharge,1,7.50,EA,1 ct,,false,,,false
SAMPLEFOODS,10001,2026-01-05,2026-02-04,PO-5512,ACCT-77,9875,90.75,SHIPPING,Delivery,1,12.00,EA,1 ct,,false,,,false
DEMOPRODUCE,10001,2026-01-05,2026-01-20,,K-1001,9875,32.00,K-500,Lemons,4,7.00,CASE,"1x 115ct",,false,,Deliver to back door,false
DEMOPRODUCE,10001,2026-01-05,2026-01-20,,K-1001,9875,32.00,FEE,Small Order Fee,1,4.00,EA,1 ct,,false,,,falseThis file produces two invoices:
10001forSAMPLEFOODShas two items (the brisket quantity is the 3.4 lb weight) plus a 7.50 Fuel expense and a 12.00 Shipping expense.10001forDEMOPRODUCEhas one item plus a 4.00 Fee expense.
{
"Key": "{SUPPLIER NAME}-v1",
"Name": "{SUPPLIER NAME}",
"Version": 1,
"InvoiceConfiguration": {
"HasHeader": true,
"UseNameMapping": true,
"ColumnDelimiter": ",",
"DateFormat": "yyyy-MM-dd",
"IsUtc": true,
"DividePriceByQuantity": false,
"ItemSizeDefault": null,
"IndexMapping": null,
"NameMapping": {
"VendorIdentifier": "Vendor",
"InvoiceIdentifier": "InvoiceNumber",
"InvoiceDate": "InvoiceDate",
"InvoiceDueDate": "InvoiceDueDate",
"PurchaseOrderIdentifier": "PurchaseOrderNumber",
"AccountIdentifier": "Account",
"StoreIdentifier": "Store",
"InvoiceTotalAmount": "InvoiceTotalAmount",
"ItemIdentifier": "Item",
"ItemDescription": "Description",
"ItemQuantity": "Quantity",
"ItemPrice": "Price",
"ItemSizeIdentifier": "Size",
"ItemPackSize": "PackSize",
"ItemUpc": "UPC",
"IsWeighted": "IsWeighted",
"ItemWeightedAmount": "ItemWeightedAmount",
"AdditionalInformation": "AdditionalInformation",
"IsExpense": "IsExpense",
"ExpenseColumns": {}
},
"ExpenseExactKeywords": {},
"ExpenseContainsKeywords": {},
"ExpenseItemIdentifiers": {
"FUEL": "Fuel",
"SHIPPING": "Shipping",
"FEE": "Fee"
}
}
}Name is used as the vendor identifier for any invoice that does not have one in the file (see Multiple Vendors).
{
"Key": "{SUPPLIER NAME}-v1",
"Name": "{SUPPLIER NAME}",
"Version": 1,
"InvoiceConfiguration": {
"IsUtc": true,
"HasHeader": true,
"DateFormat": "yyyyMMdd",
"NameMapping": null,
"IndexMapping": {
"ItemUpc": 16,
"IsExpense": null,
"ItemPrice": 5,
"IsWeighted": 14,
"InvoiceDate": 7,
"ItemPackSize": 17,
"ItemQuantity": 4,
"ExpenseColumns": {
"8": "MISC",
"9": "MISC"
},
"InvoiceDueDate": null,
"ItemIdentifier": 2,
"ItemDescription": 3,
"StoreIdentifier": 1,
"VendorIdentifier": 0,
"AccountIdentifier": 1,
"InvoiceIdentifier": 6,
"InvoiceTotalAmount": 11,
"ItemSizeIdentifier": 18,
"ItemWeightedAmount": 15,
"AdditionalInformation": null,
"PurchaseOrderIdentifier": 10
},
"UseNameMapping": false,
"ColumnDelimiter": ",",
"ItemSizeDefault": null,
"ExpenseExactKeywords": {},
"DividePriceByQuantity": false,
"ExpenseItemIdentifiers": {
"FRT": "Freight"
},
"ExpenseContainsKeywords": {}
}
}Yellow Dog picks up files from an FTP or SFTP folder on a schedule. The folder is agreed during setup (by default a subfolder named INV). Each file is removed from the folder after it is downloaded. A .zip file is unzipped. Empty files and files older than 45 days are skipped.
Include your supplier name or abbreviation, the customer number and the date and time the file was created, using only letters, digits, _ and -. For example: SAMPLEFOODS_123456_20261116T143000.csv. File names must be unique.
When your export puts a single invoice in each file, also include the invoice number. For example, a file for invoice 10001: SAMPLEFOODS_123456_10001_20261116T143000.csv.
An invoice with the same invoice number, store and vendor as one already imported is skipped. It does not update or replace the first one, and it is not duplicated. The same invoice number at a different store is a separate invoice.
There is no way to correct or void an invoice by sending it again with the same invoice number. To send a corrected invoice, give it a new, unique invoice number, for example by adding a suffix to the original (10001-C1). Tell the customer, so the original invoice can be handled in Yellow Dog.
Send returns as lines with a negative quantity (see Processing Rules and Requirements) and discounts as expense lines with a negative price (see Discounts). An invoice that is entirely negative is imported as sent.
You are not notified today. Use the Developer Tool to check every change to your export before you send files. The importer is more lenient than the tool: for example, a missing description is imported as NO_DESCRIPTION, and a file without a mapped store column is imported with the store NO_STORE. Those invoices need manual work in Yellow Dog (see Required Fields), so fix what the tool reports.
UTF-8, with or without a byte order mark. Windows (CRLF) and Unix (LF) line endings are both accepted.
Yes. With name mapping, the header must match the configured name exactly, including case and spaces. Values are not trimmed, so do not pad them with spaces.
true, false, 1 and 0. Case does not matter, so TRUE and FALSE as exported by Excel are accepted. An empty value is read as false.
Yes, a quoted number such as "5.00" is read as a number. Use . as the decimal point, no thousands separators, and a leading - for negative numbers (not (5.00)).
Yes. Store, account, item and invoice identifiers are read as text, so 001 stays 001. The store must match the store code set up in Yellow Dog exactly.
Descriptions, additional information and pack size are cut at 256 characters. Keep item identifiers, sizes, expense names, store, account, invoice and purchase order numbers to 50 characters or fewer.
Both are free text. Use the same size codes every time (for example EA, CS, LB), because Yellow Dog matches them to the vendor sizes set up for the customer. PackSize describes the pack, for example 6/1 GAL or 12x 1oz.
The vendor should provide a sample export file as well as a json configuration following the above specification. Yellow Dog will validate and certify this export and configuration.
Use the Developer Tool to check your test file and to prepare the submission.
The JSON configuration is submitted once for certification and is then used for all future files. A new configuration only needs to be certified when the mapping changes. This includes changes to columns, the delimiter, the date format and the expense rules. Sending new invoice files does not need recertification.