Expense

Canonical contract for persisted expense payloads.

Identity source_id, connection_id

Attributes

Field
Type
Description
id
string
Canonical ID — Backfill canonical record ID assigned after persistence. This is distinct from the source-system ID.
source_idrequiredidentity
string
Source ID — Stable external record ID from the source system. Backfill uses this with source_system and, when present, connection_id for idempotent imports and upserts.
source_systemrequired
string
Source System — Connector or provider that supplied the record, such as stripe, shopify, qbo, csv_upload, or manual.
connection_ididentity
string
Connection ID — Backfill tenant connection ID that scopes records to a specific external account, store, realm, or integration instance. It may participate in source identity without being required on every create payload.
subsidiary_id
string
Subsidiary ID — Business entity or subsidiary identifier for multi-entity accounting. Leave blank when the tenant does not use subsidiaries.
amountrequired
decimal
Amount
currencyrequired
string
Currency
tax_amount
decimal
Tax Amount
approval_status
string
Approval Status
draftpending_approvalapprovedrejectedvoid
document_date
date
Document Date — Date on the source document, such as the invoice date. Used for document-period reporting; when omitted, invoice normalization derives it from issued_at when possible.
effective_date
date
Effective Date — Accounting effective date for reporting, posting, and period cutoffs. Defaults to document_date when omitted.
expense_date
date
Expense Date
statusrequired
string
Status
category
string
Category
description
string
Description
memo
string
Memo
expense_account_id
string
Expense Account ID — Backfill account identifier for a related account record. Use account_id for lookups; account_code is display-only when referring to general ledger accounts and may be absent.
expense_account_code
string
Expense Account Code
vendor_id
string
Vendor ID — Identifier for the related vendor record.
vendor_name
string
Vendor Name
is_1099_eligible
boolean
1099 Eligible
form_1099_type
string
1099 Form Type
payment_method
string
Payment Method
payment_method_type
string
Payment Method Type
checkcredit_cardachcashwireother
payment_method_details
map
Payment Method Details
default: %{}
payment_account_id
string
Payment Account ID — Backfill account identifier for a related account record. Use account_id for lookups; account_code is display-only when referring to general ledger accounts and may be absent.
lines[]
array<object>
Lines
default: []
line_number
integer
Line Number — One-based display order of the line within the document. Use for ordering and presentation, not stable identity.
line_key
string
Line Key — Backfill-stable key for the line within this document. Use it for line-scoped extension fields or matching when no provider line_ref is available.
line_type
string
Line Type — Normalized kind of line, such as product, service, discount, tax, shipping, subtotal, or description_only. Used for rollups and posting behavior.
productservicediscounttaxshippingsubtotaldescription_only
detail
object
Line Detail — Typed line-detail payload. It normalizes selected flat line fields into item, discount, subtotal, or description_only shapes so consumers can branch on line kind without inferring from loose fields; the flat line fields remain the canonical compatibility surface.
typerequired
string
Detail Type — Line-detail variant. item covers product or service rows; discount, subtotal, and description_only represent non-item rows.
itemdiscountsubtotaldescription_only
item_id
string
Item ID
sku
string
SKU
quantity
decimal
Quantity
unit_amount
decimal
Unit Amount
account_id
string
Account ID
class_id
string
Class ID
location_id
string
Location ID
product
map
Product
discount_amount
decimal
Discount Amount
discount_percent
decimal
Discount Percent
basis_amount
decimal
Basis Amount
subtotal_amount
decimal
Subtotal Amount
metadata
map
Metadata
description
string
Description
amount
decimal
Amount
quantity
decimal
Quantity
class_id
string
Class ID — Identifier for the related class record.
location_id
string
Location ID — Identifier for the related location record.
tax_code
string
Tax Code
tax_amount
decimal
Tax Amount
taxable_amount
decimal
Taxable Amount
tax_rate
decimal
Tax Rate
tax_status
string
Tax Status
taxableexemptzero_ratedreverse_chargenot_applicable
tax_exempt_reason
string
Tax Exempt Reason
amount_includes_tax
boolean
Amount Includes Tax
tax_details[]
array<object>
Tax Details
tax_detail_refrequired
string
Tax Detail Ref
tax_name
string
Tax Name
tax_type
string
Tax Type
tax_code
string
Tax Code
jurisdiction_name
string
Jurisdiction Name
jurisdiction_code
string
Jurisdiction Code
jurisdiction_level
string
Jurisdiction Level
rate
decimal
Rate
taxable_amount
decimal
Taxable Amount
tax_amountrequired
decimal
Tax Amount
amount_includes_taxrequired
boolean
Amount Includes Tax
provider_key
string
Provider Key
provider_tax_rate_ref
string
Provider Tax Rate Ref
provider_detail_ref
string
Provider Detail Ref
taxability_reason
string
Taxability Reason
ship_to_ref
string
Ship To Ref
ship_from_ref
string
Ship From Ref
fulfillment_ref
string
Fulfillment Ref
allocation_ref
string
Allocation Ref
metadata
map
Metadata
expense_account_id
string
Expense Account ID — Backfill account identifier for a related account record. Use account_id for lookups; account_code is display-only when referring to general ledger accounts and may be absent.
expense_account_code
string
Expense Account Code
dimensions
map
Dimensions
metadata
map
Metadata
dimensions
map
Dimensions
default: %{}
metadata
map
Metadata
default: %{}

TypeScript SDK

Import

Every canonical resource is exposed as a top-level entity global on @backfill-io/sdk.

import { Expense } from "@backfill-io/sdk";

Create

Pass an object matching ExpenseCreateInput. Required fields are shown below.

const expense = Expense.create({
  source_id: "source_id_123",
  source_system: "…",
  amount: "100.00",
  currency: "USD",
  status: "open",
});

Get and query

Look up a single record by canonical ID, or query with filters and pagination.

const expense = Expense.get("expense_123");

const results = Expense.query({
  where: { },
  orderBy: [{ field: "inserted_at", direction: "desc" }],
  limit: 50,
});

Update

Partial update — pass only the fields you want to change.

Expense.update("expense_123", {
  // …fields to update
});

Delete

Expense.delete("expense_123");