Data Contract

This document describes the data extracts for a Stuut file sync integration. These files provide Stuut the records needed to support collections workflows. You may provide these extracts as CSV or Excel files. During onboarding, Stuut will map your source columns into Stuut’s standard data model.

File list

Customers
Contacts
Invoices
Invoice PDFs
Payments
Payment Allocations
Credit Memos
Credit Memo Allocations
Credit Memo PDFs
GL Accounts (Chart of Accounts)
Disputes

Customers

File name: YYYYMMDD_customers.csv Your customer master list. Include all active customers, plus any customers deactivated since the last file.

Column Name	Type	Description
`customer_id`	id	Unique identifier for this customer. Must be stable and never reused.
`account_number`	string	Customer account number as it appears in your system.
`company_name`	string	Primary company name.
`billing_address_line1`	string	Street address for billing.
`billing_address_line2`	string	Suite, unit, floor, etc.
`billing_city`	string	City.
`billing_state`	string	State or province.
`billing_postal_code`	string	ZIP or postal code.
`billing_country`	string	Two-letter country code (e.g., US, CA, GB).
`remittance_address_line1`	string	Remittance address, if different from billing.
`remittance_address_line2`	string
`remittance_city`	string
`remittance_state`	string
`remittance_postal_code`	string
`remittance_country`	string
`currency`	currency	Default currency for this customer (e.g., USD).
`payment_terms`	string	Default payment terms (e.g., Net 30, Net 60, 2/10 Net 30).
`credit_limit`	decimal	Maximum credit extended to this customer.
`tax_id`	string	Tax identification number (EIN, VAT, ABN, etc.).
`collector_email`	string	Email address of collector for this account.
`is_active`	boolean	Y if active, N if deactivated/closed.
`timezone`	string	Timezone to call this customer in.
`customer_segmentation`	string	Segmentation into different dunning strategies.
`parent_id`	string	customer_id of parent if parent/child relationship.

Contacts

File name: YYYYMMDD_contacts.csv Contacts associated with your customers. These are the people Stuut may communicate with regarding invoices, payments, and disputes.

Column Name	Type	Description
`contact_id`	id	Unique identifier for this contact.
`customer_id`	id	Must match a customer_id in the Customers file.
`first_name`	string	Contact’s first name.
`last_name`	string	Contact’s last name.
`email`	string	Email address.
`phone`	string	Phone number.
`job_title`	string	Job title (e.g., “AP Manager”, “Controller”).
`role`	enum	One of: AP Clerk, AP Manager, Controller, Buyer, Procurement, Executive, Other.
`is_primary`	boolean	Y if primary contact. Exactly one per customer should be primary.
`is_active`	boolean	Y if active, N if should no longer be contacted.

Invoices

File name: YYYYMMDD_invoices.csv All open invoices, plus any invoices paid, voided, or otherwise closed in the last 7 days. Each row is one line item. An invoice with 5 line items appears as 5 rows sharing the same invoice-level fields.

Column Name	Type	Description
`invoice_remote_id`	id	Remote ID or unique identifier for the invoice.
`invoice_number`	string	Invoice number the customer sees.
`customer_id`	id	Must match a customer_id in the Customers file.
`issue_date`	date	Date the invoice was issued.
`due_date`	date	Date payment is due. Critical — drives aging and collection workflows.
`paid_date`	date	Date fully paid. Blank if unpaid.
`total_amount`	decimal	Total invoice amount including tax.
`subtotal`	decimal	Amount before tax.
`tax_amount`	decimal	Total tax on the invoice.
`amount_paid`	decimal	Total amount paid to date.
`open_balance`	decimal	Current remaining balance (total_amount - amount_paid).
`currency`	currency	Currency code (e.g., USD).
`status`	enum	One of: Open, Paid, Partially Paid, Void, In Dispute.
`payment_terms`	string	Terms on this invoice if different from customer default.
`po_number`	string	Purchase order number. Important for PO-based customers.
`order_number`	string	Sales order or contract reference number.
`ship_date`	date	Date goods were shipped.
`delivery_date`	date	Date goods were delivered.
`billing_address_line1`	string	Invoice-level billing address (if different from customer master).
`billing_address_line2`	string
`billing_city`	string
`billing_state`	string
`billing_postal_code`	string
`billing_country`	string
`shipping_address_line1`	string	Ship-to address.
`shipping_address_line2`	string
`shipping_city`	string
`shipping_state`	string
`shipping_postal_code`	string
`shipping_country`	string
`gl_account_id`	string	AR GL account. Must match account_id in GL Accounts file.
`memo`	string	Any notes or memo text on the invoice.

