Skip to main content
Standards for vendor data contracts in independent cafes

Standards for vendor data contracts in independent cafes

A copyable appendix with field specs, export schedules, minimal SLA clauses and a three-step acceptance test you can paste into vendor emails and run during demos

Most cafe vendor agreements are detailed about price, delivery windows and minimum orders. They say almost nothing about the data that arrives with each delivery or sits inside each software subscription.

That gap usually costs more than a bad price. A dairy supplier changes pack sizes without changing the SKU. A POS renames a field in its export. A scheduling app only lets you download 90 days of history. None of these look like contract problems when you sign. They turn into contract problems around month four, when food cost is drifting, nobody can say why, and the vendor's answer is "that's just how our system works."

This post is a working appendix for that gap. Copy it, trim it, and attach it to supplier agreements, software contracts, or even the email thread that acts as your "contract" with a local bakery. It has a canonical field spec, export cadence templates, minimal SLA language, and a three-step acceptance test you can run in a demo or during a first delivery week. First, though, it helps to see how vendor data actually breaks inside a cafe, because the appendix only makes sense once you know which failures it's meant to prevent.

Nobody owns the data between the delivery door and the P&L

In a typical independent cafe, vendor data passes through four or five hands before it becomes a number anyone makes decisions on. Every handoff is a place where it can quietly go wrong.

Take something as boring as oat milk.

The supplier changes the case price, effective next Monday. That change lives in their system. Maybe it shows up on a price sheet emailed to whoever placed the last order, who might be a shift lead who has since left. The Monday delivery arrives with an invoice, usually a PDF and sometimes paper, showing the new price under the same item code. Whoever receives it checks quantity against the PO, maybe, and signs. The invoice goes into a folder or gets photographed. Someone keys it into inventory or accounting later in the week, often against the old cost in the item master because nobody updated the master. Recipe costing still uses the old cost, so the POS margin report says your oat latte is doing fine. Accounting books the invoice at the correct total. Two weeks later, COGS on the P&L is higher than the theoretical cost the inventory system says it should be. The variance gets labeled "waste" or "shrink," and somebody gets a talk about free-pouring.

Nobody in that chain made a real mistake. The supplier sent an invoice, the receiver checked quantities, the bookkeeper entered the total. The failure is structural: there was no agreement about how a price change travels, what identifier it's attached to, or when you'll hear about it.

Software vendors work the same way. Your POS exports item sales. Your delivery platform exports orders with its own item names. Your loyalty app exports redemptions with a different timestamp format. When you try to line these up, which is the whole point of the data-sync and reconciliation work most cafes eventually end up doing, you find the exports were never designed to talk to each other. A big share of "reconciliation" time is really translation time.

Why vendors don't solve this for you

A common assumption is that a decent vendor will just send good data. Some do. Most send data shaped for their own billing and support needs, not for your costing.

A broadline food distributor's invoice exists so they get paid and their AR team can match payments. Their item code exists for their warehouse. If they swap a 4×1 gal case for a 6×half-gal case because of their own supply issues, the code may not change at all, because on their side it's the same product line. On your side the cost per ounce just moved and every recipe using it is wrong.

Software vendors have their own version. Exports are usually built by the product team for "power users" and change whenever the product changes. A column gets renamed from itemname to displayname in an update. Nobody announces it, because internally it's cosmetic. Your spreadsheet formulas break silently and pull blanks for two weeks.

The person you negotiate with usually can't commit to any of this, either. Distributor sales reps control pricing and maybe delivery days, but not invoice format. Account managers at software companies can promise "we have a great export" but not that it won't change. So the requirement has to be written down in a form that gets routed to whoever actually controls it. Once it's in writing it stops being a favor and becomes a deliverable.

Also, owners ask vendors "can you send us a report?" and get a yes. A report and a data export are different things. A report is formatted for reading, with merged cells, subtotals, logos, a PDF. An export is formatted for machines and spreadsheets. If you don't specify, you'll get the report.

What changes when you go from one site to two or three

At one site, a lot of vendor data sloppiness gets absorbed by the owner's memory. You know the bakery's "large croissant" is your "butter croissant." You know the dairy shorted you last Tuesday because you were standing there. The data can be bad because the person reading it carries the context.

The second site removes that. Invoices now need a location identifier, and suppliers often don't include one. They have two ship-to accounts that may or may not show up on the invoice in a usable way. A manager at site two receives a delivery, while the owner at site one is the only person who knows the vendor changed their sizing. Context stops traveling with the data.

