Home/Invoicing/Data Structures

Invoicing Data Structures

Field definitions for key objects returned by Invoicing APIs.

ID Format

Resources use prefixed public IDs (for example deal_..., inv_..., form_..., ak_...).

Common Fields

Core objects share common fields: `object`, `external_id`, `source_system`, `metadata`, `livemode`, `version`, `system_updated_at`, `created_by`, `updated_by`, and `deleted_at`.

Invoice object

Object representing an invoice.

Fields

Name	Type	Required	Description
id	string	Required	Invoice ID
object	string	Required	Object type (`invoice.invoice`)
organization_id	string	Required	Organization ID
external_id	string \| null	Optional	External ID
source_system	"salesforce" \| "import" \| "api" \| "manual"	Required	Source system
record_type	string	Required	Record type
company_id	string	Required	Company ID
invoice_number	string	Required	Invoice number
status	"draft" \| "sent" \| "paid" \| "overdue" \| "cancelled"	Required	Status
issue_date	string	Required	Issue date
due_date	string \| null	Optional	Due date
subtotal	number	Required	Subtotal
tax	number	Required	Tax
total	number	Required	Total
notes	string \| null	Optional	Notes
metadata	object \| null	Optional	Additional metadata
livemode	boolean	Required	Live mode flag
version	number	Required	Revision number
created_by	string \| null	Optional	Creator ID
updated_by	string \| null	Optional	Updater ID
deleted_at	string \| null	Optional	Deleted at (ISO 8601)
created_at	string	Required	Created at (ISO 8601)
system_updated_at	string	Required	System updated at (ISO 8601)
updated_at	string	Required	Updated at (ISO 8601)

{
  "id": "inv_01JQ3KXYZ",
  "object": "invoice.invoice",
  "organization_id": "org_01HZXYZ",
  "external_id": "ext_org_01HZXYZ",
  "source_system": "api",
  "record_type": "default",
  "company_id": "comp_01JQ3KABC",
  "invoice_number": "INV-2026-0042",
  "status": "sent",
  "issue_date": "2026-02-15",
  "due_date": "2026-03-15",
  "subtotal": 100000,
  "tax": 10000,
  "total": 110000,
  "notes": null,
  "metadata": {
    "source": "api"
  },
  "livemode": false,
  "version": 5,
  "created_by": "usr_99999999999999999999999999999999",
  "updated_by": "usr_99999999999999999999999999999999",
  "deleted_at": null,
  "created_at": "2026-02-15T09:00:00Z",
  "system_updated_at": "2026-02-15T09:00:00Z",
  "updated_at": "2026-02-15T09:00:00Z"
}

Quotation object

Object representing a quotation.

Fields

Name	Type	Required	Description
id	string	Required	Quotation ID
object	string	Required	Object type (`invoice.quotation`)
organization_id	string	Required	Organization ID
external_id	string \| null	Optional	External ID
source_system	"salesforce" \| "import" \| "api" \| "manual"	Required	Source system
record_type	string	Required	Record type
company_id	string	Required	Company ID
status	"draft" \| "sent" \| "accepted" \| "rejected" \| "expired"	Required	Status (draft, sent, accepted, rejected, expired)
issue_date	string	Required	Issue date
valid_until	string \| null	Optional	Valid until
subtotal	number	Required	Subtotal
tax	number	Required	Tax
total	number	Required	Total
metadata	object \| null	Optional	Additional metadata
livemode	boolean	Required	Live mode flag
version	number	Required	Revision number
created_by	string \| null	Optional	Creator ID
updated_by	string \| null	Optional	Updater ID
deleted_at	string \| null	Optional	Deleted at (ISO 8601)
created_at	string	Required	Created at (ISO 8601)
system_updated_at	string	Required	System updated at (ISO 8601)
updated_at	string	Required	Updated at (ISO 8601)

{
  "id": "quot_01JQ3KDEF",
  "object": "invoice.quotation",
  "organization_id": "org_01HZXYZ",
  "external_id": "ext_org_01HZXYZ",
  "source_system": "api",
  "record_type": "default",
  "company_id": "comp_01JQ3KABC",
  "status": "sent",
  "issue_date": "2026-02-01",
  "valid_until": "2026-03-01",
  "subtotal": 500000,
  "tax": 50000,
  "total": 550000,
  "metadata": {
    "source": "template"
  },
  "livemode": false,
  "version": 2,
  "created_by": "usr_99999999999999999999999999999999",
  "updated_by": "usr_88888888888888888888888888888888",
  "deleted_at": null,
  "created_at": "2026-02-01T10:00:00Z",
  "system_updated_at": "2026-02-01T10:00:00Z",
  "updated_at": "2026-02-01T10:00:00Z"
}

Tax Rate object

Object representing a tax rate master. Used for tax rate references in invoice line items.

Fields

Name	Type	Required	Description
id	string	Required	Tax rate ID
object	string	Required	Object type (`invoice.tax_rate`)
organization_id	string	Required	Organization ID
name	string	Required	Tax rate name (e.g. Sales Tax 10%)
rate	number	Required	Tax rate (percentage, e.g. 10.0)
category	string \| null	Optional	Tax rate category (standard / reduced / exempt)
description	string \| null	Optional	Description
effective_from	string \| null	Optional	Effective from (ISO 8601)
effective_until	string \| null	Optional	Effective until (ISO 8601)
is_default	boolean	Required	Default tax rate flag
archived	boolean	Required	Archived flag
created_at	string	Required	Created at (ISO 8601)
updated_at	string	Required	Updated at (ISO 8601)

{
  "id": "taxrate_01JQ3KXYZ",
  "object": "invoice.tax_rate",
  "organization_id": "org_01HZXYZ",
  "name": "消費税 10%",
  "rate": 10,
  "category": "standard",
  "description": "標準税率",
  "effective_from": "2019-10-01",
  "effective_until": null,
  "is_default": true,
  "archived": false,
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}