Invoices is a file sent both from Kimelo on a regular basis, as well as sent to Kimelo by sellers. It is arguably most important file sent from the seller as it is the one that outlines the details needed for payment processing by Kimelo. Kimelo will keep sending the snapshot of invoice data in a regular fashion. This means it is not only the most recently updated invoices, but a snapshot of all invoices updated in a 30 day window, to ensure any interruption in a single file transfer gets caught and corrected on the next transfer. Once a seller uploads this file Kimelo will update the details of each invoice mentioned in the uploaded file. Sample file:

invoices_yyyy-mm-dd-hh-mm-ss.csv

Each file uploaded by the seller has to contain all details of a single invoice at a time. If a single erp_invoice_id or kimelo_order_id is present in the file Kimelo will assume that this same file contains all products that need to be present in the invoice for that order.

It is paramount that the details of invoice.csv file are correct as based on this file Kimelo will charge the end Customer when the invoices become due.

invoices.csv: Customer invoice attributes

Filename pattern invoices[datetime].csv
ERP to Kimelo Y
Kimelo to ERP Y
System of record Kimelo
Status Available
Frequency Daily

This is the format for invoices from Kimelo to the distributor’s ERP system. Kimelo creates an invoice when a vendor user marks a sales order as delivered. This invoice stays in an open status in Kimelo until the customer pays. Paid invoices appear in this file with a status of Paid.

This format is also available to send invoice information from the ERP to Kimelo. The ERP is the source for sales tax calculations.

Column Name Data Type Required Description
Repeat per invoice line:
erp_invoice_id integer Optional External-generated invoice number.
kimelo_order_id Integer Required Kimelo-generated order number.
erp_customer_id String Required Unique identifier for the customer location
status String Required (Kimelo-generated) Current status of the invoice. Status can be:
Pending_tax_calculation = a draft requiring tax calculations from the external system
Signed = delivery accepted
Paid = payment applied to this invoice
Partially_paid = payment applied less than total
created_at Timestamp Required (Kimelo-generated) Timestamp when the invoice was created.
updated_at Timestamp Required (Kimelo-generated) Timestamp of the last update made to the invoice.
total Currency Required Final total amount of the invoiced order, including all fees, taxes, and items.
cart_total Currency Required Total price of items in the cart.
promo_code_discount Currency Optional Discount applied from a promotional code.
credit_card_charge Currency Required Credit card surcharge.
deleted_at Timestamp Required (Kimelo-generated) Timestamp when the invoice was deleted, if applicable.
invoice_payment_due_date Date Required The date when the invoice payment must be paid, according to the customer payment terms
One row per invoice line:
erp_product_id String Required Distributor's identifier for a specific product
pack_type String Required A product variant defining how the product is sold (e.g., Case or Each).
quantity_units Integer (unsigned) Required Number of units accepted for delivery, in the sales unit defined in the product’s pack_type (case or each.) May be positive or zero but not negative.
unit_price Currency Required Price per unit. For catchweight items, this is the price per unit of measure (Kimelo uses imperial pound for all UOM)
line_subtotal Currency Required Total price for the line item, excluding taxes.
line_type String Required Tell apart items, taxes, and fees. See line types below.

Invoice line types

Kimelo understands the following invoice line types. Not all systems provide all of these types but they are available.

Name Description
ALCOHOL_TOTAL Total amount for alcohol items
BASE_DELIVERY_FEE Base delivery fee
CANCELLATION_FEE Fee charged for order cancellations
CART_TOTAL Total amount of items in the shopping cart
CHECKOUT_FEE Fee charged during the checkout process
CREDIT_CARD_CHARGE Fee associated with credit card transactions
CREDIT_NOTE Amount credited to the customer
CUSTOM A custom invoice item with a specific description
DAMAGE Fee for damaged goods
DISCOUNT_INVOICE_ITEM General discount applied to the invoice
FUEL_SURCHARGE_FEE Surcharge fee related to fuel costs
GENERAL_DISCOUNT General discount applied to the order
POST_CUT_OFF_CHARGE Fee charged for orders placed after a cutoff time
PRODUCT_INVOICE_ITEM Standard line item for a product
PROMO_CODE_DISCOUNT Discount applied using a promo code
REFUND Amount refunded to the customer
RETURN Fee associated with returned items
RE_DELIVERY_FEE Fee charged for re-delivery attempts
SAME_DAY_CHARGE Fee charged for same-day delivery
SUBSCRIPTION Fee for a subscription service
WILL_CALL_ORDER Fee or charge associated with will-call orders

Invoice status

The invoices sent to the seller can be in one of the four statuses:

Payments outside of Kimelo

Kimelo will charge invoices it considers unpaid on behalf of the seller. To avoid double-charging seller has to indicate to Kimelo that an invoice has been paid. This can be done by uploading the invoices.csv file containing an erp_invoice_id / kimelo_order_id with a payment status of paid or partially_paid. Kimelo will not charge the invoices marked with either of these statuses.