By three sites you usually have some central purchasing, maybe a shared item master, maybe one person doing books for all locations. This is where ID drift really starts to hurt. The same oat milk ends up with three internal names because each site set it up separately. One vendor bills under two account numbers. A software vendor's export lumps all locations together, or splits them in a way that doesn't match how you split them in accounting.

Working harder won't fix this stage. A canonical spec that every vendor maps to will. That's also the foundation of the small-cafe data architecture approach to POS integrations: stable internal IDs, with vendor data mapped onto them rather than the other way around. The contract appendix is how you push some of that mapping work back onto the vendor, or at least make sure they give you enough to do it yourself.

Timezone matters more at scale than people expect. A POS in one timezone and a delivery app reporting in UTC will put late-evening orders on the wrong business day. At one site you might notice. Across three sites with different closing times, it just shows up as unexplained daily variance.

The appendix

What follows is meant to be copied. Trim it for the vendor in front of you. A local bakery doesn't need the software section, and your POS doesn't need lot codes. Treat it as starting text, not a legal document.

If the contract is large or multi-year, have whoever handles your legal review look at the SLA language before it goes in.

Part 1: Canonical field spec

These are the fields you want every vendor to give you, in raw form, in a machine-readable file. Field names don't have to match exactly. What matters is that each field exists, stays consistent, and doesn't change meaning without notice.

For product suppliers (food, dairy, bakery, paper goods, coffee):

`` VENDOR DATA REQUIREMENTS — PRODUCT SUPPLY Each invoice line (and price list line) must include: vendorname Legal or trading name, consistent across all files vendoraccountid Our account number with you, per delivery location shiptolocation Delivery address or location code for that site invoicenumber Unique, never reused invoicedate YYYY-MM-DD deliverydate YYYY-MM-DD (actual, not scheduled) ponumber Our PO reference if provided, blank if not vendorsku Your item code. Must change if pack size, unit count, or product formulation changes itemdescription Plain text packsize Number of units per case (e.g. 6) unitsize Size of each unit (e.g. 64) unituom oz, fl oz, lb, g, ml, each qtyordered Cases or units, state which qtyshipped Same unit as qtyordered unitprice Price per case or per unit, state which linetotal qtyshipped × unitprice taxflag Y/N substitutionflag Y/N substitutedforsku Original SKU if substitutionflag = Y lotorbatch Where available (dairy, meat, prepared foods) bestbydate Where available creditreference If this line is a credit, the original invoicenumber priceeffectivedate On price lists, the date a new price applies ``

For software and platform vendors (POS, delivery, loyalty, scheduling, online ordering):

`` VENDOR DATA REQUIREMENTS — SOFTWARE / PLATFORM Transaction-level exports must include: transactionid Unique and stable; never reissued locationid Stable per site; does not change on rename businessdate The date we count the sale on, per our day-close timestamp ISO 8601 with timezone offset channel in-store, online, third-party (name), catering itemid Stable ID; does not change when item is renamed itemname Current display name modifierids Each modifier as its own ID, not merged into text qty Numeric grossamount Before discounts discountamount Separate from gross, with discountid refundflag Y/N, plus original transactionid if Y taxamount Separate tipamount Separate fees Platform fees as their own line or column tendertype card, cash, gift card, loyalty, other staff_id Where applicable Item and staff master exports must include ID, current name, active/inactive status, and date last modified. ``

If a vendor pushes back on everything else, hold onto two lines: the stable IDs, and the rule that the supplier SKU changes when the pack changes. Nearly every downstream costing problem I can think of traces back to one of those being broken.

business_date and timestamp are separate on purpose. It's the cheapest fix for the timezone and late-close problem, and most POS systems already calculate the business date internally. They just don't always export it.

Part 2: Export cadence templates

Cadence is the part people skip, and it's why data shows up too late to be useful. A price change you learn about after it hits the invoice is a variance. One you learn about five days ahead is an ordering decision.