Line-Item Fields (unique per row within the same invoice):

Column Name	Type	Description
`line_number`	integer	Line sequence number (1, 2, 3…). Unique within an invoice.
`line_description`	string	Description of the item or service.
`item_code`	string	Product code, SKU, or item ID.
`quantity`	decimal	Quantity of units.
`unit_price`	decimal	Price per unit.
`line_total`	decimal	Extended amount (quantity x unit_price).
`line_tax_amount`	decimal	Tax amount for this line item.
`line_discount_amount`	decimal	Discount applied to this line.
`line_gl_account_id`	string	GL account for this line, if posting at line level.

Invoice PDFs

PDF copies of all invoices. Each file should be named using the invoice_remote_id: {invoice_remote_id}.pdf and be placed in folder pdfs.

Payments

File name: YYYYMMDD_payments.csv All payments received in the last 30 days. Each row is one payment.

Column Name	Type	Description
`payment_id`	id	Unique identifier for this payment.
`customer_id`	id	Must match a customer_id in the Customers file.
`payment_date`	date	Date the payment was received or initiated.
`posting_date`	date	Date posted in accounting system. Defaults to payment_date if omitted.
`amount`	decimal	Total payment amount.
`currency`	currency	Currency code.
`payment_method`	enum	One of: ACH, Wire, Check, Credit Card, EFT, Cash, Portal, Other.
`reference_number`	string	Check number, wire reference, transaction ID, etc.
`payer_name`	string	Payer name as on the transaction. Often differs from customer name.
`unapplied_amount`	decimal	Portion not applied to any invoice.
`status`	enum	One of: Applied, Partially Applied, Unapplied, Reversed, Returned.
`remittance_reference`	string	Reference from remittance advice, if separate from payment.
`gl_account_id`	string	Cash/bank GL account for this deposit.
`description`	string	Any notes or memo on the payment.

Payment Allocations

File name: YYYYMMDD_payment_allocations.csv How each payment is applied to invoices. Each row links one payment to one invoice. A single payment may have multiple rows if it covers multiple invoices.

Column Name	Type	Description
`payment_id`	id	Must match a payment_id in the Payments file.
`invoice_number`	id	Must match an invoice_number in the Invoices file.
`amount_applied`	decimal	Amount from this payment applied to this invoice.
`allocation_date`	date	Date recorded. Defaults to payment’s posting_date if omitted.

Credit Memos

File name: YYYYMMDD_credit_memos.csv All open credit memos plus any applied or voided in the last 30 days.

Column Name	Type	Description
`credit_memo_remote_id`	id	Unique ID of the credit memo. MUST be unique.
`credit_memo_number`	string	Credit memo number the customer sees.
`customer_id`	id	Must match a customer_id in the Customers file.
`issue_date`	date	Date the credit memo was issued.
`effective_date`	date	Date credit takes effect, if different from issue date.
`amount`	decimal	Net credit memo amount (positive number).
`tax_amount`	decimal	Tax portion of the credit memo.
`currency`	currency	Currency code.
`status`	enum	One of: Open, Applied, Partially Applied, Void.
`reason_code`	string	Code for why credit was issued (e.g., PRICING, SHORTAGE, QUALITY, DUPLICATE, RETURN).
`reason_description`	string	Human-readable description of the reason.
`originating_invoice_number`	string	Invoice this credit was issued against, if applicable.
`gl_account_id`	string	GL account this credit was posted to.
`memo`	string	Any notes.

