Skip to content
Last updated

EDI Invoice File Format Specification

Overview

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.


Developer Tool

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

Download GenericEdiDevTool-win-x64.zip

Requirements

Install

  1. Unzip the download.
  2. 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.

Using the tool

Follow the Start here tab. It has five steps:

  1. Read the file specification (this page).
  2. 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.
  3. Make a test file that covers the cases in the Test file checklist.
  4. Validate the file and fix what is reported. Change the configuration or the file and repeat.
  5. 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.

What passing means

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.

Submitting for certification

A passing validation is required before you can submit. The Submit for certification tab then:

  1. Asks for your company, contact and export details.
  2. Fills in an email to integrationsdev@yellowdogsoftware.com. The subject starts with [GenericInvoiceSubmission].
  3. 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.


Validation Rules

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.

Errors

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.
  • Key or Name is missing or empty.
  • InvoiceConfiguration is missing.
  • A setting has a value of the wrong type, so the configuration cannot be read.
  • UseNameMapping is true but HasHeader is false, or NameMapping is missing.
  • UseNameMapping is false and IndexMapping is missing.
  • With index mapping, InvoiceIdentifier, ItemIdentifier, ItemDescription, ItemQuantity or ItemPrice is not set. Set each one, using 0 when 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 VendorIdentifier column, or a column listed in ExpenseColumns, 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 DateFormat exactly. Without a DateFormat, 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.
  • Quantity or Price is empty.
  • A number is not a number. This applies to Quantity, Price, ItemWeightedAmount, InvoiceTotalAmount and 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,50 would import as 150. Send no thousands separators.
  • IsWeighted or IsExpense is not true, false, 0 or 1.
  • IsWeighted is true but ItemWeightedAmount is empty. The weight is used as the quantity.
  • A time zone selected in the tool is not found.

Warnings

  • Version is missing from the configuration. Add "Version": 1.
  • No size column is mapped and ItemSizeDefault is not set, so items have no size.
  • No pack size column is mapped.
  • The size or pack size is empty on a line. ItemSizeDefault is 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.
  • InvoiceTotalAmount differs from the lines plus expenses by more than 0.01. Yellow Dog uses the total from the file, so check that it is right.
  • ExpenseColumnsDuplicated is true and 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 DateFormat is set, so it is read only by the importer's fallback date parse. Set DateFormat to make it exact.

Guidance for writing the file

These rules are explained where they apply:

Test file checklist

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.

  1. Typical expenses. Fuel, shipping and fees, with quantity 1 and the charge as the price. See Standard Expenses.
  2. Multiples of the same item on one line. One line with the total quantity, never the same item repeated on separate lines.
  3. A return. A negative quantity.
  4. Weighted items, if you sell by weight. Set IsWeighted and ItemWeightedAmount.
  5. Multiple invoices in one file, if your export does that. Include at least two invoices.
  6. 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.

Processing Rules and Requirements

  • 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 IsExpense column, 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:

VendorInvoiceNumberInvoiceDateStoreItemDescriptionQuantityPriceSizePackSize
SAMPLEFOODS100012026-01-019875ABC123Item 125.00CASE"12x 1oz"
SAMPLEFOODS100012026-01-019875XYZ200Item 2110.50EA1 ct
DEMOPRODUCE100022026-01-029875AAA500Item 342.25EA1 lb

Delimited Files

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:

DelimiterConfiguration Value
Comma,
Tab\t
Pipe|
Semicolon;

Example configuration:

{
    "ColumnDelimiter": ","
}

Quoting text

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.


Header Rows

File With Header

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 lb

Configuration:

{
    "HasHeader": true
}

File Without Header

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 lb

Configuration:

{
    "HasHeader": false
}

Column Mapping

The importer supports two mapping methods. Only one is supported at a time.

Name Mapping

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

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 lb

Configuration:

{
    "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
    }
}

Required Fields

The following fields are required.

Configuration PropertyDescription
InvoiceIdentifierUnique invoice number
ItemIdentifierVendor item number or SKU
ItemDescriptionProduct description
ItemQuantityQuantity purchased
ItemPriceUnit Price for the item or line excluding any tax or fees
StoreIdentifierStore receiving the invoice
InvoiceDateInvoice date

These fields are strongly recommended:

Configuration PropertyDescription
ItemSizeIdentifierItem size such as each or case
ItemPackSizePack 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.


Optional Fields

The following fields may be included if available.

Configuration PropertyDescription
VendorIdentifierVendor 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
AccountIdentifierVendor account number
InvoiceDueDateDue date. If present, it must match DateFormat
PurchaseOrderIdentifierPurchase order number
InvoiceTotalAmountInvoice 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
AdditionalInformationAdditional notes
ItemUpcUPC barcode
IsWeightedIndicates weighted item
ItemWeightedAmountWeight of item. If IsWeighted is true, this will be used in place of Quantity and is required
IsExpenseExplicitly 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

Multiple Vendors

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 VendorIdentifier is not mapped, or a line has an empty value in the mapped column, the configuration Name is used as the vendor identifier. Single-vendor files do not need this column.
  • VendorIdentifier has 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:

VendorInvoiceNumberInvoiceDateStoreItemDescriptionQuantityPriceSizePackSize
SAMPLEFOODS100012026-01-019875ABC123Item 125.00CASE"12x 1oz"
SAMPLEFOODS100012026-01-019875XYZ200Item 2110.50EA1 ct
DEMOPRODUCE100012026-01-019875K-500Item 342.25EA1 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
    }
}

Date Format

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 ValueFormat
01/31/2026MM/dd/yyyy
31-Jan-2026dd-MMM-yyyy
2026-01-31yyyy-MM-dd

UTC Dates

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
}

Price Handling

Some invoice exports provide the extended line total rather than the unit price.

Example:

QuantityPrice
420.00

Enable automatic calculation of unit price:

{
    "DividePriceByQuantity": true
}

The importer calculates:

20.00 / 4 = 5.00

The division is only applied when both price and quantity are greater than zero.


Default Item Size

If the file does not include a size column (no ItemSizeIdentifier is mapped):

{
    "ItemSizeDefault": "EA"
}

Every imported item will use:

EA

ItemSizeDefault is not applied to blank cells in a mapped size column.


Expense Detection

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:

  1. The IsExpense column
  2. Exact keyword matching
  3. Item identifier matching
  4. 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.

1. Exact Keyword Matching

{
    "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

2. Item Identifier Matching

{
    "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

3. Contains Keyword Matching

{
    "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 July

contains:

fuel

If a description contains more than one keyword, each match adds its own expense.


Combining expense methods

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 IsExpense true is an expense named by its description.
  • A line with the description Freight is a Freight expense.
  • A line with the item code FUEL is a Fuel expense.
  • A line with a description such as Energy surcharge is a Surcharge expense.
  • Any other line is an item. A Handling amount greater than zero on it adds a Handling expense.

Discounts

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 in ExpenseItemIdentifiers.
  • IsExpense set to true. The description is the expense name.
SAMPLEFOODS,10001,2026-01-05,9875,DISCOUNT,Volume Discount,1,-5.00,EA,1 ct

The 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 Expense Columns

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.

Repeated expense amounts

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.

Index Mapping

The left hand key is the column index.

{
    "IndexMapping": {
        "ExpenseColumns": {
            "10": "Department",
            "11": "CostCenter"
        }
    }
}

Name Mapping

The left hand key is the column name.

{
    "NameMapping": {
        "ExpenseColumns": {
            "Department": "Department",
            "CostCenter": "CostCenter"
        }
    }
}

Complete CSV Example

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.


Example NameMapping Configuration

{
    "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"
    }
}

Example IndexMapping Configuration

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"
    }
}

Standard Configuration for New Vendors

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.

Rules

  • 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, Size and PackSize.
  • Vendor is 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).
  • Price is the unit price. For weighted items, set IsWeighted to true and put the weight in ItemWeightedAmount; the price is per unit of weight.
  • Bool columns use true or false.

Standard Expenses

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.

ItemExpenseUse for
FUELFuelFuel surcharges
SHIPPINGShippingFreight, delivery and shipping charges
FEEFeeService, 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).

Columns

ColumnConfiguration PropertyRequired
VendorVendorIdentifierYes (standard). Not needed for a single vendor, but the standard configuration maps it
InvoiceNumberInvoiceIdentifierYes
InvoiceDateInvoiceDateYes
InvoiceDueDateInvoiceDueDateNo
PurchaseOrderNumberPurchaseOrderIdentifierNo
AccountAccountIdentifierNo
StoreStoreIdentifierYes
InvoiceTotalAmountInvoiceTotalAmountNo
ItemItemIdentifierYes
DescriptionItemDescriptionYes
QuantityItemQuantityYes
PriceItemPriceYes
SizeItemSizeIdentifierYes (standard)
PackSizeItemPackSizeYes (standard)
UPCItemUpcNo
IsWeightedIsWeightedNo
ItemWeightedAmountItemWeightedAmountNo
AdditionalInformationAdditionalInformationNo
IsExpenseIsExpenseNo

Example File

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,,,false

This file produces two invoices:

  • 10001 for SAMPLEFOODS has two items (the brisket quantity is the 3.4 lb weight) plus a 7.50 Fuel expense and a 12.00 Shipping expense.
  • 10001 for DEMOPRODUCE has one item plus a 4.00 Fee expense.

Configuration

{
  "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"
    }
  }
}

Full Configuration Example

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": {}
  }
}

Frequently Asked Questions

How are files delivered?

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.

How should files be named?

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.

What happens if an invoice number is sent again?

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.

How do I send a correction or a void?

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.

How do I send a credit memo?

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.

How will I know a file failed to import?

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.

What encoding and line endings should I use?

UTF-8, with or without a byte order mark. Windows (CRLF) and Unix (LF) line endings are both accepted.

Are column names case sensitive?

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.

Which true and false values are accepted?

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.

Can numbers be quoted?

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)).

Are leading zeros kept?

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.

Are there length limits?

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.

What values can Size and PackSize have?

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.


Certification

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.