Data typeWho sendsCadenceFormatWhy this timing
Invoice line detailProduct suppliersPer delivery, same dayCSV or XLSX attachment, or portal downloadLets receiving check against it before the next order
Price changesProduct suppliers7 calendar days before effective datePrice list file with priceeffectivedateTime to update recipe costs and menu if needed
SubstitutionsProduct suppliersBefore the truck leaves, by text or emailLine-level note with both SKUsReceiver can reject or accept knowingly
CreditsProduct suppliersWithin 5 business days of the claimCredit memo linked to original invoiceKeeps AP clean and ties back to the shorted delivery
Transaction exportPOS / online orderingDaily by 6am for prior business dayCSV, API or scheduled emailMorning manager review of yesterday
Payout / settlement detailDelivery and payment platformsWeekly, matched to payoutCSV with fees itemizedBank deposit reconciliation
Item and staff masterPOS / schedulingWeekly, or on changeCSVCatches renames and duplicate items early
Schema changesAny software vendor30 days before changeWritten notice to named contactTime to fix formulas or mappings
Full historical exportAny software vendorOn request, within 14 days; and on terminationCSV, all fields aboveProtects you when switching vendors

You don't need every vendor on daily anything. A bakery delivering three times a week with a dozen SKUs needs invoice detail and substitution notice, and that's it. Asking a two-person bakery for an API is a good way to lose a good bakery. Match the ask to the vendor's size and to how much of your COGS they represent.

Here's the paste-ready version for an email or appendix. Swap the bracketed parts for your own details.

  1. Invoice detail in CSV or XLSX, sent the same day as delivery to [ap@yourcafe.com].
  2. Price changes sent at least 7 calendar days before they take effect, in a file showing old price, new price and effective date.
  3. Substitutions communicated before dispatch to [manager phone/email], with both the ordered and substituted SKU.
  4. Credit memos issued within 5 business days of a reported shortage or quality claim, referencing the original invoice number.
  5. [Software] Daily transaction export available by 6

    00am local time for the prior business day.

  6. [Software] At least 30 days' written notice before any change to export field names, formats or meanings.

Delete the lines that don't apply to the vendor you're sending it to. A bakery gets items 1 to 4 at most.

A visual workflow makes it easier to explain responsibilities for delivery, file sending, import, and reconciliation.

Process diagram

Use a simple flow with labelled handoffs and who is accountable at each step.

Part 3: Minimal SLA language

Most small vendors won't sign a long SLA, and you don't need one. You need a few sentences that turn the field spec and cadence into obligations with a consequence attached, even a mild one.

`` DATA SERVICE COMMITMENTS a) Completeness. Files delivered under this agreement will contain the fields listed in the Vendor Data Requirements. Missing or blank required fields will be corrected and resent within 2 business days of notice. b) Stable identifiers. Item codes, location IDs and transaction IDs will not be reused or reassigned. A change in pack size, unit count or product formulation will be issued under a new item code. c) Price notice. Price increases not communicated per the Data Delivery Schedule will be honored at the prior price for the first delivery on which they appear. d) Format changes. Changes to export structure require 30 days' written notice. If a change is made without notice, Vendor will provide the prior format on request until the notice period has passed. e) Data access and portability. Customer owns its transaction, item, staff and customer data. Vendor will provide a complete export in CSV within 14 days of request and within 14 days of termination, at no additional charge. f) Corrections. Errors in invoices or exports identified by either party will be corrected through a credit or revised file that references the original document. ``

Clause (c) is the one that gets negotiated. Many suppliers will push back, and the compromise is often "honored for orders placed before notice." That's fine. What matters is that a surprise price increase costs the vendor something, which changes how carefully they send notices. Without it, notice is optional in practice.

Clause (e) matters most with software. Getting your data out is much harder after you've given notice than before. Some platforms limit history exports to 90 days, or charge for "data migration services." The time to find that out is during the demo, which brings us to the test.

Part 4: The three-step acceptance test

A manager can actually run this. It fits in a demo call or a first delivery week, and it shows whether the vendor can meet the spec before you're committed.

  1. The sample file test. Ask for a real export or invoice file covering at least two weeks, from an existing customer account (anonymized) or from your trial period. Don't accept a screenshot or a sample "template." Open it and check it against the field spec line by line. Are IDs present? Is pack size separate from the description, or buried in text like "OAT BARISTA 6/64Z"? Is there a timezone on timestamps? Are refunds their own rows tied to the original transaction, or just negative numbers? Write down every missing field and count them. If more than three or four required fields are missing, the vendor's system probably doesn't store them, and no promise will change that.
  2. The tie-out test. Take three specific records and make them agree with something outside the vendor's system. For a supplier, pick three invoices and confirm that line totals × quantities = invoice total = what hit your bank or AP. For a POS or delivery platform, pick three business days and confirm the export totals match the vendor's own dashboard summary and the payout deposit. If the vendor's export doesn't match the vendor's own dashboard, stop there. You'd spend hours every month reconciling their numbers against their numbers.
  3. The change test. Ask the vendor to show you, live or in writing, what happens when something changes. Rename an item in the POS, run the export, and see whether the item_id stays the same. Ask the supplier what happens to the SKU when they change case pack. Ask the software rep where a schema change notice would come from and who receives it. Do a refund in the demo and look at how it appears. This catches the stuff that otherwise won't surface for months, and vendors who've thought about it answer quickly. Vague answers like "our system handles that" are a signal.