Credit Memo Allocations

File name: YYYYMMDD_credit_memo_allocations.csv How each credit memo has been applied to invoices. Each row links one credit memo to one invoice.

Column Name	Type	Description
`credit_memo_number`	id	Must match a credit_memo_number in the Credit Memos file.
`invoice_number`	id	The invoice this credit was applied against.
`amount_applied`	decimal	Amount of credit applied to this invoice.
`allocation_date`	date	Date the credit was applied.

Credit Memo PDFs

PDF copies of all credit memos. Each file should be named using the credit_memo_remote_id: {credit_memo_remote_id}.pdf and be placed in folder pdfs.

GL Accounts (Chart of Accounts)

File name: YYYYMMDD_gl_accounts.csv Full chart of accounts. Allows categorization of transactions by ledger account. Send weekly (Mondays).

Column Name	Type	Description
`account_id`	id	Unique GL account identifier. Referenced by gl_account_id in other files.
`account_number`	string	Account number as displayed (e.g., 1200, 4000-10).
`account_name`	string	Account name (e.g., “Accounts Receivable”, “Cash - Operating”).
`classification`	enum	One of: Asset, Liability, Equity, Revenue, Expense, Other.
`account_type`	string	Sub-classification (e.g., “Current Asset”, “Long Term Liability”).
`currency`	currency	Currency of the account.
`is_active`	boolean	Y if active.
`parent_account_id`	string	Parent account_id if hierarchical.
`description`	string	Description of the account’s purpose.

Disputes

File name: YYYYMMDD_disputes.csv Only required if you track disputes in your ERP and want them synced. All open disputes plus any resolved in the last 30 days.

Column Name	Type	Description
`dispute_id`	id	Unique dispute identifier.
`customer_id`	id	Must match a customer_id in the Customers file.
`invoice_number`	string	Invoice(s) being disputed. If multiple, separate with semicolons (;).
`disputed_amount`	decimal	Total amount in dispute.
`currency`	currency	Currency code.
`dispute_type`	enum	One of: Pricing, Freight, Quality, Quantity/Shortage, Duplicate Billing, Unauthorized Charge, Other.
`reason_code`	string	Your internal reason code.
`reason_description`	string	Human-readable description.
`open_date`	date	Date the dispute was opened.
`resolution_date`	date	Date resolved. Blank if still open.
`status`	enum	One of: Open, Investigating, Pending Customer Response, Resolved, Escalated.
`resolution_type`	enum	One of: Full Credit, Partial Credit, Denied, Written Off, Customer Concession. Required if Resolved.
`assigned_to`	string	Person handling the dispute on your side.
`contact_name`	string	Customer contact who raised the dispute.
`contact_email`	string	Email of customer contact.
`source`	enum	One of: Email, Phone, Portal, Deduction on Payment, Other.
`related_credit_memo_number`	string	Credit memo number if resolved via credit.
`related_deduction_id`	string	Deduction/payment reference if from short-pay.
`description`	string	Free-text description.

Getting Started

Collections

Cash Application

Payments

Deductions

Disputes

Playbooks

Resources

Technical Guides

File list

Customers

Contacts

Invoices

Invoice PDFs

Payments

Payment Allocations

Credit Memos

Credit Memo Allocations

Credit Memo PDFs

GL Accounts (Chart of Accounts)

Disputes

​File list

​Customers

​Contacts

​Invoices

​Invoice PDFs

​Payments

​Payment Allocations

​Credit Memos

​Credit Memo Allocations

​Credit Memo PDFs

​GL Accounts (Chart of Accounts)

​Disputes

File list

Customers

Contacts

Invoices

Invoice PDFs

Payments

Payment Allocations

Credit Memos

Credit Memo Allocations

Credit Memo PDFs

GL Accounts (Chart of Accounts)

Disputes