A vendor that passes all three cleanly is rare, so in practice you're grading them. Passing step 2 is close to non-negotiable. Steps 1 and 3 tell you how much manual cleanup you're signing up for.

Paste-ready email for vendors

This works for an existing supplier you want to bring onto the spec, or a new software vendor before a demo. Edit the bracketed parts.

It's split into a few chunks so the lists stay readable when you paste into Gmail or Outlook. Send them in order as one email.

Subject: Data requirements for [Cafe Name] — please review before [date] Hi [Name],

  1. The fields we need on invoices / exports
  2. When we need them
  3. A few basic commitments on notice and corrections

Before [date / our demo], could you:

  1. Send a real sample file covering two weeks (anonymized is fine)
  2. Confirm which fields in the appendix you can and can't provide
  3. Let us know who on your side we should contact about file format changes

This isn't meant to be a big process. Most of it is probably stuff you already have. We just want it written down so nothing slips when people change on either side.

Thanks, [Name] [Role, Cafe]

Tone matters here. Framing it as "standardizing across all vendors" keeps it from feeling like an accusation, and asking which fields they can't provide gets you honest answers faster than asking them to confirm everything.

Real scenario: two cafes, one dairy supplier, and a pack change nobody caught

Business: Two-location independent cafe, roughly 450–550 drinks a day combined, one part-time bookkeeper shared across both sites, one owner running purchasing.

Problem: The dairy and alt-milk supplier delivered three times a week to each site with PDF invoices. Partway through spring, they changed their barista oat milk from 12×32oz to 6×64oz cases. Same total volume, same SKU, but a higher case price, around 8% more. Separately, they started substituting a different whole milk brand at one site on short-stock days, noted only as handwritten text on the delivery slip.

For about three months, recorded COGS ran consistently above theoretical cost. The unexplained gap was roughly $450–$600 a month across both sites. The owner assumed it was waste at the busier site and tightened pouring standards, which didn't move the number. Meanwhile the bookkeeper was spending five or six hours a week matching invoices to receiving notes and rekeying line items by hand.

What changed: The owner sent the vendor email above with the product supplier appendix. It turned out the supplier's portal already produced CSV invoice exports with pack size as a separate column. Nobody had ever asked for them. The supplier agreed to issue new SKUs on pack changes and to email substitutions before dispatch. They wouldn't accept the price-notice clause as written, but settled on "prior price honored for orders placed before notice."

The bookkeeper switched from rekeying PDFs to importing CSVs, mapped once against the cafe's internal item list. With pack size feeding straight into cost-per-ounce, the oat milk issue showed up within the first week.

After roughly two months: Invoice processing dropped to about 1.5–2 hours a week. The unexplained COGS gap shrank to under $150 a month, mostly real waste this time. Recipe costs on all the oat milk drinks got updated, and two drinks got a small price bump. The owner also stopped blaming the busier site's team, which mattered more than they expected.

The supplier wasn't hiding anything. The data existed. It just wasn't requested in a usable shape, and nobody had written down that a pack change means a new code.

When this actually makes sense

The appendix earns its keep when a vendor represents a meaningful chunk of your COGS or revenue flow: your main food distributor, dairy, coffee roaster, POS, and any delivery platform doing real volume. It's also worth doing at certain moments, like signing a new vendor, renewing a contract, opening a second site, or when a COGS variance has gone unexplained for more than a month or two.

It's especially useful when more than one person handles vendor data. If receiving, entry and reconciliation are done by different people, the contract is the one place the expectations live that doesn't depend on any of them remembering.

It also slots into a broader vendor decision process. If you've already set decision rights for who can approve new tools and suppliers, like the ones in the operator-first technology governance framework, the acceptance test becomes a natural gate. Nobody signs until the three steps are done.

When this is a bad idea

Sending a full appendix to a small artisan vendor who delivers a few items a week is usually counterproductive. A one-person bakery that does beautiful work and sends handwritten invoices may just stop selling to you. For those vendors, ask for two things: an emailed invoice with item, quantity and price, and a text before any substitution. Enforce it gently.

Don't send this mid-crisis either. If a supplier is already struggling to fill orders during a shortage, pushing data requirements on them signals you care more about paperwork than getting product. Wait until things settle.

And don't use the SLA clauses as a weapon over small misses. The goal is stable data, not collecting credits. If you invoke clause (c) every time a notice comes a day late, you'll get worse service on everything else.

Who should NOT do this (yet)

A single-site cafe with a handful of vendors, where the owner personally receives, enters and reconciles everything, probably doesn't need the full spec. Keeping the context in one head works at that size. A short version with stable SKUs, CSV invoices and price notice is plenty.

Cafes without an internal item list shouldn't start here either. The appendix assumes you have something to map vendor data onto. If your inventory and recipe costing aren't set up yet, a perfect vendor file just lands in a spreadsheet nobody uses. Build the internal item master first, then ask vendors to meet it.

And if nobody on your team will actually open the files, skip it. A spec that produces data no one reads is worse than no spec, because it creates a false sense that things are under control.

Before you sign: quick checklist

Keep this next to you during a demo or a vendor call. Most of it can be checked in under an hour if you have a real sample file open in front of you.

  1. Vendor has provided a real sample file, not a template or screenshot
  2. Pack size and unit size are separate fields, not buried in descriptions
  3. Item IDs stay the same when items are renamed (tested, not promised)
  4. SKU changes are tied to pack size or formulation changes, in writing
  5. Timestamps include a timezone; business date is exported separately
  6. Refunds and credits reference the original transaction or invoice
  7. Platform fees appear as their own lines, not netted out of sales
  8. Price change notice period agreed, even if shorter than 7 days
  9. Schema change notice period agreed, with a named contact on their side
  10. Full data export available on request and on termination, in CSV, without extra fees
  11. Three tie-out records matched against bank, AP or the vendor's own dashboard
  12. Someone at the cafe is named as the owner of each vendor's data feed

If the first four aren't ticked, I wouldn't sign yet. Notice periods and fee wording can be negotiated down the road, but a missing sample file or unstable IDs usually can't be fixed later.

Where software fits, and where it doesn't

Even with a good appendix in place, someone still has to check each file against the spec, map vendor SKUs to internal items, and notice when a field goes blank. It's tedious, and it's exactly the kind of work that slips during a busy week, which is also when vendors are most likely to substitute or change things.

This is where AI-assisted operational platforms have been genuinely useful in the cafes we've worked with. They don't replace the contract, they enforce it in the background. An incoming invoice file gets checked against the field spec automatically. A new vendor SKU gets matched to a likely internal item and flagged for a human to confirm, instead of silently creating a duplicate. A price that jumps past a set threshold without a matching notice gets surfaced to the owner before the invoice is approved. A POS export missing a column after an update triggers an alert the same morning, not two weeks later.

Map your highest-volume SKUs to the internal item master first so the automated matching reduces most manual work quickly.

What software can't do is get a vendor to send data they don't have, or decide which vendors are worth pushing. Those are still judgment calls, and the acceptance test is where you make them.

Start small

Vendor data problems in cafes rarely look like data problems. They look like rising food cost, a team that "can't control waste," a bookkeeper who's always behind, or a software switch that takes three months longer than planned because the old system won't release your history. The root cause is usually the same: nobody wrote down what the data should look like, when it should arrive, or what happens when it changes.

The appendix above is deliberately small. Start with your two or three biggest vendors and send the email. Run the acceptance test at your next renewal or demo. Expect some pushback and some partial wins. A distributor who only agrees to stable SKUs and CSV invoices has still removed one of the most common sources of silent COGS drift. As you add sites, the spec is what keeps every location's numbers comparable without you personally translating between them. Revisit it once a year, because your vendors' systems change even when nobody tells you.

Built for Coffee Shops Tailored to coffee shop workflows and customer service
Save Time Simplify orders, inventory, and staff coordination
Delight Customers Fast, accurate orders and personalized experiences
Grow Revenue Maximize sales and optimize resource use