API Reference

Complete reference for the Backfill HTTP API. Generated from the live OpenAPI 3.1 spec.

Base URL

https://api.backfill.ioProduction API

Authentication

Bearer Token HTTP bearer — pass token via Authorization: Bearer <token>

The Backfill HTTP API. Every operation, request body, response shape, and example.

New to the API? Start with Getting started — create a token, make your first call, and learn the response envelope. The guides cover authentication and scopes, pagination, sorting and filters, errors and retries, and the versioning policy.

Customers

GET /v1/customers

List customers

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
sort	string	Sort by a whitelisted field. Prefix with '-' for descending order, e.g. '-created_at'.
name	string	Filter by name (contains)

Responses

200 Success

Field Type Description

data required array of RecordEnvelope

Show data[] fields

Field	Type	Description
data required	object
id required	string (uuid)
object required	string

object required string

pagination required Pagination

Show pagination fields

Field	Type	Description
has_more required	boolean
limit required	integer
page required	integer
total_count required	integer

{
  "data": [
    {
      "data": {
        "address": {},
        "balance": "125.00",
        "billing_address": {},
        "category_ids": [
          "cat_1001"
        ],
        "company_name": "Acme Supplies",
        "created_at": "2026-05-05T12:00:00Z",
        "credit_limit": "1000.00",
        "currency": "USD",
        "customer_id": "cus_1001",
        "description": "Office supplies",
        "email": "jane@acme.com",
        "metadata": {},
        "name": "Acme Supplies",
        "phone": "+1 415-555-0123",
        "price_level_id": "price_level_1001",
        "sales_rep_id": "sales_rep_1001",
        "shipping_address": {},
        "tax_exempt": false,
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_exempt_status": "none",
        "tax_exemption_certificate": {},
        "tax_ids": [
          {}
        ],
        "updated_at": "2026-05-05T12:00:00Z"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "object": "customer"
    }
  ],
  "object": "list",
  "pagination": {
    "has_more": false,
    "limit": 0,
    "page": 0,
    "total_count": 0
  }
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/customers" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/customers

Create a customer

Request body required

Field	Type	Description
address	object	Address
billing_address	object	Billing Address
category_ids	array of string	Category IDs
company_name	string	Company
credit_limit	string	Credit Limit
currency	string	Currency
description	string	Description
email	string	Email
metadata	object
name required	string	Name
phone	string	Phone
price_level_id	string	Identifier for the related price level record.
sales_rep_id	string	Identifier for the related sales rep record.
shipping_address	object	Shipping Address
tax_exempt	boolean	Tax Exempt
tax_exempt_reason	string	Tax Exempt Reason
tax_exempt_status	string	Tax Exempt Status
tax_exemption_certificate	object	Tax Exemption Certificate
tax_ids	array of object	Government-issued tax identifiers for the customer, such as US EIN, SSN, or ITIN, or country-specific VAT, GST, or ABN registrations.

{
  "address": {},
  "billing_address": {},
  "category_ids": [
    "cat_1001"
  ],
  "company_name": "Acme Supplies",
  "credit_limit": "1000.00",
  "currency": "USD",
  "description": "Office supplies",
  "email": "jane@acme.com",
  "metadata": {},
  "name": "Acme Supplies",
  "phone": "+1 415-555-0123",
  "price_level_id": "price_level_1001",
  "sales_rep_id": "sales_rep_1001",
  "shipping_address": {},
  "tax_exempt": false,
  "tax_exempt_reason": "tax_exempt_reason_sample",
  "tax_exempt_status": "none",
  "tax_exemption_certificate": {},
  "tax_ids": [
    {}
  ]
}

Responses

201 Created

Field Type Description

data required CustomerRecord A customer record as returned by the API

Show data fields

Field	Type	Description
address	object	Address
balance	string	Balance
billing_address	object	Billing Address
category_ids	array of string	Category IDs
company_name	string	Company
created_at	string (date-time)
credit_limit	string	Credit Limit
currency	string	Currency
customer_id required	string	Provider-native ID for this resource. Backfill stores this as source_id on the canonical record.
description	string	Description
email	string	Email
metadata	object
name required	string	Name
phone	string	Phone
price_level_id	string	Identifier for the related price level record.
sales_rep_id	string	Identifier for the related sales rep record.
shipping_address	object	Shipping Address
tax_exempt	boolean	Tax Exempt
tax_exempt_reason	string	Tax Exempt Reason
tax_exempt_status	string	Tax Exempt Status
tax_exemption_certificate	object	Tax Exemption Certificate
tax_ids	array of object	Government-issued tax identifiers for the customer, such as US EIN, SSN, or ITIN, or country-specific VAT, GST, or ABN registrations.
updated_at	string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "address": {},
    "balance": "125.00",
    "billing_address": {},
    "category_ids": [
      "cat_1001"
    ],
    "company_name": "Acme Supplies",
    "created_at": "2026-05-05T12:00:00Z",
    "credit_limit": "1000.00",
    "currency": "USD",
    "customer_id": "cus_1001",
    "description": "Office supplies",
    "email": "jane@acme.com",
    "metadata": {},
    "name": "Acme Supplies",
    "phone": "+1 415-555-0123",
    "price_level_id": "price_level_1001",
    "sales_rep_id": "sales_rep_1001",
    "shipping_address": {},
    "tax_exempt": false,
    "tax_exempt_reason": "tax_exempt_reason_sample",
    "tax_exempt_status": "none",
    "tax_exemption_certificate": {},
    "tax_ids": [
      {}
    ],
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "customer"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/customers" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "address": {},
  "billing_address": {},
  "category_ids": [
    "cat_1001"
  ],
  "company_name": "Acme Supplies",
  "credit_limit": "1000.00",
  "currency": "USD",
  "description": "Office supplies",
  "email": "jane@acme.com",
  "metadata": {},
  "name": "Acme Supplies",
  "phone": "+1 415-555-0123",
  "price_level_id": "price_level_1001",
  "sales_rep_id": "sales_rep_1001",
  "shipping_address": {},
  "tax_exempt": false,
  "tax_exempt_reason": "tax_exempt_reason_sample",
  "tax_exempt_status": "none",
  "tax_exemption_certificate": {},
  "tax_ids": [
    {}
  ]
}'

GET /v1/customers/{id}

Get a customer

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required CustomerRecord A customer record as returned by the API

Show data fields

Field	Type	Description
address	object	Address
balance	string	Balance
billing_address	object	Billing Address
category_ids	array of string	Category IDs
company_name	string	Company
created_at	string (date-time)
credit_limit	string	Credit Limit
currency	string	Currency
customer_id required	string	Provider-native ID for this resource. Backfill stores this as source_id on the canonical record.
description	string	Description
email	string	Email
metadata	object
name required	string	Name
phone	string	Phone
price_level_id	string	Identifier for the related price level record.
sales_rep_id	string	Identifier for the related sales rep record.
shipping_address	object	Shipping Address
tax_exempt	boolean	Tax Exempt
tax_exempt_reason	string	Tax Exempt Reason
tax_exempt_status	string	Tax Exempt Status
tax_exemption_certificate	object	Tax Exemption Certificate
tax_ids	array of object	Government-issued tax identifiers for the customer, such as US EIN, SSN, or ITIN, or country-specific VAT, GST, or ABN registrations.
updated_at	string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "address": {},
    "balance": "125.00",
    "billing_address": {},
    "category_ids": [
      "cat_1001"
    ],
    "company_name": "Acme Supplies",
    "created_at": "2026-05-05T12:00:00Z",
    "credit_limit": "1000.00",
    "currency": "USD",
    "customer_id": "cus_1001",
    "description": "Office supplies",
    "email": "jane@acme.com",
    "metadata": {},
    "name": "Acme Supplies",
    "phone": "+1 415-555-0123",
    "price_level_id": "price_level_1001",
    "sales_rep_id": "sales_rep_1001",
    "shipping_address": {},
    "tax_exempt": false,
    "tax_exempt_reason": "tax_exempt_reason_sample",
    "tax_exempt_status": "none",
    "tax_exemption_certificate": {},
    "tax_ids": [
      {}
    ],
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "customer"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/customers/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

PUT /v1/customers/{id}

Update a customer

Path parameters

Name	Type	Description
id required	string	Resource identifier

Request body required

Field	Type	Description
address	object	Address
billing_address	object	Billing Address
category_ids	array of string	Category IDs
company_name	string	Company
credit_limit	string	Credit Limit
currency	string	Currency
description	string	Description
email	string	Email
metadata	object
name	string	Name
phone	string	Phone
price_level_id	string	Identifier for the related price level record.
sales_rep_id	string	Identifier for the related sales rep record.
shipping_address	object	Shipping Address
tax_exempt	boolean	Tax Exempt
tax_exempt_reason	string	Tax Exempt Reason
tax_exempt_status	string	Tax Exempt Status
tax_exemption_certificate	object	Tax Exemption Certificate
tax_ids	array of object	Government-issued tax identifiers for the customer, such as US EIN, SSN, or ITIN, or country-specific VAT, GST, or ABN registrations.

{
  "address": {},
  "billing_address": {},
  "category_ids": [
    "cat_1001"
  ],
  "company_name": "Acme Supplies",
  "credit_limit": "1000.00",
  "currency": "USD",
  "description": "Office supplies",
  "email": "jane@acme.com",
  "metadata": {},
  "name": "Acme Supplies",
  "phone": "+1 415-555-0123",
  "price_level_id": "price_level_1001",
  "sales_rep_id": "sales_rep_1001",
  "shipping_address": {},
  "tax_exempt": false,
  "tax_exempt_reason": "tax_exempt_reason_sample",
  "tax_exempt_status": "none",
  "tax_exemption_certificate": {},
  "tax_ids": [
    {}
  ]
}

Responses

200 Success

Field Type Description

data required CustomerRecord A customer record as returned by the API

Show data fields

Field	Type	Description
address	object	Address
balance	string	Balance
billing_address	object	Billing Address
category_ids	array of string	Category IDs
company_name	string	Company
created_at	string (date-time)
credit_limit	string	Credit Limit
currency	string	Currency
customer_id required	string	Provider-native ID for this resource. Backfill stores this as source_id on the canonical record.
description	string	Description
email	string	Email
metadata	object
name required	string	Name
phone	string	Phone
price_level_id	string	Identifier for the related price level record.
sales_rep_id	string	Identifier for the related sales rep record.
shipping_address	object	Shipping Address
tax_exempt	boolean	Tax Exempt
tax_exempt_reason	string	Tax Exempt Reason
tax_exempt_status	string	Tax Exempt Status
tax_exemption_certificate	object	Tax Exemption Certificate
tax_ids	array of object	Government-issued tax identifiers for the customer, such as US EIN, SSN, or ITIN, or country-specific VAT, GST, or ABN registrations.
updated_at	string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "address": {},
    "balance": "125.00",
    "billing_address": {},
    "category_ids": [
      "cat_1001"
    ],
    "company_name": "Acme Supplies",
    "created_at": "2026-05-05T12:00:00Z",
    "credit_limit": "1000.00",
    "currency": "USD",
    "customer_id": "cus_1001",
    "description": "Office supplies",
    "email": "jane@acme.com",
    "metadata": {},
    "name": "Acme Supplies",
    "phone": "+1 415-555-0123",
    "price_level_id": "price_level_1001",
    "sales_rep_id": "sales_rep_1001",
    "shipping_address": {},
    "tax_exempt": false,
    "tax_exempt_reason": "tax_exempt_reason_sample",
    "tax_exempt_status": "none",
    "tax_exemption_certificate": {},
    "tax_ids": [
      {}
    ],
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "customer"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X PUT "https://api.backfill.io/v1/customers/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "address": {},
  "billing_address": {},
  "category_ids": [
    "cat_1001"
  ],
  "company_name": "Acme Supplies",
  "credit_limit": "1000.00",
  "currency": "USD",
  "description": "Office supplies",
  "email": "jane@acme.com",
  "metadata": {},
  "name": "Acme Supplies",
  "phone": "+1 415-555-0123",
  "price_level_id": "price_level_1001",
  "sales_rep_id": "sales_rep_1001",
  "shipping_address": {},
  "tax_exempt": false,
  "tax_exempt_reason": "tax_exempt_reason_sample",
  "tax_exempt_status": "none",
  "tax_exemption_certificate": {},
  "tax_ids": [
    {}
  ]
}'

DELETE /v1/customers/{id}

Delete a customer

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Deleted

Field	Type	Description
deleted required	boolean
id required	string (uuid)
object required	string

{
  "deleted": true,
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "record"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X DELETE "https://api.backfill.io/v1/customers/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

Vendors

GET /v1/vendors

List vendors

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
sort	string	Sort by a whitelisted field. Prefix with '-' for descending order, e.g. '-created_at'.
name	string	Filter by name (contains)

Responses

200 Success

Field Type Description

data required array of RecordEnvelope

Show data[] fields

Field	Type	Description
data required	object
id required	string (uuid)
object required	string

object required string

pagination required Pagination

Show pagination fields

Field	Type	Description
has_more required	boolean
limit required	integer
page required	integer
total_count required	integer

{
  "data": [
    {
      "data": {
        "accounts_payable_account_id": "00000000-0000-0000-0000-000000000000",
        "address": {},
        "category_ids": [
          "cat_1001"
        ],
        "company_name": "Acme Supplies",
        "created_at": "2026-05-05T12:00:00Z",
        "currency": "USD",
        "default_expense_account_id": "00000000-0000-0000-0000-000000000000",
        "email": "jane@acme.com",
        "metadata": {},
        "name": "Acme Supplies",
        "phone": "+1 415-555-0123",
        "tax_ids": [
          {}
        ],
        "updated_at": "2026-05-05T12:00:00Z",
        "vendor_id": "ven_1001"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "object": "vendor"
    }
  ],
  "object": "list",
  "pagination": {
    "has_more": false,
    "limit": 0,
    "page": 0,
    "total_count": 0
  }
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/vendors" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/vendors

Create a vendor

Request body required

Field	Type	Description
accounts_payable_account_id	string (uuid)	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.
address	object	Address
category_ids	array of string	Category IDs
company_name	string	Company
currency	string	Currency
default_expense_account_id	string (uuid)	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.
email	string	Email
metadata	object
name required	string	Name
phone	string	Phone
tax_ids	array of object	Government-issued tax identifiers for the vendor, such as US EIN, SSN, or ITIN (used for 1099 reporting), or country-specific VAT, GST, or ABN registrations.

{
  "accounts_payable_account_id": "00000000-0000-0000-0000-000000000000",
  "address": {},
  "category_ids": [
    "cat_1001"
  ],
  "company_name": "Acme Supplies",
  "currency": "USD",
  "default_expense_account_id": "00000000-0000-0000-0000-000000000000",
  "email": "jane@acme.com",
  "metadata": {},
  "name": "Acme Supplies",
  "phone": "+1 415-555-0123",
  "tax_ids": [
    {}
  ]
}

Responses

201 Created

Field Type Description

data required VendorRecord A vendor record as returned by the API

Show data fields

Field	Type	Description
accounts_payable_account_id	string (uuid)	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.
address	object	Address
category_ids	array of string	Category IDs
company_name	string	Company
created_at	string (date-time)
currency	string	Currency
default_expense_account_id	string (uuid)	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.
email	string	Email
metadata	object
name required	string	Name
phone	string	Phone
tax_ids	array of object	Government-issued tax identifiers for the vendor, such as US EIN, SSN, or ITIN (used for 1099 reporting), or country-specific VAT, GST, or ABN registrations.
updated_at	string (date-time)
vendor_id required	string	Provider-native ID for this resource. Backfill stores this as source_id on the canonical record.

id required string (uuid)

object required string

{
  "data": {
    "accounts_payable_account_id": "00000000-0000-0000-0000-000000000000",
    "address": {},
    "category_ids": [
      "cat_1001"
    ],
    "company_name": "Acme Supplies",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "default_expense_account_id": "00000000-0000-0000-0000-000000000000",
    "email": "jane@acme.com",
    "metadata": {},
    "name": "Acme Supplies",
    "phone": "+1 415-555-0123",
    "tax_ids": [
      {}
    ],
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "vendor"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/vendors" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "accounts_payable_account_id": "00000000-0000-0000-0000-000000000000",
  "address": {},
  "category_ids": [
    "cat_1001"
  ],
  "company_name": "Acme Supplies",
  "currency": "USD",
  "default_expense_account_id": "00000000-0000-0000-0000-000000000000",
  "email": "jane@acme.com",
  "metadata": {},
  "name": "Acme Supplies",
  "phone": "+1 415-555-0123",
  "tax_ids": [
    {}
  ]
}'

GET /v1/vendors/{id}

Get a vendor

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required VendorRecord A vendor record as returned by the API

Show data fields

Field	Type	Description
accounts_payable_account_id	string (uuid)	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.
address	object	Address
category_ids	array of string	Category IDs
company_name	string	Company
created_at	string (date-time)
currency	string	Currency
default_expense_account_id	string (uuid)	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.
email	string	Email
metadata	object
name required	string	Name
phone	string	Phone
tax_ids	array of object	Government-issued tax identifiers for the vendor, such as US EIN, SSN, or ITIN (used for 1099 reporting), or country-specific VAT, GST, or ABN registrations.
updated_at	string (date-time)
vendor_id required	string	Provider-native ID for this resource. Backfill stores this as source_id on the canonical record.

id required string (uuid)

object required string

{
  "data": {
    "accounts_payable_account_id": "00000000-0000-0000-0000-000000000000",
    "address": {},
    "category_ids": [
      "cat_1001"
    ],
    "company_name": "Acme Supplies",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "default_expense_account_id": "00000000-0000-0000-0000-000000000000",
    "email": "jane@acme.com",
    "metadata": {},
    "name": "Acme Supplies",
    "phone": "+1 415-555-0123",
    "tax_ids": [
      {}
    ],
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "vendor"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/vendors/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

PUT /v1/vendors/{id}

Update a vendor

Path parameters

Name	Type	Description
id required	string	Resource identifier

Request body required

Field	Type	Description
accounts_payable_account_id	string (uuid)	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.
address	object	Address
category_ids	array of string	Category IDs
company_name	string	Company
currency	string	Currency
default_expense_account_id	string (uuid)	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.
email	string	Email
metadata	object
name	string	Name
phone	string	Phone
tax_ids	array of object	Government-issued tax identifiers for the vendor, such as US EIN, SSN, or ITIN (used for 1099 reporting), or country-specific VAT, GST, or ABN registrations.

{
  "accounts_payable_account_id": "00000000-0000-0000-0000-000000000000",
  "address": {},
  "category_ids": [
    "cat_1001"
  ],
  "company_name": "Acme Supplies",
  "currency": "USD",
  "default_expense_account_id": "00000000-0000-0000-0000-000000000000",
  "email": "jane@acme.com",
  "metadata": {},
  "name": "Acme Supplies",
  "phone": "+1 415-555-0123",
  "tax_ids": [
    {}
  ]
}

Responses

200 Success

Field Type Description

data required VendorRecord A vendor record as returned by the API

Show data fields

Field	Type	Description
accounts_payable_account_id	string (uuid)	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.
address	object	Address
category_ids	array of string	Category IDs
company_name	string	Company
created_at	string (date-time)
currency	string	Currency
default_expense_account_id	string (uuid)	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.
email	string	Email
metadata	object
name required	string	Name
phone	string	Phone
tax_ids	array of object	Government-issued tax identifiers for the vendor, such as US EIN, SSN, or ITIN (used for 1099 reporting), or country-specific VAT, GST, or ABN registrations.
updated_at	string (date-time)
vendor_id required	string	Provider-native ID for this resource. Backfill stores this as source_id on the canonical record.

id required string (uuid)

object required string

{
  "data": {
    "accounts_payable_account_id": "00000000-0000-0000-0000-000000000000",
    "address": {},
    "category_ids": [
      "cat_1001"
    ],
    "company_name": "Acme Supplies",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "default_expense_account_id": "00000000-0000-0000-0000-000000000000",
    "email": "jane@acme.com",
    "metadata": {},
    "name": "Acme Supplies",
    "phone": "+1 415-555-0123",
    "tax_ids": [
      {}
    ],
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "vendor"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X PUT "https://api.backfill.io/v1/vendors/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "accounts_payable_account_id": "00000000-0000-0000-0000-000000000000",
  "address": {},
  "category_ids": [
    "cat_1001"
  ],
  "company_name": "Acme Supplies",
  "currency": "USD",
  "default_expense_account_id": "00000000-0000-0000-0000-000000000000",
  "email": "jane@acme.com",
  "metadata": {},
  "name": "Acme Supplies",
  "phone": "+1 415-555-0123",
  "tax_ids": [
    {}
  ]
}'

DELETE /v1/vendors/{id}

Delete a vendor

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Deleted

Field	Type	Description
deleted required	boolean
id required	string (uuid)
object required	string

{
  "deleted": true,
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "record"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X DELETE "https://api.backfill.io/v1/vendors/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

Items

GET /v1/items

List items

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
sort	string	Sort by a whitelisted field. Prefix with '-' for descending order, e.g. '-created_at'.
name	string	Filter by name (contains)
type	string	Filter by item type

Responses

200 Success

Field Type Description

data required array of RecordEnvelope

Show data[] fields

Field	Type	Description
data required	object
id required	string (uuid)
object required	string

object required string

pagination required Pagination

Show pagination fields

Field	Type	Description
has_more required	boolean
limit required	integer
page required	integer
total_count required	integer

{
  "data": [
    {
      "data": {
        "active": false,
        "asset_account_id": "acc_1001",
        "class_id": "class_1001",
        "cogs_account_id": "acc_1001",
        "connection_id": "conn_1001",
        "created_at": "2026-05-05T12:00:00Z",
        "description": "Office supplies",
        "expense_account_id": "acc_1001",
        "is_purchased": false,
        "is_sold": false,
        "locations": [
          {
            "location_id": "loc_1001",
            "quantity_on_hand": "1",
            "reorder_point": "reorder_point_sample"
          }
        ],
        "metadata": {},
        "name": "Acme Supplies",
        "preferred_vendor_id": "ven_1001",
        "product_id": "prod_1001",
        "purchase_cost": "purchase_cost_sample",
        "quantity_on_hand": "1",
        "reorder_point": "reorder_point_sample",
        "revenue_account_id": "acc_1001",
        "sku": "SKU-1001",
        "source_system": "api",
        "subsidiary_id": "subsidiary_id_sample",
        "track_inventory": false,
        "type": "good",
        "unit_label": "unit_label_sample",
        "unit_price": "unit_price_sample",
        "updated_at": "2026-05-05T12:00:00Z"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "object": "item"
    }
  ],
  "object": "list",
  "pagination": {
    "has_more": false,
    "limit": 0,
    "page": 0,
    "total_count": 0
  }
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/items" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/items

Create an item

Request body required

Field Type Description

active boolean Active

asset_account_id string Asset Account ID

class_id string Class ID

cogs_account_id string COGS Account ID

description string Description

expense_account_id string Expense Account ID

is_purchased boolean Purchased

is_sold boolean Sold

locations array of object Locations

Show locations[] fields

Field	Type	Description
location_id	string	Location ID
quantity_on_hand	string	Quantity on Hand
reorder_point	string	Reorder Point

metadata object

name required string Name

preferred_vendor_id string Preferred Vendor ID

purchase_cost string Cost

quantity_on_hand string Qty on Hand

reorder_point string Reorder Point

revenue_account_id string Revenue Account ID

sku string SKU

subsidiary_id string Subsidiary ID

track_inventory boolean Track Inventory

type string Type

unit_label string Unit

unit_price string Price

{
  "active": false,
  "asset_account_id": "acc_1001",
  "class_id": "class_1001",
  "cogs_account_id": "acc_1001",
  "description": "Office supplies",
  "expense_account_id": "acc_1001",
  "is_purchased": false,
  "is_sold": false,
  "locations": [
    {
      "location_id": "loc_1001",
      "quantity_on_hand": "1",
      "reorder_point": "reorder_point_sample"
    }
  ],
  "metadata": {},
  "name": "Acme Supplies",
  "preferred_vendor_id": "ven_1001",
  "purchase_cost": "purchase_cost_sample",
  "quantity_on_hand": "1",
  "reorder_point": "reorder_point_sample",
  "revenue_account_id": "acc_1001",
  "sku": "SKU-1001",
  "subsidiary_id": "subsidiary_id_sample",
  "track_inventory": false,
  "type": "good",
  "unit_label": "unit_label_sample",
  "unit_price": "unit_price_sample"
}

Responses

201 Created

Field Type Description

data required ItemRecord A item record as returned by the API

Show data fields

Field Type Description

active boolean Active

asset_account_id string Asset Account ID

class_id string Class ID

cogs_account_id string COGS Account ID

connection_id string Connection ID

created_at string (date-time)

description string Description

expense_account_id string Expense Account ID

is_purchased boolean Purchased

is_sold boolean Sold

locations array of object Locations

Show locations[] fields

Field	Type	Description
location_id	string	Location ID
quantity_on_hand	string	Quantity on Hand
reorder_point	string	Reorder Point

metadata object

name required string Name

preferred_vendor_id string Preferred Vendor ID

product_id required string Product ID

purchase_cost string Cost

quantity_on_hand string Qty on Hand

reorder_point string Reorder Point

revenue_account_id string Revenue Account ID

sku string SKU

source_system string Source

subsidiary_id string Subsidiary ID

track_inventory boolean Track Inventory

type string Type

unit_label string Unit

unit_price string Price

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "active": false,
    "asset_account_id": "acc_1001",
    "class_id": "class_1001",
    "cogs_account_id": "acc_1001",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "description": "Office supplies",
    "expense_account_id": "acc_1001",
    "is_purchased": false,
    "is_sold": false,
    "locations": [
      {
        "location_id": "loc_1001",
        "quantity_on_hand": "1",
        "reorder_point": "reorder_point_sample"
      }
    ],
    "metadata": {},
    "name": "Acme Supplies",
    "preferred_vendor_id": "ven_1001",
    "product_id": "prod_1001",
    "purchase_cost": "purchase_cost_sample",
    "quantity_on_hand": "1",
    "reorder_point": "reorder_point_sample",
    "revenue_account_id": "acc_1001",
    "sku": "SKU-1001",
    "source_system": "api",
    "subsidiary_id": "subsidiary_id_sample",
    "track_inventory": false,
    "type": "good",
    "unit_label": "unit_label_sample",
    "unit_price": "unit_price_sample",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "item"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/items" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "active": false,
  "asset_account_id": "acc_1001",
  "class_id": "class_1001",
  "cogs_account_id": "acc_1001",
  "description": "Office supplies",
  "expense_account_id": "acc_1001",
  "is_purchased": false,
  "is_sold": false,
  "locations": [
    {
      "location_id": "loc_1001",
      "quantity_on_hand": "1",
      "reorder_point": "reorder_point_sample"
    }
  ],
  "metadata": {},
  "name": "Acme Supplies",
  "preferred_vendor_id": "ven_1001",
  "purchase_cost": "purchase_cost_sample",
  "quantity_on_hand": "1",
  "reorder_point": "reorder_point_sample",
  "revenue_account_id": "acc_1001",
  "sku": "SKU-1001",
  "subsidiary_id": "subsidiary_id_sample",
  "track_inventory": false,
  "type": "good",
  "unit_label": "unit_label_sample",
  "unit_price": "unit_price_sample"
}'

GET /v1/items/{id}

Get an item

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required ItemRecord A item record as returned by the API

Show data fields

Field Type Description

active boolean Active

asset_account_id string Asset Account ID

class_id string Class ID

cogs_account_id string COGS Account ID

connection_id string Connection ID

created_at string (date-time)

description string Description

expense_account_id string Expense Account ID

is_purchased boolean Purchased

is_sold boolean Sold

locations array of object Locations

Show locations[] fields

Field	Type	Description
location_id	string	Location ID
quantity_on_hand	string	Quantity on Hand
reorder_point	string	Reorder Point

metadata object

name required string Name

preferred_vendor_id string Preferred Vendor ID

product_id required string Product ID

purchase_cost string Cost

quantity_on_hand string Qty on Hand

reorder_point string Reorder Point

revenue_account_id string Revenue Account ID

sku string SKU

source_system string Source

subsidiary_id string Subsidiary ID

track_inventory boolean Track Inventory

type string Type

unit_label string Unit

unit_price string Price

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "active": false,
    "asset_account_id": "acc_1001",
    "class_id": "class_1001",
    "cogs_account_id": "acc_1001",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "description": "Office supplies",
    "expense_account_id": "acc_1001",
    "is_purchased": false,
    "is_sold": false,
    "locations": [
      {
        "location_id": "loc_1001",
        "quantity_on_hand": "1",
        "reorder_point": "reorder_point_sample"
      }
    ],
    "metadata": {},
    "name": "Acme Supplies",
    "preferred_vendor_id": "ven_1001",
    "product_id": "prod_1001",
    "purchase_cost": "purchase_cost_sample",
    "quantity_on_hand": "1",
    "reorder_point": "reorder_point_sample",
    "revenue_account_id": "acc_1001",
    "sku": "SKU-1001",
    "source_system": "api",
    "subsidiary_id": "subsidiary_id_sample",
    "track_inventory": false,
    "type": "good",
    "unit_label": "unit_label_sample",
    "unit_price": "unit_price_sample",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "item"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/items/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

PUT /v1/items/{id}

Update an item

Path parameters

Name	Type	Description
id required	string	Resource identifier

Request body required

Field Type Description

active boolean Active

asset_account_id string Asset Account ID

class_id string Class ID

cogs_account_id string COGS Account ID

description string Description

expense_account_id string Expense Account ID

is_purchased boolean Purchased

is_sold boolean Sold

locations array of object Locations

Show locations[] fields

Field	Type	Description
location_id	string	Location ID
quantity_on_hand	string	Quantity on Hand
reorder_point	string	Reorder Point

metadata object

name string Name

preferred_vendor_id string Preferred Vendor ID

purchase_cost string Cost

quantity_on_hand string Qty on Hand

reorder_point string Reorder Point

revenue_account_id string Revenue Account ID

sku string SKU

subsidiary_id string Subsidiary ID

track_inventory boolean Track Inventory

type string Type

unit_label string Unit

unit_price string Price

{
  "active": false,
  "asset_account_id": "acc_1001",
  "class_id": "class_1001",
  "cogs_account_id": "acc_1001",
  "description": "Office supplies",
  "expense_account_id": "acc_1001",
  "is_purchased": false,
  "is_sold": false,
  "locations": [
    {
      "location_id": "loc_1001",
      "quantity_on_hand": "1",
      "reorder_point": "reorder_point_sample"
    }
  ],
  "metadata": {},
  "name": "Acme Supplies",
  "preferred_vendor_id": "ven_1001",
  "purchase_cost": "purchase_cost_sample",
  "quantity_on_hand": "1",
  "reorder_point": "reorder_point_sample",
  "revenue_account_id": "acc_1001",
  "sku": "SKU-1001",
  "subsidiary_id": "subsidiary_id_sample",
  "track_inventory": false,
  "type": "good",
  "unit_label": "unit_label_sample",
  "unit_price": "unit_price_sample"
}

Responses

200 Success

Field Type Description

data required ItemRecord A item record as returned by the API

Show data fields

Field Type Description

active boolean Active

asset_account_id string Asset Account ID

class_id string Class ID

cogs_account_id string COGS Account ID

connection_id string Connection ID

created_at string (date-time)

description string Description

expense_account_id string Expense Account ID

is_purchased boolean Purchased

is_sold boolean Sold

locations array of object Locations

Show locations[] fields

Field	Type	Description
location_id	string	Location ID
quantity_on_hand	string	Quantity on Hand
reorder_point	string	Reorder Point

metadata object

name required string Name

preferred_vendor_id string Preferred Vendor ID

product_id required string Product ID

purchase_cost string Cost

quantity_on_hand string Qty on Hand

reorder_point string Reorder Point

revenue_account_id string Revenue Account ID

sku string SKU

source_system string Source

subsidiary_id string Subsidiary ID

track_inventory boolean Track Inventory

type string Type

unit_label string Unit

unit_price string Price

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "active": false,
    "asset_account_id": "acc_1001",
    "class_id": "class_1001",
    "cogs_account_id": "acc_1001",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "description": "Office supplies",
    "expense_account_id": "acc_1001",
    "is_purchased": false,
    "is_sold": false,
    "locations": [
      {
        "location_id": "loc_1001",
        "quantity_on_hand": "1",
        "reorder_point": "reorder_point_sample"
      }
    ],
    "metadata": {},
    "name": "Acme Supplies",
    "preferred_vendor_id": "ven_1001",
    "product_id": "prod_1001",
    "purchase_cost": "purchase_cost_sample",
    "quantity_on_hand": "1",
    "reorder_point": "reorder_point_sample",
    "revenue_account_id": "acc_1001",
    "sku": "SKU-1001",
    "source_system": "api",
    "subsidiary_id": "subsidiary_id_sample",
    "track_inventory": false,
    "type": "good",
    "unit_label": "unit_label_sample",
    "unit_price": "unit_price_sample",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "item"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X PUT "https://api.backfill.io/v1/items/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "active": false,
  "asset_account_id": "acc_1001",
  "class_id": "class_1001",
  "cogs_account_id": "acc_1001",
  "description": "Office supplies",
  "expense_account_id": "acc_1001",
  "is_purchased": false,
  "is_sold": false,
  "locations": [
    {
      "location_id": "loc_1001",
      "quantity_on_hand": "1",
      "reorder_point": "reorder_point_sample"
    }
  ],
  "metadata": {},
  "name": "Acme Supplies",
  "preferred_vendor_id": "ven_1001",
  "purchase_cost": "purchase_cost_sample",
  "quantity_on_hand": "1",
  "reorder_point": "reorder_point_sample",
  "revenue_account_id": "acc_1001",
  "sku": "SKU-1001",
  "subsidiary_id": "subsidiary_id_sample",
  "track_inventory": false,
  "type": "good",
  "unit_label": "unit_label_sample",
  "unit_price": "unit_price_sample"
}'

DELETE /v1/items/{id}

Delete an item

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Deleted

Field	Type	Description
deleted required	boolean
id required	string (uuid)
object required	string

{
  "deleted": true,
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "record"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X DELETE "https://api.backfill.io/v1/items/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

Accounts

GET /v1/accounts

List accounts

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
sort	string	Sort by a whitelisted field. Prefix with '-' for descending order, e.g. '-created_at'.
as_of_date	string	Balance as of date (YYYY-MM-DD)
type	string	Filter by account type
active	boolean	Filter by active status

Responses

200 Success

Field Type Description

as_of_date required string (date)

data required array of object

Show data[] fields

Field Type Description

data required object

Show data fields

Field	Type	Description
account_type required	string
balance	[string null]
code	[string null]
is_active required	boolean
name required	string
normal_balance required	string

id required string (uuid)

object required string

pagination required object

Show pagination fields

Field	Type	Description
limit required	integer
page required	integer

{
  "as_of_date": "2026-05-05",
  "data": [
    {
      "data": {
        "account_type": "asset",
        "balance": "125.00",
        "code": "VALIDATION_ERROR",
        "is_active": false,
        "name": "Acme Supplies",
        "normal_balance": "debit"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "object": "account"
    }
  ],
  "object": "list",
  "pagination": {
    "limit": 0,
    "page": 0
  }
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/accounts" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/accounts

Create an account

Request body required

Field	Type	Description
active	boolean	Active
code	string	Code
description	string	Description
name required	string	Name
parent_name	string	Parent
slot	string	Slot
sub_type	string	Sub Type
subsidiary_id	string	Business entity or subsidiary identifier for multi-entity accounting. Leave blank when the tenant does not use subsidiaries.
type required	string	Type

{
  "active": false,
  "code": "VALIDATION_ERROR",
  "description": "Office supplies",
  "name": "Acme Supplies",
  "parent_name": "Acme Supplies",
  "slot": "slot_sample",
  "sub_type": "sub_type_sample",
  "subsidiary_id": "subsidiary_id_sample",
  "type": "asset"
}

Responses

201 Created

Field Type Description

data required AccountRecord A account record as returned by the API

Show data fields

Field	Type	Description
account_id	string	Provider-native ID for this resource. Backfill stores this as source_id on the canonical record.
active	boolean	Active
code	string	Code
created_at	string (date-time)
description	string	Description
name required	string	Name
parent_name	string	Parent
slot	string	Slot
sub_type	string	Sub Type
subsidiary_id	string	Business entity or subsidiary identifier for multi-entity accounting. Leave blank when the tenant does not use subsidiaries.
type required	string	Type
updated_at	string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "account_id": "acc_1001",
    "active": false,
    "code": "VALIDATION_ERROR",
    "created_at": "2026-05-05T12:00:00Z",
    "description": "Office supplies",
    "name": "Acme Supplies",
    "parent_name": "Acme Supplies",
    "slot": "slot_sample",
    "sub_type": "sub_type_sample",
    "subsidiary_id": "subsidiary_id_sample",
    "type": "asset",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "account"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/accounts" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "active": false,
  "code": "VALIDATION_ERROR",
  "description": "Office supplies",
  "name": "Acme Supplies",
  "parent_name": "Acme Supplies",
  "slot": "slot_sample",
  "sub_type": "sub_type_sample",
  "subsidiary_id": "subsidiary_id_sample",
  "type": "asset"
}'

GET /v1/accounts/{id}

Get an account

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required object

Show data fields

Field	Type	Description
account_type required	string
balance	[string null]
code	[string null]
description	[string null]
is_active required	boolean
name required	string
normal_balance required	string

id required string (uuid)

object required string

{
  "data": {
    "account_type": "asset",
    "balance": "125.00",
    "code": "VALIDATION_ERROR",
    "description": "Office supplies",
    "is_active": false,
    "name": "Acme Supplies",
    "normal_balance": "debit"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "account"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/accounts/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

PUT /v1/accounts/{id}

Update an account

Path parameters

Name	Type	Description
id required	string	Resource identifier

Request body required

Field	Type	Description
active	boolean	Active
code	string	Code
description	string	Description
name	string	Name
parent_name	string	Parent
slot	string	Slot
sub_type	string	Sub Type
subsidiary_id	string	Business entity or subsidiary identifier for multi-entity accounting. Leave blank when the tenant does not use subsidiaries.
type	string	Type

{
  "active": false,
  "code": "VALIDATION_ERROR",
  "description": "Office supplies",
  "name": "Acme Supplies",
  "parent_name": "Acme Supplies",
  "slot": "slot_sample",
  "sub_type": "sub_type_sample",
  "subsidiary_id": "subsidiary_id_sample",
  "type": "asset"
}

Responses

200 Success

Field Type Description

data required AccountRecord A account record as returned by the API

Show data fields

Field	Type	Description
account_id	string	Provider-native ID for this resource. Backfill stores this as source_id on the canonical record.
active	boolean	Active
code	string	Code
created_at	string (date-time)
description	string	Description
name required	string	Name
parent_name	string	Parent
slot	string	Slot
sub_type	string	Sub Type
subsidiary_id	string	Business entity or subsidiary identifier for multi-entity accounting. Leave blank when the tenant does not use subsidiaries.
type required	string	Type
updated_at	string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "account_id": "acc_1001",
    "active": false,
    "code": "VALIDATION_ERROR",
    "created_at": "2026-05-05T12:00:00Z",
    "description": "Office supplies",
    "name": "Acme Supplies",
    "parent_name": "Acme Supplies",
    "slot": "slot_sample",
    "sub_type": "sub_type_sample",
    "subsidiary_id": "subsidiary_id_sample",
    "type": "asset",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "account"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X PUT "https://api.backfill.io/v1/accounts/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "active": false,
  "code": "VALIDATION_ERROR",
  "description": "Office supplies",
  "name": "Acme Supplies",
  "parent_name": "Acme Supplies",
  "slot": "slot_sample",
  "sub_type": "sub_type_sample",
  "subsidiary_id": "subsidiary_id_sample",
  "type": "asset"
}'

POST /v1/accounts/bulk

Bulk create chart of accounts entries

Request body required

Field Type Description

accounts required array of object

Show accounts[] fields

Field	Type	Description
account_id	string	Provider-native ID for this resource. Backfill stores this as source_id on the canonical record.
active	boolean	Active
code	string	Code
description	string	Description
name required	string	Name
parent_name	string	Parent
slot	string	Slot
sub_type	string	Sub Type
subsidiary_id	string	Business entity or subsidiary identifier for multi-entity accounting. Leave blank when the tenant does not use subsidiaries.
type required	string	Type

{
  "accounts": [
    {
      "account_id": "acc_1001",
      "active": false,
      "code": "VALIDATION_ERROR",
      "description": "Office supplies",
      "name": "Acme Supplies",
      "parent_name": "Acme Supplies",
      "slot": "slot_sample",
      "sub_type": "sub_type_sample",
      "subsidiary_id": "subsidiary_id_sample",
      "type": "asset"
    }
  ]
}

Responses

200 Bulk account creation result

Field Type Description

data required object

Show data fields

Field Type Description

failed required integer

processed required integer

results required array of object

Show results[] fields

Field	Type	Description
account	object
index required	integer
reason	object
status required	string

succeeded required integer

object required string

{
  "data": {
    "failed": 0,
    "processed": 0,
    "results": [
      {
        "account": {},
        "index": 0,
        "reason": {},
        "status": "success"
      }
    ],
    "succeeded": 0
  },
  "object": "bulk_result"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/accounts/bulk" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "accounts": [
    {
      "account_id": "acc_1001",
      "active": false,
      "code": "VALIDATION_ERROR",
      "description": "Office supplies",
      "name": "Acme Supplies",
      "parent_name": "Acme Supplies",
      "slot": "slot_sample",
      "sub_type": "sub_type_sample",
      "subsidiary_id": "subsidiary_id_sample",
      "type": "asset"
    }
  ]
}'

Invoices

GET /v1/invoices

List invoices

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
sort	string	Sort by a whitelisted field. Prefix with '-' for descending order, e.g. '-created_at'.
status	string	Filter by status
customer_id	string	Filter by customer ID
include	string	Comma-separated extension field tokens: extension_fields.entity, extension_fields.line

Responses

200 Success

Field Type Description

data required array of RecordEnvelope

Show data[] fields

Field	Type	Description
data required	object
id required	string (uuid)
object required	string

object required string

pagination required Pagination

Show pagination fields

Field	Type	Description
has_more required	boolean
limit required	integer
page required	integer
total_count required	integer

{
  "data": [
    {
      "data": {
        "billing_address": {},
        "connection_id": "conn_1001",
        "created_at": "2026-05-05T12:00:00Z",
        "currency": "USD",
        "customer": {
          "email": "jane@acme.com",
          "id": "00000000-0000-0000-0000-000000000000",
          "metadata": {},
          "name": "Acme Supplies"
        },
        "discount_amount": "125.00",
        "discount_details": [
          {}
        ],
        "document_date": "2026-05-05",
        "document_number": "INV-1001",
        "due_at": "2026-05-05T12:00:00Z",
        "effective_date": "2026-05-05",
        "id": "00000000-0000-0000-0000-000000000000",
        "issued_at": "2026-05-05T12:00:00Z",
        "lines": [
          {
            "account_id": "acc_1001",
            "amount": "125.00",
            "amount_includes_tax": false,
            "billing_period_end": "2026-05-05T12:00:00Z",
            "billing_period_start": "2026-05-05T12:00:00Z",
            "class_id": "class_1001",
            "currency": "USD",
            "description": "Office supplies",
            "detail": {
              "account_id": "...",
              "basis_amount": "...",
              "class_id": "...",
              "discount_amount": "...",
              "discount_percent": "...",
              "item_id": "...",
              "location_id": "...",
              "metadata": "...",
              "product": "...",
              "quantity": "...",
              "sku": "...",
              "subtotal_amount": "...",
              "type": "...",
              "unit_amount": "..."
            },
            "dimensions": {},
            "discount_amount": "125.00",
            "fulfillment_line_ref": "fulfillment_line_ref_sample",
            "line_key": "line_key_sample",
            "line_number": 0,
            "line_ref": "line_ref_sample",
            "line_type": "product",
            "location_id": "loc_1001",
            "metadata": {},
            "order_line_ref": "order_line_ref_sample",
            "product": {},
            "product_id": "prod_1001",
            "quantity": "1",
            "sku": "SKU-1001",
            "subscription_item_id": "item_1001",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_details": [
              "..."
            ],
            "tax_exempt_reason": "tax_exempt_reason_sample",
            "tax_rate": "1.00",
            "tax_status": "taxable",
            "taxable_amount": "125.00",
            "unit_amount": "125.00"
          }
        ],
        "metadata": {},
        "ship_method": "ship_method_sample",
        "shipping_address": {},
        "shipping_details": {},
        "source_id": "src_1001",
        "source_system": "api",
        "status": "draft",
        "subsidiary_id": "subsidiary_id_sample",
        "subtotal": "subtotal_sample",
        "tax_amount": "125.00",
        "tax_behavior": "inclusive",
        "total_amount": "125.00",
        "updated_at": "2026-05-05T12:00:00Z"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "object": "invoice"
    }
  ],
  "object": "list",
  "pagination": {
    "has_more": false,
    "limit": 0,
    "page": 0,
    "total_count": 0
  }
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/invoices" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/invoices

Create an invoice

Request body required

Field Type Description

billing_address object Billing Address

currency required string Currency

customer_id string Customer ID

customer_name string Customer Name

discount_details array of object Discount Details

document_number string Document Number

due_at string (date-time) Due At

issued_at string (date-time) Issued At

lines required array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount required string Amount

amount_includes_tax boolean Amount Includes Tax

billing_period_end string (date-time) Billing Period End

billing_period_start string (date-time) Billing Period Start

class_id string Class ID

currency string Currency

description required string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

fulfillment_line_ref string Fulfillment Line Ref

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

order_line_ref string Order Line Ref

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

subscription_item_id string Subscription Item ID

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

memo string Optional memo or notes

metadata object Metadata

ship_method string Ship Method

shipping_address object Shipping Address

shipping_details object Shipping Details

status string Status

tax_behavior string Tax Behavior

terms string Terms

total_amount required string Total Amount

{
  "billing_address": {},
  "currency": "USD",
  "customer_id": "cus_1001",
  "customer_name": "cus_1001",
  "discount_details": [
    {}
  ],
  "document_number": "INV-1001",
  "due_at": "2026-05-05T12:00:00Z",
  "issued_at": "2026-05-05T12:00:00Z",
  "lines": [
    {
      "account_id": "acc_1001",
      "amount": "125.00",
      "amount_includes_tax": false,
      "billing_period_end": "2026-05-05T12:00:00Z",
      "billing_period_start": "2026-05-05T12:00:00Z",
      "class_id": "class_1001",
      "currency": "USD",
      "description": "Office supplies",
      "detail": {
        "account_id": "acc_1001",
        "basis_amount": "125.00",
        "class_id": "class_1001",
        "discount_amount": "125.00",
        "discount_percent": "discount_percent_sample",
        "item_id": "item_1001",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "quantity": "1",
        "sku": "SKU-1001",
        "subtotal_amount": "125.00",
        "type": "item",
        "unit_amount": "125.00"
      },
      "dimensions": {},
      "discount_amount": "125.00",
      "fulfillment_line_ref": "fulfillment_line_ref_sample",
      "line_key": "line_key_sample",
      "line_number": 0,
      "line_ref": "line_ref_sample",
      "line_type": "product",
      "location_id": "loc_1001",
      "metadata": {},
      "order_line_ref": "order_line_ref_sample",
      "product": {},
      "product_id": "prod_1001",
      "quantity": "1",
      "sku": "SKU-1001",
      "subscription_item_id": "item_1001",
      "tax_amount": "125.00",
      "tax_code": "VALIDATION_ERROR",
      "tax_details": [
        {
          "allocation_ref": "loc_1001",
          "amount_includes_tax": false,
          "fulfillment_ref": "fulfillment_ref_sample",
          "jurisdiction_code": "VALIDATION_ERROR",
          "jurisdiction_level": "jurisdiction_level_sample",
          "jurisdiction_name": "Acme Supplies",
          "metadata": {},
          "provider_detail_ref": "provider_detail_ref_sample",
          "provider_key": "provider_key_sample",
          "provider_tax_rate_ref": "1.00",
          "rate": "1.00",
          "ship_from_ref": "ship_from_ref_sample",
          "ship_to_ref": "ship_to_ref_sample",
          "tax_amount": "125.00",
          "tax_code": "VALIDATION_ERROR",
          "tax_detail_ref": "tax_detail_ref_sample",
          "tax_name": "Acme Supplies",
          "tax_type": "tax_type_sample",
          "taxability_reason": "taxability_reason_sample",
          "taxable_amount": "125.00"
        }
      ],
      "tax_exempt_reason": "tax_exempt_reason_sample",
      "tax_rate": "1.00",
      "tax_status": "taxable",
      "taxable_amount": "125.00",
      "unit_amount": "125.00"
    }
  ],
  "memo": "Payment received",
  "metadata": {},
  "ship_method": "ship_method_sample",
  "shipping_address": {},
  "shipping_details": {},
  "status": "draft",
  "tax_behavior": "inclusive",
  "terms": "terms_sample",
  "total_amount": "125.00"
}

Responses

201 Created

Field Type Description

data required InvoiceRecord A invoice record as returned by the API

Show data fields

Field Type Description

billing_address object Billing Address

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

customer object Customer

Show customer fields

Field	Type	Description
email	string	Customer Email
id	string	Customer ID
metadata	object	Customer Metadata
name	string	Customer Name

discount_amount string Discount Amount

discount_details array of object Discount Details

document_date string (date) Document Date

document_number string Document Number

due_at string (date-time) Due At

effective_date string (date) Effective Date

id string Canonical ID

issued_at string (date-time) Issued At

lines required array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount required string Amount

amount_includes_tax boolean Amount Includes Tax

billing_period_end string (date-time) Billing Period End

billing_period_start string (date-time) Billing Period Start

class_id string Class ID

currency string Currency

description required string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

fulfillment_line_ref string Fulfillment Line Ref

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

order_line_ref string Order Line Ref

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

subscription_item_id string Subscription Item ID

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

ship_method string Ship Method

shipping_address object Shipping Address

shipping_details object Shipping Details

source_id required string Source ID

source_system required string Source System

status string Status

subsidiary_id string Subsidiary ID

subtotal string Subtotal

tax_amount string Tax Amount

tax_behavior string Tax Behavior

total_amount required string Total Amount

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "billing_address": {},
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer": {
      "email": "jane@acme.com",
      "id": "00000000-0000-0000-0000-000000000000",
      "metadata": {},
      "name": "Acme Supplies"
    },
    "discount_amount": "125.00",
    "discount_details": [
      {}
    ],
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "due_at": "2026-05-05T12:00:00Z",
    "effective_date": "2026-05-05",
    "id": "00000000-0000-0000-0000-000000000000",
    "issued_at": "2026-05-05T12:00:00Z",
    "lines": [
      {
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "billing_period_end": "2026-05-05T12:00:00Z",
        "billing_period_start": "2026-05-05T12:00:00Z",
        "class_id": "class_1001",
        "currency": "USD",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "fulfillment_line_ref": "fulfillment_line_ref_sample",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "order_line_ref": "order_line_ref_sample",
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "sku": "SKU-1001",
        "subscription_item_id": "item_1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "ship_method": "ship_method_sample",
    "shipping_address": {},
    "shipping_details": {},
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "subsidiary_id": "subsidiary_id_sample",
    "subtotal": "subtotal_sample",
    "tax_amount": "125.00",
    "tax_behavior": "inclusive",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "invoice"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/invoices" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "billing_address": {},
  "currency": "USD",
  "customer_id": "cus_1001",
  "customer_name": "cus_1001",
  "discount_details": [
    {}
  ],
  "document_number": "INV-1001",
  "due_at": "2026-05-05T12:00:00Z",
  "issued_at": "2026-05-05T12:00:00Z",
  "lines": [
    {
      "account_id": "acc_1001",
      "amount": "125.00",
      "amount_includes_tax": false,
      "billing_period_end": "2026-05-05T12:00:00Z",
      "billing_period_start": "2026-05-05T12:00:00Z",
      "class_id": "class_1001",
      "currency": "USD",
      "description": "Office supplies",
      "detail": {
        "account_id": "acc_1001",
        "basis_amount": "125.00",
        "class_id": "class_1001",
        "discount_amount": "125.00",
        "discount_percent": "discount_percent_sample",
        "item_id": "item_1001",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "quantity": "1",
        "sku": "SKU-1001",
        "subtotal_amount": "125.00",
        "type": "item",
        "unit_amount": "125.00"
      },
      "dimensions": {},
      "discount_amount": "125.00",
      "fulfillment_line_ref": "fulfillment_line_ref_sample",
      "line_key": "line_key_sample",
      "line_number": 0,
      "line_ref": "line_ref_sample",
      "line_type": "product",
      "location_id": "loc_1001",
      "metadata": {},
      "order_line_ref": "order_line_ref_sample",
      "product": {},
      "product_id": "prod_1001",
      "quantity": "1",
      "sku": "SKU-1001",
      "subscription_item_id": "item_1001",
      "tax_amount": "125.00",
      "tax_code": "VALIDATION_ERROR",
      "tax_details": [
        {
          "allocation_ref": "loc_1001",
          "amount_includes_tax": false,
          "fulfillment_ref": "fulfillment_ref_sample",
          "jurisdiction_code": "VALIDATION_ERROR",
          "jurisdiction_level": "jurisdiction_level_sample",
          "jurisdiction_name": "Acme Supplies",
          "metadata": {},
          "provider_detail_ref": "provider_detail_ref_sample",
          "provider_key": "provider_key_sample",
          "provider_tax_rate_ref": "1.00",
          "rate": "1.00",
          "ship_from_ref": "ship_from_ref_sample",
          "ship_to_ref": "ship_to_ref_sample",
          "tax_amount": "125.00",
          "tax_code": "VALIDATION_ERROR",
          "tax_detail_ref": "tax_detail_ref_sample",
          "tax_name": "Acme Supplies",
          "tax_type": "tax_type_sample",
          "taxability_reason": "taxability_reason_sample",
          "taxable_amount": "125.00"
        }
      ],
      "tax_exempt_reason": "tax_exempt_reason_sample",
      "tax_rate": "1.00",
      "tax_status": "taxable",
      "taxable_amount": "125.00",
      "unit_amount": "125.00"
    }
  ],
  "memo": "Payment received",
  "metadata": {},
  "ship_method": "ship_method_sample",
  "shipping_address": {},
  "shipping_details": {},
  "status": "draft",
  "tax_behavior": "inclusive",
  "terms": "terms_sample",
  "total_amount": "125.00"
}'

GET /v1/invoices/{id}

Get an invoice

Path parameters

Name	Type	Description
id required	string	Resource identifier

Query parameters

Name	Type	Description
include	string	Comma-separated extension field tokens: extension_fields.entity, extension_fields.line

Responses

200 Success

Field Type Description

data required InvoiceRecord A invoice record as returned by the API

Show data fields

Field Type Description

billing_address object Billing Address

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

customer object Customer

Show customer fields

Field	Type	Description
email	string	Customer Email
id	string	Customer ID
metadata	object	Customer Metadata
name	string	Customer Name

discount_amount string Discount Amount

discount_details array of object Discount Details

document_date string (date) Document Date

document_number string Document Number

due_at string (date-time) Due At

effective_date string (date) Effective Date

id string Canonical ID

issued_at string (date-time) Issued At

lines required array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount required string Amount

amount_includes_tax boolean Amount Includes Tax

billing_period_end string (date-time) Billing Period End

billing_period_start string (date-time) Billing Period Start

class_id string Class ID

currency string Currency

description required string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

fulfillment_line_ref string Fulfillment Line Ref

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

order_line_ref string Order Line Ref

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

subscription_item_id string Subscription Item ID

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

ship_method string Ship Method

shipping_address object Shipping Address

shipping_details object Shipping Details

source_id required string Source ID

source_system required string Source System

status string Status

subsidiary_id string Subsidiary ID

subtotal string Subtotal

tax_amount string Tax Amount

tax_behavior string Tax Behavior

total_amount required string Total Amount

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "billing_address": {},
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer": {
      "email": "jane@acme.com",
      "id": "00000000-0000-0000-0000-000000000000",
      "metadata": {},
      "name": "Acme Supplies"
    },
    "discount_amount": "125.00",
    "discount_details": [
      {}
    ],
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "due_at": "2026-05-05T12:00:00Z",
    "effective_date": "2026-05-05",
    "id": "00000000-0000-0000-0000-000000000000",
    "issued_at": "2026-05-05T12:00:00Z",
    "lines": [
      {
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "billing_period_end": "2026-05-05T12:00:00Z",
        "billing_period_start": "2026-05-05T12:00:00Z",
        "class_id": "class_1001",
        "currency": "USD",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "fulfillment_line_ref": "fulfillment_line_ref_sample",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "order_line_ref": "order_line_ref_sample",
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "sku": "SKU-1001",
        "subscription_item_id": "item_1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "ship_method": "ship_method_sample",
    "shipping_address": {},
    "shipping_details": {},
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "subsidiary_id": "subsidiary_id_sample",
    "subtotal": "subtotal_sample",
    "tax_amount": "125.00",
    "tax_behavior": "inclusive",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "invoice"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/invoices/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

PUT /v1/invoices/{id}

Update an invoice

Path parameters

Name	Type	Description
id required	string	Resource identifier

Request body required

Field Type Description

billing_address object Billing Address

currency string Currency

customer_id string Customer ID

customer_name string Customer Name

discount_details array of object Discount Details

document_number string Document Number

due_at string (date-time) Due At

issued_at string (date-time) Issued At

lines array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount required string Amount

amount_includes_tax boolean Amount Includes Tax

billing_period_end string (date-time) Billing Period End

billing_period_start string (date-time) Billing Period Start

class_id string Class ID

currency string Currency

description required string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

fulfillment_line_ref string Fulfillment Line Ref

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

order_line_ref string Order Line Ref

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

subscription_item_id string Subscription Item ID

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

memo string Optional memo or notes

metadata object Metadata

ship_method string Ship Method

shipping_address object Shipping Address

shipping_details object Shipping Details

status string Status

tax_behavior string Tax Behavior

terms string Terms

total_amount string Total Amount

{
  "billing_address": {},
  "currency": "USD",
  "customer_id": "cus_1001",
  "customer_name": "cus_1001",
  "discount_details": [
    {}
  ],
  "document_number": "INV-1001",
  "due_at": "2026-05-05T12:00:00Z",
  "issued_at": "2026-05-05T12:00:00Z",
  "lines": [
    {
      "account_id": "acc_1001",
      "amount": "125.00",
      "amount_includes_tax": false,
      "billing_period_end": "2026-05-05T12:00:00Z",
      "billing_period_start": "2026-05-05T12:00:00Z",
      "class_id": "class_1001",
      "currency": "USD",
      "description": "Office supplies",
      "detail": {
        "account_id": "acc_1001",
        "basis_amount": "125.00",
        "class_id": "class_1001",
        "discount_amount": "125.00",
        "discount_percent": "discount_percent_sample",
        "item_id": "item_1001",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "quantity": "1",
        "sku": "SKU-1001",
        "subtotal_amount": "125.00",
        "type": "item",
        "unit_amount": "125.00"
      },
      "dimensions": {},
      "discount_amount": "125.00",
      "fulfillment_line_ref": "fulfillment_line_ref_sample",
      "line_key": "line_key_sample",
      "line_number": 0,
      "line_ref": "line_ref_sample",
      "line_type": "product",
      "location_id": "loc_1001",
      "metadata": {},
      "order_line_ref": "order_line_ref_sample",
      "product": {},
      "product_id": "prod_1001",
      "quantity": "1",
      "sku": "SKU-1001",
      "subscription_item_id": "item_1001",
      "tax_amount": "125.00",
      "tax_code": "VALIDATION_ERROR",
      "tax_details": [
        {
          "allocation_ref": "loc_1001",
          "amount_includes_tax": false,
          "fulfillment_ref": "fulfillment_ref_sample",
          "jurisdiction_code": "VALIDATION_ERROR",
          "jurisdiction_level": "jurisdiction_level_sample",
          "jurisdiction_name": "Acme Supplies",
          "metadata": {},
          "provider_detail_ref": "provider_detail_ref_sample",
          "provider_key": "provider_key_sample",
          "provider_tax_rate_ref": "1.00",
          "rate": "1.00",
          "ship_from_ref": "ship_from_ref_sample",
          "ship_to_ref": "ship_to_ref_sample",
          "tax_amount": "125.00",
          "tax_code": "VALIDATION_ERROR",
          "tax_detail_ref": "tax_detail_ref_sample",
          "tax_name": "Acme Supplies",
          "tax_type": "tax_type_sample",
          "taxability_reason": "taxability_reason_sample",
          "taxable_amount": "125.00"
        }
      ],
      "tax_exempt_reason": "tax_exempt_reason_sample",
      "tax_rate": "1.00",
      "tax_status": "taxable",
      "taxable_amount": "125.00",
      "unit_amount": "125.00"
    }
  ],
  "memo": "Payment received",
  "metadata": {},
  "ship_method": "ship_method_sample",
  "shipping_address": {},
  "shipping_details": {},
  "status": "draft",
  "tax_behavior": "inclusive",
  "terms": "terms_sample",
  "total_amount": "125.00"
}

Responses

200 Success

Field Type Description

data required InvoiceRecord A invoice record as returned by the API

Show data fields

Field Type Description

billing_address object Billing Address

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

customer object Customer

Show customer fields

Field	Type	Description
email	string	Customer Email
id	string	Customer ID
metadata	object	Customer Metadata
name	string	Customer Name

discount_amount string Discount Amount

discount_details array of object Discount Details

document_date string (date) Document Date

document_number string Document Number

due_at string (date-time) Due At

effective_date string (date) Effective Date

id string Canonical ID

issued_at string (date-time) Issued At

lines required array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount required string Amount

amount_includes_tax boolean Amount Includes Tax

billing_period_end string (date-time) Billing Period End

billing_period_start string (date-time) Billing Period Start

class_id string Class ID

currency string Currency

description required string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

fulfillment_line_ref string Fulfillment Line Ref

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

order_line_ref string Order Line Ref

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

subscription_item_id string Subscription Item ID

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

ship_method string Ship Method

shipping_address object Shipping Address

shipping_details object Shipping Details

source_id required string Source ID

source_system required string Source System

status string Status

subsidiary_id string Subsidiary ID

subtotal string Subtotal

tax_amount string Tax Amount

tax_behavior string Tax Behavior

total_amount required string Total Amount

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "billing_address": {},
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer": {
      "email": "jane@acme.com",
      "id": "00000000-0000-0000-0000-000000000000",
      "metadata": {},
      "name": "Acme Supplies"
    },
    "discount_amount": "125.00",
    "discount_details": [
      {}
    ],
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "due_at": "2026-05-05T12:00:00Z",
    "effective_date": "2026-05-05",
    "id": "00000000-0000-0000-0000-000000000000",
    "issued_at": "2026-05-05T12:00:00Z",
    "lines": [
      {
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "billing_period_end": "2026-05-05T12:00:00Z",
        "billing_period_start": "2026-05-05T12:00:00Z",
        "class_id": "class_1001",
        "currency": "USD",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "fulfillment_line_ref": "fulfillment_line_ref_sample",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "order_line_ref": "order_line_ref_sample",
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "sku": "SKU-1001",
        "subscription_item_id": "item_1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "ship_method": "ship_method_sample",
    "shipping_address": {},
    "shipping_details": {},
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "subsidiary_id": "subsidiary_id_sample",
    "subtotal": "subtotal_sample",
    "tax_amount": "125.00",
    "tax_behavior": "inclusive",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "invoice"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X PUT "https://api.backfill.io/v1/invoices/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "billing_address": {},
  "currency": "USD",
  "customer_id": "cus_1001",
  "customer_name": "cus_1001",
  "discount_details": [
    {}
  ],
  "document_number": "INV-1001",
  "due_at": "2026-05-05T12:00:00Z",
  "issued_at": "2026-05-05T12:00:00Z",
  "lines": [
    {
      "account_id": "acc_1001",
      "amount": "125.00",
      "amount_includes_tax": false,
      "billing_period_end": "2026-05-05T12:00:00Z",
      "billing_period_start": "2026-05-05T12:00:00Z",
      "class_id": "class_1001",
      "currency": "USD",
      "description": "Office supplies",
      "detail": {
        "account_id": "acc_1001",
        "basis_amount": "125.00",
        "class_id": "class_1001",
        "discount_amount": "125.00",
        "discount_percent": "discount_percent_sample",
        "item_id": "item_1001",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "quantity": "1",
        "sku": "SKU-1001",
        "subtotal_amount": "125.00",
        "type": "item",
        "unit_amount": "125.00"
      },
      "dimensions": {},
      "discount_amount": "125.00",
      "fulfillment_line_ref": "fulfillment_line_ref_sample",
      "line_key": "line_key_sample",
      "line_number": 0,
      "line_ref": "line_ref_sample",
      "line_type": "product",
      "location_id": "loc_1001",
      "metadata": {},
      "order_line_ref": "order_line_ref_sample",
      "product": {},
      "product_id": "prod_1001",
      "quantity": "1",
      "sku": "SKU-1001",
      "subscription_item_id": "item_1001",
      "tax_amount": "125.00",
      "tax_code": "VALIDATION_ERROR",
      "tax_details": [
        {
          "allocation_ref": "loc_1001",
          "amount_includes_tax": false,
          "fulfillment_ref": "fulfillment_ref_sample",
          "jurisdiction_code": "VALIDATION_ERROR",
          "jurisdiction_level": "jurisdiction_level_sample",
          "jurisdiction_name": "Acme Supplies",
          "metadata": {},
          "provider_detail_ref": "provider_detail_ref_sample",
          "provider_key": "provider_key_sample",
          "provider_tax_rate_ref": "1.00",
          "rate": "1.00",
          "ship_from_ref": "ship_from_ref_sample",
          "ship_to_ref": "ship_to_ref_sample",
          "tax_amount": "125.00",
          "tax_code": "VALIDATION_ERROR",
          "tax_detail_ref": "tax_detail_ref_sample",
          "tax_name": "Acme Supplies",
          "tax_type": "tax_type_sample",
          "taxability_reason": "taxability_reason_sample",
          "taxable_amount": "125.00"
        }
      ],
      "tax_exempt_reason": "tax_exempt_reason_sample",
      "tax_rate": "1.00",
      "tax_status": "taxable",
      "taxable_amount": "125.00",
      "unit_amount": "125.00"
    }
  ],
  "memo": "Payment received",
  "metadata": {},
  "ship_method": "ship_method_sample",
  "shipping_address": {},
  "shipping_details": {},
  "status": "draft",
  "tax_behavior": "inclusive",
  "terms": "terms_sample",
  "total_amount": "125.00"
}'

DELETE /v1/invoices/{id}

Delete an invoice

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Deleted

Field	Type	Description
deleted required	boolean
id required	string (uuid)
object required	string

{
  "deleted": true,
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "record"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X DELETE "https://api.backfill.io/v1/invoices/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/invoices/{id}/approve

Approve a pending document

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required InvoiceRecord A invoice record as returned by the API

Show data fields

Field Type Description

billing_address object Billing Address

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

customer object Customer

Show customer fields

Field	Type	Description
email	string	Customer Email
id	string	Customer ID
metadata	object	Customer Metadata
name	string	Customer Name

discount_amount string Discount Amount

discount_details array of object Discount Details

document_date string (date) Document Date

document_number string Document Number

due_at string (date-time) Due At

effective_date string (date) Effective Date

id string Canonical ID

issued_at string (date-time) Issued At

lines required array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount required string Amount

amount_includes_tax boolean Amount Includes Tax

billing_period_end string (date-time) Billing Period End

billing_period_start string (date-time) Billing Period Start

class_id string Class ID

currency string Currency

description required string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

fulfillment_line_ref string Fulfillment Line Ref

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

order_line_ref string Order Line Ref

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

subscription_item_id string Subscription Item ID

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

ship_method string Ship Method

shipping_address object Shipping Address

shipping_details object Shipping Details

source_id required string Source ID

source_system required string Source System

status string Status

subsidiary_id string Subsidiary ID

subtotal string Subtotal

tax_amount string Tax Amount

tax_behavior string Tax Behavior

total_amount required string Total Amount

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "billing_address": {},
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer": {
      "email": "jane@acme.com",
      "id": "00000000-0000-0000-0000-000000000000",
      "metadata": {},
      "name": "Acme Supplies"
    },
    "discount_amount": "125.00",
    "discount_details": [
      {}
    ],
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "due_at": "2026-05-05T12:00:00Z",
    "effective_date": "2026-05-05",
    "id": "00000000-0000-0000-0000-000000000000",
    "issued_at": "2026-05-05T12:00:00Z",
    "lines": [
      {
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "billing_period_end": "2026-05-05T12:00:00Z",
        "billing_period_start": "2026-05-05T12:00:00Z",
        "class_id": "class_1001",
        "currency": "USD",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "fulfillment_line_ref": "fulfillment_line_ref_sample",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "order_line_ref": "order_line_ref_sample",
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "sku": "SKU-1001",
        "subscription_item_id": "item_1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "ship_method": "ship_method_sample",
    "shipping_address": {},
    "shipping_details": {},
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "subsidiary_id": "subsidiary_id_sample",
    "subtotal": "subtotal_sample",
    "tax_amount": "125.00",
    "tax_behavior": "inclusive",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "invoice"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/invoices/{id}/approve" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/invoices/{id}/confirm

Deprecated alias for marking an invoice paid

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required InvoiceRecord A invoice record as returned by the API

Show data fields

Field Type Description

billing_address object Billing Address

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

customer object Customer

Show customer fields

Field	Type	Description
email	string	Customer Email
id	string	Customer ID
metadata	object	Customer Metadata
name	string	Customer Name

discount_amount string Discount Amount

discount_details array of object Discount Details

document_date string (date) Document Date

document_number string Document Number

due_at string (date-time) Due At

effective_date string (date) Effective Date

id string Canonical ID

issued_at string (date-time) Issued At

lines required array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount required string Amount

amount_includes_tax boolean Amount Includes Tax

billing_period_end string (date-time) Billing Period End

billing_period_start string (date-time) Billing Period Start

class_id string Class ID

currency string Currency

description required string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

fulfillment_line_ref string Fulfillment Line Ref

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

order_line_ref string Order Line Ref

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

subscription_item_id string Subscription Item ID

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

ship_method string Ship Method

shipping_address object Shipping Address

shipping_details object Shipping Details

source_id required string Source ID

source_system required string Source System

status string Status

subsidiary_id string Subsidiary ID

subtotal string Subtotal

tax_amount string Tax Amount

tax_behavior string Tax Behavior

total_amount required string Total Amount

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "billing_address": {},
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer": {
      "email": "jane@acme.com",
      "id": "00000000-0000-0000-0000-000000000000",
      "metadata": {},
      "name": "Acme Supplies"
    },
    "discount_amount": "125.00",
    "discount_details": [
      {}
    ],
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "due_at": "2026-05-05T12:00:00Z",
    "effective_date": "2026-05-05",
    "id": "00000000-0000-0000-0000-000000000000",
    "issued_at": "2026-05-05T12:00:00Z",
    "lines": [
      {
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "billing_period_end": "2026-05-05T12:00:00Z",
        "billing_period_start": "2026-05-05T12:00:00Z",
        "class_id": "class_1001",
        "currency": "USD",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "fulfillment_line_ref": "fulfillment_line_ref_sample",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "order_line_ref": "order_line_ref_sample",
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "sku": "SKU-1001",
        "subscription_item_id": "item_1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "ship_method": "ship_method_sample",
    "shipping_address": {},
    "shipping_details": {},
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "subsidiary_id": "subsidiary_id_sample",
    "subtotal": "subtotal_sample",
    "tax_amount": "125.00",
    "tax_behavior": "inclusive",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "invoice"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/invoices/{id}/confirm" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/invoices/{id}/mark_paid

Mark an invoice paid

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required InvoiceRecord A invoice record as returned by the API

Show data fields

Field Type Description

billing_address object Billing Address

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

customer object Customer

Show customer fields

Field	Type	Description
email	string	Customer Email
id	string	Customer ID
metadata	object	Customer Metadata
name	string	Customer Name

discount_amount string Discount Amount

discount_details array of object Discount Details

document_date string (date) Document Date

document_number string Document Number

due_at string (date-time) Due At

effective_date string (date) Effective Date

id string Canonical ID

issued_at string (date-time) Issued At

lines required array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount required string Amount

amount_includes_tax boolean Amount Includes Tax

billing_period_end string (date-time) Billing Period End

billing_period_start string (date-time) Billing Period Start

class_id string Class ID

currency string Currency

description required string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

fulfillment_line_ref string Fulfillment Line Ref

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

order_line_ref string Order Line Ref

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

subscription_item_id string Subscription Item ID

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

ship_method string Ship Method

shipping_address object Shipping Address

shipping_details object Shipping Details

source_id required string Source ID

source_system required string Source System

status string Status

subsidiary_id string Subsidiary ID

subtotal string Subtotal

tax_amount string Tax Amount

tax_behavior string Tax Behavior

total_amount required string Total Amount

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "billing_address": {},
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer": {
      "email": "jane@acme.com",
      "id": "00000000-0000-0000-0000-000000000000",
      "metadata": {},
      "name": "Acme Supplies"
    },
    "discount_amount": "125.00",
    "discount_details": [
      {}
    ],
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "due_at": "2026-05-05T12:00:00Z",
    "effective_date": "2026-05-05",
    "id": "00000000-0000-0000-0000-000000000000",
    "issued_at": "2026-05-05T12:00:00Z",
    "lines": [
      {
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "billing_period_end": "2026-05-05T12:00:00Z",
        "billing_period_start": "2026-05-05T12:00:00Z",
        "class_id": "class_1001",
        "currency": "USD",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "fulfillment_line_ref": "fulfillment_line_ref_sample",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "order_line_ref": "order_line_ref_sample",
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "sku": "SKU-1001",
        "subscription_item_id": "item_1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "ship_method": "ship_method_sample",
    "shipping_address": {},
    "shipping_details": {},
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "subsidiary_id": "subsidiary_id_sample",
    "subtotal": "subtotal_sample",
    "tax_amount": "125.00",
    "tax_behavior": "inclusive",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "invoice"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/invoices/{id}/mark_paid" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/invoices/{id}/reject

Reject a pending document

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required InvoiceRecord A invoice record as returned by the API

Show data fields

Field Type Description

billing_address object Billing Address

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

customer object Customer

Show customer fields

Field	Type	Description
email	string	Customer Email
id	string	Customer ID
metadata	object	Customer Metadata
name	string	Customer Name

discount_amount string Discount Amount

discount_details array of object Discount Details

document_date string (date) Document Date

document_number string Document Number

due_at string (date-time) Due At

effective_date string (date) Effective Date

id string Canonical ID

issued_at string (date-time) Issued At

lines required array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount required string Amount

amount_includes_tax boolean Amount Includes Tax

billing_period_end string (date-time) Billing Period End

billing_period_start string (date-time) Billing Period Start

class_id string Class ID

currency string Currency

description required string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

fulfillment_line_ref string Fulfillment Line Ref

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

order_line_ref string Order Line Ref

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

subscription_item_id string Subscription Item ID

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

ship_method string Ship Method

shipping_address object Shipping Address

shipping_details object Shipping Details

source_id required string Source ID

source_system required string Source System

status string Status

subsidiary_id string Subsidiary ID

subtotal string Subtotal

tax_amount string Tax Amount

tax_behavior string Tax Behavior

total_amount required string Total Amount

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "billing_address": {},
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer": {
      "email": "jane@acme.com",
      "id": "00000000-0000-0000-0000-000000000000",
      "metadata": {},
      "name": "Acme Supplies"
    },
    "discount_amount": "125.00",
    "discount_details": [
      {}
    ],
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "due_at": "2026-05-05T12:00:00Z",
    "effective_date": "2026-05-05",
    "id": "00000000-0000-0000-0000-000000000000",
    "issued_at": "2026-05-05T12:00:00Z",
    "lines": [
      {
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "billing_period_end": "2026-05-05T12:00:00Z",
        "billing_period_start": "2026-05-05T12:00:00Z",
        "class_id": "class_1001",
        "currency": "USD",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "fulfillment_line_ref": "fulfillment_line_ref_sample",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "order_line_ref": "order_line_ref_sample",
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "sku": "SKU-1001",
        "subscription_item_id": "item_1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "ship_method": "ship_method_sample",
    "shipping_address": {},
    "shipping_details": {},
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "subsidiary_id": "subsidiary_id_sample",
    "subtotal": "subtotal_sample",
    "tax_amount": "125.00",
    "tax_behavior": "inclusive",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "invoice"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/invoices/{id}/reject" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/invoices/{id}/submit

Submit a document for approval

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required InvoiceRecord A invoice record as returned by the API

Show data fields

Field Type Description

billing_address object Billing Address

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

customer object Customer

Show customer fields

Field	Type	Description
email	string	Customer Email
id	string	Customer ID
metadata	object	Customer Metadata
name	string	Customer Name

discount_amount string Discount Amount

discount_details array of object Discount Details

document_date string (date) Document Date

document_number string Document Number

due_at string (date-time) Due At

effective_date string (date) Effective Date

id string Canonical ID

issued_at string (date-time) Issued At

lines required array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount required string Amount

amount_includes_tax boolean Amount Includes Tax

billing_period_end string (date-time) Billing Period End

billing_period_start string (date-time) Billing Period Start

class_id string Class ID

currency string Currency

description required string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

fulfillment_line_ref string Fulfillment Line Ref

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

order_line_ref string Order Line Ref

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

subscription_item_id string Subscription Item ID

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

ship_method string Ship Method

shipping_address object Shipping Address

shipping_details object Shipping Details

source_id required string Source ID

source_system required string Source System

status string Status

subsidiary_id string Subsidiary ID

subtotal string Subtotal

tax_amount string Tax Amount

tax_behavior string Tax Behavior

total_amount required string Total Amount

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "billing_address": {},
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer": {
      "email": "jane@acme.com",
      "id": "00000000-0000-0000-0000-000000000000",
      "metadata": {},
      "name": "Acme Supplies"
    },
    "discount_amount": "125.00",
    "discount_details": [
      {}
    ],
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "due_at": "2026-05-05T12:00:00Z",
    "effective_date": "2026-05-05",
    "id": "00000000-0000-0000-0000-000000000000",
    "issued_at": "2026-05-05T12:00:00Z",
    "lines": [
      {
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "billing_period_end": "2026-05-05T12:00:00Z",
        "billing_period_start": "2026-05-05T12:00:00Z",
        "class_id": "class_1001",
        "currency": "USD",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "fulfillment_line_ref": "fulfillment_line_ref_sample",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "order_line_ref": "order_line_ref_sample",
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "sku": "SKU-1001",
        "subscription_item_id": "item_1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "ship_method": "ship_method_sample",
    "shipping_address": {},
    "shipping_details": {},
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "subsidiary_id": "subsidiary_id_sample",
    "subtotal": "subtotal_sample",
    "tax_amount": "125.00",
    "tax_behavior": "inclusive",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "invoice"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/invoices/{id}/submit" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/invoices/{id}/void

Void a document

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required InvoiceRecord A invoice record as returned by the API

Show data fields

Field Type Description

billing_address object Billing Address

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

customer object Customer

Show customer fields

Field	Type	Description
email	string	Customer Email
id	string	Customer ID
metadata	object	Customer Metadata
name	string	Customer Name

discount_amount string Discount Amount

discount_details array of object Discount Details

document_date string (date) Document Date

document_number string Document Number

due_at string (date-time) Due At

effective_date string (date) Effective Date

id string Canonical ID

issued_at string (date-time) Issued At

lines required array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount required string Amount

amount_includes_tax boolean Amount Includes Tax

billing_period_end string (date-time) Billing Period End

billing_period_start string (date-time) Billing Period Start

class_id string Class ID

currency string Currency

description required string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

fulfillment_line_ref string Fulfillment Line Ref

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

order_line_ref string Order Line Ref

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

subscription_item_id string Subscription Item ID

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

ship_method string Ship Method

shipping_address object Shipping Address

shipping_details object Shipping Details

source_id required string Source ID

source_system required string Source System

status string Status

subsidiary_id string Subsidiary ID

subtotal string Subtotal

tax_amount string Tax Amount

tax_behavior string Tax Behavior

total_amount required string Total Amount

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "billing_address": {},
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer": {
      "email": "jane@acme.com",
      "id": "00000000-0000-0000-0000-000000000000",
      "metadata": {},
      "name": "Acme Supplies"
    },
    "discount_amount": "125.00",
    "discount_details": [
      {}
    ],
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "due_at": "2026-05-05T12:00:00Z",
    "effective_date": "2026-05-05",
    "id": "00000000-0000-0000-0000-000000000000",
    "issued_at": "2026-05-05T12:00:00Z",
    "lines": [
      {
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "billing_period_end": "2026-05-05T12:00:00Z",
        "billing_period_start": "2026-05-05T12:00:00Z",
        "class_id": "class_1001",
        "currency": "USD",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "fulfillment_line_ref": "fulfillment_line_ref_sample",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "order_line_ref": "order_line_ref_sample",
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "sku": "SKU-1001",
        "subscription_item_id": "item_1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "ship_method": "ship_method_sample",
    "shipping_address": {},
    "shipping_details": {},
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "subsidiary_id": "subsidiary_id_sample",
    "subtotal": "subtotal_sample",
    "tax_amount": "125.00",
    "tax_behavior": "inclusive",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "invoice"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/invoices/{id}/void" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

Payments

GET /v1/payments

List payments

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
sort	string	Sort by a whitelisted field. Prefix with '-' for descending order, e.g. '-created_at'.
status	string	Filter by status
invoice_id	string	Filter by invoice reference
start_date	string	Filter by occurred_at >= (YYYY-MM-DD)
end_date	string	Filter by occurred_at <= (YYYY-MM-DD)

Responses

200 Success

Field Type Description

data required array of RecordEnvelope

Show data[] fields

Field	Type	Description
data required	object
id required	string (uuid)
object required	string

object required string

pagination required Pagination

Show pagination fields

Field	Type	Description
has_more required	boolean
limit required	integer
page required	integer
total_count required	integer

{
  "data": [
    {
      "data": {
        "allocations": [
          {
            "allocated_at": "2026-05-05T12:00:00Z",
            "amount": "125.00",
            "invoice_id": "inv_1001"
          }
        ],
        "amount": "125.00",
        "connection_id": "conn_1001",
        "created_at": "2026-05-05T12:00:00Z",
        "currency": "USD",
        "customer_id": "cus_1001",
        "deposit_to_account_code": "VALIDATION_ERROR",
        "deposit_to_account_id": "acc_1001",
        "dimensions": {},
        "exchange_rate": "1.00",
        "fees": "fees_sample",
        "invoice_id": "inv_1001",
        "memo": "Payment received",
        "metadata": {},
        "net_amount": "125.00",
        "occurred_at": "2026-05-05T12:00:00Z",
        "payment_method": "pay_1001",
        "payment_method_details": {},
        "payment_method_type": "check",
        "reference_number": "REF-1001",
        "settled_at": "2026-05-05T12:00:00Z",
        "source_id": "src_1001",
        "source_system": "api",
        "status": "pending",
        "updated_at": "2026-05-05T12:00:00Z"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "object": "payment"
    }
  ],
  "object": "list",
  "pagination": {
    "has_more": false,
    "limit": 0,
    "page": 0,
    "total_count": 0
  }
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/payments" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/payments

Create a payment

Request body required

Field Type Description

allocations array of object Allocations

Show allocations[] fields

Field	Type	Description
allocated_at	string (date-time)	Allocated At
amount required	string	Amount
invoice_id required	string	Invoice ID

amount required string Amount

currency required string Currency

customer_id string Customer ID

deposit_to_account_code string Deposit Account Code

deposit_to_account_id string Deposit Account ID

dimensions object Dimensions

exchange_rate string Exchange Rate

fees string Fees

invoice_id string Invoice ID

memo string Memo

metadata object Metadata

net_amount string Net Amount

occurred_at string (date-time) Occurred At

payment_method string Payment Method

payment_method_details object Payment Method Details

payment_method_type string Payment Method Type

reference_number string Reference Number

settled_at string (date-time) Settled At

status required string Status

{
  "allocations": [
    {
      "allocated_at": "2026-05-05T12:00:00Z",
      "amount": "125.00",
      "invoice_id": "inv_1001"
    }
  ],
  "amount": "125.00",
  "currency": "USD",
  "customer_id": "cus_1001",
  "deposit_to_account_code": "VALIDATION_ERROR",
  "deposit_to_account_id": "acc_1001",
  "dimensions": {},
  "exchange_rate": "1.00",
  "fees": "fees_sample",
  "invoice_id": "inv_1001",
  "memo": "Payment received",
  "metadata": {},
  "net_amount": "125.00",
  "occurred_at": "2026-05-05T12:00:00Z",
  "payment_method": "pay_1001",
  "payment_method_details": {},
  "payment_method_type": "check",
  "reference_number": "REF-1001",
  "settled_at": "2026-05-05T12:00:00Z",
  "status": "pending"
}

Responses

201 Created

Field Type Description

data required PaymentRecord A payment record as returned by the API

Show data fields

Field Type Description

allocations array of object Allocations

Show allocations[] fields

Field	Type	Description
allocated_at	string (date-time)	Allocated At
amount required	string	Amount
invoice_id required	string	Invoice ID

amount required string Amount

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

customer_id string Customer ID

deposit_to_account_code string Deposit Account Code

deposit_to_account_id string Deposit Account ID

dimensions object Dimensions

exchange_rate string Exchange Rate

fees string Fees

invoice_id string Invoice ID

memo string Memo

metadata object Metadata

net_amount string Net Amount

occurred_at string (date-time) Occurred At

payment_method string Payment Method

payment_method_details object Payment Method Details

payment_method_type string Payment Method Type

reference_number string Reference Number

settled_at string (date-time) Settled At

source_id required string Source ID

source_system required string Source System

status required string Status

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "allocations": [
      {
        "allocated_at": "2026-05-05T12:00:00Z",
        "amount": "125.00",
        "invoice_id": "inv_1001"
      }
    ],
    "amount": "125.00",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "deposit_to_account_code": "VALIDATION_ERROR",
    "deposit_to_account_id": "acc_1001",
    "dimensions": {},
    "exchange_rate": "1.00",
    "fees": "fees_sample",
    "invoice_id": "inv_1001",
    "memo": "Payment received",
    "metadata": {},
    "net_amount": "125.00",
    "occurred_at": "2026-05-05T12:00:00Z",
    "payment_method": "pay_1001",
    "payment_method_details": {},
    "payment_method_type": "check",
    "reference_number": "REF-1001",
    "settled_at": "2026-05-05T12:00:00Z",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "pending",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "payment"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/payments" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "allocations": [
    {
      "allocated_at": "2026-05-05T12:00:00Z",
      "amount": "125.00",
      "invoice_id": "inv_1001"
    }
  ],
  "amount": "125.00",
  "currency": "USD",
  "customer_id": "cus_1001",
  "deposit_to_account_code": "VALIDATION_ERROR",
  "deposit_to_account_id": "acc_1001",
  "dimensions": {},
  "exchange_rate": "1.00",
  "fees": "fees_sample",
  "invoice_id": "inv_1001",
  "memo": "Payment received",
  "metadata": {},
  "net_amount": "125.00",
  "occurred_at": "2026-05-05T12:00:00Z",
  "payment_method": "pay_1001",
  "payment_method_details": {},
  "payment_method_type": "check",
  "reference_number": "REF-1001",
  "settled_at": "2026-05-05T12:00:00Z",
  "status": "pending"
}'

GET /v1/payments/{id}

Get a payment

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required PaymentRecord A payment record as returned by the API

Show data fields

Field Type Description

allocations array of object Allocations

Show allocations[] fields

Field	Type	Description
allocated_at	string (date-time)	Allocated At
amount required	string	Amount
invoice_id required	string	Invoice ID

amount required string Amount

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

customer_id string Customer ID

deposit_to_account_code string Deposit Account Code

deposit_to_account_id string Deposit Account ID

dimensions object Dimensions

exchange_rate string Exchange Rate

fees string Fees

invoice_id string Invoice ID

memo string Memo

metadata object Metadata

net_amount string Net Amount

occurred_at string (date-time) Occurred At

payment_method string Payment Method

payment_method_details object Payment Method Details

payment_method_type string Payment Method Type

reference_number string Reference Number

settled_at string (date-time) Settled At

source_id required string Source ID

source_system required string Source System

status required string Status

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "allocations": [
      {
        "allocated_at": "2026-05-05T12:00:00Z",
        "amount": "125.00",
        "invoice_id": "inv_1001"
      }
    ],
    "amount": "125.00",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "deposit_to_account_code": "VALIDATION_ERROR",
    "deposit_to_account_id": "acc_1001",
    "dimensions": {},
    "exchange_rate": "1.00",
    "fees": "fees_sample",
    "invoice_id": "inv_1001",
    "memo": "Payment received",
    "metadata": {},
    "net_amount": "125.00",
    "occurred_at": "2026-05-05T12:00:00Z",
    "payment_method": "pay_1001",
    "payment_method_details": {},
    "payment_method_type": "check",
    "reference_number": "REF-1001",
    "settled_at": "2026-05-05T12:00:00Z",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "pending",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "payment"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/payments/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/payments/{id}/confirm

Confirm a draft payment

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required PaymentRecord A payment record as returned by the API

Show data fields

Field Type Description

allocations array of object Allocations

Show allocations[] fields

Field	Type	Description
allocated_at	string (date-time)	Allocated At
amount required	string	Amount
invoice_id required	string	Invoice ID

amount required string Amount

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

customer_id string Customer ID

deposit_to_account_code string Deposit Account Code

deposit_to_account_id string Deposit Account ID

dimensions object Dimensions

exchange_rate string Exchange Rate

fees string Fees

invoice_id string Invoice ID

memo string Memo

metadata object Metadata

net_amount string Net Amount

occurred_at string (date-time) Occurred At

payment_method string Payment Method

payment_method_details object Payment Method Details

payment_method_type string Payment Method Type

reference_number string Reference Number

settled_at string (date-time) Settled At

source_id required string Source ID

source_system required string Source System

status required string Status

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "allocations": [
      {
        "allocated_at": "2026-05-05T12:00:00Z",
        "amount": "125.00",
        "invoice_id": "inv_1001"
      }
    ],
    "amount": "125.00",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "deposit_to_account_code": "VALIDATION_ERROR",
    "deposit_to_account_id": "acc_1001",
    "dimensions": {},
    "exchange_rate": "1.00",
    "fees": "fees_sample",
    "invoice_id": "inv_1001",
    "memo": "Payment received",
    "metadata": {},
    "net_amount": "125.00",
    "occurred_at": "2026-05-05T12:00:00Z",
    "payment_method": "pay_1001",
    "payment_method_details": {},
    "payment_method_type": "check",
    "reference_number": "REF-1001",
    "settled_at": "2026-05-05T12:00:00Z",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "pending",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "payment"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/payments/{id}/confirm" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

Sales Receipts

GET /v1/sales_receipts

List sales receipts

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
sort	string	Sort by a whitelisted field. Prefix with '-' for descending order, e.g. '-created_at'.
status	string	Filter by status
include	string	Comma-separated extension field tokens: extension_fields.entity, extension_fields.line

Responses

200 Success

Field Type Description

data required array of RecordEnvelope

Show data[] fields

Field	Type	Description
data required	object
id required	string (uuid)
object required	string

object required string

pagination required Pagination

Show pagination fields

Field	Type	Description
has_more required	boolean
limit required	integer
page required	integer
total_count required	integer

{
  "data": [
    {
      "data": {
        "approval_status": "draft",
        "connection_id": "conn_1001",
        "created_at": "2026-05-05T12:00:00Z",
        "currency": "USD",
        "customer_id": "cus_1001",
        "deposit_to_account_code": "VALIDATION_ERROR",
        "deposit_to_account_id": "acc_1001",
        "dimensions": {},
        "discount_amount": "125.00",
        "document_date": "2026-05-05",
        "document_number": "INV-1001",
        "effective_date": "2026-05-05",
        "id": "00000000-0000-0000-0000-000000000000",
        "lines": [
          {
            "account_id": "acc_1001",
            "amount": "125.00",
            "amount_includes_tax": false,
            "class_id": "class_1001",
            "currency": "USD",
            "description": "Office supplies",
            "detail": {
              "account_id": "...",
              "basis_amount": "...",
              "class_id": "...",
              "discount_amount": "...",
              "discount_percent": "...",
              "item_id": "...",
              "location_id": "...",
              "metadata": "...",
              "product": "...",
              "quantity": "...",
              "sku": "...",
              "subtotal_amount": "...",
              "type": "...",
              "unit_amount": "..."
            },
            "dimensions": {},
            "discount_amount": "125.00",
            "line_key": "line_key_sample",
            "line_number": 0,
            "line_ref": "line_ref_sample",
            "line_type": "product",
            "location_id": "loc_1001",
            "metadata": {},
            "product": {},
            "product_id": "prod_1001",
            "quantity": "1",
            "sku": "SKU-1001",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_details": [
              "..."
            ],
            "tax_exempt_reason": "tax_exempt_reason_sample",
            "tax_rate": "1.00",
            "tax_status": "taxable",
            "taxable_amount": "125.00",
            "unit_amount": "125.00"
          }
        ],
        "location_id": "loc_1001",
        "memo": "Payment received",
        "metadata": {},
        "payment_method": "pay_1001",
        "receipt_date": "2026-05-05",
        "register_id": "register_id_sample",
        "revenue_account_id": "acc_1001",
        "sales_rep_id": "sales_rep_1001",
        "ship_method": "ship_method_sample",
        "source_id": "src_1001",
        "source_system": "api",
        "status": "draft",
        "subtotal": "subtotal_sample",
        "tax_amount": "125.00",
        "total_amount": "125.00",
        "updated_at": "2026-05-05T12:00:00Z"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "object": "sales_receipt"
    }
  ],
  "object": "list",
  "pagination": {
    "has_more": false,
    "limit": 0,
    "page": 0,
    "total_count": 0
  }
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/sales_receipts" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/sales_receipts

Create a sales receipt

Request body required

Field Type Description

approval_status string Approval Status

currency required string Currency

customer_id string Customer ID

deposit_to_account_code string Deposit Account Code

deposit_to_account_id string Deposit Account ID

dimensions object Dimensions

document_date string (date) Document Date

document_number string Document Number

effective_date string (date) Effective Date

line_items array of object Lines

Show line_items[] fields

Field Type Description

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

currency string Currency

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

location_id string Location ID

memo string Memo

metadata object Metadata

payment_method string Payment Method

receipt_date string (date) Receipt Date

register_id string Register ID

revenue_account_id string Revenue Account ID

sales_rep_id string Sales Rep ID

ship_method string Ship Method

status string Status

total_amount required string Total Amount

{
  "approval_status": "draft",
  "currency": "USD",
  "customer_id": "cus_1001",
  "deposit_to_account_code": "VALIDATION_ERROR",
  "deposit_to_account_id": "acc_1001",
  "dimensions": {},
  "document_date": "2026-05-05",
  "document_number": "INV-1001",
  "effective_date": "2026-05-05",
  "line_items": [
    {
      "account_id": "acc_1001",
      "amount": "125.00",
      "amount_includes_tax": false,
      "class_id": "class_1001",
      "currency": "USD",
      "description": "Office supplies",
      "detail": {
        "account_id": "acc_1001",
        "basis_amount": "125.00",
        "class_id": "class_1001",
        "discount_amount": "125.00",
        "discount_percent": "discount_percent_sample",
        "item_id": "item_1001",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "quantity": "1",
        "sku": "SKU-1001",
        "subtotal_amount": "125.00",
        "type": "item",
        "unit_amount": "125.00"
      },
      "dimensions": {},
      "discount_amount": "125.00",
      "line_key": "line_key_sample",
      "line_number": 0,
      "line_ref": "line_ref_sample",
      "line_type": "product",
      "location_id": "loc_1001",
      "metadata": {},
      "product": {},
      "product_id": "prod_1001",
      "quantity": "1",
      "sku": "SKU-1001",
      "tax_amount": "125.00",
      "tax_code": "VALIDATION_ERROR",
      "tax_details": [
        {
          "allocation_ref": "loc_1001",
          "amount_includes_tax": false,
          "fulfillment_ref": "fulfillment_ref_sample",
          "jurisdiction_code": "VALIDATION_ERROR",
          "jurisdiction_level": "jurisdiction_level_sample",
          "jurisdiction_name": "Acme Supplies",
          "metadata": {},
          "provider_detail_ref": "provider_detail_ref_sample",
          "provider_key": "provider_key_sample",
          "provider_tax_rate_ref": "1.00",
          "rate": "1.00",
          "ship_from_ref": "ship_from_ref_sample",
          "ship_to_ref": "ship_to_ref_sample",
          "tax_amount": "125.00",
          "tax_code": "VALIDATION_ERROR",
          "tax_detail_ref": "tax_detail_ref_sample",
          "tax_name": "Acme Supplies",
          "tax_type": "tax_type_sample",
          "taxability_reason": "taxability_reason_sample",
          "taxable_amount": "125.00"
        }
      ],
      "tax_exempt_reason": "tax_exempt_reason_sample",
      "tax_rate": "1.00",
      "tax_status": "taxable",
      "taxable_amount": "125.00",
      "unit_amount": "125.00"
    }
  ],
  "location_id": "loc_1001",
  "memo": "Payment received",
  "metadata": {},
  "payment_method": "pay_1001",
  "receipt_date": "2026-05-05",
  "register_id": "register_id_sample",
  "revenue_account_id": "acc_1001",
  "sales_rep_id": "sales_rep_1001",
  "ship_method": "ship_method_sample",
  "status": "draft",
  "total_amount": "125.00"
}

Responses

201 Created

Field Type Description

data required SalesReceiptRecord A sales_receipt record as returned by the API

Show data fields

Field Type Description

approval_status string Approval Status

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

customer_id string Customer ID

deposit_to_account_code string Deposit Account Code

deposit_to_account_id string Deposit Account ID

dimensions object Dimensions

discount_amount string Discount Amount

document_date string (date) Document Date

document_number string Document Number

effective_date string (date) Effective Date

id string Canonical ID

lines array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

currency string Currency

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

location_id string Location ID

memo string Memo

metadata object Metadata

payment_method string Payment Method

receipt_date string (date) Receipt Date

register_id string Register ID

revenue_account_id string Revenue Account ID

sales_rep_id string Sales Rep ID

ship_method string Ship Method

source_id required string Source ID

source_system required string Source System

status required string Status

subtotal string Subtotal

tax_amount string Tax Amount

total_amount required string Total Amount

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "deposit_to_account_code": "VALIDATION_ERROR",
    "deposit_to_account_id": "acc_1001",
    "dimensions": {},
    "discount_amount": "125.00",
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "effective_date": "2026-05-05",
    "id": "00000000-0000-0000-0000-000000000000",
    "lines": [
      {
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "class_id": "class_1001",
        "currency": "USD",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "sku": "SKU-1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "location_id": "loc_1001",
    "memo": "Payment received",
    "metadata": {},
    "payment_method": "pay_1001",
    "receipt_date": "2026-05-05",
    "register_id": "register_id_sample",
    "revenue_account_id": "acc_1001",
    "sales_rep_id": "sales_rep_1001",
    "ship_method": "ship_method_sample",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "subtotal": "subtotal_sample",
    "tax_amount": "125.00",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "sales_receipt"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/sales_receipts" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "approval_status": "draft",
  "currency": "USD",
  "customer_id": "cus_1001",
  "deposit_to_account_code": "VALIDATION_ERROR",
  "deposit_to_account_id": "acc_1001",
  "dimensions": {},
  "document_date": "2026-05-05",
  "document_number": "INV-1001",
  "effective_date": "2026-05-05",
  "line_items": [
    {
      "account_id": "acc_1001",
      "amount": "125.00",
      "amount_includes_tax": false,
      "class_id": "class_1001",
      "currency": "USD",
      "description": "Office supplies",
      "detail": {
        "account_id": "acc_1001",
        "basis_amount": "125.00",
        "class_id": "class_1001",
        "discount_amount": "125.00",
        "discount_percent": "discount_percent_sample",
        "item_id": "item_1001",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "quantity": "1",
        "sku": "SKU-1001",
        "subtotal_amount": "125.00",
        "type": "item",
        "unit_amount": "125.00"
      },
      "dimensions": {},
      "discount_amount": "125.00",
      "line_key": "line_key_sample",
      "line_number": 0,
      "line_ref": "line_ref_sample",
      "line_type": "product",
      "location_id": "loc_1001",
      "metadata": {},
      "product": {},
      "product_id": "prod_1001",
      "quantity": "1",
      "sku": "SKU-1001",
      "tax_amount": "125.00",
      "tax_code": "VALIDATION_ERROR",
      "tax_details": [
        {
          "allocation_ref": "loc_1001",
          "amount_includes_tax": false,
          "fulfillment_ref": "fulfillment_ref_sample",
          "jurisdiction_code": "VALIDATION_ERROR",
          "jurisdiction_level": "jurisdiction_level_sample",
          "jurisdiction_name": "Acme Supplies",
          "metadata": {},
          "provider_detail_ref": "provider_detail_ref_sample",
          "provider_key": "provider_key_sample",
          "provider_tax_rate_ref": "1.00",
          "rate": "1.00",
          "ship_from_ref": "ship_from_ref_sample",
          "ship_to_ref": "ship_to_ref_sample",
          "tax_amount": "125.00",
          "tax_code": "VALIDATION_ERROR",
          "tax_detail_ref": "tax_detail_ref_sample",
          "tax_name": "Acme Supplies",
          "tax_type": "tax_type_sample",
          "taxability_reason": "taxability_reason_sample",
          "taxable_amount": "125.00"
        }
      ],
      "tax_exempt_reason": "tax_exempt_reason_sample",
      "tax_rate": "1.00",
      "tax_status": "taxable",
      "taxable_amount": "125.00",
      "unit_amount": "125.00"
    }
  ],
  "location_id": "loc_1001",
  "memo": "Payment received",
  "metadata": {},
  "payment_method": "pay_1001",
  "receipt_date": "2026-05-05",
  "register_id": "register_id_sample",
  "revenue_account_id": "acc_1001",
  "sales_rep_id": "sales_rep_1001",
  "ship_method": "ship_method_sample",
  "status": "draft",
  "total_amount": "125.00"
}'

GET /v1/sales_receipts/{id}

Get a sales receipt

Path parameters

Name	Type	Description
id required	string	Resource identifier

Query parameters

Name	Type	Description
include	string	Comma-separated extension field tokens: extension_fields.entity, extension_fields.line

Responses

200 Success

Field Type Description

data required SalesReceiptRecord A sales_receipt record as returned by the API

Show data fields

Field Type Description

approval_status string Approval Status

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

customer_id string Customer ID

deposit_to_account_code string Deposit Account Code

deposit_to_account_id string Deposit Account ID

dimensions object Dimensions

discount_amount string Discount Amount

document_date string (date) Document Date

document_number string Document Number

effective_date string (date) Effective Date

id string Canonical ID

lines array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

currency string Currency

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

location_id string Location ID

memo string Memo

metadata object Metadata

payment_method string Payment Method

receipt_date string (date) Receipt Date

register_id string Register ID

revenue_account_id string Revenue Account ID

sales_rep_id string Sales Rep ID

ship_method string Ship Method

source_id required string Source ID

source_system required string Source System

status required string Status

subtotal string Subtotal

tax_amount string Tax Amount

total_amount required string Total Amount

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "deposit_to_account_code": "VALIDATION_ERROR",
    "deposit_to_account_id": "acc_1001",
    "dimensions": {},
    "discount_amount": "125.00",
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "effective_date": "2026-05-05",
    "id": "00000000-0000-0000-0000-000000000000",
    "lines": [
      {
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "class_id": "class_1001",
        "currency": "USD",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "sku": "SKU-1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "location_id": "loc_1001",
    "memo": "Payment received",
    "metadata": {},
    "payment_method": "pay_1001",
    "receipt_date": "2026-05-05",
    "register_id": "register_id_sample",
    "revenue_account_id": "acc_1001",
    "sales_rep_id": "sales_rep_1001",
    "ship_method": "ship_method_sample",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "subtotal": "subtotal_sample",
    "tax_amount": "125.00",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "sales_receipt"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/sales_receipts/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

PUT /v1/sales_receipts/{id}

Update a sales receipt

Path parameters

Name	Type	Description
id required	string	Resource identifier

Request body required

Field Type Description

approval_status string Approval Status

currency string Currency

customer_id string Customer ID

deposit_to_account_code string Deposit Account Code

deposit_to_account_id string Deposit Account ID

dimensions object Dimensions

document_date string (date) Document Date

document_number string Document Number

effective_date string (date) Effective Date

line_items array of object Lines

Show line_items[] fields

Field Type Description

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

currency string Currency

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

location_id string Location ID

memo string Memo

metadata object Metadata

payment_method string Payment Method

receipt_date string (date) Receipt Date

register_id string Register ID

revenue_account_id string Revenue Account ID

sales_rep_id string Sales Rep ID

ship_method string Ship Method

status string Status

total_amount string Total Amount

{
  "approval_status": "draft",
  "currency": "USD",
  "customer_id": "cus_1001",
  "deposit_to_account_code": "VALIDATION_ERROR",
  "deposit_to_account_id": "acc_1001",
  "dimensions": {},
  "document_date": "2026-05-05",
  "document_number": "INV-1001",
  "effective_date": "2026-05-05",
  "line_items": [
    {
      "account_id": "acc_1001",
      "amount": "125.00",
      "amount_includes_tax": false,
      "class_id": "class_1001",
      "currency": "USD",
      "description": "Office supplies",
      "detail": {
        "account_id": "acc_1001",
        "basis_amount": "125.00",
        "class_id": "class_1001",
        "discount_amount": "125.00",
        "discount_percent": "discount_percent_sample",
        "item_id": "item_1001",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "quantity": "1",
        "sku": "SKU-1001",
        "subtotal_amount": "125.00",
        "type": "item",
        "unit_amount": "125.00"
      },
      "dimensions": {},
      "discount_amount": "125.00",
      "line_key": "line_key_sample",
      "line_number": 0,
      "line_ref": "line_ref_sample",
      "line_type": "product",
      "location_id": "loc_1001",
      "metadata": {},
      "product": {},
      "product_id": "prod_1001",
      "quantity": "1",
      "sku": "SKU-1001",
      "tax_amount": "125.00",
      "tax_code": "VALIDATION_ERROR",
      "tax_details": [
        {
          "allocation_ref": "loc_1001",
          "amount_includes_tax": false,
          "fulfillment_ref": "fulfillment_ref_sample",
          "jurisdiction_code": "VALIDATION_ERROR",
          "jurisdiction_level": "jurisdiction_level_sample",
          "jurisdiction_name": "Acme Supplies",
          "metadata": {},
          "provider_detail_ref": "provider_detail_ref_sample",
          "provider_key": "provider_key_sample",
          "provider_tax_rate_ref": "1.00",
          "rate": "1.00",
          "ship_from_ref": "ship_from_ref_sample",
          "ship_to_ref": "ship_to_ref_sample",
          "tax_amount": "125.00",
          "tax_code": "VALIDATION_ERROR",
          "tax_detail_ref": "tax_detail_ref_sample",
          "tax_name": "Acme Supplies",
          "tax_type": "tax_type_sample",
          "taxability_reason": "taxability_reason_sample",
          "taxable_amount": "125.00"
        }
      ],
      "tax_exempt_reason": "tax_exempt_reason_sample",
      "tax_rate": "1.00",
      "tax_status": "taxable",
      "taxable_amount": "125.00",
      "unit_amount": "125.00"
    }
  ],
  "location_id": "loc_1001",
  "memo": "Payment received",
  "metadata": {},
  "payment_method": "pay_1001",
  "receipt_date": "2026-05-05",
  "register_id": "register_id_sample",
  "revenue_account_id": "acc_1001",
  "sales_rep_id": "sales_rep_1001",
  "ship_method": "ship_method_sample",
  "status": "draft",
  "total_amount": "125.00"
}

Responses

200 Success

Field Type Description

data required SalesReceiptRecord A sales_receipt record as returned by the API

Show data fields

Field Type Description

approval_status string Approval Status

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

customer_id string Customer ID

deposit_to_account_code string Deposit Account Code

deposit_to_account_id string Deposit Account ID

dimensions object Dimensions

discount_amount string Discount Amount

document_date string (date) Document Date

document_number string Document Number

effective_date string (date) Effective Date

id string Canonical ID

lines array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

currency string Currency

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

location_id string Location ID

memo string Memo

metadata object Metadata

payment_method string Payment Method

receipt_date string (date) Receipt Date

register_id string Register ID

revenue_account_id string Revenue Account ID

sales_rep_id string Sales Rep ID

ship_method string Ship Method

source_id required string Source ID

source_system required string Source System

status required string Status

subtotal string Subtotal

tax_amount string Tax Amount

total_amount required string Total Amount

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "deposit_to_account_code": "VALIDATION_ERROR",
    "deposit_to_account_id": "acc_1001",
    "dimensions": {},
    "discount_amount": "125.00",
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "effective_date": "2026-05-05",
    "id": "00000000-0000-0000-0000-000000000000",
    "lines": [
      {
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "class_id": "class_1001",
        "currency": "USD",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "sku": "SKU-1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "location_id": "loc_1001",
    "memo": "Payment received",
    "metadata": {},
    "payment_method": "pay_1001",
    "receipt_date": "2026-05-05",
    "register_id": "register_id_sample",
    "revenue_account_id": "acc_1001",
    "sales_rep_id": "sales_rep_1001",
    "ship_method": "ship_method_sample",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "subtotal": "subtotal_sample",
    "tax_amount": "125.00",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "sales_receipt"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X PUT "https://api.backfill.io/v1/sales_receipts/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "approval_status": "draft",
  "currency": "USD",
  "customer_id": "cus_1001",
  "deposit_to_account_code": "VALIDATION_ERROR",
  "deposit_to_account_id": "acc_1001",
  "dimensions": {},
  "document_date": "2026-05-05",
  "document_number": "INV-1001",
  "effective_date": "2026-05-05",
  "line_items": [
    {
      "account_id": "acc_1001",
      "amount": "125.00",
      "amount_includes_tax": false,
      "class_id": "class_1001",
      "currency": "USD",
      "description": "Office supplies",
      "detail": {
        "account_id": "acc_1001",
        "basis_amount": "125.00",
        "class_id": "class_1001",
        "discount_amount": "125.00",
        "discount_percent": "discount_percent_sample",
        "item_id": "item_1001",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "quantity": "1",
        "sku": "SKU-1001",
        "subtotal_amount": "125.00",
        "type": "item",
        "unit_amount": "125.00"
      },
      "dimensions": {},
      "discount_amount": "125.00",
      "line_key": "line_key_sample",
      "line_number": 0,
      "line_ref": "line_ref_sample",
      "line_type": "product",
      "location_id": "loc_1001",
      "metadata": {},
      "product": {},
      "product_id": "prod_1001",
      "quantity": "1",
      "sku": "SKU-1001",
      "tax_amount": "125.00",
      "tax_code": "VALIDATION_ERROR",
      "tax_details": [
        {
          "allocation_ref": "loc_1001",
          "amount_includes_tax": false,
          "fulfillment_ref": "fulfillment_ref_sample",
          "jurisdiction_code": "VALIDATION_ERROR",
          "jurisdiction_level": "jurisdiction_level_sample",
          "jurisdiction_name": "Acme Supplies",
          "metadata": {},
          "provider_detail_ref": "provider_detail_ref_sample",
          "provider_key": "provider_key_sample",
          "provider_tax_rate_ref": "1.00",
          "rate": "1.00",
          "ship_from_ref": "ship_from_ref_sample",
          "ship_to_ref": "ship_to_ref_sample",
          "tax_amount": "125.00",
          "tax_code": "VALIDATION_ERROR",
          "tax_detail_ref": "tax_detail_ref_sample",
          "tax_name": "Acme Supplies",
          "tax_type": "tax_type_sample",
          "taxability_reason": "taxability_reason_sample",
          "taxable_amount": "125.00"
        }
      ],
      "tax_exempt_reason": "tax_exempt_reason_sample",
      "tax_rate": "1.00",
      "tax_status": "taxable",
      "taxable_amount": "125.00",
      "unit_amount": "125.00"
    }
  ],
  "location_id": "loc_1001",
  "memo": "Payment received",
  "metadata": {},
  "payment_method": "pay_1001",
  "receipt_date": "2026-05-05",
  "register_id": "register_id_sample",
  "revenue_account_id": "acc_1001",
  "sales_rep_id": "sales_rep_1001",
  "ship_method": "ship_method_sample",
  "status": "draft",
  "total_amount": "125.00"
}'

DELETE /v1/sales_receipts/{id}

Delete a sales receipt

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Deleted

Field	Type	Description
deleted required	boolean
id required	string (uuid)
object required	string

{
  "deleted": true,
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "record"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X DELETE "https://api.backfill.io/v1/sales_receipts/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/sales_receipts/{id}/approve

Approve a pending document

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required SalesReceiptRecord A sales_receipt record as returned by the API

Show data fields

Field Type Description

approval_status string Approval Status

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

customer_id string Customer ID

deposit_to_account_code string Deposit Account Code

deposit_to_account_id string Deposit Account ID

dimensions object Dimensions

discount_amount string Discount Amount

document_date string (date) Document Date

document_number string Document Number

effective_date string (date) Effective Date

id string Canonical ID

lines array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

currency string Currency

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

location_id string Location ID

memo string Memo

metadata object Metadata

payment_method string Payment Method

receipt_date string (date) Receipt Date

register_id string Register ID

revenue_account_id string Revenue Account ID

sales_rep_id string Sales Rep ID

ship_method string Ship Method

source_id required string Source ID

source_system required string Source System

status required string Status

subtotal string Subtotal

tax_amount string Tax Amount

total_amount required string Total Amount

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "deposit_to_account_code": "VALIDATION_ERROR",
    "deposit_to_account_id": "acc_1001",
    "dimensions": {},
    "discount_amount": "125.00",
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "effective_date": "2026-05-05",
    "id": "00000000-0000-0000-0000-000000000000",
    "lines": [
      {
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "class_id": "class_1001",
        "currency": "USD",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "sku": "SKU-1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "location_id": "loc_1001",
    "memo": "Payment received",
    "metadata": {},
    "payment_method": "pay_1001",
    "receipt_date": "2026-05-05",
    "register_id": "register_id_sample",
    "revenue_account_id": "acc_1001",
    "sales_rep_id": "sales_rep_1001",
    "ship_method": "ship_method_sample",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "subtotal": "subtotal_sample",
    "tax_amount": "125.00",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "sales_receipt"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/sales_receipts/{id}/approve" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/sales_receipts/{id}/reject

Reject a pending document

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required SalesReceiptRecord A sales_receipt record as returned by the API

Show data fields

Field Type Description

approval_status string Approval Status

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

customer_id string Customer ID

deposit_to_account_code string Deposit Account Code

deposit_to_account_id string Deposit Account ID

dimensions object Dimensions

discount_amount string Discount Amount

document_date string (date) Document Date

document_number string Document Number

effective_date string (date) Effective Date

id string Canonical ID

lines array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

currency string Currency

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

location_id string Location ID

memo string Memo

metadata object Metadata

payment_method string Payment Method

receipt_date string (date) Receipt Date

register_id string Register ID

revenue_account_id string Revenue Account ID

sales_rep_id string Sales Rep ID

ship_method string Ship Method

source_id required string Source ID

source_system required string Source System

status required string Status

subtotal string Subtotal

tax_amount string Tax Amount

total_amount required string Total Amount

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "deposit_to_account_code": "VALIDATION_ERROR",
    "deposit_to_account_id": "acc_1001",
    "dimensions": {},
    "discount_amount": "125.00",
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "effective_date": "2026-05-05",
    "id": "00000000-0000-0000-0000-000000000000",
    "lines": [
      {
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "class_id": "class_1001",
        "currency": "USD",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "sku": "SKU-1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "location_id": "loc_1001",
    "memo": "Payment received",
    "metadata": {},
    "payment_method": "pay_1001",
    "receipt_date": "2026-05-05",
    "register_id": "register_id_sample",
    "revenue_account_id": "acc_1001",
    "sales_rep_id": "sales_rep_1001",
    "ship_method": "ship_method_sample",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "subtotal": "subtotal_sample",
    "tax_amount": "125.00",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "sales_receipt"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/sales_receipts/{id}/reject" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/sales_receipts/{id}/submit

Submit a document for approval

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required SalesReceiptRecord A sales_receipt record as returned by the API

Show data fields

Field Type Description

approval_status string Approval Status

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

customer_id string Customer ID

deposit_to_account_code string Deposit Account Code

deposit_to_account_id string Deposit Account ID

dimensions object Dimensions

discount_amount string Discount Amount

document_date string (date) Document Date

document_number string Document Number

effective_date string (date) Effective Date

id string Canonical ID

lines array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

currency string Currency

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

location_id string Location ID

memo string Memo

metadata object Metadata

payment_method string Payment Method

receipt_date string (date) Receipt Date

register_id string Register ID

revenue_account_id string Revenue Account ID

sales_rep_id string Sales Rep ID

ship_method string Ship Method

source_id required string Source ID

source_system required string Source System

status required string Status

subtotal string Subtotal

tax_amount string Tax Amount

total_amount required string Total Amount

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "deposit_to_account_code": "VALIDATION_ERROR",
    "deposit_to_account_id": "acc_1001",
    "dimensions": {},
    "discount_amount": "125.00",
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "effective_date": "2026-05-05",
    "id": "00000000-0000-0000-0000-000000000000",
    "lines": [
      {
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "class_id": "class_1001",
        "currency": "USD",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "sku": "SKU-1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "location_id": "loc_1001",
    "memo": "Payment received",
    "metadata": {},
    "payment_method": "pay_1001",
    "receipt_date": "2026-05-05",
    "register_id": "register_id_sample",
    "revenue_account_id": "acc_1001",
    "sales_rep_id": "sales_rep_1001",
    "ship_method": "ship_method_sample",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "subtotal": "subtotal_sample",
    "tax_amount": "125.00",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "sales_receipt"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/sales_receipts/{id}/submit" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/sales_receipts/{id}/void

Void a document

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required SalesReceiptRecord A sales_receipt record as returned by the API

Show data fields

Field Type Description

approval_status string Approval Status

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

customer_id string Customer ID

deposit_to_account_code string Deposit Account Code

deposit_to_account_id string Deposit Account ID

dimensions object Dimensions

discount_amount string Discount Amount

document_date string (date) Document Date

document_number string Document Number

effective_date string (date) Effective Date

id string Canonical ID

lines array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

currency string Currency

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

location_id string Location ID

memo string Memo

metadata object Metadata

payment_method string Payment Method

receipt_date string (date) Receipt Date

register_id string Register ID

revenue_account_id string Revenue Account ID

sales_rep_id string Sales Rep ID

ship_method string Ship Method

source_id required string Source ID

source_system required string Source System

status required string Status

subtotal string Subtotal

tax_amount string Tax Amount

total_amount required string Total Amount

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "deposit_to_account_code": "VALIDATION_ERROR",
    "deposit_to_account_id": "acc_1001",
    "dimensions": {},
    "discount_amount": "125.00",
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "effective_date": "2026-05-05",
    "id": "00000000-0000-0000-0000-000000000000",
    "lines": [
      {
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "class_id": "class_1001",
        "currency": "USD",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "sku": "SKU-1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "location_id": "loc_1001",
    "memo": "Payment received",
    "metadata": {},
    "payment_method": "pay_1001",
    "receipt_date": "2026-05-05",
    "register_id": "register_id_sample",
    "revenue_account_id": "acc_1001",
    "sales_rep_id": "sales_rep_1001",
    "ship_method": "ship_method_sample",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "subtotal": "subtotal_sample",
    "tax_amount": "125.00",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "sales_receipt"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/sales_receipts/{id}/void" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

Credit Memos

GET /v1/credit_memos

List credit memos

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
sort	string	Sort by a whitelisted field. Prefix with '-' for descending order, e.g. '-created_at'.
status	string	Filter by application status
approval_status	string	Filter by approval status
include	string	Comma-separated extension field tokens: extension_fields.entity, extension_fields.line

Responses

200 Success

Field Type Description

data required array of RecordEnvelope

Show data[] fields

Field	Type	Description
data required	object
id required	string (uuid)
object required	string

object required string

pagination required Pagination

Show pagination fields

Field	Type	Description
has_more required	boolean
limit required	integer
page required	integer
total_count required	integer

{
  "data": [
    {
      "data": {
        "applied_at": "2026-05-05T12:00:00Z",
        "approval_status": "draft",
        "connection_id": "conn_1001",
        "created_at": "2026-05-05T12:00:00Z",
        "currency": "USD",
        "customer_id": "cus_1001",
        "dimensions": {},
        "document_date": "2026-05-05",
        "document_number": "INV-1001",
        "effective_date": "2026-05-05",
        "id": "00000000-0000-0000-0000-000000000000",
        "invoice_id": "inv_1001",
        "issued_at": "2026-05-05T12:00:00Z",
        "lines": [
          {
            "account_id": "acc_1001",
            "amount": "125.00",
            "amount_includes_tax": false,
            "class_id": "class_1001",
            "currency": "USD",
            "description": "Office supplies",
            "detail": {
              "account_id": "...",
              "basis_amount": "...",
              "class_id": "...",
              "discount_amount": "...",
              "discount_percent": "...",
              "item_id": "...",
              "location_id": "...",
              "metadata": "...",
              "product": "...",
              "quantity": "...",
              "sku": "...",
              "subtotal_amount": "...",
              "type": "...",
              "unit_amount": "..."
            },
            "dimensions": {},
            "discount_amount": "125.00",
            "invoice_line_ref": "inv_1001",
            "line_key": "line_key_sample",
            "line_number": 0,
            "line_ref": "line_ref_sample",
            "line_type": "product",
            "location_id": "loc_1001",
            "metadata": {},
            "product": {},
            "product_id": "prod_1001",
            "quantity": "1",
            "reason_code": "VALIDATION_ERROR",
            "return_quantity": "1",
            "sku": "SKU-1001",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_details": [
              "..."
            ],
            "tax_exempt_reason": "tax_exempt_reason_sample",
            "tax_rate": "1.00",
            "tax_status": "taxable",
            "taxable_amount": "125.00",
            "unit_amount": "125.00"
          }
        ],
        "metadata": {},
        "reason_code": "VALIDATION_ERROR",
        "refunded_at": "2026-05-05T12:00:00Z",
        "source_id": "src_1001",
        "source_system": "api",
        "status": "open",
        "total_amount": "125.00",
        "updated_at": "2026-05-05T12:00:00Z"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "object": "credit_memo"
    }
  ],
  "object": "list",
  "pagination": {
    "has_more": false,
    "limit": 0,
    "page": 0,
    "total_count": 0
  }
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/credit_memos" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/credit_memos

Create a credit memo

Request body required

Field Type Description

approval_status string Approval Status

currency required string Currency

customer_id string Customer ID

dimensions object Dimensions

document_date string (date) Document Date

document_number string Document Number

effective_date string (date) Effective Date

invoice_id string Invoice ID

issued_at string (date-time) Issued At

lines array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

currency string Currency

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

invoice_line_ref string Invoice Line Ref

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

reason_code string Reason Code

return_quantity string Return Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

reason_code string Reason Code

status required string Status

total_amount required string Total Amount

{
  "approval_status": "draft",
  "currency": "USD",
  "customer_id": "cus_1001",
  "dimensions": {},
  "document_date": "2026-05-05",
  "document_number": "INV-1001",
  "effective_date": "2026-05-05",
  "invoice_id": "inv_1001",
  "issued_at": "2026-05-05T12:00:00Z",
  "lines": [
    {
      "account_id": "acc_1001",
      "amount": "125.00",
      "amount_includes_tax": false,
      "class_id": "class_1001",
      "currency": "USD",
      "description": "Office supplies",
      "detail": {
        "account_id": "acc_1001",
        "basis_amount": "125.00",
        "class_id": "class_1001",
        "discount_amount": "125.00",
        "discount_percent": "discount_percent_sample",
        "item_id": "item_1001",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "quantity": "1",
        "sku": "SKU-1001",
        "subtotal_amount": "125.00",
        "type": "item",
        "unit_amount": "125.00"
      },
      "dimensions": {},
      "discount_amount": "125.00",
      "invoice_line_ref": "inv_1001",
      "line_key": "line_key_sample",
      "line_number": 0,
      "line_ref": "line_ref_sample",
      "line_type": "product",
      "location_id": "loc_1001",
      "metadata": {},
      "product": {},
      "product_id": "prod_1001",
      "quantity": "1",
      "reason_code": "VALIDATION_ERROR",
      "return_quantity": "1",
      "sku": "SKU-1001",
      "tax_amount": "125.00",
      "tax_code": "VALIDATION_ERROR",
      "tax_details": [
        {
          "allocation_ref": "loc_1001",
          "amount_includes_tax": false,
          "fulfillment_ref": "fulfillment_ref_sample",
          "jurisdiction_code": "VALIDATION_ERROR",
          "jurisdiction_level": "jurisdiction_level_sample",
          "jurisdiction_name": "Acme Supplies",
          "metadata": {},
          "provider_detail_ref": "provider_detail_ref_sample",
          "provider_key": "provider_key_sample",
          "provider_tax_rate_ref": "1.00",
          "rate": "1.00",
          "ship_from_ref": "ship_from_ref_sample",
          "ship_to_ref": "ship_to_ref_sample",
          "tax_amount": "125.00",
          "tax_code": "VALIDATION_ERROR",
          "tax_detail_ref": "tax_detail_ref_sample",
          "tax_name": "Acme Supplies",
          "tax_type": "tax_type_sample",
          "taxability_reason": "taxability_reason_sample",
          "taxable_amount": "125.00"
        }
      ],
      "tax_exempt_reason": "tax_exempt_reason_sample",
      "tax_rate": "1.00",
      "tax_status": "taxable",
      "taxable_amount": "125.00",
      "unit_amount": "125.00"
    }
  ],
  "metadata": {},
  "reason_code": "VALIDATION_ERROR",
  "status": "open",
  "total_amount": "125.00"
}

Responses

201 Created

Field Type Description

data required CreditMemoRecord A credit_memo record as returned by the API

Show data fields

Field Type Description

applied_at string (date-time) Applied At

approval_status string Approval Status

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

customer_id string Customer ID

dimensions object Dimensions

document_date string (date) Document Date

document_number string Document Number

effective_date string (date) Effective Date

id string Canonical ID

invoice_id string Invoice ID

issued_at string (date-time) Issued At

lines array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

currency string Currency

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

invoice_line_ref string Invoice Line Ref

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

reason_code string Reason Code

return_quantity string Return Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

reason_code string Reason Code

refunded_at string (date-time) Refunded At

source_id required string Source ID

source_system required string Source System

status required string Status

total_amount required string Total Amount

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "applied_at": "2026-05-05T12:00:00Z",
    "approval_status": "draft",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "dimensions": {},
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "effective_date": "2026-05-05",
    "id": "00000000-0000-0000-0000-000000000000",
    "invoice_id": "inv_1001",
    "issued_at": "2026-05-05T12:00:00Z",
    "lines": [
      {
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "class_id": "class_1001",
        "currency": "USD",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "invoice_line_ref": "inv_1001",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "reason_code": "VALIDATION_ERROR",
        "return_quantity": "1",
        "sku": "SKU-1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "reason_code": "VALIDATION_ERROR",
    "refunded_at": "2026-05-05T12:00:00Z",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "open",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "credit_memo"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/credit_memos" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "approval_status": "draft",
  "currency": "USD",
  "customer_id": "cus_1001",
  "dimensions": {},
  "document_date": "2026-05-05",
  "document_number": "INV-1001",
  "effective_date": "2026-05-05",
  "invoice_id": "inv_1001",
  "issued_at": "2026-05-05T12:00:00Z",
  "lines": [
    {
      "account_id": "acc_1001",
      "amount": "125.00",
      "amount_includes_tax": false,
      "class_id": "class_1001",
      "currency": "USD",
      "description": "Office supplies",
      "detail": {
        "account_id": "acc_1001",
        "basis_amount": "125.00",
        "class_id": "class_1001",
        "discount_amount": "125.00",
        "discount_percent": "discount_percent_sample",
        "item_id": "item_1001",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "quantity": "1",
        "sku": "SKU-1001",
        "subtotal_amount": "125.00",
        "type": "item",
        "unit_amount": "125.00"
      },
      "dimensions": {},
      "discount_amount": "125.00",
      "invoice_line_ref": "inv_1001",
      "line_key": "line_key_sample",
      "line_number": 0,
      "line_ref": "line_ref_sample",
      "line_type": "product",
      "location_id": "loc_1001",
      "metadata": {},
      "product": {},
      "product_id": "prod_1001",
      "quantity": "1",
      "reason_code": "VALIDATION_ERROR",
      "return_quantity": "1",
      "sku": "SKU-1001",
      "tax_amount": "125.00",
      "tax_code": "VALIDATION_ERROR",
      "tax_details": [
        {
          "allocation_ref": "loc_1001",
          "amount_includes_tax": false,
          "fulfillment_ref": "fulfillment_ref_sample",
          "jurisdiction_code": "VALIDATION_ERROR",
          "jurisdiction_level": "jurisdiction_level_sample",
          "jurisdiction_name": "Acme Supplies",
          "metadata": {},
          "provider_detail_ref": "provider_detail_ref_sample",
          "provider_key": "provider_key_sample",
          "provider_tax_rate_ref": "1.00",
          "rate": "1.00",
          "ship_from_ref": "ship_from_ref_sample",
          "ship_to_ref": "ship_to_ref_sample",
          "tax_amount": "125.00",
          "tax_code": "VALIDATION_ERROR",
          "tax_detail_ref": "tax_detail_ref_sample",
          "tax_name": "Acme Supplies",
          "tax_type": "tax_type_sample",
          "taxability_reason": "taxability_reason_sample",
          "taxable_amount": "125.00"
        }
      ],
      "tax_exempt_reason": "tax_exempt_reason_sample",
      "tax_rate": "1.00",
      "tax_status": "taxable",
      "taxable_amount": "125.00",
      "unit_amount": "125.00"
    }
  ],
  "metadata": {},
  "reason_code": "VALIDATION_ERROR",
  "status": "open",
  "total_amount": "125.00"
}'

GET /v1/credit_memos/{id}

Get a credit memo

Path parameters

Name	Type	Description
id required	string	Resource identifier

Query parameters

Name	Type	Description
include	string	Comma-separated extension field tokens: extension_fields.entity, extension_fields.line

Responses

200 Success

Field Type Description

data required CreditMemoRecord A credit_memo record as returned by the API

Show data fields

Field Type Description

applied_at string (date-time) Applied At

approval_status string Approval Status

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

customer_id string Customer ID

dimensions object Dimensions

document_date string (date) Document Date

document_number string Document Number

effective_date string (date) Effective Date

id string Canonical ID

invoice_id string Invoice ID

issued_at string (date-time) Issued At

lines array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

currency string Currency

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

invoice_line_ref string Invoice Line Ref

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

reason_code string Reason Code

return_quantity string Return Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

reason_code string Reason Code

refunded_at string (date-time) Refunded At

source_id required string Source ID

source_system required string Source System

status required string Status

total_amount required string Total Amount

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "applied_at": "2026-05-05T12:00:00Z",
    "approval_status": "draft",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "dimensions": {},
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "effective_date": "2026-05-05",
    "id": "00000000-0000-0000-0000-000000000000",
    "invoice_id": "inv_1001",
    "issued_at": "2026-05-05T12:00:00Z",
    "lines": [
      {
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "class_id": "class_1001",
        "currency": "USD",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "invoice_line_ref": "inv_1001",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "reason_code": "VALIDATION_ERROR",
        "return_quantity": "1",
        "sku": "SKU-1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "reason_code": "VALIDATION_ERROR",
    "refunded_at": "2026-05-05T12:00:00Z",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "open",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "credit_memo"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/credit_memos/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

PUT /v1/credit_memos/{id}

Update a credit memo

Path parameters

Name	Type	Description
id required	string	Resource identifier

Request body required

Field Type Description

approval_status string Approval Status

currency string Currency

customer_id string Customer ID

dimensions object Dimensions

document_date string (date) Document Date

document_number string Document Number

effective_date string (date) Effective Date

invoice_id string Invoice ID

issued_at string (date-time) Issued At

lines array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

currency string Currency

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

invoice_line_ref string Invoice Line Ref

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

reason_code string Reason Code

return_quantity string Return Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

reason_code string Reason Code

status string Status

total_amount string Total Amount

{
  "approval_status": "draft",
  "currency": "USD",
  "customer_id": "cus_1001",
  "dimensions": {},
  "document_date": "2026-05-05",
  "document_number": "INV-1001",
  "effective_date": "2026-05-05",
  "invoice_id": "inv_1001",
  "issued_at": "2026-05-05T12:00:00Z",
  "lines": [
    {
      "account_id": "acc_1001",
      "amount": "125.00",
      "amount_includes_tax": false,
      "class_id": "class_1001",
      "currency": "USD",
      "description": "Office supplies",
      "detail": {
        "account_id": "acc_1001",
        "basis_amount": "125.00",
        "class_id": "class_1001",
        "discount_amount": "125.00",
        "discount_percent": "discount_percent_sample",
        "item_id": "item_1001",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "quantity": "1",
        "sku": "SKU-1001",
        "subtotal_amount": "125.00",
        "type": "item",
        "unit_amount": "125.00"
      },
      "dimensions": {},
      "discount_amount": "125.00",
      "invoice_line_ref": "inv_1001",
      "line_key": "line_key_sample",
      "line_number": 0,
      "line_ref": "line_ref_sample",
      "line_type": "product",
      "location_id": "loc_1001",
      "metadata": {},
      "product": {},
      "product_id": "prod_1001",
      "quantity": "1",
      "reason_code": "VALIDATION_ERROR",
      "return_quantity": "1",
      "sku": "SKU-1001",
      "tax_amount": "125.00",
      "tax_code": "VALIDATION_ERROR",
      "tax_details": [
        {
          "allocation_ref": "loc_1001",
          "amount_includes_tax": false,
          "fulfillment_ref": "fulfillment_ref_sample",
          "jurisdiction_code": "VALIDATION_ERROR",
          "jurisdiction_level": "jurisdiction_level_sample",
          "jurisdiction_name": "Acme Supplies",
          "metadata": {},
          "provider_detail_ref": "provider_detail_ref_sample",
          "provider_key": "provider_key_sample",
          "provider_tax_rate_ref": "1.00",
          "rate": "1.00",
          "ship_from_ref": "ship_from_ref_sample",
          "ship_to_ref": "ship_to_ref_sample",
          "tax_amount": "125.00",
          "tax_code": "VALIDATION_ERROR",
          "tax_detail_ref": "tax_detail_ref_sample",
          "tax_name": "Acme Supplies",
          "tax_type": "tax_type_sample",
          "taxability_reason": "taxability_reason_sample",
          "taxable_amount": "125.00"
        }
      ],
      "tax_exempt_reason": "tax_exempt_reason_sample",
      "tax_rate": "1.00",
      "tax_status": "taxable",
      "taxable_amount": "125.00",
      "unit_amount": "125.00"
    }
  ],
  "metadata": {},
  "reason_code": "VALIDATION_ERROR",
  "status": "open",
  "total_amount": "125.00"
}

Responses

200 Success

Field Type Description

data required CreditMemoRecord A credit_memo record as returned by the API

Show data fields

Field Type Description

applied_at string (date-time) Applied At

approval_status string Approval Status

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

customer_id string Customer ID

dimensions object Dimensions

document_date string (date) Document Date

document_number string Document Number

effective_date string (date) Effective Date

id string Canonical ID

invoice_id string Invoice ID

issued_at string (date-time) Issued At

lines array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

currency string Currency

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

invoice_line_ref string Invoice Line Ref

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

reason_code string Reason Code

return_quantity string Return Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

reason_code string Reason Code

refunded_at string (date-time) Refunded At

source_id required string Source ID

source_system required string Source System

status required string Status

total_amount required string Total Amount

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "applied_at": "2026-05-05T12:00:00Z",
    "approval_status": "draft",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "dimensions": {},
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "effective_date": "2026-05-05",
    "id": "00000000-0000-0000-0000-000000000000",
    "invoice_id": "inv_1001",
    "issued_at": "2026-05-05T12:00:00Z",
    "lines": [
      {
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "class_id": "class_1001",
        "currency": "USD",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "invoice_line_ref": "inv_1001",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "reason_code": "VALIDATION_ERROR",
        "return_quantity": "1",
        "sku": "SKU-1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "reason_code": "VALIDATION_ERROR",
    "refunded_at": "2026-05-05T12:00:00Z",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "open",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "credit_memo"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X PUT "https://api.backfill.io/v1/credit_memos/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "approval_status": "draft",
  "currency": "USD",
  "customer_id": "cus_1001",
  "dimensions": {},
  "document_date": "2026-05-05",
  "document_number": "INV-1001",
  "effective_date": "2026-05-05",
  "invoice_id": "inv_1001",
  "issued_at": "2026-05-05T12:00:00Z",
  "lines": [
    {
      "account_id": "acc_1001",
      "amount": "125.00",
      "amount_includes_tax": false,
      "class_id": "class_1001",
      "currency": "USD",
      "description": "Office supplies",
      "detail": {
        "account_id": "acc_1001",
        "basis_amount": "125.00",
        "class_id": "class_1001",
        "discount_amount": "125.00",
        "discount_percent": "discount_percent_sample",
        "item_id": "item_1001",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "quantity": "1",
        "sku": "SKU-1001",
        "subtotal_amount": "125.00",
        "type": "item",
        "unit_amount": "125.00"
      },
      "dimensions": {},
      "discount_amount": "125.00",
      "invoice_line_ref": "inv_1001",
      "line_key": "line_key_sample",
      "line_number": 0,
      "line_ref": "line_ref_sample",
      "line_type": "product",
      "location_id": "loc_1001",
      "metadata": {},
      "product": {},
      "product_id": "prod_1001",
      "quantity": "1",
      "reason_code": "VALIDATION_ERROR",
      "return_quantity": "1",
      "sku": "SKU-1001",
      "tax_amount": "125.00",
      "tax_code": "VALIDATION_ERROR",
      "tax_details": [
        {
          "allocation_ref": "loc_1001",
          "amount_includes_tax": false,
          "fulfillment_ref": "fulfillment_ref_sample",
          "jurisdiction_code": "VALIDATION_ERROR",
          "jurisdiction_level": "jurisdiction_level_sample",
          "jurisdiction_name": "Acme Supplies",
          "metadata": {},
          "provider_detail_ref": "provider_detail_ref_sample",
          "provider_key": "provider_key_sample",
          "provider_tax_rate_ref": "1.00",
          "rate": "1.00",
          "ship_from_ref": "ship_from_ref_sample",
          "ship_to_ref": "ship_to_ref_sample",
          "tax_amount": "125.00",
          "tax_code": "VALIDATION_ERROR",
          "tax_detail_ref": "tax_detail_ref_sample",
          "tax_name": "Acme Supplies",
          "tax_type": "tax_type_sample",
          "taxability_reason": "taxability_reason_sample",
          "taxable_amount": "125.00"
        }
      ],
      "tax_exempt_reason": "tax_exempt_reason_sample",
      "tax_rate": "1.00",
      "tax_status": "taxable",
      "taxable_amount": "125.00",
      "unit_amount": "125.00"
    }
  ],
  "metadata": {},
  "reason_code": "VALIDATION_ERROR",
  "status": "open",
  "total_amount": "125.00"
}'

DELETE /v1/credit_memos/{id}

Delete a credit memo

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Deleted

Field	Type	Description
deleted required	boolean
id required	string (uuid)
object required	string

{
  "deleted": true,
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "record"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X DELETE "https://api.backfill.io/v1/credit_memos/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/credit_memos/{id}/approve

Approve a pending document

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required CreditMemoRecord A credit_memo record as returned by the API

Show data fields

Field Type Description

applied_at string (date-time) Applied At

approval_status string Approval Status

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

customer_id string Customer ID

dimensions object Dimensions

document_date string (date) Document Date

document_number string Document Number

effective_date string (date) Effective Date

id string Canonical ID

invoice_id string Invoice ID

issued_at string (date-time) Issued At

lines array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

currency string Currency

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

invoice_line_ref string Invoice Line Ref

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

reason_code string Reason Code

return_quantity string Return Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

reason_code string Reason Code

refunded_at string (date-time) Refunded At

source_id required string Source ID

source_system required string Source System

status required string Status

total_amount required string Total Amount

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "applied_at": "2026-05-05T12:00:00Z",
    "approval_status": "draft",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "dimensions": {},
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "effective_date": "2026-05-05",
    "id": "00000000-0000-0000-0000-000000000000",
    "invoice_id": "inv_1001",
    "issued_at": "2026-05-05T12:00:00Z",
    "lines": [
      {
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "class_id": "class_1001",
        "currency": "USD",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "invoice_line_ref": "inv_1001",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "reason_code": "VALIDATION_ERROR",
        "return_quantity": "1",
        "sku": "SKU-1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "reason_code": "VALIDATION_ERROR",
    "refunded_at": "2026-05-05T12:00:00Z",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "open",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "credit_memo"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/credit_memos/{id}/approve" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/credit_memos/{id}/reject

Reject a pending document

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required CreditMemoRecord A credit_memo record as returned by the API

Show data fields

Field Type Description

applied_at string (date-time) Applied At

approval_status string Approval Status

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

customer_id string Customer ID

dimensions object Dimensions

document_date string (date) Document Date

document_number string Document Number

effective_date string (date) Effective Date

id string Canonical ID

invoice_id string Invoice ID

issued_at string (date-time) Issued At

lines array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

currency string Currency

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

invoice_line_ref string Invoice Line Ref

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

reason_code string Reason Code

return_quantity string Return Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

reason_code string Reason Code

refunded_at string (date-time) Refunded At

source_id required string Source ID

source_system required string Source System

status required string Status

total_amount required string Total Amount

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "applied_at": "2026-05-05T12:00:00Z",
    "approval_status": "draft",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "dimensions": {},
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "effective_date": "2026-05-05",
    "id": "00000000-0000-0000-0000-000000000000",
    "invoice_id": "inv_1001",
    "issued_at": "2026-05-05T12:00:00Z",
    "lines": [
      {
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "class_id": "class_1001",
        "currency": "USD",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "invoice_line_ref": "inv_1001",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "reason_code": "VALIDATION_ERROR",
        "return_quantity": "1",
        "sku": "SKU-1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "reason_code": "VALIDATION_ERROR",
    "refunded_at": "2026-05-05T12:00:00Z",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "open",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "credit_memo"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/credit_memos/{id}/reject" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/credit_memos/{id}/submit

Submit a document for approval

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required CreditMemoRecord A credit_memo record as returned by the API

Show data fields

Field Type Description

applied_at string (date-time) Applied At

approval_status string Approval Status

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

customer_id string Customer ID

dimensions object Dimensions

document_date string (date) Document Date

document_number string Document Number

effective_date string (date) Effective Date

id string Canonical ID

invoice_id string Invoice ID

issued_at string (date-time) Issued At

lines array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

currency string Currency

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

invoice_line_ref string Invoice Line Ref

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

reason_code string Reason Code

return_quantity string Return Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

reason_code string Reason Code

refunded_at string (date-time) Refunded At

source_id required string Source ID

source_system required string Source System

status required string Status

total_amount required string Total Amount

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "applied_at": "2026-05-05T12:00:00Z",
    "approval_status": "draft",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "dimensions": {},
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "effective_date": "2026-05-05",
    "id": "00000000-0000-0000-0000-000000000000",
    "invoice_id": "inv_1001",
    "issued_at": "2026-05-05T12:00:00Z",
    "lines": [
      {
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "class_id": "class_1001",
        "currency": "USD",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "invoice_line_ref": "inv_1001",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "reason_code": "VALIDATION_ERROR",
        "return_quantity": "1",
        "sku": "SKU-1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "reason_code": "VALIDATION_ERROR",
    "refunded_at": "2026-05-05T12:00:00Z",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "open",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "credit_memo"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/credit_memos/{id}/submit" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/credit_memos/{id}/void

Void a document

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required CreditMemoRecord A credit_memo record as returned by the API

Show data fields

Field Type Description

applied_at string (date-time) Applied At

approval_status string Approval Status

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

customer_id string Customer ID

dimensions object Dimensions

document_date string (date) Document Date

document_number string Document Number

effective_date string (date) Effective Date

id string Canonical ID

invoice_id string Invoice ID

issued_at string (date-time) Issued At

lines array of object Lines

Show lines[] fields

Field Type Description

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

currency string Currency

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

invoice_line_ref string Invoice Line Ref

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

reason_code string Reason Code

return_quantity string Return Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

reason_code string Reason Code

refunded_at string (date-time) Refunded At

source_id required string Source ID

source_system required string Source System

status required string Status

total_amount required string Total Amount

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "applied_at": "2026-05-05T12:00:00Z",
    "approval_status": "draft",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "dimensions": {},
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "effective_date": "2026-05-05",
    "id": "00000000-0000-0000-0000-000000000000",
    "invoice_id": "inv_1001",
    "issued_at": "2026-05-05T12:00:00Z",
    "lines": [
      {
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "class_id": "class_1001",
        "currency": "USD",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "invoice_line_ref": "inv_1001",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "reason_code": "VALIDATION_ERROR",
        "return_quantity": "1",
        "sku": "SKU-1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "reason_code": "VALIDATION_ERROR",
    "refunded_at": "2026-05-05T12:00:00Z",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "open",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "credit_memo"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/credit_memos/{id}/void" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

Refund Receipts

GET /v1/refund_receipts

List refund receipts

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
sort	string	Sort by a whitelisted field. Prefix with '-' for descending order, e.g. '-created_at'.
status	string	Filter by status
customer_id	string	Filter by customer UUID
payment_id	string	Filter by payment reference
start_date	string	Filter by refund_date >= (YYYY-MM-DD)
end_date	string	Filter by refund_date <= (YYYY-MM-DD)
include	string	Comma-separated extension field tokens: extension_fields.entity, extension_fields.line

Responses

200 Success

Field Type Description

data required array of RecordEnvelope

Show data[] fields

Field	Type	Description
data required	object
id required	string (uuid)
object required	string

object required string

pagination required Pagination

Show pagination fields

Field	Type	Description
has_more required	boolean
limit required	integer
page required	integer
total_count required	integer

{
  "data": [
    {
      "data": {
        "charge_id": "charge_id_sample",
        "created_at": "2026-05-05T12:00:00Z",
        "currency": "USD",
        "customer_id": "cus_1001",
        "customer_name": "cus_1001",
        "document_date": "2026-05-05",
        "document_number": "INV-1001",
        "effective_date": "2026-05-05",
        "lines": [
          {
            "account_code": "VALIDATION_ERROR",
            "account_id": "acc_1001",
            "amount": "125.00",
            "charge_line_ref": "charge_line_ref_sample",
            "class_id": "class_1001",
            "description": "Office supplies",
            "dimensions": {},
            "line_key": "line_key_sample",
            "line_number": 0,
            "line_type": "product",
            "location_id": "loc_1001",
            "metadata": {},
            "payment_line_ref": "pay_1001",
            "quantity": "1",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "unit_amount": "125.00"
          }
        ],
        "metadata": {},
        "net_amount": "125.00",
        "payment_id": "pay_1001",
        "reason": "reason_sample",
        "refund_date": "2026-05-05T12:00:00Z",
        "refund_id": "refund_id_sample",
        "source_system": "api",
        "status": "pending",
        "total_amount": "125.00",
        "updated_at": "2026-05-05T12:00:00Z"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "object": "refund_receipt"
    }
  ],
  "object": "list",
  "pagination": {
    "has_more": false,
    "limit": 0,
    "page": 0,
    "total_count": 0
  }
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/refund_receipts" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/refund_receipts

Create a refund receipt

Request body required

Field	Type	Description
charge_id	string	Charge ID
currency required	string	Currency
customer_id	string	Customer ID
document_date	string (date)	Document Date
document_number	string	Number
effective_date	string (date)	Effective Date
metadata	object
net_amount	string	Net Amount
payment_id	string	Payment ID
reason	string	Reason
refund_date	string (date-time)	Refund Date
status	string	Status
total_amount required	string	Total

{
  "charge_id": "charge_id_sample",
  "currency": "USD",
  "customer_id": "cus_1001",
  "document_date": "2026-05-05",
  "document_number": "INV-1001",
  "effective_date": "2026-05-05",
  "metadata": {},
  "net_amount": "125.00",
  "payment_id": "pay_1001",
  "reason": "reason_sample",
  "refund_date": "2026-05-05T12:00:00Z",
  "status": "pending",
  "total_amount": "125.00"
}

Responses

201 Created

Field Type Description

data required RefundReceiptRecord A refund_receipt record as returned by the API

Show data fields

Field Type Description

charge_id string Charge ID

created_at string (date-time)

currency required string Currency

customer_id string Customer ID

customer_name string Customer

document_date string (date) Document Date

document_number string Number

effective_date string (date) Effective Date

lines array of object Lines

Show lines[] fields

Field	Type	Description
account_code	string	Account Code
account_id	string	Account ID
amount	string	Amount
charge_line_ref	string	Charge Line Ref
class_id	string	Class ID
description	string	Description
dimensions	object	Dimensions
line_key	string	Line Key
line_number	integer	Line Number
line_type	string	Line Type
location_id	string	Location ID
metadata	object	Metadata
payment_line_ref	string	Payment Line Ref
quantity	string	Quantity
tax_amount	string	Tax Amount
tax_code	string	Tax Code
unit_amount	string	Unit Amount

metadata object

net_amount string Net Amount

payment_id string Payment ID

reason string Reason

refund_date string (date-time) Refund Date

refund_id required string Refund ID

source_system string Source

status string Status

total_amount required string Total

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "charge_id": "charge_id_sample",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "customer_name": "cus_1001",
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "effective_date": "2026-05-05",
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "amount": "125.00",
        "charge_line_ref": "charge_line_ref_sample",
        "class_id": "class_1001",
        "description": "Office supplies",
        "dimensions": {},
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "payment_line_ref": "pay_1001",
        "quantity": "1",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "net_amount": "125.00",
    "payment_id": "pay_1001",
    "reason": "reason_sample",
    "refund_date": "2026-05-05T12:00:00Z",
    "refund_id": "refund_id_sample",
    "source_system": "api",
    "status": "pending",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "refund_receipt"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/refund_receipts" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "charge_id": "charge_id_sample",
  "currency": "USD",
  "customer_id": "cus_1001",
  "document_date": "2026-05-05",
  "document_number": "INV-1001",
  "effective_date": "2026-05-05",
  "metadata": {},
  "net_amount": "125.00",
  "payment_id": "pay_1001",
  "reason": "reason_sample",
  "refund_date": "2026-05-05T12:00:00Z",
  "status": "pending",
  "total_amount": "125.00"
}'

GET /v1/refund_receipts/{id}

Get a refund receipt

Path parameters

Name	Type	Description
id required	string	Resource identifier

Query parameters

Name	Type	Description
include	string	Comma-separated extension field tokens: extension_fields.entity, extension_fields.line

Responses

200 Success

Field Type Description

data required RefundReceiptRecord A refund_receipt record as returned by the API

Show data fields

Field Type Description

charge_id string Charge ID

created_at string (date-time)

currency required string Currency

customer_id string Customer ID

customer_name string Customer

document_date string (date) Document Date

document_number string Number

effective_date string (date) Effective Date

lines array of object Lines

Show lines[] fields

Field	Type	Description
account_code	string	Account Code
account_id	string	Account ID
amount	string	Amount
charge_line_ref	string	Charge Line Ref
class_id	string	Class ID
description	string	Description
dimensions	object	Dimensions
line_key	string	Line Key
line_number	integer	Line Number
line_type	string	Line Type
location_id	string	Location ID
metadata	object	Metadata
payment_line_ref	string	Payment Line Ref
quantity	string	Quantity
tax_amount	string	Tax Amount
tax_code	string	Tax Code
unit_amount	string	Unit Amount

metadata object

net_amount string Net Amount

payment_id string Payment ID

reason string Reason

refund_date string (date-time) Refund Date

refund_id required string Refund ID

source_system string Source

status string Status

total_amount required string Total

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "charge_id": "charge_id_sample",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "customer_name": "cus_1001",
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "effective_date": "2026-05-05",
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "amount": "125.00",
        "charge_line_ref": "charge_line_ref_sample",
        "class_id": "class_1001",
        "description": "Office supplies",
        "dimensions": {},
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "payment_line_ref": "pay_1001",
        "quantity": "1",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "net_amount": "125.00",
    "payment_id": "pay_1001",
    "reason": "reason_sample",
    "refund_date": "2026-05-05T12:00:00Z",
    "refund_id": "refund_id_sample",
    "source_system": "api",
    "status": "pending",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "refund_receipt"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/refund_receipts/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

PUT /v1/refund_receipts/{id}

Update a refund receipt

Path parameters

Name	Type	Description
id required	string	Resource identifier

Request body required

Field	Type	Description
charge_id	string	Charge ID
currency	string	Currency
customer_id	string	Customer ID
document_date	string (date)	Document Date
document_number	string	Number
effective_date	string (date)	Effective Date
metadata	object
net_amount	string	Net Amount
payment_id	string	Payment ID
reason	string	Reason
refund_date	string (date-time)	Refund Date
status	string	Status
total_amount	string	Total

{
  "charge_id": "charge_id_sample",
  "currency": "USD",
  "customer_id": "cus_1001",
  "document_date": "2026-05-05",
  "document_number": "INV-1001",
  "effective_date": "2026-05-05",
  "metadata": {},
  "net_amount": "125.00",
  "payment_id": "pay_1001",
  "reason": "reason_sample",
  "refund_date": "2026-05-05T12:00:00Z",
  "status": "pending",
  "total_amount": "125.00"
}

Responses

200 Success

Field Type Description

data required RefundReceiptRecord A refund_receipt record as returned by the API

Show data fields

Field Type Description

charge_id string Charge ID

created_at string (date-time)

currency required string Currency

customer_id string Customer ID

customer_name string Customer

document_date string (date) Document Date

document_number string Number

effective_date string (date) Effective Date

lines array of object Lines

Show lines[] fields

Field	Type	Description
account_code	string	Account Code
account_id	string	Account ID
amount	string	Amount
charge_line_ref	string	Charge Line Ref
class_id	string	Class ID
description	string	Description
dimensions	object	Dimensions
line_key	string	Line Key
line_number	integer	Line Number
line_type	string	Line Type
location_id	string	Location ID
metadata	object	Metadata
payment_line_ref	string	Payment Line Ref
quantity	string	Quantity
tax_amount	string	Tax Amount
tax_code	string	Tax Code
unit_amount	string	Unit Amount

metadata object

net_amount string Net Amount

payment_id string Payment ID

reason string Reason

refund_date string (date-time) Refund Date

refund_id required string Refund ID

source_system string Source

status string Status

total_amount required string Total

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "charge_id": "charge_id_sample",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "customer_name": "cus_1001",
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "effective_date": "2026-05-05",
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "amount": "125.00",
        "charge_line_ref": "charge_line_ref_sample",
        "class_id": "class_1001",
        "description": "Office supplies",
        "dimensions": {},
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "payment_line_ref": "pay_1001",
        "quantity": "1",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "net_amount": "125.00",
    "payment_id": "pay_1001",
    "reason": "reason_sample",
    "refund_date": "2026-05-05T12:00:00Z",
    "refund_id": "refund_id_sample",
    "source_system": "api",
    "status": "pending",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "refund_receipt"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X PUT "https://api.backfill.io/v1/refund_receipts/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "charge_id": "charge_id_sample",
  "currency": "USD",
  "customer_id": "cus_1001",
  "document_date": "2026-05-05",
  "document_number": "INV-1001",
  "effective_date": "2026-05-05",
  "metadata": {},
  "net_amount": "125.00",
  "payment_id": "pay_1001",
  "reason": "reason_sample",
  "refund_date": "2026-05-05T12:00:00Z",
  "status": "pending",
  "total_amount": "125.00"
}'

DELETE /v1/refund_receipts/{id}

Delete a refund receipt

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Deleted

Field	Type	Description
deleted required	boolean
id required	string (uuid)
object required	string

{
  "deleted": true,
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "record"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X DELETE "https://api.backfill.io/v1/refund_receipts/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

Vendor Bills

GET /v1/vendor_bills

List vendor bills

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
sort	string	Sort by a whitelisted field. Prefix with '-' for descending order, e.g. '-created_at'.
status	string	Filter by approval status
include	string	Comma-separated extension field tokens: extension_fields.entity, extension_fields.line

Responses

200 Success

Field Type Description

data required array of RecordEnvelope

Show data[] fields

Field	Type	Description
data required	object
id required	string (uuid)
object required	string

object required string

pagination required Pagination

Show pagination fields

Field	Type	Description
has_more required	boolean
limit required	integer
page required	integer
total_count required	integer

{
  "data": [
    {
      "data": {
        "approval_status": "draft",
        "bill_date": "2026-05-05",
        "connection_id": "conn_1001",
        "created_at": "2026-05-05T12:00:00Z",
        "currency": "USD",
        "dimensions": {},
        "document_date": "2026-05-05",
        "document_number": "INV-1001",
        "due_date": "2026-05-05",
        "effective_date": "2026-05-05",
        "form_1099_type": "form_1099_type_sample",
        "id": "00000000-0000-0000-0000-000000000000",
        "is_1099_eligible": false,
        "lines": [
          {
            "account_code": "VALIDATION_ERROR",
            "account_id": "acc_1001",
            "amount": "125.00",
            "amount_includes_tax": false,
            "billable": false,
            "class_id": "class_1001",
            "currency": "USD",
            "customer_id": "cus_1001",
            "description": "Office supplies",
            "detail": {
              "account_id": "...",
              "basis_amount": "...",
              "class_id": "...",
              "discount_amount": "...",
              "discount_percent": "...",
              "item_id": "...",
              "location_id": "...",
              "metadata": "...",
              "product": "...",
              "quantity": "...",
              "sku": "...",
              "subtotal_amount": "...",
              "type": "...",
              "unit_amount": "..."
            },
            "dimensions": {},
            "discount_amount": "125.00",
            "line_key": "line_key_sample",
            "line_number": 0,
            "line_ref": "line_ref_sample",
            "line_type": "product",
            "location_id": "loc_1001",
            "metadata": {},
            "product": {},
            "product_id": "prod_1001",
            "quantity": "1",
            "sku": "SKU-1001",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_details": [
              "..."
            ],
            "tax_exempt_reason": "tax_exempt_reason_sample",
            "tax_rate": "1.00",
            "tax_status": "taxable",
            "taxable_amount": "125.00",
            "unit_amount": "125.00"
          }
        ],
        "metadata": {},
        "paid_date": "2026-05-05",
        "purchase_order_id": "purchase_order_id_sample",
        "source_id": "src_1001",
        "source_system": "api",
        "status": "draft",
        "total_amount": "125.00",
        "updated_at": "2026-05-05T12:00:00Z",
        "vendor_id": "ven_1001"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "object": "vendor_bill"
    }
  ],
  "object": "list",
  "pagination": {
    "has_more": false,
    "limit": 0,
    "page": 0,
    "total_count": 0
  }
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/vendor_bills" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/vendor_bills

Create a vendor bill

Request body required

Field Type Description

approval_status string Approval Status

bill_date string (date) Bill Date

currency required string Currency

dimensions object Dimensions

document_date string (date) Document Date

document_number string Document Number

due_date string (date) Due Date

effective_date string (date) Effective Date

form_1099_type string 1099 Form Type

is_1099_eligible boolean 1099 Eligible

lines array of object Lines

Show lines[] fields

Field Type Description

account_code string Account Code

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

billable boolean Billable

class_id string Class ID

currency string Currency

customer_id string Customer ID

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

purchase_order_id string Purchase Order ID

status required string Status

total_amount required string Total Amount

vendor_id required string Vendor ID

{
  "approval_status": "draft",
  "bill_date": "2026-05-05",
  "currency": "USD",
  "dimensions": {},
  "document_date": "2026-05-05",
  "document_number": "INV-1001",
  "due_date": "2026-05-05",
  "effective_date": "2026-05-05",
  "form_1099_type": "form_1099_type_sample",
  "is_1099_eligible": false,
  "lines": [
    {
      "account_code": "VALIDATION_ERROR",
      "account_id": "acc_1001",
      "amount": "125.00",
      "amount_includes_tax": false,
      "billable": false,
      "class_id": "class_1001",
      "currency": "USD",
      "customer_id": "cus_1001",
      "description": "Office supplies",
      "detail": {
        "account_id": "acc_1001",
        "basis_amount": "125.00",
        "class_id": "class_1001",
        "discount_amount": "125.00",
        "discount_percent": "discount_percent_sample",
        "item_id": "item_1001",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "quantity": "1",
        "sku": "SKU-1001",
        "subtotal_amount": "125.00",
        "type": "item",
        "unit_amount": "125.00"
      },
      "dimensions": {},
      "discount_amount": "125.00",
      "line_key": "line_key_sample",
      "line_number": 0,
      "line_ref": "line_ref_sample",
      "line_type": "product",
      "location_id": "loc_1001",
      "metadata": {},
      "product": {},
      "product_id": "prod_1001",
      "quantity": "1",
      "sku": "SKU-1001",
      "tax_amount": "125.00",
      "tax_code": "VALIDATION_ERROR",
      "tax_details": [
        {
          "allocation_ref": "loc_1001",
          "amount_includes_tax": false,
          "fulfillment_ref": "fulfillment_ref_sample",
          "jurisdiction_code": "VALIDATION_ERROR",
          "jurisdiction_level": "jurisdiction_level_sample",
          "jurisdiction_name": "Acme Supplies",
          "metadata": {},
          "provider_detail_ref": "provider_detail_ref_sample",
          "provider_key": "provider_key_sample",
          "provider_tax_rate_ref": "1.00",
          "rate": "1.00",
          "ship_from_ref": "ship_from_ref_sample",
          "ship_to_ref": "ship_to_ref_sample",
          "tax_amount": "125.00",
          "tax_code": "VALIDATION_ERROR",
          "tax_detail_ref": "tax_detail_ref_sample",
          "tax_name": "Acme Supplies",
          "tax_type": "tax_type_sample",
          "taxability_reason": "taxability_reason_sample",
          "taxable_amount": "125.00"
        }
      ],
      "tax_exempt_reason": "tax_exempt_reason_sample",
      "tax_rate": "1.00",
      "tax_status": "taxable",
      "taxable_amount": "125.00",
      "unit_amount": "125.00"
    }
  ],
  "metadata": {},
  "purchase_order_id": "purchase_order_id_sample",
  "status": "draft",
  "total_amount": "125.00",
  "vendor_id": "ven_1001"
}

Responses

201 Created

Field Type Description

data required VendorBillRecord A vendor_bill record as returned by the API

Show data fields

Field Type Description

approval_status string Approval Status

bill_date string (date) Bill Date

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

dimensions object Dimensions

document_date string (date) Document Date

document_number string Document Number

due_date string (date) Due Date

effective_date string (date) Effective Date

form_1099_type string 1099 Form Type

id string Canonical ID

is_1099_eligible boolean 1099 Eligible

lines array of object Lines

Show lines[] fields

Field Type Description

account_code string Account Code

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

billable boolean Billable

class_id string Class ID

currency string Currency

customer_id string Customer ID

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

paid_date string (date) Paid Date

purchase_order_id string Purchase Order ID

source_id required string Source ID

source_system required string Source System

status required string Status

total_amount required string Total Amount

updated_at string (date-time)

vendor_id required string Vendor ID

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "bill_date": "2026-05-05",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "dimensions": {},
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "due_date": "2026-05-05",
    "effective_date": "2026-05-05",
    "form_1099_type": "form_1099_type_sample",
    "id": "00000000-0000-0000-0000-000000000000",
    "is_1099_eligible": false,
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "billable": false,
        "class_id": "class_1001",
        "currency": "USD",
        "customer_id": "cus_1001",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "sku": "SKU-1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "paid_date": "2026-05-05",
    "purchase_order_id": "purchase_order_id_sample",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "vendor_bill"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/vendor_bills" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "approval_status": "draft",
  "bill_date": "2026-05-05",
  "currency": "USD",
  "dimensions": {},
  "document_date": "2026-05-05",
  "document_number": "INV-1001",
  "due_date": "2026-05-05",
  "effective_date": "2026-05-05",
  "form_1099_type": "form_1099_type_sample",
  "is_1099_eligible": false,
  "lines": [
    {
      "account_code": "VALIDATION_ERROR",
      "account_id": "acc_1001",
      "amount": "125.00",
      "amount_includes_tax": false,
      "billable": false,
      "class_id": "class_1001",
      "currency": "USD",
      "customer_id": "cus_1001",
      "description": "Office supplies",
      "detail": {
        "account_id": "acc_1001",
        "basis_amount": "125.00",
        "class_id": "class_1001",
        "discount_amount": "125.00",
        "discount_percent": "discount_percent_sample",
        "item_id": "item_1001",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "quantity": "1",
        "sku": "SKU-1001",
        "subtotal_amount": "125.00",
        "type": "item",
        "unit_amount": "125.00"
      },
      "dimensions": {},
      "discount_amount": "125.00",
      "line_key": "line_key_sample",
      "line_number": 0,
      "line_ref": "line_ref_sample",
      "line_type": "product",
      "location_id": "loc_1001",
      "metadata": {},
      "product": {},
      "product_id": "prod_1001",
      "quantity": "1",
      "sku": "SKU-1001",
      "tax_amount": "125.00",
      "tax_code": "VALIDATION_ERROR",
      "tax_details": [
        {
          "allocation_ref": "loc_1001",
          "amount_includes_tax": false,
          "fulfillment_ref": "fulfillment_ref_sample",
          "jurisdiction_code": "VALIDATION_ERROR",
          "jurisdiction_level": "jurisdiction_level_sample",
          "jurisdiction_name": "Acme Supplies",
          "metadata": {},
          "provider_detail_ref": "provider_detail_ref_sample",
          "provider_key": "provider_key_sample",
          "provider_tax_rate_ref": "1.00",
          "rate": "1.00",
          "ship_from_ref": "ship_from_ref_sample",
          "ship_to_ref": "ship_to_ref_sample",
          "tax_amount": "125.00",
          "tax_code": "VALIDATION_ERROR",
          "tax_detail_ref": "tax_detail_ref_sample",
          "tax_name": "Acme Supplies",
          "tax_type": "tax_type_sample",
          "taxability_reason": "taxability_reason_sample",
          "taxable_amount": "125.00"
        }
      ],
      "tax_exempt_reason": "tax_exempt_reason_sample",
      "tax_rate": "1.00",
      "tax_status": "taxable",
      "taxable_amount": "125.00",
      "unit_amount": "125.00"
    }
  ],
  "metadata": {},
  "purchase_order_id": "purchase_order_id_sample",
  "status": "draft",
  "total_amount": "125.00",
  "vendor_id": "ven_1001"
}'

GET /v1/vendor_bills/{id}

Get a vendor bill

Path parameters

Name	Type	Description
id required	string	Resource identifier

Query parameters

Name	Type	Description
include	string	Comma-separated extension field tokens: extension_fields.entity, extension_fields.line

Responses

200 Success

Field Type Description

data required VendorBillRecord A vendor_bill record as returned by the API

Show data fields

Field Type Description

approval_status string Approval Status

bill_date string (date) Bill Date

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

dimensions object Dimensions

document_date string (date) Document Date

document_number string Document Number

due_date string (date) Due Date

effective_date string (date) Effective Date

form_1099_type string 1099 Form Type

id string Canonical ID

is_1099_eligible boolean 1099 Eligible

lines array of object Lines

Show lines[] fields

Field Type Description

account_code string Account Code

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

billable boolean Billable

class_id string Class ID

currency string Currency

customer_id string Customer ID

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

paid_date string (date) Paid Date

purchase_order_id string Purchase Order ID

source_id required string Source ID

source_system required string Source System

status required string Status

total_amount required string Total Amount

updated_at string (date-time)

vendor_id required string Vendor ID

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "bill_date": "2026-05-05",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "dimensions": {},
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "due_date": "2026-05-05",
    "effective_date": "2026-05-05",
    "form_1099_type": "form_1099_type_sample",
    "id": "00000000-0000-0000-0000-000000000000",
    "is_1099_eligible": false,
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "billable": false,
        "class_id": "class_1001",
        "currency": "USD",
        "customer_id": "cus_1001",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "sku": "SKU-1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "paid_date": "2026-05-05",
    "purchase_order_id": "purchase_order_id_sample",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "vendor_bill"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/vendor_bills/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

PUT /v1/vendor_bills/{id}

Update a vendor bill

Path parameters

Name	Type	Description
id required	string	Resource identifier

Request body required

Field Type Description

approval_status string Approval Status

bill_date string (date) Bill Date

currency string Currency

dimensions object Dimensions

document_date string (date) Document Date

document_number string Document Number

due_date string (date) Due Date

effective_date string (date) Effective Date

form_1099_type string 1099 Form Type

is_1099_eligible boolean 1099 Eligible

lines array of object Lines

Show lines[] fields

Field Type Description

account_code string Account Code

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

billable boolean Billable

class_id string Class ID

currency string Currency

customer_id string Customer ID

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

purchase_order_id string Purchase Order ID

status string Status

total_amount string Total Amount

vendor_id string Vendor ID

{
  "approval_status": "draft",
  "bill_date": "2026-05-05",
  "currency": "USD",
  "dimensions": {},
  "document_date": "2026-05-05",
  "document_number": "INV-1001",
  "due_date": "2026-05-05",
  "effective_date": "2026-05-05",
  "form_1099_type": "form_1099_type_sample",
  "is_1099_eligible": false,
  "lines": [
    {
      "account_code": "VALIDATION_ERROR",
      "account_id": "acc_1001",
      "amount": "125.00",
      "amount_includes_tax": false,
      "billable": false,
      "class_id": "class_1001",
      "currency": "USD",
      "customer_id": "cus_1001",
      "description": "Office supplies",
      "detail": {
        "account_id": "acc_1001",
        "basis_amount": "125.00",
        "class_id": "class_1001",
        "discount_amount": "125.00",
        "discount_percent": "discount_percent_sample",
        "item_id": "item_1001",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "quantity": "1",
        "sku": "SKU-1001",
        "subtotal_amount": "125.00",
        "type": "item",
        "unit_amount": "125.00"
      },
      "dimensions": {},
      "discount_amount": "125.00",
      "line_key": "line_key_sample",
      "line_number": 0,
      "line_ref": "line_ref_sample",
      "line_type": "product",
      "location_id": "loc_1001",
      "metadata": {},
      "product": {},
      "product_id": "prod_1001",
      "quantity": "1",
      "sku": "SKU-1001",
      "tax_amount": "125.00",
      "tax_code": "VALIDATION_ERROR",
      "tax_details": [
        {
          "allocation_ref": "loc_1001",
          "amount_includes_tax": false,
          "fulfillment_ref": "fulfillment_ref_sample",
          "jurisdiction_code": "VALIDATION_ERROR",
          "jurisdiction_level": "jurisdiction_level_sample",
          "jurisdiction_name": "Acme Supplies",
          "metadata": {},
          "provider_detail_ref": "provider_detail_ref_sample",
          "provider_key": "provider_key_sample",
          "provider_tax_rate_ref": "1.00",
          "rate": "1.00",
          "ship_from_ref": "ship_from_ref_sample",
          "ship_to_ref": "ship_to_ref_sample",
          "tax_amount": "125.00",
          "tax_code": "VALIDATION_ERROR",
          "tax_detail_ref": "tax_detail_ref_sample",
          "tax_name": "Acme Supplies",
          "tax_type": "tax_type_sample",
          "taxability_reason": "taxability_reason_sample",
          "taxable_amount": "125.00"
        }
      ],
      "tax_exempt_reason": "tax_exempt_reason_sample",
      "tax_rate": "1.00",
      "tax_status": "taxable",
      "taxable_amount": "125.00",
      "unit_amount": "125.00"
    }
  ],
  "metadata": {},
  "purchase_order_id": "purchase_order_id_sample",
  "status": "draft",
  "total_amount": "125.00",
  "vendor_id": "ven_1001"
}

Responses

200 Success

Field Type Description

data required VendorBillRecord A vendor_bill record as returned by the API

Show data fields

Field Type Description

approval_status string Approval Status

bill_date string (date) Bill Date

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

dimensions object Dimensions

document_date string (date) Document Date

document_number string Document Number

due_date string (date) Due Date

effective_date string (date) Effective Date

form_1099_type string 1099 Form Type

id string Canonical ID

is_1099_eligible boolean 1099 Eligible

lines array of object Lines

Show lines[] fields

Field Type Description

account_code string Account Code

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

billable boolean Billable

class_id string Class ID

currency string Currency

customer_id string Customer ID

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

paid_date string (date) Paid Date

purchase_order_id string Purchase Order ID

source_id required string Source ID

source_system required string Source System

status required string Status

total_amount required string Total Amount

updated_at string (date-time)

vendor_id required string Vendor ID

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "bill_date": "2026-05-05",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "dimensions": {},
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "due_date": "2026-05-05",
    "effective_date": "2026-05-05",
    "form_1099_type": "form_1099_type_sample",
    "id": "00000000-0000-0000-0000-000000000000",
    "is_1099_eligible": false,
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "billable": false,
        "class_id": "class_1001",
        "currency": "USD",
        "customer_id": "cus_1001",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "sku": "SKU-1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "paid_date": "2026-05-05",
    "purchase_order_id": "purchase_order_id_sample",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "vendor_bill"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X PUT "https://api.backfill.io/v1/vendor_bills/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "approval_status": "draft",
  "bill_date": "2026-05-05",
  "currency": "USD",
  "dimensions": {},
  "document_date": "2026-05-05",
  "document_number": "INV-1001",
  "due_date": "2026-05-05",
  "effective_date": "2026-05-05",
  "form_1099_type": "form_1099_type_sample",
  "is_1099_eligible": false,
  "lines": [
    {
      "account_code": "VALIDATION_ERROR",
      "account_id": "acc_1001",
      "amount": "125.00",
      "amount_includes_tax": false,
      "billable": false,
      "class_id": "class_1001",
      "currency": "USD",
      "customer_id": "cus_1001",
      "description": "Office supplies",
      "detail": {
        "account_id": "acc_1001",
        "basis_amount": "125.00",
        "class_id": "class_1001",
        "discount_amount": "125.00",
        "discount_percent": "discount_percent_sample",
        "item_id": "item_1001",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "quantity": "1",
        "sku": "SKU-1001",
        "subtotal_amount": "125.00",
        "type": "item",
        "unit_amount": "125.00"
      },
      "dimensions": {},
      "discount_amount": "125.00",
      "line_key": "line_key_sample",
      "line_number": 0,
      "line_ref": "line_ref_sample",
      "line_type": "product",
      "location_id": "loc_1001",
      "metadata": {},
      "product": {},
      "product_id": "prod_1001",
      "quantity": "1",
      "sku": "SKU-1001",
      "tax_amount": "125.00",
      "tax_code": "VALIDATION_ERROR",
      "tax_details": [
        {
          "allocation_ref": "loc_1001",
          "amount_includes_tax": false,
          "fulfillment_ref": "fulfillment_ref_sample",
          "jurisdiction_code": "VALIDATION_ERROR",
          "jurisdiction_level": "jurisdiction_level_sample",
          "jurisdiction_name": "Acme Supplies",
          "metadata": {},
          "provider_detail_ref": "provider_detail_ref_sample",
          "provider_key": "provider_key_sample",
          "provider_tax_rate_ref": "1.00",
          "rate": "1.00",
          "ship_from_ref": "ship_from_ref_sample",
          "ship_to_ref": "ship_to_ref_sample",
          "tax_amount": "125.00",
          "tax_code": "VALIDATION_ERROR",
          "tax_detail_ref": "tax_detail_ref_sample",
          "tax_name": "Acme Supplies",
          "tax_type": "tax_type_sample",
          "taxability_reason": "taxability_reason_sample",
          "taxable_amount": "125.00"
        }
      ],
      "tax_exempt_reason": "tax_exempt_reason_sample",
      "tax_rate": "1.00",
      "tax_status": "taxable",
      "taxable_amount": "125.00",
      "unit_amount": "125.00"
    }
  ],
  "metadata": {},
  "purchase_order_id": "purchase_order_id_sample",
  "status": "draft",
  "total_amount": "125.00",
  "vendor_id": "ven_1001"
}'

DELETE /v1/vendor_bills/{id}

Delete a vendor bill

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Deleted

Field	Type	Description
deleted required	boolean
id required	string (uuid)
object required	string

{
  "deleted": true,
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "record"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X DELETE "https://api.backfill.io/v1/vendor_bills/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/vendor_bills/{id}/approve

Approve a pending document

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required VendorBillRecord A vendor_bill record as returned by the API

Show data fields

Field Type Description

approval_status string Approval Status

bill_date string (date) Bill Date

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

dimensions object Dimensions

document_date string (date) Document Date

document_number string Document Number

due_date string (date) Due Date

effective_date string (date) Effective Date

form_1099_type string 1099 Form Type

id string Canonical ID

is_1099_eligible boolean 1099 Eligible

lines array of object Lines

Show lines[] fields

Field Type Description

account_code string Account Code

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

billable boolean Billable

class_id string Class ID

currency string Currency

customer_id string Customer ID

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

paid_date string (date) Paid Date

purchase_order_id string Purchase Order ID

source_id required string Source ID

source_system required string Source System

status required string Status

total_amount required string Total Amount

updated_at string (date-time)

vendor_id required string Vendor ID

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "bill_date": "2026-05-05",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "dimensions": {},
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "due_date": "2026-05-05",
    "effective_date": "2026-05-05",
    "form_1099_type": "form_1099_type_sample",
    "id": "00000000-0000-0000-0000-000000000000",
    "is_1099_eligible": false,
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "billable": false,
        "class_id": "class_1001",
        "currency": "USD",
        "customer_id": "cus_1001",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "sku": "SKU-1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "paid_date": "2026-05-05",
    "purchase_order_id": "purchase_order_id_sample",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "vendor_bill"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/vendor_bills/{id}/approve" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/vendor_bills/{id}/reject

Reject a pending document

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required VendorBillRecord A vendor_bill record as returned by the API

Show data fields

Field Type Description

approval_status string Approval Status

bill_date string (date) Bill Date

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

dimensions object Dimensions

document_date string (date) Document Date

document_number string Document Number

due_date string (date) Due Date

effective_date string (date) Effective Date

form_1099_type string 1099 Form Type

id string Canonical ID

is_1099_eligible boolean 1099 Eligible

lines array of object Lines

Show lines[] fields

Field Type Description

account_code string Account Code

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

billable boolean Billable

class_id string Class ID

currency string Currency

customer_id string Customer ID

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

paid_date string (date) Paid Date

purchase_order_id string Purchase Order ID

source_id required string Source ID

source_system required string Source System

status required string Status

total_amount required string Total Amount

updated_at string (date-time)

vendor_id required string Vendor ID

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "bill_date": "2026-05-05",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "dimensions": {},
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "due_date": "2026-05-05",
    "effective_date": "2026-05-05",
    "form_1099_type": "form_1099_type_sample",
    "id": "00000000-0000-0000-0000-000000000000",
    "is_1099_eligible": false,
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "billable": false,
        "class_id": "class_1001",
        "currency": "USD",
        "customer_id": "cus_1001",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "sku": "SKU-1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "paid_date": "2026-05-05",
    "purchase_order_id": "purchase_order_id_sample",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "vendor_bill"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/vendor_bills/{id}/reject" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/vendor_bills/{id}/submit

Submit a document for approval

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required VendorBillRecord A vendor_bill record as returned by the API

Show data fields

Field Type Description

approval_status string Approval Status

bill_date string (date) Bill Date

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

dimensions object Dimensions

document_date string (date) Document Date

document_number string Document Number

due_date string (date) Due Date

effective_date string (date) Effective Date

form_1099_type string 1099 Form Type

id string Canonical ID

is_1099_eligible boolean 1099 Eligible

lines array of object Lines

Show lines[] fields

Field Type Description

account_code string Account Code

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

billable boolean Billable

class_id string Class ID

currency string Currency

customer_id string Customer ID

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

paid_date string (date) Paid Date

purchase_order_id string Purchase Order ID

source_id required string Source ID

source_system required string Source System

status required string Status

total_amount required string Total Amount

updated_at string (date-time)

vendor_id required string Vendor ID

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "bill_date": "2026-05-05",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "dimensions": {},
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "due_date": "2026-05-05",
    "effective_date": "2026-05-05",
    "form_1099_type": "form_1099_type_sample",
    "id": "00000000-0000-0000-0000-000000000000",
    "is_1099_eligible": false,
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "billable": false,
        "class_id": "class_1001",
        "currency": "USD",
        "customer_id": "cus_1001",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "sku": "SKU-1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "paid_date": "2026-05-05",
    "purchase_order_id": "purchase_order_id_sample",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "vendor_bill"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/vendor_bills/{id}/submit" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/vendor_bills/{id}/void

Void a document

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required VendorBillRecord A vendor_bill record as returned by the API

Show data fields

Field Type Description

approval_status string Approval Status

bill_date string (date) Bill Date

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

dimensions object Dimensions

document_date string (date) Document Date

document_number string Document Number

due_date string (date) Due Date

effective_date string (date) Effective Date

form_1099_type string 1099 Form Type

id string Canonical ID

is_1099_eligible boolean 1099 Eligible

lines array of object Lines

Show lines[] fields

Field Type Description

account_code string Account Code

account_id string Account ID

amount string Amount

amount_includes_tax boolean Amount Includes Tax

billable boolean Billable

class_id string Class ID

currency string Currency

customer_id string Customer ID

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

discount_amount string Discount Amount

line_key string Line Key

line_number integer Line Number

line_ref string Line Ref

line_type string Line Type

location_id string Location ID

metadata object Metadata

product object Product

product_id string Product ID

quantity string Quantity

sku string SKU

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

unit_amount string Unit Amount

metadata object Metadata

paid_date string (date) Paid Date

purchase_order_id string Purchase Order ID

source_id required string Source ID

source_system required string Source System

status required string Status

total_amount required string Total Amount

updated_at string (date-time)

vendor_id required string Vendor ID

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "bill_date": "2026-05-05",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "dimensions": {},
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "due_date": "2026-05-05",
    "effective_date": "2026-05-05",
    "form_1099_type": "form_1099_type_sample",
    "id": "00000000-0000-0000-0000-000000000000",
    "is_1099_eligible": false,
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "amount": "125.00",
        "amount_includes_tax": false,
        "billable": false,
        "class_id": "class_1001",
        "currency": "USD",
        "customer_id": "cus_1001",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "discount_amount": "125.00",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "product_id": "prod_1001",
        "quantity": "1",
        "sku": "SKU-1001",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "paid_date": "2026-05-05",
    "purchase_order_id": "purchase_order_id_sample",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "vendor_bill"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/vendor_bills/{id}/void" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

Bill Payments

GET /v1/bill_payments

List bill payments

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
sort	string	Sort by a whitelisted field. Prefix with '-' for descending order, e.g. '-created_at'.
status	string	Filter by status

Responses

200 Success

Field Type Description

data required array of RecordEnvelope

Show data[] fields

Field	Type	Description
data required	object
id required	string (uuid)
object required	string

object required string

pagination required Pagination

Show pagination fields

Field	Type	Description
has_more required	boolean
limit required	integer
page required	integer
total_count required	integer

{
  "data": [
    {
      "data": {
        "allocations": [
          {
            "allocated_on": "2026-05-05",
            "amount": "125.00",
            "bill_id": "bill_id_sample"
          }
        ],
        "amount": "125.00",
        "approval_status": "draft",
        "bill_id": "bill_id_sample",
        "connection_id": "conn_1001",
        "created_at": "2026-05-05T12:00:00Z",
        "currency": "USD",
        "form_1099_type": "form_1099_type_sample",
        "is_1099_eligible": false,
        "metadata": {},
        "payment_date": "2026-05-05",
        "payment_method": "pay_1001",
        "payment_method_details": {},
        "payment_method_type": "check",
        "payment_number": "pay_1001",
        "source_id": "src_1001",
        "source_system": "api",
        "status": "pending",
        "updated_at": "2026-05-05T12:00:00Z",
        "vendor_id": "ven_1001"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "object": "bill_payment"
    }
  ],
  "object": "list",
  "pagination": {
    "has_more": false,
    "limit": 0,
    "page": 0,
    "total_count": 0
  }
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/bill_payments" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/bill_payments

Create a bill payment

Request body required

Field	Type	Description
amount required	string	Amount
approval_status	string	Approval Status
bill_id	string	Bill ID
currency required	string	Currency
form_1099_type	string	1099 Form Type
is_1099_eligible	boolean	1099 Eligible
metadata	object	Metadata
payment_date	string (date)	Payment Date
payment_method	string	Payment Method
payment_method_details	object	Payment Method Details
payment_method_type	string	Payment Method Type
payment_number	string	Payment Number
status	string	Status
vendor_id required	string	Vendor ID

{
  "amount": "125.00",
  "approval_status": "draft",
  "bill_id": "bill_id_sample",
  "currency": "USD",
  "form_1099_type": "form_1099_type_sample",
  "is_1099_eligible": false,
  "metadata": {},
  "payment_date": "2026-05-05",
  "payment_method": "pay_1001",
  "payment_method_details": {},
  "payment_method_type": "check",
  "payment_number": "pay_1001",
  "status": "pending",
  "vendor_id": "ven_1001"
}

Responses

201 Created

Field Type Description

data required BillPaymentRecord A bill_payment record as returned by the API

Show data fields

Field Type Description

allocations array of object Allocations

Show allocations[] fields

Field	Type	Description
allocated_on	string (date)	Allocated On
amount required	string	Amount
bill_id required	string	Bill ID

amount required string Amount

approval_status string Approval Status

bill_id string Bill ID

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

form_1099_type string 1099 Form Type

is_1099_eligible boolean 1099 Eligible

metadata object Metadata

payment_date string (date) Payment Date

payment_method string Payment Method

payment_method_details object Payment Method Details

payment_method_type string Payment Method Type

payment_number string Payment Number

source_id required string Source ID

source_system required string Source System

status required string Status

updated_at string (date-time)

vendor_id required string Vendor ID

id required string (uuid)

object required string

{
  "data": {
    "allocations": [
      {
        "allocated_on": "2026-05-05",
        "amount": "125.00",
        "bill_id": "bill_id_sample"
      }
    ],
    "amount": "125.00",
    "approval_status": "draft",
    "bill_id": "bill_id_sample",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "form_1099_type": "form_1099_type_sample",
    "is_1099_eligible": false,
    "metadata": {},
    "payment_date": "2026-05-05",
    "payment_method": "pay_1001",
    "payment_method_details": {},
    "payment_method_type": "check",
    "payment_number": "pay_1001",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "pending",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "bill_payment"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/bill_payments" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "125.00",
  "approval_status": "draft",
  "bill_id": "bill_id_sample",
  "currency": "USD",
  "form_1099_type": "form_1099_type_sample",
  "is_1099_eligible": false,
  "metadata": {},
  "payment_date": "2026-05-05",
  "payment_method": "pay_1001",
  "payment_method_details": {},
  "payment_method_type": "check",
  "payment_number": "pay_1001",
  "status": "pending",
  "vendor_id": "ven_1001"
}'

GET /v1/bill_payments/{id}

Get a bill payment

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required BillPaymentRecord A bill_payment record as returned by the API

Show data fields

Field Type Description

allocations array of object Allocations

Show allocations[] fields

Field	Type	Description
allocated_on	string (date)	Allocated On
amount required	string	Amount
bill_id required	string	Bill ID

amount required string Amount

approval_status string Approval Status

bill_id string Bill ID

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

form_1099_type string 1099 Form Type

is_1099_eligible boolean 1099 Eligible

metadata object Metadata

payment_date string (date) Payment Date

payment_method string Payment Method

payment_method_details object Payment Method Details

payment_method_type string Payment Method Type

payment_number string Payment Number

source_id required string Source ID

source_system required string Source System

status required string Status

updated_at string (date-time)

vendor_id required string Vendor ID

id required string (uuid)

object required string

{
  "data": {
    "allocations": [
      {
        "allocated_on": "2026-05-05",
        "amount": "125.00",
        "bill_id": "bill_id_sample"
      }
    ],
    "amount": "125.00",
    "approval_status": "draft",
    "bill_id": "bill_id_sample",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "form_1099_type": "form_1099_type_sample",
    "is_1099_eligible": false,
    "metadata": {},
    "payment_date": "2026-05-05",
    "payment_method": "pay_1001",
    "payment_method_details": {},
    "payment_method_type": "check",
    "payment_number": "pay_1001",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "pending",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "bill_payment"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/bill_payments/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

PUT /v1/bill_payments/{id}

Update a bill payment

Path parameters

Name	Type	Description
id required	string	Resource identifier

Request body required

Field	Type	Description
amount	string	Amount
approval_status	string	Approval Status
bill_id	string	Bill ID
currency	string	Currency
form_1099_type	string	1099 Form Type
is_1099_eligible	boolean	1099 Eligible
metadata	object	Metadata
payment_date	string (date)	Payment Date
payment_method	string	Payment Method
payment_method_details	object	Payment Method Details
payment_method_type	string	Payment Method Type
payment_number	string	Payment Number
status	string	Status
vendor_id	string	Vendor ID

{
  "amount": "125.00",
  "approval_status": "draft",
  "bill_id": "bill_id_sample",
  "currency": "USD",
  "form_1099_type": "form_1099_type_sample",
  "is_1099_eligible": false,
  "metadata": {},
  "payment_date": "2026-05-05",
  "payment_method": "pay_1001",
  "payment_method_details": {},
  "payment_method_type": "check",
  "payment_number": "pay_1001",
  "status": "pending",
  "vendor_id": "ven_1001"
}

Responses

200 Success

Field Type Description

data required BillPaymentRecord A bill_payment record as returned by the API

Show data fields

Field Type Description

allocations array of object Allocations

Show allocations[] fields

Field	Type	Description
allocated_on	string (date)	Allocated On
amount required	string	Amount
bill_id required	string	Bill ID

amount required string Amount

approval_status string Approval Status

bill_id string Bill ID

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

form_1099_type string 1099 Form Type

is_1099_eligible boolean 1099 Eligible

metadata object Metadata

payment_date string (date) Payment Date

payment_method string Payment Method

payment_method_details object Payment Method Details

payment_method_type string Payment Method Type

payment_number string Payment Number

source_id required string Source ID

source_system required string Source System

status required string Status

updated_at string (date-time)

vendor_id required string Vendor ID

id required string (uuid)

object required string

{
  "data": {
    "allocations": [
      {
        "allocated_on": "2026-05-05",
        "amount": "125.00",
        "bill_id": "bill_id_sample"
      }
    ],
    "amount": "125.00",
    "approval_status": "draft",
    "bill_id": "bill_id_sample",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "form_1099_type": "form_1099_type_sample",
    "is_1099_eligible": false,
    "metadata": {},
    "payment_date": "2026-05-05",
    "payment_method": "pay_1001",
    "payment_method_details": {},
    "payment_method_type": "check",
    "payment_number": "pay_1001",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "pending",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "bill_payment"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X PUT "https://api.backfill.io/v1/bill_payments/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "125.00",
  "approval_status": "draft",
  "bill_id": "bill_id_sample",
  "currency": "USD",
  "form_1099_type": "form_1099_type_sample",
  "is_1099_eligible": false,
  "metadata": {},
  "payment_date": "2026-05-05",
  "payment_method": "pay_1001",
  "payment_method_details": {},
  "payment_method_type": "check",
  "payment_number": "pay_1001",
  "status": "pending",
  "vendor_id": "ven_1001"
}'

DELETE /v1/bill_payments/{id}

Delete a bill payment

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Deleted

Field	Type	Description
deleted required	boolean
id required	string (uuid)
object required	string

{
  "deleted": true,
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "record"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X DELETE "https://api.backfill.io/v1/bill_payments/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

Expenses

GET /v1/expenses

List expenses

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
sort	string	Sort by a whitelisted field. Prefix with '-' for descending order, e.g. '-created_at'.
status	string	Filter by approval status
start_date	string	Filter by expense_date >= (YYYY-MM-DD)
end_date	string	Filter by expense_date <= (YYYY-MM-DD)
include	string	Comma-separated extension field tokens: extension_fields.entity, extension_fields.line

Responses

200 Success

Field Type Description

data required array of RecordEnvelope

Show data[] fields

Field	Type	Description
data required	object
id required	string (uuid)
object required	string

object required string

pagination required Pagination

Show pagination fields

Field	Type	Description
has_more required	boolean
limit required	integer
page required	integer
total_count required	integer

{
  "data": [
    {
      "data": {
        "amount": "125.00",
        "category": "cat_1001",
        "connection_id": "conn_1001",
        "created_at": "2026-05-05T12:00:00Z",
        "currency": "USD",
        "description": "Office supplies",
        "dimensions": {},
        "document_date": "2026-05-05",
        "effective_date": "2026-05-05",
        "expense_account_code": "VALIDATION_ERROR",
        "expense_account_id": "acc_1001",
        "expense_date": "2026-05-05",
        "form_1099_type": "form_1099_type_sample",
        "id": "00000000-0000-0000-0000-000000000000",
        "is_1099_eligible": false,
        "line_items": [
          {
            "amount": "125.00",
            "amount_includes_tax": false,
            "class_id": "class_1001",
            "description": "Office supplies",
            "detail": {
              "account_id": "...",
              "basis_amount": "...",
              "class_id": "...",
              "discount_amount": "...",
              "discount_percent": "...",
              "item_id": "...",
              "location_id": "...",
              "metadata": "...",
              "product": "...",
              "quantity": "...",
              "sku": "...",
              "subtotal_amount": "...",
              "type": "...",
              "unit_amount": "..."
            },
            "dimensions": {},
            "expense_account_code": "VALIDATION_ERROR",
            "expense_account_id": "acc_1001",
            "line_key": "line_key_sample",
            "line_number": 0,
            "line_type": "product",
            "location_id": "loc_1001",
            "metadata": {},
            "quantity": "1",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_details": [
              "..."
            ],
            "tax_exempt_reason": "tax_exempt_reason_sample",
            "tax_rate": "1.00",
            "tax_status": "taxable",
            "taxable_amount": "125.00"
          }
        ],
        "metadata": {},
        "payment_account_id": "acc_1001",
        "payment_method": "pay_1001",
        "payment_method_details": {},
        "payment_method_type": "check",
        "source_id": "src_1001",
        "source_system": "api",
        "status": "draft",
        "tax_amount": "125.00",
        "updated_at": "2026-05-05T12:00:00Z",
        "vendor_id": "ven_1001",
        "vendor_name": "ven_1001"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "object": "expense"
    }
  ],
  "object": "list",
  "pagination": {
    "has_more": false,
    "limit": 0,
    "page": 0,
    "total_count": 0
  }
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/expenses" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/expenses

Create an expense

Request body required

Field Type Description

amount required string Amount

category string Category

currency required string Currency

description string Description

dimensions object Dimensions

document_date string (date) Document Date

effective_date string (date) Effective Date

expense_account_code string Expense Account Code

expense_account_id string Expense Account ID

expense_date string (date) Expense Date

form_1099_type string 1099 Form Type

is_1099_eligible boolean 1099 Eligible

lines array of object Lines

Show lines[] fields

Field Type Description

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

expense_account_code string Expense Account Code

expense_account_id string Expense Account ID

line_key string Line Key

line_number integer Line Number

line_type string Line Type

location_id string Location ID

metadata object Metadata

quantity string Quantity

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

metadata object Metadata

payment_account_id string Payment Account ID

payment_method string Payment Method

payment_method_details object Payment Method Details

payment_method_type string Payment Method Type

status string Status

tax_amount string Tax Amount

vendor_id string Vendor ID

vendor_name string Vendor Name

{
  "amount": "125.00",
  "category": "cat_1001",
  "currency": "USD",
  "description": "Office supplies",
  "dimensions": {},
  "document_date": "2026-05-05",
  "effective_date": "2026-05-05",
  "expense_account_code": "VALIDATION_ERROR",
  "expense_account_id": "acc_1001",
  "expense_date": "2026-05-05",
  "form_1099_type": "form_1099_type_sample",
  "is_1099_eligible": false,
  "lines": [
    {
      "amount": "125.00",
      "amount_includes_tax": false,
      "class_id": "class_1001",
      "description": "Office supplies",
      "detail": {
        "account_id": "acc_1001",
        "basis_amount": "125.00",
        "class_id": "class_1001",
        "discount_amount": "125.00",
        "discount_percent": "discount_percent_sample",
        "item_id": "item_1001",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "quantity": "1",
        "sku": "SKU-1001",
        "subtotal_amount": "125.00",
        "type": "item",
        "unit_amount": "125.00"
      },
      "dimensions": {},
      "expense_account_code": "VALIDATION_ERROR",
      "expense_account_id": "acc_1001",
      "line_key": "line_key_sample",
      "line_number": 0,
      "line_type": "product",
      "location_id": "loc_1001",
      "metadata": {},
      "quantity": "1",
      "tax_amount": "125.00",
      "tax_code": "VALIDATION_ERROR",
      "tax_details": [
        {
          "allocation_ref": "loc_1001",
          "amount_includes_tax": false,
          "fulfillment_ref": "fulfillment_ref_sample",
          "jurisdiction_code": "VALIDATION_ERROR",
          "jurisdiction_level": "jurisdiction_level_sample",
          "jurisdiction_name": "Acme Supplies",
          "metadata": {},
          "provider_detail_ref": "provider_detail_ref_sample",
          "provider_key": "provider_key_sample",
          "provider_tax_rate_ref": "1.00",
          "rate": "1.00",
          "ship_from_ref": "ship_from_ref_sample",
          "ship_to_ref": "ship_to_ref_sample",
          "tax_amount": "125.00",
          "tax_code": "VALIDATION_ERROR",
          "tax_detail_ref": "tax_detail_ref_sample",
          "tax_name": "Acme Supplies",
          "tax_type": "tax_type_sample",
          "taxability_reason": "taxability_reason_sample",
          "taxable_amount": "125.00"
        }
      ],
      "tax_exempt_reason": "tax_exempt_reason_sample",
      "tax_rate": "1.00",
      "tax_status": "taxable",
      "taxable_amount": "125.00"
    }
  ],
  "metadata": {},
  "payment_account_id": "acc_1001",
  "payment_method": "pay_1001",
  "payment_method_details": {},
  "payment_method_type": "check",
  "status": "draft",
  "tax_amount": "125.00",
  "vendor_id": "ven_1001",
  "vendor_name": "ven_1001"
}

Responses

201 Created

Field Type Description

data required ExpenseRecord A expense record as returned by the API

Show data fields

Field Type Description

amount required string Amount

category string Category

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

description string Description

dimensions object Dimensions

document_date string (date) Document Date

effective_date string (date) Effective Date

expense_account_code string Expense Account Code

expense_account_id string Expense Account ID

expense_date string (date) Expense Date

form_1099_type string 1099 Form Type

id string Canonical ID

is_1099_eligible boolean 1099 Eligible

line_items array of object Lines

Show line_items[] fields

Field Type Description

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

expense_account_code string Expense Account Code

expense_account_id string Expense Account ID

line_key string Line Key

line_number integer Line Number

line_type string Line Type

location_id string Location ID

metadata object Metadata

quantity string Quantity

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

metadata object Metadata

payment_account_id string Payment Account ID

payment_method string Payment Method

payment_method_details object Payment Method Details

payment_method_type string Payment Method Type

source_id required string Source ID

source_system required string Source System

status required string Status

tax_amount string Tax Amount

updated_at string (date-time)

vendor_id string Vendor ID

vendor_name string Vendor Name

id required string (uuid)

object required string

{
  "data": {
    "amount": "125.00",
    "category": "cat_1001",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "description": "Office supplies",
    "dimensions": {},
    "document_date": "2026-05-05",
    "effective_date": "2026-05-05",
    "expense_account_code": "VALIDATION_ERROR",
    "expense_account_id": "acc_1001",
    "expense_date": "2026-05-05",
    "form_1099_type": "form_1099_type_sample",
    "id": "00000000-0000-0000-0000-000000000000",
    "is_1099_eligible": false,
    "line_items": [
      {
        "amount": "125.00",
        "amount_includes_tax": false,
        "class_id": "class_1001",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "expense_account_code": "VALIDATION_ERROR",
        "expense_account_id": "acc_1001",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "quantity": "1",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00"
      }
    ],
    "metadata": {},
    "payment_account_id": "acc_1001",
    "payment_method": "pay_1001",
    "payment_method_details": {},
    "payment_method_type": "check",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "tax_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001",
    "vendor_name": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "expense"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/expenses" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "125.00",
  "category": "cat_1001",
  "currency": "USD",
  "description": "Office supplies",
  "dimensions": {},
  "document_date": "2026-05-05",
  "effective_date": "2026-05-05",
  "expense_account_code": "VALIDATION_ERROR",
  "expense_account_id": "acc_1001",
  "expense_date": "2026-05-05",
  "form_1099_type": "form_1099_type_sample",
  "is_1099_eligible": false,
  "lines": [
    {
      "amount": "125.00",
      "amount_includes_tax": false,
      "class_id": "class_1001",
      "description": "Office supplies",
      "detail": {
        "account_id": "acc_1001",
        "basis_amount": "125.00",
        "class_id": "class_1001",
        "discount_amount": "125.00",
        "discount_percent": "discount_percent_sample",
        "item_id": "item_1001",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "quantity": "1",
        "sku": "SKU-1001",
        "subtotal_amount": "125.00",
        "type": "item",
        "unit_amount": "125.00"
      },
      "dimensions": {},
      "expense_account_code": "VALIDATION_ERROR",
      "expense_account_id": "acc_1001",
      "line_key": "line_key_sample",
      "line_number": 0,
      "line_type": "product",
      "location_id": "loc_1001",
      "metadata": {},
      "quantity": "1",
      "tax_amount": "125.00",
      "tax_code": "VALIDATION_ERROR",
      "tax_details": [
        {
          "allocation_ref": "loc_1001",
          "amount_includes_tax": false,
          "fulfillment_ref": "fulfillment_ref_sample",
          "jurisdiction_code": "VALIDATION_ERROR",
          "jurisdiction_level": "jurisdiction_level_sample",
          "jurisdiction_name": "Acme Supplies",
          "metadata": {},
          "provider_detail_ref": "provider_detail_ref_sample",
          "provider_key": "provider_key_sample",
          "provider_tax_rate_ref": "1.00",
          "rate": "1.00",
          "ship_from_ref": "ship_from_ref_sample",
          "ship_to_ref": "ship_to_ref_sample",
          "tax_amount": "125.00",
          "tax_code": "VALIDATION_ERROR",
          "tax_detail_ref": "tax_detail_ref_sample",
          "tax_name": "Acme Supplies",
          "tax_type": "tax_type_sample",
          "taxability_reason": "taxability_reason_sample",
          "taxable_amount": "125.00"
        }
      ],
      "tax_exempt_reason": "tax_exempt_reason_sample",
      "tax_rate": "1.00",
      "tax_status": "taxable",
      "taxable_amount": "125.00"
    }
  ],
  "metadata": {},
  "payment_account_id": "acc_1001",
  "payment_method": "pay_1001",
  "payment_method_details": {},
  "payment_method_type": "check",
  "status": "draft",
  "tax_amount": "125.00",
  "vendor_id": "ven_1001",
  "vendor_name": "ven_1001"
}'

GET /v1/expenses/{id}

Get an expense

Path parameters

Name	Type	Description
id required	string	Resource identifier

Query parameters

Name	Type	Description
include	string	Comma-separated extension field tokens: extension_fields.entity, extension_fields.line

Responses

200 Success

Field Type Description

data required ExpenseRecord A expense record as returned by the API

Show data fields

Field Type Description

amount required string Amount

category string Category

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

description string Description

dimensions object Dimensions

document_date string (date) Document Date

effective_date string (date) Effective Date

expense_account_code string Expense Account Code

expense_account_id string Expense Account ID

expense_date string (date) Expense Date

form_1099_type string 1099 Form Type

id string Canonical ID

is_1099_eligible boolean 1099 Eligible

line_items array of object Lines

Show line_items[] fields

Field Type Description

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

expense_account_code string Expense Account Code

expense_account_id string Expense Account ID

line_key string Line Key

line_number integer Line Number

line_type string Line Type

location_id string Location ID

metadata object Metadata

quantity string Quantity

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

metadata object Metadata

payment_account_id string Payment Account ID

payment_method string Payment Method

payment_method_details object Payment Method Details

payment_method_type string Payment Method Type

source_id required string Source ID

source_system required string Source System

status required string Status

tax_amount string Tax Amount

updated_at string (date-time)

vendor_id string Vendor ID

vendor_name string Vendor Name

id required string (uuid)

object required string

{
  "data": {
    "amount": "125.00",
    "category": "cat_1001",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "description": "Office supplies",
    "dimensions": {},
    "document_date": "2026-05-05",
    "effective_date": "2026-05-05",
    "expense_account_code": "VALIDATION_ERROR",
    "expense_account_id": "acc_1001",
    "expense_date": "2026-05-05",
    "form_1099_type": "form_1099_type_sample",
    "id": "00000000-0000-0000-0000-000000000000",
    "is_1099_eligible": false,
    "line_items": [
      {
        "amount": "125.00",
        "amount_includes_tax": false,
        "class_id": "class_1001",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "expense_account_code": "VALIDATION_ERROR",
        "expense_account_id": "acc_1001",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "quantity": "1",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00"
      }
    ],
    "metadata": {},
    "payment_account_id": "acc_1001",
    "payment_method": "pay_1001",
    "payment_method_details": {},
    "payment_method_type": "check",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "tax_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001",
    "vendor_name": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "expense"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/expenses/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

PUT /v1/expenses/{id}

Update an expense

Path parameters

Name	Type	Description
id required	string	Resource identifier

Request body required

Field Type Description

amount string Amount

category string Category

currency string Currency

description string Description

dimensions object Dimensions

document_date string (date) Document Date

effective_date string (date) Effective Date

expense_account_code string Expense Account Code

expense_account_id string Expense Account ID

expense_date string (date) Expense Date

form_1099_type string 1099 Form Type

is_1099_eligible boolean 1099 Eligible

lines array of object Lines

Show lines[] fields

Field Type Description

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

expense_account_code string Expense Account Code

expense_account_id string Expense Account ID

line_key string Line Key

line_number integer Line Number

line_type string Line Type

location_id string Location ID

metadata object Metadata

quantity string Quantity

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

metadata object Metadata

payment_account_id string Payment Account ID

payment_method string Payment Method

payment_method_details object Payment Method Details

payment_method_type string Payment Method Type

status string Status

tax_amount string Tax Amount

vendor_id string Vendor ID

vendor_name string Vendor Name

{
  "amount": "125.00",
  "category": "cat_1001",
  "currency": "USD",
  "description": "Office supplies",
  "dimensions": {},
  "document_date": "2026-05-05",
  "effective_date": "2026-05-05",
  "expense_account_code": "VALIDATION_ERROR",
  "expense_account_id": "acc_1001",
  "expense_date": "2026-05-05",
  "form_1099_type": "form_1099_type_sample",
  "is_1099_eligible": false,
  "lines": [
    {
      "amount": "125.00",
      "amount_includes_tax": false,
      "class_id": "class_1001",
      "description": "Office supplies",
      "detail": {
        "account_id": "acc_1001",
        "basis_amount": "125.00",
        "class_id": "class_1001",
        "discount_amount": "125.00",
        "discount_percent": "discount_percent_sample",
        "item_id": "item_1001",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "quantity": "1",
        "sku": "SKU-1001",
        "subtotal_amount": "125.00",
        "type": "item",
        "unit_amount": "125.00"
      },
      "dimensions": {},
      "expense_account_code": "VALIDATION_ERROR",
      "expense_account_id": "acc_1001",
      "line_key": "line_key_sample",
      "line_number": 0,
      "line_type": "product",
      "location_id": "loc_1001",
      "metadata": {},
      "quantity": "1",
      "tax_amount": "125.00",
      "tax_code": "VALIDATION_ERROR",
      "tax_details": [
        {
          "allocation_ref": "loc_1001",
          "amount_includes_tax": false,
          "fulfillment_ref": "fulfillment_ref_sample",
          "jurisdiction_code": "VALIDATION_ERROR",
          "jurisdiction_level": "jurisdiction_level_sample",
          "jurisdiction_name": "Acme Supplies",
          "metadata": {},
          "provider_detail_ref": "provider_detail_ref_sample",
          "provider_key": "provider_key_sample",
          "provider_tax_rate_ref": "1.00",
          "rate": "1.00",
          "ship_from_ref": "ship_from_ref_sample",
          "ship_to_ref": "ship_to_ref_sample",
          "tax_amount": "125.00",
          "tax_code": "VALIDATION_ERROR",
          "tax_detail_ref": "tax_detail_ref_sample",
          "tax_name": "Acme Supplies",
          "tax_type": "tax_type_sample",
          "taxability_reason": "taxability_reason_sample",
          "taxable_amount": "125.00"
        }
      ],
      "tax_exempt_reason": "tax_exempt_reason_sample",
      "tax_rate": "1.00",
      "tax_status": "taxable",
      "taxable_amount": "125.00"
    }
  ],
  "metadata": {},
  "payment_account_id": "acc_1001",
  "payment_method": "pay_1001",
  "payment_method_details": {},
  "payment_method_type": "check",
  "status": "draft",
  "tax_amount": "125.00",
  "vendor_id": "ven_1001",
  "vendor_name": "ven_1001"
}

Responses

200 Success

Field Type Description

data required ExpenseRecord A expense record as returned by the API

Show data fields

Field Type Description

amount required string Amount

category string Category

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

description string Description

dimensions object Dimensions

document_date string (date) Document Date

effective_date string (date) Effective Date

expense_account_code string Expense Account Code

expense_account_id string Expense Account ID

expense_date string (date) Expense Date

form_1099_type string 1099 Form Type

id string Canonical ID

is_1099_eligible boolean 1099 Eligible

line_items array of object Lines

Show line_items[] fields

Field Type Description

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

expense_account_code string Expense Account Code

expense_account_id string Expense Account ID

line_key string Line Key

line_number integer Line Number

line_type string Line Type

location_id string Location ID

metadata object Metadata

quantity string Quantity

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

metadata object Metadata

payment_account_id string Payment Account ID

payment_method string Payment Method

payment_method_details object Payment Method Details

payment_method_type string Payment Method Type

source_id required string Source ID

source_system required string Source System

status required string Status

tax_amount string Tax Amount

updated_at string (date-time)

vendor_id string Vendor ID

vendor_name string Vendor Name

id required string (uuid)

object required string

{
  "data": {
    "amount": "125.00",
    "category": "cat_1001",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "description": "Office supplies",
    "dimensions": {},
    "document_date": "2026-05-05",
    "effective_date": "2026-05-05",
    "expense_account_code": "VALIDATION_ERROR",
    "expense_account_id": "acc_1001",
    "expense_date": "2026-05-05",
    "form_1099_type": "form_1099_type_sample",
    "id": "00000000-0000-0000-0000-000000000000",
    "is_1099_eligible": false,
    "line_items": [
      {
        "amount": "125.00",
        "amount_includes_tax": false,
        "class_id": "class_1001",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "expense_account_code": "VALIDATION_ERROR",
        "expense_account_id": "acc_1001",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "quantity": "1",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00"
      }
    ],
    "metadata": {},
    "payment_account_id": "acc_1001",
    "payment_method": "pay_1001",
    "payment_method_details": {},
    "payment_method_type": "check",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "tax_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001",
    "vendor_name": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "expense"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X PUT "https://api.backfill.io/v1/expenses/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "125.00",
  "category": "cat_1001",
  "currency": "USD",
  "description": "Office supplies",
  "dimensions": {},
  "document_date": "2026-05-05",
  "effective_date": "2026-05-05",
  "expense_account_code": "VALIDATION_ERROR",
  "expense_account_id": "acc_1001",
  "expense_date": "2026-05-05",
  "form_1099_type": "form_1099_type_sample",
  "is_1099_eligible": false,
  "lines": [
    {
      "amount": "125.00",
      "amount_includes_tax": false,
      "class_id": "class_1001",
      "description": "Office supplies",
      "detail": {
        "account_id": "acc_1001",
        "basis_amount": "125.00",
        "class_id": "class_1001",
        "discount_amount": "125.00",
        "discount_percent": "discount_percent_sample",
        "item_id": "item_1001",
        "location_id": "loc_1001",
        "metadata": {},
        "product": {},
        "quantity": "1",
        "sku": "SKU-1001",
        "subtotal_amount": "125.00",
        "type": "item",
        "unit_amount": "125.00"
      },
      "dimensions": {},
      "expense_account_code": "VALIDATION_ERROR",
      "expense_account_id": "acc_1001",
      "line_key": "line_key_sample",
      "line_number": 0,
      "line_type": "product",
      "location_id": "loc_1001",
      "metadata": {},
      "quantity": "1",
      "tax_amount": "125.00",
      "tax_code": "VALIDATION_ERROR",
      "tax_details": [
        {
          "allocation_ref": "loc_1001",
          "amount_includes_tax": false,
          "fulfillment_ref": "fulfillment_ref_sample",
          "jurisdiction_code": "VALIDATION_ERROR",
          "jurisdiction_level": "jurisdiction_level_sample",
          "jurisdiction_name": "Acme Supplies",
          "metadata": {},
          "provider_detail_ref": "provider_detail_ref_sample",
          "provider_key": "provider_key_sample",
          "provider_tax_rate_ref": "1.00",
          "rate": "1.00",
          "ship_from_ref": "ship_from_ref_sample",
          "ship_to_ref": "ship_to_ref_sample",
          "tax_amount": "125.00",
          "tax_code": "VALIDATION_ERROR",
          "tax_detail_ref": "tax_detail_ref_sample",
          "tax_name": "Acme Supplies",
          "tax_type": "tax_type_sample",
          "taxability_reason": "taxability_reason_sample",
          "taxable_amount": "125.00"
        }
      ],
      "tax_exempt_reason": "tax_exempt_reason_sample",
      "tax_rate": "1.00",
      "tax_status": "taxable",
      "taxable_amount": "125.00"
    }
  ],
  "metadata": {},
  "payment_account_id": "acc_1001",
  "payment_method": "pay_1001",
  "payment_method_details": {},
  "payment_method_type": "check",
  "status": "draft",
  "tax_amount": "125.00",
  "vendor_id": "ven_1001",
  "vendor_name": "ven_1001"
}'

DELETE /v1/expenses/{id}

Delete an expense

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Deleted

Field	Type	Description
deleted required	boolean
id required	string (uuid)
object required	string

{
  "deleted": true,
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "record"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X DELETE "https://api.backfill.io/v1/expenses/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/expenses/{id}/approve

Approve a pending document

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required ExpenseRecord A expense record as returned by the API

Show data fields

Field Type Description

amount required string Amount

category string Category

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

description string Description

dimensions object Dimensions

document_date string (date) Document Date

effective_date string (date) Effective Date

expense_account_code string Expense Account Code

expense_account_id string Expense Account ID

expense_date string (date) Expense Date

form_1099_type string 1099 Form Type

id string Canonical ID

is_1099_eligible boolean 1099 Eligible

line_items array of object Lines

Show line_items[] fields

Field Type Description

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

expense_account_code string Expense Account Code

expense_account_id string Expense Account ID

line_key string Line Key

line_number integer Line Number

line_type string Line Type

location_id string Location ID

metadata object Metadata

quantity string Quantity

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

metadata object Metadata

payment_account_id string Payment Account ID

payment_method string Payment Method

payment_method_details object Payment Method Details

payment_method_type string Payment Method Type

source_id required string Source ID

source_system required string Source System

status required string Status

tax_amount string Tax Amount

updated_at string (date-time)

vendor_id string Vendor ID

vendor_name string Vendor Name

id required string (uuid)

object required string

{
  "data": {
    "amount": "125.00",
    "category": "cat_1001",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "description": "Office supplies",
    "dimensions": {},
    "document_date": "2026-05-05",
    "effective_date": "2026-05-05",
    "expense_account_code": "VALIDATION_ERROR",
    "expense_account_id": "acc_1001",
    "expense_date": "2026-05-05",
    "form_1099_type": "form_1099_type_sample",
    "id": "00000000-0000-0000-0000-000000000000",
    "is_1099_eligible": false,
    "line_items": [
      {
        "amount": "125.00",
        "amount_includes_tax": false,
        "class_id": "class_1001",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "expense_account_code": "VALIDATION_ERROR",
        "expense_account_id": "acc_1001",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "quantity": "1",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00"
      }
    ],
    "metadata": {},
    "payment_account_id": "acc_1001",
    "payment_method": "pay_1001",
    "payment_method_details": {},
    "payment_method_type": "check",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "tax_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001",
    "vendor_name": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "expense"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/expenses/{id}/approve" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/expenses/{id}/reject

Reject a pending document

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required ExpenseRecord A expense record as returned by the API

Show data fields

Field Type Description

amount required string Amount

category string Category

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

description string Description

dimensions object Dimensions

document_date string (date) Document Date

effective_date string (date) Effective Date

expense_account_code string Expense Account Code

expense_account_id string Expense Account ID

expense_date string (date) Expense Date

form_1099_type string 1099 Form Type

id string Canonical ID

is_1099_eligible boolean 1099 Eligible

line_items array of object Lines

Show line_items[] fields

Field Type Description

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

expense_account_code string Expense Account Code

expense_account_id string Expense Account ID

line_key string Line Key

line_number integer Line Number

line_type string Line Type

location_id string Location ID

metadata object Metadata

quantity string Quantity

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

metadata object Metadata

payment_account_id string Payment Account ID

payment_method string Payment Method

payment_method_details object Payment Method Details

payment_method_type string Payment Method Type

source_id required string Source ID

source_system required string Source System

status required string Status

tax_amount string Tax Amount

updated_at string (date-time)

vendor_id string Vendor ID

vendor_name string Vendor Name

id required string (uuid)

object required string

{
  "data": {
    "amount": "125.00",
    "category": "cat_1001",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "description": "Office supplies",
    "dimensions": {},
    "document_date": "2026-05-05",
    "effective_date": "2026-05-05",
    "expense_account_code": "VALIDATION_ERROR",
    "expense_account_id": "acc_1001",
    "expense_date": "2026-05-05",
    "form_1099_type": "form_1099_type_sample",
    "id": "00000000-0000-0000-0000-000000000000",
    "is_1099_eligible": false,
    "line_items": [
      {
        "amount": "125.00",
        "amount_includes_tax": false,
        "class_id": "class_1001",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "expense_account_code": "VALIDATION_ERROR",
        "expense_account_id": "acc_1001",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "quantity": "1",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00"
      }
    ],
    "metadata": {},
    "payment_account_id": "acc_1001",
    "payment_method": "pay_1001",
    "payment_method_details": {},
    "payment_method_type": "check",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "tax_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001",
    "vendor_name": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "expense"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/expenses/{id}/reject" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/expenses/{id}/submit

Submit a document for approval

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required ExpenseRecord A expense record as returned by the API

Show data fields

Field Type Description

amount required string Amount

category string Category

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

description string Description

dimensions object Dimensions

document_date string (date) Document Date

effective_date string (date) Effective Date

expense_account_code string Expense Account Code

expense_account_id string Expense Account ID

expense_date string (date) Expense Date

form_1099_type string 1099 Form Type

id string Canonical ID

is_1099_eligible boolean 1099 Eligible

line_items array of object Lines

Show line_items[] fields

Field Type Description

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

expense_account_code string Expense Account Code

expense_account_id string Expense Account ID

line_key string Line Key

line_number integer Line Number

line_type string Line Type

location_id string Location ID

metadata object Metadata

quantity string Quantity

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

metadata object Metadata

payment_account_id string Payment Account ID

payment_method string Payment Method

payment_method_details object Payment Method Details

payment_method_type string Payment Method Type

source_id required string Source ID

source_system required string Source System

status required string Status

tax_amount string Tax Amount

updated_at string (date-time)

vendor_id string Vendor ID

vendor_name string Vendor Name

id required string (uuid)

object required string

{
  "data": {
    "amount": "125.00",
    "category": "cat_1001",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "description": "Office supplies",
    "dimensions": {},
    "document_date": "2026-05-05",
    "effective_date": "2026-05-05",
    "expense_account_code": "VALIDATION_ERROR",
    "expense_account_id": "acc_1001",
    "expense_date": "2026-05-05",
    "form_1099_type": "form_1099_type_sample",
    "id": "00000000-0000-0000-0000-000000000000",
    "is_1099_eligible": false,
    "line_items": [
      {
        "amount": "125.00",
        "amount_includes_tax": false,
        "class_id": "class_1001",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "expense_account_code": "VALIDATION_ERROR",
        "expense_account_id": "acc_1001",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "quantity": "1",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00"
      }
    ],
    "metadata": {},
    "payment_account_id": "acc_1001",
    "payment_method": "pay_1001",
    "payment_method_details": {},
    "payment_method_type": "check",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "tax_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001",
    "vendor_name": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "expense"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/expenses/{id}/submit" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/expenses/{id}/void

Void a document

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required ExpenseRecord A expense record as returned by the API

Show data fields

Field Type Description

amount required string Amount

category string Category

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

description string Description

dimensions object Dimensions

document_date string (date) Document Date

effective_date string (date) Effective Date

expense_account_code string Expense Account Code

expense_account_id string Expense Account ID

expense_date string (date) Expense Date

form_1099_type string 1099 Form Type

id string Canonical ID

is_1099_eligible boolean 1099 Eligible

line_items array of object Lines

Show line_items[] fields

Field Type Description

amount string Amount

amount_includes_tax boolean Amount Includes Tax

class_id string Class ID

description string Description

detail object Line Detail

Show detail fields

Field	Type	Description
account_id	string	Account ID
basis_amount	string	Basis Amount
class_id	string	Class ID
discount_amount	string	Discount Amount
discount_percent	string	Discount Percent
item_id	string	Item ID
location_id	string	Location ID
metadata	object	Metadata
product	object	Product
quantity	string	Quantity
sku	string	SKU
subtotal_amount	string	Subtotal Amount
type required	string	Detail Type
unit_amount	string	Unit Amount

dimensions object Dimensions

expense_account_code string Expense Account Code

expense_account_id string Expense Account ID

line_key string Line Key

line_number integer Line Number

line_type string Line Type

location_id string Location ID

metadata object Metadata

quantity string Quantity

tax_amount string Tax Amount

tax_code string Tax Code

tax_details array of object Tax Details

Show tax_details[] fields

Field	Type	Description
allocation_ref	string	Allocation Ref
amount_includes_tax required	boolean	Amount Includes Tax
fulfillment_ref	string	Fulfillment Ref
jurisdiction_code	string	Jurisdiction Code
jurisdiction_level	string	Jurisdiction Level
jurisdiction_name	string	Jurisdiction Name
metadata	object	Metadata
provider_detail_ref	string	Provider Detail Ref
provider_key	string	Provider Key
provider_tax_rate_ref	string	Provider Tax Rate Ref
rate	string	Rate
ship_from_ref	string	Ship From Ref
ship_to_ref	string	Ship To Ref
tax_amount required	string	Tax Amount
tax_code	string	Tax Code
tax_detail_ref required	string	Tax Detail Ref
tax_name	string	Tax Name
tax_type	string	Tax Type
taxability_reason	string	Taxability Reason
taxable_amount	string	Taxable Amount

tax_exempt_reason string Tax Exempt Reason

tax_rate string Tax Rate

tax_status string Tax Status

taxable_amount string Taxable Amount

metadata object Metadata

payment_account_id string Payment Account ID

payment_method string Payment Method

payment_method_details object Payment Method Details

payment_method_type string Payment Method Type

source_id required string Source ID

source_system required string Source System

status required string Status

tax_amount string Tax Amount

updated_at string (date-time)

vendor_id string Vendor ID

vendor_name string Vendor Name

id required string (uuid)

object required string

{
  "data": {
    "amount": "125.00",
    "category": "cat_1001",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "description": "Office supplies",
    "dimensions": {},
    "document_date": "2026-05-05",
    "effective_date": "2026-05-05",
    "expense_account_code": "VALIDATION_ERROR",
    "expense_account_id": "acc_1001",
    "expense_date": "2026-05-05",
    "form_1099_type": "form_1099_type_sample",
    "id": "00000000-0000-0000-0000-000000000000",
    "is_1099_eligible": false,
    "line_items": [
      {
        "amount": "125.00",
        "amount_includes_tax": false,
        "class_id": "class_1001",
        "description": "Office supplies",
        "detail": {
          "account_id": "acc_1001",
          "basis_amount": "125.00",
          "class_id": "class_1001",
          "discount_amount": "125.00",
          "discount_percent": "discount_percent_sample",
          "item_id": "item_1001",
          "location_id": "loc_1001",
          "metadata": {},
          "product": {},
          "quantity": "1",
          "sku": "SKU-1001",
          "subtotal_amount": "125.00",
          "type": "item",
          "unit_amount": "125.00"
        },
        "dimensions": {},
        "expense_account_code": "VALIDATION_ERROR",
        "expense_account_id": "acc_1001",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "quantity": "1",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "tax_details": [
          {
            "allocation_ref": "loc_1001",
            "amount_includes_tax": false,
            "fulfillment_ref": "fulfillment_ref_sample",
            "jurisdiction_code": "VALIDATION_ERROR",
            "jurisdiction_level": "jurisdiction_level_sample",
            "jurisdiction_name": "Acme Supplies",
            "metadata": {},
            "provider_detail_ref": "provider_detail_ref_sample",
            "provider_key": "provider_key_sample",
            "provider_tax_rate_ref": "1.00",
            "rate": "1.00",
            "ship_from_ref": "ship_from_ref_sample",
            "ship_to_ref": "ship_to_ref_sample",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "tax_detail_ref": "tax_detail_ref_sample",
            "tax_name": "Acme Supplies",
            "tax_type": "tax_type_sample",
            "taxability_reason": "taxability_reason_sample",
            "taxable_amount": "125.00"
          }
        ],
        "tax_exempt_reason": "tax_exempt_reason_sample",
        "tax_rate": "1.00",
        "tax_status": "taxable",
        "taxable_amount": "125.00"
      }
    ],
    "metadata": {},
    "payment_account_id": "acc_1001",
    "payment_method": "pay_1001",
    "payment_method_details": {},
    "payment_method_type": "check",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "tax_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001",
    "vendor_name": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "expense"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/expenses/{id}/void" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

Vendor Credits

GET /v1/vendor_credits

List vendor credits

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
sort	string	Sort by a whitelisted field. Prefix with '-' for descending order, e.g. '-created_at'.
status	string	Filter by display status
approval_status	string	Filter by approval status
application_status	string	Filter by application status
vendor_id	string	Filter by vendor UUID
start_date	string	Filter by credit_date >= (YYYY-MM-DD)
end_date	string	Filter by credit_date <= (YYYY-MM-DD)
include	string	Comma-separated extension field tokens: extension_fields.entity, extension_fields.line

Responses

200 Success

Field Type Description

data required array of RecordEnvelope

Show data[] fields

Field	Type	Description
data required	object
id required	string (uuid)
object required	string

object required string

pagination required Pagination

Show pagination fields

Field	Type	Description
has_more required	boolean
limit required	integer
page required	integer
total_count required	integer

{
  "data": [
    {
      "data": {
        "amount_remaining": "125.00",
        "application_status": "open",
        "approval_status": "draft",
        "created_at": "2026-05-05T12:00:00Z",
        "credit_date": "2026-05-05",
        "credit_id": "credit_id_sample",
        "currency": "USD",
        "description": "Office supplies",
        "document_date": "2026-05-05",
        "document_number": "INV-1001",
        "effective_date": "2026-05-05",
        "lines": [
          {
            "account_code": "VALIDATION_ERROR",
            "account_id": "acc_1001",
            "amount": "125.00",
            "bill_line_ref": "bill_line_ref_sample",
            "class_id": "class_1001",
            "description": "Office supplies",
            "dimensions": {},
            "line_key": "line_key_sample",
            "line_number": 0,
            "line_type": "product",
            "location_id": "loc_1001",
            "metadata": {},
            "quantity": "1",
            "reason_code": "VALIDATION_ERROR",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "unit_amount": "125.00"
          }
        ],
        "metadata": {},
        "source_system": "api",
        "total_amount": "125.00",
        "updated_at": "2026-05-05T12:00:00Z",
        "vendor_id": "ven_1001",
        "vendor_name": "ven_1001"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "object": "vendor_credit"
    }
  ],
  "object": "list",
  "pagination": {
    "has_more": false,
    "limit": 0,
    "page": 0,
    "total_count": 0
  }
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/vendor_credits" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/vendor_credits

Create a vendor credit

Request body required

Field	Type	Description
credit_date	string (date)	Credit Date
currency required	string	Currency
description	string	Description
document_date	string (date)	Document Date
document_number	string	Number
effective_date	string (date)	Effective Date
metadata	object
total_amount required	string	Total
vendor_id	string	Vendor ID
vendor_name	string	Vendor

{
  "credit_date": "2026-05-05",
  "currency": "USD",
  "description": "Office supplies",
  "document_date": "2026-05-05",
  "document_number": "INV-1001",
  "effective_date": "2026-05-05",
  "metadata": {},
  "total_amount": "125.00",
  "vendor_id": "ven_1001",
  "vendor_name": "ven_1001"
}

Responses

201 Created

Field Type Description

data required VendorCreditRecord A vendor_credit record as returned by the API

Show data fields

Field Type Description

amount_remaining string Remaining

application_status string Application

approval_status string Status

created_at string (date-time)

credit_date string (date) Credit Date

credit_id required string Credit ID

currency required string Currency

description string Description

document_date string (date) Document Date

document_number string Number

effective_date string (date) Effective Date

lines array of object Lines

Show lines[] fields

Field	Type	Description
account_code	string	Account Code
account_id	string	Account ID
amount	string	Amount
bill_line_ref	string	Bill Line Ref
class_id	string	Class ID
description	string	Description
dimensions	object	Dimensions
line_key	string	Line Key
line_number	integer	Line Number
line_type	string	Line Type
location_id	string	Location ID
metadata	object	Metadata
quantity	string	Quantity
reason_code	string	Reason Code
tax_amount	string	Tax Amount
tax_code	string	Tax Code
unit_amount	string	Unit Amount

metadata object

source_system string Source

total_amount required string Total

updated_at string (date-time)

vendor_id string Vendor ID

vendor_name string Vendor

id required string (uuid)

object required string

{
  "data": {
    "amount_remaining": "125.00",
    "application_status": "open",
    "approval_status": "draft",
    "created_at": "2026-05-05T12:00:00Z",
    "credit_date": "2026-05-05",
    "credit_id": "credit_id_sample",
    "currency": "USD",
    "description": "Office supplies",
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "effective_date": "2026-05-05",
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "amount": "125.00",
        "bill_line_ref": "bill_line_ref_sample",
        "class_id": "class_1001",
        "description": "Office supplies",
        "dimensions": {},
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "quantity": "1",
        "reason_code": "VALIDATION_ERROR",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "source_system": "api",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001",
    "vendor_name": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "vendor_credit"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/vendor_credits" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "credit_date": "2026-05-05",
  "currency": "USD",
  "description": "Office supplies",
  "document_date": "2026-05-05",
  "document_number": "INV-1001",
  "effective_date": "2026-05-05",
  "metadata": {},
  "total_amount": "125.00",
  "vendor_id": "ven_1001",
  "vendor_name": "ven_1001"
}'

GET /v1/vendor_credits/{id}

Get a vendor credit

Path parameters

Name	Type	Description
id required	string	Resource identifier

Query parameters

Name	Type	Description
include	string	Comma-separated extension field tokens: extension_fields.entity, extension_fields.line

Responses

200 Success

Field Type Description

data required VendorCreditRecord A vendor_credit record as returned by the API

Show data fields

Field Type Description

amount_remaining string Remaining

application_status string Application

approval_status string Status

created_at string (date-time)

credit_date string (date) Credit Date

credit_id required string Credit ID

currency required string Currency

description string Description

document_date string (date) Document Date

document_number string Number

effective_date string (date) Effective Date

lines array of object Lines

Show lines[] fields

Field	Type	Description
account_code	string	Account Code
account_id	string	Account ID
amount	string	Amount
bill_line_ref	string	Bill Line Ref
class_id	string	Class ID
description	string	Description
dimensions	object	Dimensions
line_key	string	Line Key
line_number	integer	Line Number
line_type	string	Line Type
location_id	string	Location ID
metadata	object	Metadata
quantity	string	Quantity
reason_code	string	Reason Code
tax_amount	string	Tax Amount
tax_code	string	Tax Code
unit_amount	string	Unit Amount

metadata object

source_system string Source

total_amount required string Total

updated_at string (date-time)

vendor_id string Vendor ID

vendor_name string Vendor

id required string (uuid)

object required string

{
  "data": {
    "amount_remaining": "125.00",
    "application_status": "open",
    "approval_status": "draft",
    "created_at": "2026-05-05T12:00:00Z",
    "credit_date": "2026-05-05",
    "credit_id": "credit_id_sample",
    "currency": "USD",
    "description": "Office supplies",
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "effective_date": "2026-05-05",
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "amount": "125.00",
        "bill_line_ref": "bill_line_ref_sample",
        "class_id": "class_1001",
        "description": "Office supplies",
        "dimensions": {},
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "quantity": "1",
        "reason_code": "VALIDATION_ERROR",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "source_system": "api",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001",
    "vendor_name": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "vendor_credit"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/vendor_credits/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

PUT /v1/vendor_credits/{id}

Update a vendor credit

Path parameters

Name	Type	Description
id required	string	Resource identifier

Request body required

Field	Type	Description
credit_date	string (date)	Credit Date
currency	string	Currency
description	string	Description
document_date	string (date)	Document Date
document_number	string	Number
effective_date	string (date)	Effective Date
metadata	object
total_amount	string	Total
vendor_id	string	Vendor ID
vendor_name	string	Vendor

{
  "credit_date": "2026-05-05",
  "currency": "USD",
  "description": "Office supplies",
  "document_date": "2026-05-05",
  "document_number": "INV-1001",
  "effective_date": "2026-05-05",
  "metadata": {},
  "total_amount": "125.00",
  "vendor_id": "ven_1001",
  "vendor_name": "ven_1001"
}

Responses

200 Success

Field Type Description

data required VendorCreditRecord A vendor_credit record as returned by the API

Show data fields

Field Type Description

amount_remaining string Remaining

application_status string Application

approval_status string Status

created_at string (date-time)

credit_date string (date) Credit Date

credit_id required string Credit ID

currency required string Currency

description string Description

document_date string (date) Document Date

document_number string Number

effective_date string (date) Effective Date

lines array of object Lines

Show lines[] fields

Field	Type	Description
account_code	string	Account Code
account_id	string	Account ID
amount	string	Amount
bill_line_ref	string	Bill Line Ref
class_id	string	Class ID
description	string	Description
dimensions	object	Dimensions
line_key	string	Line Key
line_number	integer	Line Number
line_type	string	Line Type
location_id	string	Location ID
metadata	object	Metadata
quantity	string	Quantity
reason_code	string	Reason Code
tax_amount	string	Tax Amount
tax_code	string	Tax Code
unit_amount	string	Unit Amount

metadata object

source_system string Source

total_amount required string Total

updated_at string (date-time)

vendor_id string Vendor ID

vendor_name string Vendor

id required string (uuid)

object required string

{
  "data": {
    "amount_remaining": "125.00",
    "application_status": "open",
    "approval_status": "draft",
    "created_at": "2026-05-05T12:00:00Z",
    "credit_date": "2026-05-05",
    "credit_id": "credit_id_sample",
    "currency": "USD",
    "description": "Office supplies",
    "document_date": "2026-05-05",
    "document_number": "INV-1001",
    "effective_date": "2026-05-05",
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "amount": "125.00",
        "bill_line_ref": "bill_line_ref_sample",
        "class_id": "class_1001",
        "description": "Office supplies",
        "dimensions": {},
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "quantity": "1",
        "reason_code": "VALIDATION_ERROR",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "source_system": "api",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001",
    "vendor_name": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "vendor_credit"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X PUT "https://api.backfill.io/v1/vendor_credits/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "credit_date": "2026-05-05",
  "currency": "USD",
  "description": "Office supplies",
  "document_date": "2026-05-05",
  "document_number": "INV-1001",
  "effective_date": "2026-05-05",
  "metadata": {},
  "total_amount": "125.00",
  "vendor_id": "ven_1001",
  "vendor_name": "ven_1001"
}'

DELETE /v1/vendor_credits/{id}

Delete a vendor credit

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Deleted

Field	Type	Description
deleted required	boolean
id required	string (uuid)
object required	string

{
  "deleted": true,
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "record"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X DELETE "https://api.backfill.io/v1/vendor_credits/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

Quotes

GET /v1/quotes

List quotes

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
sort	string	Sort by a whitelisted field. Prefix with '-' for descending order, e.g. '-created_at'.
status	string	Filter by status
approval_status	string	Filter by approval status
customer_id	string	Filter by customer UUID
start_date	string	Filter by issued_at >= (YYYY-MM-DD)
end_date	string	Filter by issued_at <= (YYYY-MM-DD)
include	string	Comma-separated extension field tokens: extension_fields.entity, extension_fields.line

Responses

200 Success

Field Type Description

data required array of RecordEnvelope

Show data[] fields

Field	Type	Description
data required	object
id required	string (uuid)
object required	string

object required string

pagination required Pagination

Show pagination fields

Field	Type	Description
has_more required	boolean
limit required	integer
page required	integer
total_count required	integer

{
  "data": [
    {
      "data": {
        "approval_status": "draft",
        "created_at": "2026-05-05T12:00:00Z",
        "currency": "USD",
        "customer_id": "cus_1001",
        "customer_name": "cus_1001",
        "description": "Office supplies",
        "document_number": "INV-1001",
        "expires_at": "2026-05-05T12:00:00Z",
        "issued_at": "2026-05-05T12:00:00Z",
        "lines": [
          {
            "account_code": "VALIDATION_ERROR",
            "account_id": "acc_1001",
            "amount": "125.00",
            "class_id": "class_1001",
            "description": "Office supplies",
            "dimensions": {},
            "line_key": "line_key_sample",
            "line_number": 0,
            "line_type": "product",
            "location_id": "loc_1001",
            "metadata": {},
            "quantity": "1",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "unit_amount": "125.00"
          }
        ],
        "metadata": {},
        "quote_id": "quote_id_sample",
        "source_system": "api",
        "status": "draft",
        "total_amount": "125.00",
        "updated_at": "2026-05-05T12:00:00Z"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "object": "quote"
    }
  ],
  "object": "list",
  "pagination": {
    "has_more": false,
    "limit": 0,
    "page": 0,
    "total_count": 0
  }
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/quotes" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/quotes

Create a quote

Request body required

Field	Type	Description
currency required	string	Currency
customer_id	string	Customer ID
customer_name	string	Customer
description	string	Description
document_number	string	Number
expires_at	string (date-time)	Expires
issued_at	string (date-time)	Issue Date
metadata	object
status	string	Status
total_amount required	string	Total

{
  "currency": "USD",
  "customer_id": "cus_1001",
  "customer_name": "cus_1001",
  "description": "Office supplies",
  "document_number": "INV-1001",
  "expires_at": "2026-05-05T12:00:00Z",
  "issued_at": "2026-05-05T12:00:00Z",
  "metadata": {},
  "status": "draft",
  "total_amount": "125.00"
}

Responses

201 Created

Field Type Description

data required QuoteRecord A quote record as returned by the API

Show data fields

Field Type Description

approval_status string Approval

created_at string (date-time)

currency required string Currency

customer_id string Customer ID

customer_name string Customer

description string Description

document_number string Number

expires_at string (date-time) Expires

issued_at string (date-time) Issue Date

lines array of object Lines

Show lines[] fields

Field	Type	Description
account_code	string	Account Code
account_id	string	Account ID
amount	string	Amount
class_id	string	Class ID
description	string	Description
dimensions	object	Dimensions
line_key	string	Line Key
line_number	integer	Line Number
line_type	string	Line Type
location_id	string	Location ID
metadata	object	Metadata
quantity	string	Quantity
tax_amount	string	Tax Amount
tax_code	string	Tax Code
unit_amount	string	Unit Amount

metadata object

quote_id required string Quote ID

source_system string Source

status string Status

total_amount required string Total

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "customer_name": "cus_1001",
    "description": "Office supplies",
    "document_number": "INV-1001",
    "expires_at": "2026-05-05T12:00:00Z",
    "issued_at": "2026-05-05T12:00:00Z",
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "amount": "125.00",
        "class_id": "class_1001",
        "description": "Office supplies",
        "dimensions": {},
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "quantity": "1",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "quote_id": "quote_id_sample",
    "source_system": "api",
    "status": "draft",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "quote"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/quotes" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "currency": "USD",
  "customer_id": "cus_1001",
  "customer_name": "cus_1001",
  "description": "Office supplies",
  "document_number": "INV-1001",
  "expires_at": "2026-05-05T12:00:00Z",
  "issued_at": "2026-05-05T12:00:00Z",
  "metadata": {},
  "status": "draft",
  "total_amount": "125.00"
}'

GET /v1/quotes/{id}

Get a quote

Path parameters

Name	Type	Description
id required	string	Resource identifier

Query parameters

Name	Type	Description
include	string	Comma-separated extension field tokens: extension_fields.entity, extension_fields.line

Responses

200 Success

Field Type Description

data required QuoteRecord A quote record as returned by the API

Show data fields

Field Type Description

approval_status string Approval

created_at string (date-time)

currency required string Currency

customer_id string Customer ID

customer_name string Customer

description string Description

document_number string Number

expires_at string (date-time) Expires

issued_at string (date-time) Issue Date

lines array of object Lines

Show lines[] fields

Field	Type	Description
account_code	string	Account Code
account_id	string	Account ID
amount	string	Amount
class_id	string	Class ID
description	string	Description
dimensions	object	Dimensions
line_key	string	Line Key
line_number	integer	Line Number
line_type	string	Line Type
location_id	string	Location ID
metadata	object	Metadata
quantity	string	Quantity
tax_amount	string	Tax Amount
tax_code	string	Tax Code
unit_amount	string	Unit Amount

metadata object

quote_id required string Quote ID

source_system string Source

status string Status

total_amount required string Total

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "customer_name": "cus_1001",
    "description": "Office supplies",
    "document_number": "INV-1001",
    "expires_at": "2026-05-05T12:00:00Z",
    "issued_at": "2026-05-05T12:00:00Z",
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "amount": "125.00",
        "class_id": "class_1001",
        "description": "Office supplies",
        "dimensions": {},
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "quantity": "1",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "quote_id": "quote_id_sample",
    "source_system": "api",
    "status": "draft",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "quote"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/quotes/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

PUT /v1/quotes/{id}

Update a quote

Path parameters

Name	Type	Description
id required	string	Resource identifier

Request body required

Field	Type	Description
currency	string	Currency
customer_id	string	Customer ID
customer_name	string	Customer
description	string	Description
document_number	string	Number
expires_at	string (date-time)	Expires
issued_at	string (date-time)	Issue Date
metadata	object
status	string	Status
total_amount	string	Total

{
  "currency": "USD",
  "customer_id": "cus_1001",
  "customer_name": "cus_1001",
  "description": "Office supplies",
  "document_number": "INV-1001",
  "expires_at": "2026-05-05T12:00:00Z",
  "issued_at": "2026-05-05T12:00:00Z",
  "metadata": {},
  "status": "draft",
  "total_amount": "125.00"
}

Responses

200 Success

Field Type Description

data required QuoteRecord A quote record as returned by the API

Show data fields

Field Type Description

approval_status string Approval

created_at string (date-time)

currency required string Currency

customer_id string Customer ID

customer_name string Customer

description string Description

document_number string Number

expires_at string (date-time) Expires

issued_at string (date-time) Issue Date

lines array of object Lines

Show lines[] fields

Field	Type	Description
account_code	string	Account Code
account_id	string	Account ID
amount	string	Amount
class_id	string	Class ID
description	string	Description
dimensions	object	Dimensions
line_key	string	Line Key
line_number	integer	Line Number
line_type	string	Line Type
location_id	string	Location ID
metadata	object	Metadata
quantity	string	Quantity
tax_amount	string	Tax Amount
tax_code	string	Tax Code
unit_amount	string	Unit Amount

metadata object

quote_id required string Quote ID

source_system string Source

status string Status

total_amount required string Total

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "customer_name": "cus_1001",
    "description": "Office supplies",
    "document_number": "INV-1001",
    "expires_at": "2026-05-05T12:00:00Z",
    "issued_at": "2026-05-05T12:00:00Z",
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "amount": "125.00",
        "class_id": "class_1001",
        "description": "Office supplies",
        "dimensions": {},
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "quantity": "1",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "quote_id": "quote_id_sample",
    "source_system": "api",
    "status": "draft",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "quote"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X PUT "https://api.backfill.io/v1/quotes/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "currency": "USD",
  "customer_id": "cus_1001",
  "customer_name": "cus_1001",
  "description": "Office supplies",
  "document_number": "INV-1001",
  "expires_at": "2026-05-05T12:00:00Z",
  "issued_at": "2026-05-05T12:00:00Z",
  "metadata": {},
  "status": "draft",
  "total_amount": "125.00"
}'

DELETE /v1/quotes/{id}

Delete a quote

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Deleted

Field	Type	Description
deleted required	boolean
id required	string (uuid)
object required	string

{
  "deleted": true,
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "record"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X DELETE "https://api.backfill.io/v1/quotes/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

Sales Orders

GET /v1/sales_orders

List sales orders

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
sort	string	Sort by a whitelisted field. Prefix with '-' for descending order, e.g. '-created_at'.
status	string	Filter by status
customer_id	string	Filter by customer UUID
start_date	string	Filter by issued_at >= (YYYY-MM-DD)
end_date	string	Filter by issued_at <= (YYYY-MM-DD)
include	string	Comma-separated extension field tokens: extension_fields.entity, extension_fields.line

Responses

200 Success

Field Type Description

data required array of RecordEnvelope

Show data[] fields

Field	Type	Description
data required	object
id required	string (uuid)
object required	string

object required string

pagination required Pagination

Show pagination fields

Field	Type	Description
has_more required	boolean
limit required	integer
page required	integer
total_count required	integer

{
  "data": [
    {
      "data": {
        "approval_status": "draft",
        "created_at": "2026-05-05T12:00:00Z",
        "currency": "USD",
        "customer_id": "cus_1001",
        "customer_name": "cus_1001",
        "document_number": "INV-1001",
        "issued_at": "2026-05-05T12:00:00Z",
        "lines": [
          {
            "account_code": "VALIDATION_ERROR",
            "account_id": "acc_1001",
            "amount": "125.00",
            "class_id": "class_1001",
            "description": "Office supplies",
            "dimensions": {},
            "fulfilled_quantity": "1",
            "invoiced_quantity": "1",
            "line_key": "line_key_sample",
            "line_number": 0,
            "line_type": "product",
            "location_id": "loc_1001",
            "metadata": {},
            "quantity": "1",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "unit_amount": "125.00"
          }
        ],
        "metadata": {},
        "sales_order_id": "sales_order_id_sample",
        "source_system": "api",
        "status": "draft",
        "total_amount": "125.00",
        "updated_at": "2026-05-05T12:00:00Z"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "object": "sales_order"
    }
  ],
  "object": "list",
  "pagination": {
    "has_more": false,
    "limit": 0,
    "page": 0,
    "total_count": 0
  }
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/sales_orders" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/sales_orders

Create a sales order

Request body required

Field	Type	Description
currency required	string	Currency
customer_id	string	Customer ID
document_number	string	Number
issued_at	string (date-time)	Issue Date
metadata	object
status	string	Status
total_amount required	string	Total

{
  "currency": "USD",
  "customer_id": "cus_1001",
  "document_number": "INV-1001",
  "issued_at": "2026-05-05T12:00:00Z",
  "metadata": {},
  "status": "draft",
  "total_amount": "125.00"
}

Responses

201 Created

Field Type Description

data required SalesOrderRecord A sales_order record as returned by the API

Show data fields

Field Type Description

approval_status string Approval

created_at string (date-time)

currency required string Currency

customer_id string Customer ID

customer_name string Customer

document_number string Number

issued_at string (date-time) Issue Date

lines array of object Lines

Show lines[] fields

Field	Type	Description
account_code	string	Account Code
account_id	string	Account ID
amount	string	Amount
class_id	string	Class ID
description	string	Description
dimensions	object	Dimensions
fulfilled_quantity	string	Fulfilled Quantity
invoiced_quantity	string	Invoiced Quantity
line_key	string	Line Key
line_number	integer	Line Number
line_type	string	Line Type
location_id	string	Location ID
metadata	object	Metadata
quantity	string	Quantity
tax_amount	string	Tax Amount
tax_code	string	Tax Code
unit_amount	string	Unit Amount

metadata object

sales_order_id required string Sales Order ID

source_system string Source

status string Status

total_amount required string Total

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "customer_name": "cus_1001",
    "document_number": "INV-1001",
    "issued_at": "2026-05-05T12:00:00Z",
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "amount": "125.00",
        "class_id": "class_1001",
        "description": "Office supplies",
        "dimensions": {},
        "fulfilled_quantity": "1",
        "invoiced_quantity": "1",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "quantity": "1",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "sales_order_id": "sales_order_id_sample",
    "source_system": "api",
    "status": "draft",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "sales_order"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/sales_orders" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "currency": "USD",
  "customer_id": "cus_1001",
  "document_number": "INV-1001",
  "issued_at": "2026-05-05T12:00:00Z",
  "metadata": {},
  "status": "draft",
  "total_amount": "125.00"
}'

GET /v1/sales_orders/{id}

Get a sales order

Path parameters

Name	Type	Description
id required	string	Resource identifier

Query parameters

Name	Type	Description
include	string	Comma-separated extension field tokens: extension_fields.entity, extension_fields.line

Responses

200 Success

Field Type Description

data required SalesOrderRecord A sales_order record as returned by the API

Show data fields

Field Type Description

approval_status string Approval

created_at string (date-time)

currency required string Currency

customer_id string Customer ID

customer_name string Customer

document_number string Number

issued_at string (date-time) Issue Date

lines array of object Lines

Show lines[] fields

Field	Type	Description
account_code	string	Account Code
account_id	string	Account ID
amount	string	Amount
class_id	string	Class ID
description	string	Description
dimensions	object	Dimensions
fulfilled_quantity	string	Fulfilled Quantity
invoiced_quantity	string	Invoiced Quantity
line_key	string	Line Key
line_number	integer	Line Number
line_type	string	Line Type
location_id	string	Location ID
metadata	object	Metadata
quantity	string	Quantity
tax_amount	string	Tax Amount
tax_code	string	Tax Code
unit_amount	string	Unit Amount

metadata object

sales_order_id required string Sales Order ID

source_system string Source

status string Status

total_amount required string Total

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "customer_name": "cus_1001",
    "document_number": "INV-1001",
    "issued_at": "2026-05-05T12:00:00Z",
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "amount": "125.00",
        "class_id": "class_1001",
        "description": "Office supplies",
        "dimensions": {},
        "fulfilled_quantity": "1",
        "invoiced_quantity": "1",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "quantity": "1",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "sales_order_id": "sales_order_id_sample",
    "source_system": "api",
    "status": "draft",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "sales_order"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/sales_orders/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

PUT /v1/sales_orders/{id}

Update a sales order

Path parameters

Name	Type	Description
id required	string	Resource identifier

Request body required

Field	Type	Description
currency	string	Currency
customer_id	string	Customer ID
document_number	string	Number
issued_at	string (date-time)	Issue Date
metadata	object
status	string	Status
total_amount	string	Total

{
  "currency": "USD",
  "customer_id": "cus_1001",
  "document_number": "INV-1001",
  "issued_at": "2026-05-05T12:00:00Z",
  "metadata": {},
  "status": "draft",
  "total_amount": "125.00"
}

Responses

200 Success

Field Type Description

data required SalesOrderRecord A sales_order record as returned by the API

Show data fields

Field Type Description

approval_status string Approval

created_at string (date-time)

currency required string Currency

customer_id string Customer ID

customer_name string Customer

document_number string Number

issued_at string (date-time) Issue Date

lines array of object Lines

Show lines[] fields

Field	Type	Description
account_code	string	Account Code
account_id	string	Account ID
amount	string	Amount
class_id	string	Class ID
description	string	Description
dimensions	object	Dimensions
fulfilled_quantity	string	Fulfilled Quantity
invoiced_quantity	string	Invoiced Quantity
line_key	string	Line Key
line_number	integer	Line Number
line_type	string	Line Type
location_id	string	Location ID
metadata	object	Metadata
quantity	string	Quantity
tax_amount	string	Tax Amount
tax_code	string	Tax Code
unit_amount	string	Unit Amount

metadata object

sales_order_id required string Sales Order ID

source_system string Source

status string Status

total_amount required string Total

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "customer_name": "cus_1001",
    "document_number": "INV-1001",
    "issued_at": "2026-05-05T12:00:00Z",
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "amount": "125.00",
        "class_id": "class_1001",
        "description": "Office supplies",
        "dimensions": {},
        "fulfilled_quantity": "1",
        "invoiced_quantity": "1",
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "quantity": "1",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "sales_order_id": "sales_order_id_sample",
    "source_system": "api",
    "status": "draft",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "sales_order"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X PUT "https://api.backfill.io/v1/sales_orders/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "currency": "USD",
  "customer_id": "cus_1001",
  "document_number": "INV-1001",
  "issued_at": "2026-05-05T12:00:00Z",
  "metadata": {},
  "status": "draft",
  "total_amount": "125.00"
}'

DELETE /v1/sales_orders/{id}

Delete a sales order

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Deleted

Field	Type	Description
deleted required	boolean
id required	string (uuid)
object required	string

{
  "deleted": true,
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "record"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X DELETE "https://api.backfill.io/v1/sales_orders/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

Purchase Orders

GET /v1/purchase_orders

List purchase orders

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
sort	string	Sort by a whitelisted field. Prefix with '-' for descending order, e.g. '-created_at'.
approval_status	string	Filter by approval status
vendor_id	string	Filter by vendor UUID
start_date	string	Filter by issued_at >= (YYYY-MM-DD)
end_date	string	Filter by issued_at <= (YYYY-MM-DD)
include	string	Comma-separated extension field tokens: extension_fields.entity, extension_fields.line

Responses

200 Success

Field Type Description

data required array of RecordEnvelope

Show data[] fields

Field	Type	Description
data required	object
id required	string (uuid)
object required	string

object required string

pagination required Pagination

Show pagination fields

Field	Type	Description
has_more required	boolean
limit required	integer
page required	integer
total_count required	integer

{
  "data": [
    {
      "data": {
        "approval_status": "draft",
        "created_at": "2026-05-05T12:00:00Z",
        "currency": "USD",
        "description": "Office supplies",
        "document_number": "INV-1001",
        "expected_date": "2026-05-05",
        "issued_at": "2026-05-05T12:00:00Z",
        "lines": [
          {
            "account_code": "VALIDATION_ERROR",
            "account_id": "acc_1001",
            "amount": "125.00",
            "billed_quantity": "1",
            "class_id": "class_1001",
            "description": "Office supplies",
            "dimensions": {},
            "line_key": "line_key_sample",
            "line_number": 0,
            "line_type": "product",
            "location_id": "loc_1001",
            "metadata": {},
            "quantity": "1",
            "received_quantity": "1",
            "tax_amount": "125.00",
            "tax_code": "VALIDATION_ERROR",
            "unit_amount": "125.00"
          }
        ],
        "metadata": {},
        "po_id": "po_id_sample",
        "source_system": "api",
        "total_amount": "125.00",
        "updated_at": "2026-05-05T12:00:00Z",
        "vendor_id": "ven_1001",
        "vendor_name": "ven_1001"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "object": "purchase_order"
    }
  ],
  "object": "list",
  "pagination": {
    "has_more": false,
    "limit": 0,
    "page": 0,
    "total_count": 0
  }
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/purchase_orders" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/purchase_orders

Create a purchase order

Request body required

Field	Type	Description
approval_status	string	Status
currency required	string	Currency
description	string	Description
document_number	string	Number
expected_date	string (date)	Expected Date
issued_at	string (date-time)	Issue Date
metadata	object
total_amount required	string	Total
vendor_id	string	Vendor ID
vendor_name	string	Vendor

{
  "approval_status": "draft",
  "currency": "USD",
  "description": "Office supplies",
  "document_number": "INV-1001",
  "expected_date": "2026-05-05",
  "issued_at": "2026-05-05T12:00:00Z",
  "metadata": {},
  "total_amount": "125.00",
  "vendor_id": "ven_1001",
  "vendor_name": "ven_1001"
}

Responses

201 Created

Field Type Description

data required PurchaseOrderRecord A purchase_order record as returned by the API

Show data fields

Field Type Description

approval_status string Status

created_at string (date-time)

currency required string Currency

description string Description

document_number string Number

expected_date string (date) Expected Date

issued_at string (date-time) Issue Date

lines array of object Lines

Show lines[] fields

Field	Type	Description
account_code	string	Account Code
account_id	string	Account ID
amount	string	Amount
billed_quantity	string	Billed Quantity
class_id	string	Class ID
description	string	Description
dimensions	object	Dimensions
line_key	string	Line Key
line_number	integer	Line Number
line_type	string	Line Type
location_id	string	Location ID
metadata	object	Metadata
quantity	string	Quantity
received_quantity	string	Received Quantity
tax_amount	string	Tax Amount
tax_code	string	Tax Code
unit_amount	string	Unit Amount

metadata object

po_id required string PO ID

source_system string Source

total_amount required string Total

updated_at string (date-time)

vendor_id string Vendor ID

vendor_name string Vendor

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "description": "Office supplies",
    "document_number": "INV-1001",
    "expected_date": "2026-05-05",
    "issued_at": "2026-05-05T12:00:00Z",
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "amount": "125.00",
        "billed_quantity": "1",
        "class_id": "class_1001",
        "description": "Office supplies",
        "dimensions": {},
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "quantity": "1",
        "received_quantity": "1",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "po_id": "po_id_sample",
    "source_system": "api",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001",
    "vendor_name": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "purchase_order"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/purchase_orders" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "approval_status": "draft",
  "currency": "USD",
  "description": "Office supplies",
  "document_number": "INV-1001",
  "expected_date": "2026-05-05",
  "issued_at": "2026-05-05T12:00:00Z",
  "metadata": {},
  "total_amount": "125.00",
  "vendor_id": "ven_1001",
  "vendor_name": "ven_1001"
}'

GET /v1/purchase_orders/{id}

Get a purchase order

Path parameters

Name	Type	Description
id required	string	Resource identifier

Query parameters

Name	Type	Description
include	string	Comma-separated extension field tokens: extension_fields.entity, extension_fields.line

Responses

200 Success

Field Type Description

data required PurchaseOrderRecord A purchase_order record as returned by the API

Show data fields

Field Type Description

approval_status string Status

created_at string (date-time)

currency required string Currency

description string Description

document_number string Number

expected_date string (date) Expected Date

issued_at string (date-time) Issue Date

lines array of object Lines

Show lines[] fields

Field	Type	Description
account_code	string	Account Code
account_id	string	Account ID
amount	string	Amount
billed_quantity	string	Billed Quantity
class_id	string	Class ID
description	string	Description
dimensions	object	Dimensions
line_key	string	Line Key
line_number	integer	Line Number
line_type	string	Line Type
location_id	string	Location ID
metadata	object	Metadata
quantity	string	Quantity
received_quantity	string	Received Quantity
tax_amount	string	Tax Amount
tax_code	string	Tax Code
unit_amount	string	Unit Amount

metadata object

po_id required string PO ID

source_system string Source

total_amount required string Total

updated_at string (date-time)

vendor_id string Vendor ID

vendor_name string Vendor

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "description": "Office supplies",
    "document_number": "INV-1001",
    "expected_date": "2026-05-05",
    "issued_at": "2026-05-05T12:00:00Z",
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "amount": "125.00",
        "billed_quantity": "1",
        "class_id": "class_1001",
        "description": "Office supplies",
        "dimensions": {},
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "quantity": "1",
        "received_quantity": "1",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "po_id": "po_id_sample",
    "source_system": "api",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001",
    "vendor_name": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "purchase_order"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/purchase_orders/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

PUT /v1/purchase_orders/{id}

Update a purchase order

Path parameters

Name	Type	Description
id required	string	Resource identifier

Request body required

Field	Type	Description
approval_status	string	Status
currency	string	Currency
description	string	Description
document_number	string	Number
expected_date	string (date)	Expected Date
issued_at	string (date-time)	Issue Date
metadata	object
total_amount	string	Total
vendor_id	string	Vendor ID
vendor_name	string	Vendor

{
  "approval_status": "draft",
  "currency": "USD",
  "description": "Office supplies",
  "document_number": "INV-1001",
  "expected_date": "2026-05-05",
  "issued_at": "2026-05-05T12:00:00Z",
  "metadata": {},
  "total_amount": "125.00",
  "vendor_id": "ven_1001",
  "vendor_name": "ven_1001"
}

Responses

200 Success

Field Type Description

data required PurchaseOrderRecord A purchase_order record as returned by the API

Show data fields

Field Type Description

approval_status string Status

created_at string (date-time)

currency required string Currency

description string Description

document_number string Number

expected_date string (date) Expected Date

issued_at string (date-time) Issue Date

lines array of object Lines

Show lines[] fields

Field	Type	Description
account_code	string	Account Code
account_id	string	Account ID
amount	string	Amount
billed_quantity	string	Billed Quantity
class_id	string	Class ID
description	string	Description
dimensions	object	Dimensions
line_key	string	Line Key
line_number	integer	Line Number
line_type	string	Line Type
location_id	string	Location ID
metadata	object	Metadata
quantity	string	Quantity
received_quantity	string	Received Quantity
tax_amount	string	Tax Amount
tax_code	string	Tax Code
unit_amount	string	Unit Amount

metadata object

po_id required string PO ID

source_system string Source

total_amount required string Total

updated_at string (date-time)

vendor_id string Vendor ID

vendor_name string Vendor

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "description": "Office supplies",
    "document_number": "INV-1001",
    "expected_date": "2026-05-05",
    "issued_at": "2026-05-05T12:00:00Z",
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "amount": "125.00",
        "billed_quantity": "1",
        "class_id": "class_1001",
        "description": "Office supplies",
        "dimensions": {},
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_type": "product",
        "location_id": "loc_1001",
        "metadata": {},
        "quantity": "1",
        "received_quantity": "1",
        "tax_amount": "125.00",
        "tax_code": "VALIDATION_ERROR",
        "unit_amount": "125.00"
      }
    ],
    "metadata": {},
    "po_id": "po_id_sample",
    "source_system": "api",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001",
    "vendor_name": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "purchase_order"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X PUT "https://api.backfill.io/v1/purchase_orders/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "approval_status": "draft",
  "currency": "USD",
  "description": "Office supplies",
  "document_number": "INV-1001",
  "expected_date": "2026-05-05",
  "issued_at": "2026-05-05T12:00:00Z",
  "metadata": {},
  "total_amount": "125.00",
  "vendor_id": "ven_1001",
  "vendor_name": "ven_1001"
}'

DELETE /v1/purchase_orders/{id}

Delete a purchase order

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Deleted

Field	Type	Description
deleted required	boolean
id required	string (uuid)
object required	string

{
  "deleted": true,
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "record"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X DELETE "https://api.backfill.io/v1/purchase_orders/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

Banking

GET /v1/bank/accounts

List banking

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
sort	string	Sort by a whitelisted field. Prefix with '-' for descending order, e.g. '-created_at'.

Responses

200 Success

Field Type Description

data required array of RecordEnvelope

Show data[] fields

Field	Type	Description
data required	object
id required	string (uuid)
object required	string

object required string

pagination required Pagination

Show pagination fields

Field	Type	Description
has_more required	boolean
limit required	integer
page required	integer
total_count required	integer

{
  "data": [
    {
      "data": {
        "account_type": "checking",
        "available_balance": "125.00",
        "balance_as_of": "2026-05-05T12:00:00Z",
        "bank_account_id": "acc_1001",
        "created_at": "2026-05-05T12:00:00Z",
        "currency": "USD",
        "current_balance": "125.00",
        "gl_account_code": "VALIDATION_ERROR",
        "gl_account_id": "acc_1001",
        "institution_name": "Acme Supplies",
        "last_import_at": "2026-05-05T12:00:00Z",
        "last_transaction_date": "2026-05-05",
        "mask": "mask_sample",
        "metadata": {},
        "name": "Acme Supplies",
        "status": "active",
        "updated_at": "2026-05-05T12:00:00Z"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "object": "bank_account"
    }
  ],
  "object": "list",
  "pagination": {
    "has_more": false,
    "limit": 0,
    "page": 0,
    "total_count": 0
  }
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/bank/accounts" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

GET /v1/bank/transactions

List banking

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
sort	string	Sort by a whitelisted field. Prefix with '-' for descending order, e.g. '-created_at'.
bank_account_id	string	Filter by bank account ID
status	string	Filter by status

Responses

200 Success

Field Type Description

data required array of RecordEnvelope

Show data[] fields

Field	Type	Description
data required	object
id required	string (uuid)
object required	string

object required string

pagination required Pagination

Show pagination fields

Field	Type	Description
has_more required	boolean
limit required	integer
page required	integer
total_count required	integer

{
  "data": [
    {
      "data": {
        "amount": "125.00",
        "bank_account_id": "acc_1001",
        "category": "cat_1001",
        "check_number": "1001",
        "created_at": "2026-05-05T12:00:00Z",
        "currency": "USD",
        "customer_id": "cus_1001",
        "description": "Office supplies",
        "expense_account_code": "VALIDATION_ERROR",
        "expense_account_id": "acc_1001",
        "merchant_name": "Acme Supplies",
        "metadata": {},
        "posted_at": "2026-05-05T12:00:00Z",
        "reference_number": "REF-1001",
        "revenue_account_code": "VALIDATION_ERROR",
        "revenue_account_id": "acc_1001",
        "running_balance": "125.00",
        "status": "pending",
        "transaction_id": "transaction_id_sample",
        "transaction_type": "expense",
        "transfer_account_code": "VALIDATION_ERROR",
        "transfer_account_id": "acc_1001",
        "updated_at": "2026-05-05T12:00:00Z",
        "vendor_id": "ven_1001"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "object": "bank_transaction"
    }
  ],
  "object": "list",
  "pagination": {
    "has_more": false,
    "limit": 0,
    "page": 0,
    "total_count": 0
  }
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/bank/transactions" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

GET /v1/bank/transactions/{id}/matches

List bank transaction match suggestions

Path parameters

Name	Type	Description
id required	string	Bank transaction ID

Responses

200 List of suggested document matches

Field Type Description

data required array of object

Show data[] fields

Field	Type	Description
amount	[string null]
amount_difference	[string null]
confidence required	number
counterparty_id	[string null] (uuid)
counterparty_name	[string null]
date	[string null] (date)
days_apart	integer
document_id required	string (uuid)
document_type required	string
match_key required	string
match_reasons required	array of string
object required	string

object required string

pagination required object

Show pagination fields

Field	Type	Description
has_more required	boolean
limit required	integer
page required	integer
total_count required	integer

{
  "data": [
    {
      "amount": "125.00",
      "amount_difference": "125.00",
      "confidence": 0,
      "counterparty_id": "00000000-0000-0000-0000-000000000000",
      "counterparty_name": "Acme Supplies",
      "date": "2026-05-05",
      "days_apart": 0,
      "document_id": "00000000-0000-0000-0000-000000000000",
      "document_type": "invoice",
      "match_key": "match_key_sample",
      "match_reasons": [
        "match_reasons_sample"
      ],
      "object": "bank_transaction_match"
    }
  ],
  "object": "list",
  "pagination": {
    "has_more": false,
    "limit": 0,
    "page": 0,
    "total_count": 0
  }
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/bank/transactions/{id}/matches" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

GET /v1/bank/transactions/pending

List pending bank transactions

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
sort	string	Sort by a whitelisted field. Prefix with '-' for descending order, e.g. '-created_at'.

Responses

200 List of pending transactions

Field Type Description

data required array of object

Show data[] fields

Field	Type	Description
data required	object
id required	string (uuid)
object required	string

object required string

pagination required object

Show pagination fields

Field	Type	Description
has_more required	boolean
limit required	integer
page required	integer
total_count required	integer

total_pending integer

{
  "data": [
    {
      "data": {},
      "id": "00000000-0000-0000-0000-000000000000",
      "object": "bank_transaction"
    }
  ],
  "object": "list",
  "pagination": {
    "has_more": false,
    "limit": 0,
    "page": 0,
    "total_count": 0
  },
  "total_pending": 0
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/bank/transactions/pending" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

GET /v1/bank/accounts/{id}

Get a bank account

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required BankAccountRecord A bank_account record as returned by the API

Show data fields

Field	Type	Description
account_type	string	Type
available_balance	string	Available Balance
balance_as_of	string (date-time)	Balance As Of
bank_account_id	string	Provider-native ID for this resource. Backfill stores this as source_id on the canonical record.
created_at	string (date-time)
currency	string	Currency
current_balance	string	Balance
gl_account_code	string	GL Account Code
gl_account_id	string	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.
institution_name	string	Institution
last_import_at	string (date-time)	Last Import
last_transaction_date	string (date)	Last Transaction Date
mask	string	Mask
metadata	object
name required	string	Name
status	string	Status
updated_at	string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "account_type": "checking",
    "available_balance": "125.00",
    "balance_as_of": "2026-05-05T12:00:00Z",
    "bank_account_id": "acc_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "current_balance": "125.00",
    "gl_account_code": "VALIDATION_ERROR",
    "gl_account_id": "acc_1001",
    "institution_name": "Acme Supplies",
    "last_import_at": "2026-05-05T12:00:00Z",
    "last_transaction_date": "2026-05-05",
    "mask": "mask_sample",
    "metadata": {},
    "name": "Acme Supplies",
    "status": "active",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "bank_account"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/bank/accounts/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

GET /v1/bank/transactions/{id}

Get a bank transaction

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required BankTransactionRecord A bank_transaction record as returned by the API

Show data fields

Field	Type	Description
amount required	string	Amount
bank_account_id required	string	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.
category	string	Category
check_number	string	Check #
created_at	string (date-time)
currency	string	Currency
customer_id	string	Identifier for the related customer record.
description	string	Description
expense_account_code	string	Expense Account Code
expense_account_id	string	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.
merchant_name	string	Merchant
metadata	object
posted_at required	string (date-time)	Posted
reference_number	string	Reference #
revenue_account_code	string	Revenue Account Code
revenue_account_id	string	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.
running_balance	string	Running Balance
status	string	Status
transaction_id	string	Provider-native ID for this resource. Backfill stores this as source_id on the canonical record.
transaction_type	string	Type
transfer_account_code	string	Transfer Account Code
transfer_account_id	string	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.
updated_at	string (date-time)
vendor_id	string	Identifier for the related vendor record.

id required string (uuid)

object required string

{
  "data": {
    "amount": "125.00",
    "bank_account_id": "acc_1001",
    "category": "cat_1001",
    "check_number": "1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "description": "Office supplies",
    "expense_account_code": "VALIDATION_ERROR",
    "expense_account_id": "acc_1001",
    "merchant_name": "Acme Supplies",
    "metadata": {},
    "posted_at": "2026-05-05T12:00:00Z",
    "reference_number": "REF-1001",
    "revenue_account_code": "VALIDATION_ERROR",
    "revenue_account_id": "acc_1001",
    "running_balance": "125.00",
    "status": "pending",
    "transaction_id": "transaction_id_sample",
    "transaction_type": "expense",
    "transfer_account_code": "VALIDATION_ERROR",
    "transfer_account_id": "acc_1001",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "bank_transaction"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/bank/transactions/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/bank/transactions/batch

Batch categorize bank transactions

Request body required

Field Type Description

transactions array of object

Show transactions[] fields

Field	Type	Description
action	string
exclude_reason	string
expense_account_id	string (uuid)
id	string
revenue_account_id	string (uuid)
transaction_type	string
transfer_account_id	string (uuid)

{
  "transactions": [
    {
      "action": "categorize",
      "exclude_reason": "exclude_reason_sample",
      "expense_account_id": "00000000-0000-0000-0000-000000000000",
      "id": "00000000-0000-0000-0000-000000000000",
      "revenue_account_id": "00000000-0000-0000-0000-000000000000",
      "transaction_type": "transaction_type_sample",
      "transfer_account_id": "00000000-0000-0000-0000-000000000000"
    }
  ]
}

Responses

200 Batch result

Field Type Description

data required object

Show data fields

Field Type Description

failed required integer

processed required integer

results required array of object

Show results[] fields

Field	Type	Description
id	[string null] (uuid)
reason	[string null]
status required	string

succeeded required integer

object required string

{
  "data": {
    "failed": 0,
    "processed": 0,
    "results": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "reason": "reason_sample",
        "status": "success"
      }
    ],
    "succeeded": 0
  },
  "object": "batch_result"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/bank/transactions/batch" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "transactions": [
    {
      "action": "categorize",
      "exclude_reason": "exclude_reason_sample",
      "expense_account_id": "00000000-0000-0000-0000-000000000000",
      "id": "00000000-0000-0000-0000-000000000000",
      "revenue_account_id": "00000000-0000-0000-0000-000000000000",
      "transaction_type": "transaction_type_sample",
      "transfer_account_id": "00000000-0000-0000-0000-000000000000"
    }
  ]
}'

POST /v1/bank/transactions/{id}/categorize

Categorize a bank transaction

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required BankTransactionRecord A bank_transaction record as returned by the API

Show data fields

Field	Type	Description
amount required	string	Amount
bank_account_id required	string	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.
category	string	Category
check_number	string	Check #
created_at	string (date-time)
currency	string	Currency
customer_id	string	Identifier for the related customer record.
description	string	Description
expense_account_code	string	Expense Account Code
expense_account_id	string	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.
merchant_name	string	Merchant
metadata	object
posted_at required	string (date-time)	Posted
reference_number	string	Reference #
revenue_account_code	string	Revenue Account Code
revenue_account_id	string	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.
running_balance	string	Running Balance
status	string	Status
transaction_id	string	Provider-native ID for this resource. Backfill stores this as source_id on the canonical record.
transaction_type	string	Type
transfer_account_code	string	Transfer Account Code
transfer_account_id	string	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.
updated_at	string (date-time)
vendor_id	string	Identifier for the related vendor record.

id required string (uuid)

object required string

{
  "data": {
    "amount": "125.00",
    "bank_account_id": "acc_1001",
    "category": "cat_1001",
    "check_number": "1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "description": "Office supplies",
    "expense_account_code": "VALIDATION_ERROR",
    "expense_account_id": "acc_1001",
    "merchant_name": "Acme Supplies",
    "metadata": {},
    "posted_at": "2026-05-05T12:00:00Z",
    "reference_number": "REF-1001",
    "revenue_account_code": "VALIDATION_ERROR",
    "revenue_account_id": "acc_1001",
    "running_balance": "125.00",
    "status": "pending",
    "transaction_id": "transaction_id_sample",
    "transaction_type": "expense",
    "transfer_account_code": "VALIDATION_ERROR",
    "transfer_account_id": "acc_1001",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "bank_transaction"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/bank/transactions/{id}/categorize" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/bank/transactions/{id}/reconcile

Reconcile a bank transaction

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required BankTransactionRecord A bank_transaction record as returned by the API

Show data fields

Field	Type	Description
amount required	string	Amount
bank_account_id required	string	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.
category	string	Category
check_number	string	Check #
created_at	string (date-time)
currency	string	Currency
customer_id	string	Identifier for the related customer record.
description	string	Description
expense_account_code	string	Expense Account Code
expense_account_id	string	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.
merchant_name	string	Merchant
metadata	object
posted_at required	string (date-time)	Posted
reference_number	string	Reference #
revenue_account_code	string	Revenue Account Code
revenue_account_id	string	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.
running_balance	string	Running Balance
status	string	Status
transaction_id	string	Provider-native ID for this resource. Backfill stores this as source_id on the canonical record.
transaction_type	string	Type
transfer_account_code	string	Transfer Account Code
transfer_account_id	string	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.
updated_at	string (date-time)
vendor_id	string	Identifier for the related vendor record.

id required string (uuid)

object required string

{
  "data": {
    "amount": "125.00",
    "bank_account_id": "acc_1001",
    "category": "cat_1001",
    "check_number": "1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "description": "Office supplies",
    "expense_account_code": "VALIDATION_ERROR",
    "expense_account_id": "acc_1001",
    "merchant_name": "Acme Supplies",
    "metadata": {},
    "posted_at": "2026-05-05T12:00:00Z",
    "reference_number": "REF-1001",
    "revenue_account_code": "VALIDATION_ERROR",
    "revenue_account_id": "acc_1001",
    "running_balance": "125.00",
    "status": "pending",
    "transaction_id": "transaction_id_sample",
    "transaction_type": "expense",
    "transfer_account_code": "VALIDATION_ERROR",
    "transfer_account_id": "acc_1001",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "bank_transaction"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/bank/transactions/{id}/reconcile" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/bank/accounts/{id}/sync

Trigger a sync for this bank account

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required BankAccountRecord A bank_account record as returned by the API

Show data fields

Field	Type	Description
account_type	string	Type
available_balance	string	Available Balance
balance_as_of	string (date-time)	Balance As Of
bank_account_id	string	Provider-native ID for this resource. Backfill stores this as source_id on the canonical record.
created_at	string (date-time)
currency	string	Currency
current_balance	string	Balance
gl_account_code	string	GL Account Code
gl_account_id	string	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.
institution_name	string	Institution
last_import_at	string (date-time)	Last Import
last_transaction_date	string (date)	Last Transaction Date
mask	string	Mask
metadata	object
name required	string	Name
status	string	Status
updated_at	string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "account_type": "checking",
    "available_balance": "125.00",
    "balance_as_of": "2026-05-05T12:00:00Z",
    "bank_account_id": "acc_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "current_balance": "125.00",
    "gl_account_code": "VALIDATION_ERROR",
    "gl_account_id": "acc_1001",
    "institution_name": "Acme Supplies",
    "last_import_at": "2026-05-05T12:00:00Z",
    "last_transaction_date": "2026-05-05",
    "mask": "mask_sample",
    "metadata": {},
    "name": "Acme Supplies",
    "status": "active",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "bank_account"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/bank/accounts/{id}/sync" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/bank/transactions/{id}/unreconcile

Unreconcile a bank transaction

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required BankTransactionRecord A bank_transaction record as returned by the API

Show data fields

Field	Type	Description
amount required	string	Amount
bank_account_id required	string	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.
category	string	Category
check_number	string	Check #
created_at	string (date-time)
currency	string	Currency
customer_id	string	Identifier for the related customer record.
description	string	Description
expense_account_code	string	Expense Account Code
expense_account_id	string	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.
merchant_name	string	Merchant
metadata	object
posted_at required	string (date-time)	Posted
reference_number	string	Reference #
revenue_account_code	string	Revenue Account Code
revenue_account_id	string	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.
running_balance	string	Running Balance
status	string	Status
transaction_id	string	Provider-native ID for this resource. Backfill stores this as source_id on the canonical record.
transaction_type	string	Type
transfer_account_code	string	Transfer Account Code
transfer_account_id	string	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.
updated_at	string (date-time)
vendor_id	string	Identifier for the related vendor record.

id required string (uuid)

object required string

{
  "data": {
    "amount": "125.00",
    "bank_account_id": "acc_1001",
    "category": "cat_1001",
    "check_number": "1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "customer_id": "cus_1001",
    "description": "Office supplies",
    "expense_account_code": "VALIDATION_ERROR",
    "expense_account_id": "acc_1001",
    "merchant_name": "Acme Supplies",
    "metadata": {},
    "posted_at": "2026-05-05T12:00:00Z",
    "reference_number": "REF-1001",
    "revenue_account_code": "VALIDATION_ERROR",
    "revenue_account_id": "acc_1001",
    "running_balance": "125.00",
    "status": "pending",
    "transaction_id": "transaction_id_sample",
    "transaction_type": "expense",
    "transfer_account_code": "VALIDATION_ERROR",
    "transfer_account_id": "acc_1001",
    "updated_at": "2026-05-05T12:00:00Z",
    "vendor_id": "ven_1001"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "bank_transaction"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/bank/transactions/{id}/unreconcile" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

Bank Transfers

GET /v1/bank_transfers

List bank transfers

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
sort	string	Sort by a whitelisted field. Prefix with '-' for descending order, e.g. '-created_at'.
status	string	Filter by status
start_date	string	Filter by transfer_date >= (YYYY-MM-DD)
end_date	string	Filter by transfer_date <= (YYYY-MM-DD)
from_account_id	string	Filter by source account ID
to_account_id	string	Filter by destination account ID

Responses

200 Success

Field Type Description

data required array of RecordEnvelope

Show data[] fields

Field	Type	Description
data required	object
id required	string (uuid)
object required	string

object required string

pagination required Pagination

Show pagination fields

Field	Type	Description
has_more required	boolean
limit required	integer
page required	integer
total_count required	integer

{
  "data": [
    {
      "data": {
        "amount": "125.00",
        "approved_at": "2026-05-05T12:00:00Z",
        "approved_by": "approved_by_sample",
        "created_at": "2026-05-05T12:00:00Z",
        "currency": "USD",
        "dimensions": {},
        "from_account_code": "VALIDATION_ERROR",
        "from_account_id": "acc_1001",
        "id": "00000000-0000-0000-0000-000000000000",
        "memo": "Payment received",
        "metadata": {},
        "source_id": "src_1001",
        "source_system": "api",
        "status": "draft",
        "to_account_code": "VALIDATION_ERROR",
        "to_account_id": "acc_1001",
        "transfer_date": "2026-05-05",
        "transfer_number": "1001",
        "updated_at": "2026-05-05T12:00:00Z"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "object": "bank_transfer"
    }
  ],
  "object": "list",
  "pagination": {
    "has_more": false,
    "limit": 0,
    "page": 0,
    "total_count": 0
  }
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/bank_transfers" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/bank_transfers

Create a bank transfer

Request body required

Field	Type	Description
amount required	string	Amount
currency required	string	Currency
from_account_id required	string	From Account ID
memo	string	Memo
metadata	object	Metadata
status	string	Status
to_account_id required	string	To Account ID
transfer_date required	string (date)	Transfer Date
transfer_number	string	Transfer Number

{
  "amount": "125.00",
  "currency": "USD",
  "from_account_id": "acc_1001",
  "memo": "Payment received",
  "metadata": {},
  "status": "draft",
  "to_account_id": "acc_1001",
  "transfer_date": "2026-05-05",
  "transfer_number": "1001"
}

Responses

201 Created

Field Type Description

data required BankTransferRecord A bank_transfer record as returned by the API

Show data fields

Field	Type	Description
amount required	string	Amount
approved_at	string (date-time)	Approved At
approved_by	string	Approved By
created_at	string (date-time)
currency required	string	Currency
dimensions	object	Dimensions
from_account_code	string	From Account Code
from_account_id required	string	From Account ID
id	string	Canonical ID
memo	string	Memo
metadata	object	Metadata
source_id required	string	Source ID
source_system required	string	Source System
status required	string	Status
to_account_code	string	To Account Code
to_account_id required	string	To Account ID
transfer_date required	string (date)	Transfer Date
transfer_number	string	Transfer Number
updated_at	string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "amount": "125.00",
    "approved_at": "2026-05-05T12:00:00Z",
    "approved_by": "approved_by_sample",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "dimensions": {},
    "from_account_code": "VALIDATION_ERROR",
    "from_account_id": "acc_1001",
    "id": "00000000-0000-0000-0000-000000000000",
    "memo": "Payment received",
    "metadata": {},
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "to_account_code": "VALIDATION_ERROR",
    "to_account_id": "acc_1001",
    "transfer_date": "2026-05-05",
    "transfer_number": "1001",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "bank_transfer"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/bank_transfers" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "125.00",
  "currency": "USD",
  "from_account_id": "acc_1001",
  "memo": "Payment received",
  "metadata": {},
  "status": "draft",
  "to_account_id": "acc_1001",
  "transfer_date": "2026-05-05",
  "transfer_number": "1001"
}'

GET /v1/bank_transfers/{id}

Get a bank transfer

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required BankTransferRecord A bank_transfer record as returned by the API

Show data fields

Field	Type	Description
amount required	string	Amount
approved_at	string (date-time)	Approved At
approved_by	string	Approved By
created_at	string (date-time)
currency required	string	Currency
dimensions	object	Dimensions
from_account_code	string	From Account Code
from_account_id required	string	From Account ID
id	string	Canonical ID
memo	string	Memo
metadata	object	Metadata
source_id required	string	Source ID
source_system required	string	Source System
status required	string	Status
to_account_code	string	To Account Code
to_account_id required	string	To Account ID
transfer_date required	string (date)	Transfer Date
transfer_number	string	Transfer Number
updated_at	string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "amount": "125.00",
    "approved_at": "2026-05-05T12:00:00Z",
    "approved_by": "approved_by_sample",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "dimensions": {},
    "from_account_code": "VALIDATION_ERROR",
    "from_account_id": "acc_1001",
    "id": "00000000-0000-0000-0000-000000000000",
    "memo": "Payment received",
    "metadata": {},
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "to_account_code": "VALIDATION_ERROR",
    "to_account_id": "acc_1001",
    "transfer_date": "2026-05-05",
    "transfer_number": "1001",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "bank_transfer"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/bank_transfers/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

PUT /v1/bank_transfers/{id}

Update a bank transfer

Path parameters

Name	Type	Description
id required	string	Resource identifier

Request body required

Field	Type	Description
amount	string	Amount
currency	string	Currency
from_account_id	string	From Account ID
memo	string	Memo
metadata	object	Metadata
status	string	Status
to_account_id	string	To Account ID
transfer_date	string (date)	Transfer Date
transfer_number	string	Transfer Number

{
  "amount": "125.00",
  "currency": "USD",
  "from_account_id": "acc_1001",
  "memo": "Payment received",
  "metadata": {},
  "status": "draft",
  "to_account_id": "acc_1001",
  "transfer_date": "2026-05-05",
  "transfer_number": "1001"
}

Responses

200 Success

Field Type Description

data required BankTransferRecord A bank_transfer record as returned by the API

Show data fields

Field	Type	Description
amount required	string	Amount
approved_at	string (date-time)	Approved At
approved_by	string	Approved By
created_at	string (date-time)
currency required	string	Currency
dimensions	object	Dimensions
from_account_code	string	From Account Code
from_account_id required	string	From Account ID
id	string	Canonical ID
memo	string	Memo
metadata	object	Metadata
source_id required	string	Source ID
source_system required	string	Source System
status required	string	Status
to_account_code	string	To Account Code
to_account_id required	string	To Account ID
transfer_date required	string (date)	Transfer Date
transfer_number	string	Transfer Number
updated_at	string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "amount": "125.00",
    "approved_at": "2026-05-05T12:00:00Z",
    "approved_by": "approved_by_sample",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "dimensions": {},
    "from_account_code": "VALIDATION_ERROR",
    "from_account_id": "acc_1001",
    "id": "00000000-0000-0000-0000-000000000000",
    "memo": "Payment received",
    "metadata": {},
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "to_account_code": "VALIDATION_ERROR",
    "to_account_id": "acc_1001",
    "transfer_date": "2026-05-05",
    "transfer_number": "1001",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "bank_transfer"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X PUT "https://api.backfill.io/v1/bank_transfers/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "125.00",
  "currency": "USD",
  "from_account_id": "acc_1001",
  "memo": "Payment received",
  "metadata": {},
  "status": "draft",
  "to_account_id": "acc_1001",
  "transfer_date": "2026-05-05",
  "transfer_number": "1001"
}'

DELETE /v1/bank_transfers/{id}

Delete a bank transfer

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Deleted

Field	Type	Description
deleted required	boolean
id required	string (uuid)
object required	string

{
  "deleted": true,
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "record"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X DELETE "https://api.backfill.io/v1/bank_transfers/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

Deposits

GET /v1/deposits

List deposits

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
sort	string	Sort by a whitelisted field. Prefix with '-' for descending order, e.g. '-created_at'.
status	string	Filter by status
start_date	string	Filter by deposit_date >= (YYYY-MM-DD)
end_date	string	Filter by deposit_date <= (YYYY-MM-DD)
include	string	Comma-separated extension field tokens: extension_fields.entity, extension_fields.line

Responses

200 Success

Field Type Description

data required array of RecordEnvelope

Show data[] fields

Field	Type	Description
data required	object
id required	string (uuid)
object required	string

object required string

pagination required Pagination

Show pagination fields

Field	Type	Description
has_more required	boolean
limit required	integer
page required	integer
total_count required	integer

{
  "data": [
    {
      "data": {
        "cashback_account_id": "acc_1001",
        "cashback_amount": "125.00",
        "cashback_memo": "Payment received",
        "connection_id": "conn_1001",
        "created_at": "2026-05-05T12:00:00Z",
        "currency": "USD",
        "deposit_date": "2026-05-05",
        "deposit_to_account_code": "VALIDATION_ERROR",
        "deposit_to_account_id": "acc_1001",
        "dimensions": {},
        "document_number": "INV-1001",
        "id": "00000000-0000-0000-0000-000000000000",
        "line_items": [
          {
            "account_code": "VALIDATION_ERROR",
            "account_id": "acc_1001",
            "amount": "125.00",
            "check_number": "1001",
            "currency": "USD",
            "customer_id": "cus_1001",
            "description": "Office supplies",
            "dimensions": {},
            "line_key": "line_key_sample",
            "line_number": 0,
            "line_ref": "line_ref_sample",
            "metadata": {},
            "payment_method": "pay_1001",
            "reference_number": "REF-1001",
            "source_document_id": "src_1001",
            "source_document_number": "INV-1001",
            "source_document_type": "src_1001"
          }
        ],
        "memo": "Payment received",
        "metadata": {},
        "source_id": "src_1001",
        "source_system": "api",
        "status": "pending",
        "total_amount": "125.00",
        "updated_at": "2026-05-05T12:00:00Z"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "object": "deposit"
    }
  ],
  "object": "list",
  "pagination": {
    "has_more": false,
    "limit": 0,
    "page": 0,
    "total_count": 0
  }
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/deposits" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/deposits

Create a deposit

Request body required

Field Type Description

cashback_account_id string Cash Back Account ID

cashback_amount string Cash Back Amount

cashback_memo string Cash Back Memo

currency required string Currency

deposit_date string (date) Deposit Date

deposit_to_account_code string Deposit To Account Code

deposit_to_account_id string Deposit To Account ID

dimensions object Dimensions

document_number string Document Number

lines array of object Lines

Show lines[] fields

Field	Type	Description
account_code	string	Account Code
account_id	string	Line Posting Account ID
amount	string	Amount
check_number	string	Check Number
currency	string	Currency
customer_id	string	Customer ID
description	string	Description
dimensions	object	Dimensions
line_key	string	Line Key
line_number	integer	Line Number
line_ref	string	Line Ref
metadata	object	Metadata
payment_method	string	Payment Method
reference_number	string	Reference Number
source_document_id	string	Source Document ID
source_document_number	string	Source Document Number
source_document_type	string	Source Document Type

memo string Memo

metadata object Metadata

status string Status

total_amount required string Total Amount

{
  "cashback_account_id": "acc_1001",
  "cashback_amount": "125.00",
  "cashback_memo": "Payment received",
  "currency": "USD",
  "deposit_date": "2026-05-05",
  "deposit_to_account_code": "VALIDATION_ERROR",
  "deposit_to_account_id": "acc_1001",
  "dimensions": {},
  "document_number": "INV-1001",
  "lines": [
    {
      "account_code": "VALIDATION_ERROR",
      "account_id": "acc_1001",
      "amount": "125.00",
      "check_number": "1001",
      "currency": "USD",
      "customer_id": "cus_1001",
      "description": "Office supplies",
      "dimensions": {},
      "line_key": "line_key_sample",
      "line_number": 0,
      "line_ref": "line_ref_sample",
      "metadata": {},
      "payment_method": "pay_1001",
      "reference_number": "REF-1001",
      "source_document_id": "src_1001",
      "source_document_number": "INV-1001",
      "source_document_type": "src_1001"
    }
  ],
  "memo": "Payment received",
  "metadata": {},
  "status": "pending",
  "total_amount": "125.00"
}

Responses

201 Created

Field Type Description

data required DepositRecord A deposit record as returned by the API

Show data fields

Field Type Description

cashback_account_id string Cash Back Account ID

cashback_amount string Cash Back Amount

cashback_memo string Cash Back Memo

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

deposit_date string (date) Deposit Date

deposit_to_account_code string Deposit To Account Code

deposit_to_account_id string Deposit To Account ID

dimensions object Dimensions

document_number string Document Number

id string Canonical ID

line_items array of object Lines

Show line_items[] fields

Field	Type	Description
account_code	string	Account Code
account_id	string	Line Posting Account ID
amount	string	Amount
check_number	string	Check Number
currency	string	Currency
customer_id	string	Customer ID
description	string	Description
dimensions	object	Dimensions
line_key	string	Line Key
line_number	integer	Line Number
line_ref	string	Line Ref
metadata	object	Metadata
payment_method	string	Payment Method
reference_number	string	Reference Number
source_document_id	string	Source Document ID
source_document_number	string	Source Document Number
source_document_type	string	Source Document Type

memo string Memo

metadata object Metadata

source_id required string Source ID

source_system required string Source System

status required string Status

total_amount required string Total Amount

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "cashback_account_id": "acc_1001",
    "cashback_amount": "125.00",
    "cashback_memo": "Payment received",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "deposit_date": "2026-05-05",
    "deposit_to_account_code": "VALIDATION_ERROR",
    "deposit_to_account_id": "acc_1001",
    "dimensions": {},
    "document_number": "INV-1001",
    "id": "00000000-0000-0000-0000-000000000000",
    "line_items": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "amount": "125.00",
        "check_number": "1001",
        "currency": "USD",
        "customer_id": "cus_1001",
        "description": "Office supplies",
        "dimensions": {},
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "metadata": {},
        "payment_method": "pay_1001",
        "reference_number": "REF-1001",
        "source_document_id": "src_1001",
        "source_document_number": "INV-1001",
        "source_document_type": "src_1001"
      }
    ],
    "memo": "Payment received",
    "metadata": {},
    "source_id": "src_1001",
    "source_system": "api",
    "status": "pending",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "deposit"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/deposits" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "cashback_account_id": "acc_1001",
  "cashback_amount": "125.00",
  "cashback_memo": "Payment received",
  "currency": "USD",
  "deposit_date": "2026-05-05",
  "deposit_to_account_code": "VALIDATION_ERROR",
  "deposit_to_account_id": "acc_1001",
  "dimensions": {},
  "document_number": "INV-1001",
  "lines": [
    {
      "account_code": "VALIDATION_ERROR",
      "account_id": "acc_1001",
      "amount": "125.00",
      "check_number": "1001",
      "currency": "USD",
      "customer_id": "cus_1001",
      "description": "Office supplies",
      "dimensions": {},
      "line_key": "line_key_sample",
      "line_number": 0,
      "line_ref": "line_ref_sample",
      "metadata": {},
      "payment_method": "pay_1001",
      "reference_number": "REF-1001",
      "source_document_id": "src_1001",
      "source_document_number": "INV-1001",
      "source_document_type": "src_1001"
    }
  ],
  "memo": "Payment received",
  "metadata": {},
  "status": "pending",
  "total_amount": "125.00"
}'

GET /v1/deposits/{id}

Get a deposit

Path parameters

Name	Type	Description
id required	string	Resource identifier

Query parameters

Name	Type	Description
include	string	Comma-separated extension field tokens: extension_fields.entity, extension_fields.line

Responses

200 Success

Field Type Description

data required DepositRecord A deposit record as returned by the API

Show data fields

Field Type Description

cashback_account_id string Cash Back Account ID

cashback_amount string Cash Back Amount

cashback_memo string Cash Back Memo

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

deposit_date string (date) Deposit Date

deposit_to_account_code string Deposit To Account Code

deposit_to_account_id string Deposit To Account ID

dimensions object Dimensions

document_number string Document Number

id string Canonical ID

line_items array of object Lines

Show line_items[] fields

Field	Type	Description
account_code	string	Account Code
account_id	string	Line Posting Account ID
amount	string	Amount
check_number	string	Check Number
currency	string	Currency
customer_id	string	Customer ID
description	string	Description
dimensions	object	Dimensions
line_key	string	Line Key
line_number	integer	Line Number
line_ref	string	Line Ref
metadata	object	Metadata
payment_method	string	Payment Method
reference_number	string	Reference Number
source_document_id	string	Source Document ID
source_document_number	string	Source Document Number
source_document_type	string	Source Document Type

memo string Memo

metadata object Metadata

source_id required string Source ID

source_system required string Source System

status required string Status

total_amount required string Total Amount

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "cashback_account_id": "acc_1001",
    "cashback_amount": "125.00",
    "cashback_memo": "Payment received",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "deposit_date": "2026-05-05",
    "deposit_to_account_code": "VALIDATION_ERROR",
    "deposit_to_account_id": "acc_1001",
    "dimensions": {},
    "document_number": "INV-1001",
    "id": "00000000-0000-0000-0000-000000000000",
    "line_items": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "amount": "125.00",
        "check_number": "1001",
        "currency": "USD",
        "customer_id": "cus_1001",
        "description": "Office supplies",
        "dimensions": {},
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "metadata": {},
        "payment_method": "pay_1001",
        "reference_number": "REF-1001",
        "source_document_id": "src_1001",
        "source_document_number": "INV-1001",
        "source_document_type": "src_1001"
      }
    ],
    "memo": "Payment received",
    "metadata": {},
    "source_id": "src_1001",
    "source_system": "api",
    "status": "pending",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "deposit"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/deposits/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

PUT /v1/deposits/{id}

Update a deposit

Path parameters

Name	Type	Description
id required	string	Resource identifier

Request body required

Field Type Description

cashback_account_id string Cash Back Account ID

cashback_amount string Cash Back Amount

cashback_memo string Cash Back Memo

currency string Currency

deposit_date string (date) Deposit Date

deposit_to_account_code string Deposit To Account Code

deposit_to_account_id string Deposit To Account ID

dimensions object Dimensions

document_number string Document Number

lines array of object Lines

Show lines[] fields

Field	Type	Description
account_code	string	Account Code
account_id	string	Line Posting Account ID
amount	string	Amount
check_number	string	Check Number
currency	string	Currency
customer_id	string	Customer ID
description	string	Description
dimensions	object	Dimensions
line_key	string	Line Key
line_number	integer	Line Number
line_ref	string	Line Ref
metadata	object	Metadata
payment_method	string	Payment Method
reference_number	string	Reference Number
source_document_id	string	Source Document ID
source_document_number	string	Source Document Number
source_document_type	string	Source Document Type

memo string Memo

metadata object Metadata

status string Status

total_amount string Total Amount

{
  "cashback_account_id": "acc_1001",
  "cashback_amount": "125.00",
  "cashback_memo": "Payment received",
  "currency": "USD",
  "deposit_date": "2026-05-05",
  "deposit_to_account_code": "VALIDATION_ERROR",
  "deposit_to_account_id": "acc_1001",
  "dimensions": {},
  "document_number": "INV-1001",
  "lines": [
    {
      "account_code": "VALIDATION_ERROR",
      "account_id": "acc_1001",
      "amount": "125.00",
      "check_number": "1001",
      "currency": "USD",
      "customer_id": "cus_1001",
      "description": "Office supplies",
      "dimensions": {},
      "line_key": "line_key_sample",
      "line_number": 0,
      "line_ref": "line_ref_sample",
      "metadata": {},
      "payment_method": "pay_1001",
      "reference_number": "REF-1001",
      "source_document_id": "src_1001",
      "source_document_number": "INV-1001",
      "source_document_type": "src_1001"
    }
  ],
  "memo": "Payment received",
  "metadata": {},
  "status": "pending",
  "total_amount": "125.00"
}

Responses

200 Success

Field Type Description

data required DepositRecord A deposit record as returned by the API

Show data fields

Field Type Description

cashback_account_id string Cash Back Account ID

cashback_amount string Cash Back Amount

cashback_memo string Cash Back Memo

connection_id string Connection ID

created_at string (date-time)

currency required string Currency

deposit_date string (date) Deposit Date

deposit_to_account_code string Deposit To Account Code

deposit_to_account_id string Deposit To Account ID

dimensions object Dimensions

document_number string Document Number

id string Canonical ID

line_items array of object Lines

Show line_items[] fields

Field	Type	Description
account_code	string	Account Code
account_id	string	Line Posting Account ID
amount	string	Amount
check_number	string	Check Number
currency	string	Currency
customer_id	string	Customer ID
description	string	Description
dimensions	object	Dimensions
line_key	string	Line Key
line_number	integer	Line Number
line_ref	string	Line Ref
metadata	object	Metadata
payment_method	string	Payment Method
reference_number	string	Reference Number
source_document_id	string	Source Document ID
source_document_number	string	Source Document Number
source_document_type	string	Source Document Type

memo string Memo

metadata object Metadata

source_id required string Source ID

source_system required string Source System

status required string Status

total_amount required string Total Amount

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "cashback_account_id": "acc_1001",
    "cashback_amount": "125.00",
    "cashback_memo": "Payment received",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "deposit_date": "2026-05-05",
    "deposit_to_account_code": "VALIDATION_ERROR",
    "deposit_to_account_id": "acc_1001",
    "dimensions": {},
    "document_number": "INV-1001",
    "id": "00000000-0000-0000-0000-000000000000",
    "line_items": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "amount": "125.00",
        "check_number": "1001",
        "currency": "USD",
        "customer_id": "cus_1001",
        "description": "Office supplies",
        "dimensions": {},
        "line_key": "line_key_sample",
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "metadata": {},
        "payment_method": "pay_1001",
        "reference_number": "REF-1001",
        "source_document_id": "src_1001",
        "source_document_number": "INV-1001",
        "source_document_type": "src_1001"
      }
    ],
    "memo": "Payment received",
    "metadata": {},
    "source_id": "src_1001",
    "source_system": "api",
    "status": "pending",
    "total_amount": "125.00",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "deposit"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X PUT "https://api.backfill.io/v1/deposits/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "cashback_account_id": "acc_1001",
  "cashback_amount": "125.00",
  "cashback_memo": "Payment received",
  "currency": "USD",
  "deposit_date": "2026-05-05",
  "deposit_to_account_code": "VALIDATION_ERROR",
  "deposit_to_account_id": "acc_1001",
  "dimensions": {},
  "document_number": "INV-1001",
  "lines": [
    {
      "account_code": "VALIDATION_ERROR",
      "account_id": "acc_1001",
      "amount": "125.00",
      "check_number": "1001",
      "currency": "USD",
      "customer_id": "cus_1001",
      "description": "Office supplies",
      "dimensions": {},
      "line_key": "line_key_sample",
      "line_number": 0,
      "line_ref": "line_ref_sample",
      "metadata": {},
      "payment_method": "pay_1001",
      "reference_number": "REF-1001",
      "source_document_id": "src_1001",
      "source_document_number": "INV-1001",
      "source_document_type": "src_1001"
    }
  ],
  "memo": "Payment received",
  "metadata": {},
  "status": "pending",
  "total_amount": "125.00"
}'

DELETE /v1/deposits/{id}

Delete a deposit

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Deleted

Field	Type	Description
deleted required	boolean
id required	string (uuid)
object required	string

{
  "deleted": true,
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "record"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X DELETE "https://api.backfill.io/v1/deposits/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

Journal Entries

GET /v1/journal_entries

List journal entries

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
sort	string	Sort by a whitelisted field. Prefix with '-' for descending order, e.g. '-created_at'.

Responses

200 Success

Field Type Description

data required array of RecordEnvelope

Show data[] fields

Field	Type	Description
data required	object
id required	string (uuid)
object required	string

object required string

pagination required Pagination

Show pagination fields

Field	Type	Description
has_more required	boolean
limit required	integer
page required	integer
total_count required	integer

{
  "data": [
    {
      "data": {
        "approval_status": "draft",
        "connection_id": "conn_1001",
        "created_at": "2026-05-05T12:00:00Z",
        "currency": "USD",
        "dimensions": {},
        "document_date": "2026-05-05",
        "effective_date": "2026-05-05",
        "entry_date": "2026-05-05",
        "entry_number": "1001",
        "id": "00000000-0000-0000-0000-000000000000",
        "lines": [
          {
            "account_code": "VALIDATION_ERROR",
            "account_id": "acc_1001",
            "class_id": "class_1001",
            "credit_amount": "125.00",
            "debit_amount": "125.00",
            "description": "Office supplies",
            "dimensions": {},
            "line_number": 0,
            "line_ref": "line_ref_sample",
            "location_id": "loc_1001",
            "metadata": {}
          }
        ],
        "memo": "Payment received",
        "metadata": {},
        "posting_period": "posting_period_sample",
        "reverses_entry_id": "reverses_entry_id_sample",
        "source_id": "src_1001",
        "source_system": "api",
        "status": "draft",
        "updated_at": "2026-05-05T12:00:00Z"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "object": "journal_entry"
    }
  ],
  "object": "list",
  "pagination": {
    "has_more": false,
    "limit": 0,
    "page": 0,
    "total_count": 0
  }
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/journal_entries" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/journal_entries

Create a journal entry

Request body required

Field Type Description

approval_status string Approval Status

currency string Currency

dimensions object Dimensions

document_date string (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 string (date) Accounting effective date for reporting, posting, and period cutoffs. Defaults to document_date when omitted.

entry_date required string (date) Entry Date

lines required array of object Lines

Show lines[] fields

Field	Type	Description
account_code	string	Account Code
account_id required	string	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.
class_id	string	Identifier for the related class record.
credit_amount	string	Credit Amount
debit_amount	string	Debit Amount
description	string	Description
dimensions	object	Dimensions
line_number	integer	One-based display order of the line within the document. Use for ordering and presentation, not stable identity.
line_ref	string	Provider-native line reference. Use it to match the same source line across document versions and related documents.
location_id	string	Identifier for the related location record.
metadata	object	Metadata

memo string Memo

metadata object Metadata

posting_period string Posting Period

reverses_entry_id string Identifier for the related reverses entry record.

status required string Status

{
  "approval_status": "draft",
  "currency": "USD",
  "dimensions": {},
  "document_date": "2026-05-05",
  "effective_date": "2026-05-05",
  "entry_date": "2026-05-05",
  "lines": [
    {
      "account_code": "VALIDATION_ERROR",
      "account_id": "acc_1001",
      "class_id": "class_1001",
      "credit_amount": "125.00",
      "debit_amount": "125.00",
      "description": "Office supplies",
      "dimensions": {},
      "line_number": 0,
      "line_ref": "line_ref_sample",
      "location_id": "loc_1001",
      "metadata": {}
    }
  ],
  "memo": "Payment received",
  "metadata": {},
  "posting_period": "posting_period_sample",
  "reverses_entry_id": "reverses_entry_id_sample",
  "status": "draft"
}

Responses

201 Created

Field Type Description

data required JournalEntryRecord A journal_entry record as returned by the API

Show data fields

Field Type Description

approval_status string Approval Status

connection_id string 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.

created_at string (date-time)

currency string Currency

dimensions object Dimensions

document_date string (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 string (date) Accounting effective date for reporting, posting, and period cutoffs. Defaults to document_date when omitted.

entry_date required string (date) Entry Date

entry_number string Entry Number

id string Backfill canonical record ID assigned after persistence. This is distinct from the source-system ID.

lines required array of object Lines

Show lines[] fields

Field	Type	Description
account_code	string	Account Code
account_id required	string	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.
class_id	string	Identifier for the related class record.
credit_amount	string	Credit Amount
debit_amount	string	Debit Amount
description	string	Description
dimensions	object	Dimensions
line_number	integer	One-based display order of the line within the document. Use for ordering and presentation, not stable identity.
line_ref	string	Provider-native line reference. Use it to match the same source line across document versions and related documents.
location_id	string	Identifier for the related location record.
metadata	object	Metadata

memo string Memo

metadata object Metadata

posting_period string Posting Period

reverses_entry_id string Identifier for the related reverses entry record.

source_id required string 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_system required string Connector or provider that supplied the record, such as stripe, shopify, qbo, csv_upload, or manual.

status required string Status

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "dimensions": {},
    "document_date": "2026-05-05",
    "effective_date": "2026-05-05",
    "entry_date": "2026-05-05",
    "entry_number": "1001",
    "id": "00000000-0000-0000-0000-000000000000",
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "class_id": "class_1001",
        "credit_amount": "125.00",
        "debit_amount": "125.00",
        "description": "Office supplies",
        "dimensions": {},
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "location_id": "loc_1001",
        "metadata": {}
      }
    ],
    "memo": "Payment received",
    "metadata": {},
    "posting_period": "posting_period_sample",
    "reverses_entry_id": "reverses_entry_id_sample",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "journal_entry"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/journal_entries" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "approval_status": "draft",
  "currency": "USD",
  "dimensions": {},
  "document_date": "2026-05-05",
  "effective_date": "2026-05-05",
  "entry_date": "2026-05-05",
  "lines": [
    {
      "account_code": "VALIDATION_ERROR",
      "account_id": "acc_1001",
      "class_id": "class_1001",
      "credit_amount": "125.00",
      "debit_amount": "125.00",
      "description": "Office supplies",
      "dimensions": {},
      "line_number": 0,
      "line_ref": "line_ref_sample",
      "location_id": "loc_1001",
      "metadata": {}
    }
  ],
  "memo": "Payment received",
  "metadata": {},
  "posting_period": "posting_period_sample",
  "reverses_entry_id": "reverses_entry_id_sample",
  "status": "draft"
}'

GET /v1/journal_entries/{id}

Get a journal entry

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required JournalEntryRecord A journal_entry record as returned by the API

Show data fields

Field Type Description

approval_status string Approval Status

created_at string (date-time)

currency string Currency

dimensions object Dimensions

document_date string (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 string (date) Accounting effective date for reporting, posting, and period cutoffs. Defaults to document_date when omitted.

entry_date required string (date) Entry Date

entry_number string Entry Number

id string Backfill canonical record ID assigned after persistence. This is distinct from the source-system ID.

lines required array of object Lines

Show lines[] fields

Field	Type	Description
account_code	string	Account Code
account_id required	string	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.
class_id	string	Identifier for the related class record.
credit_amount	string	Credit Amount
debit_amount	string	Debit Amount
description	string	Description
dimensions	object	Dimensions
line_number	integer	One-based display order of the line within the document. Use for ordering and presentation, not stable identity.
line_ref	string	Provider-native line reference. Use it to match the same source line across document versions and related documents.
location_id	string	Identifier for the related location record.
metadata	object	Metadata

memo string Memo

metadata object Metadata

posting_period string Posting Period

reverses_entry_id string Identifier for the related reverses entry record.

source_id required string 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_system required string Connector or provider that supplied the record, such as stripe, shopify, qbo, csv_upload, or manual.

status required string Status

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "dimensions": {},
    "document_date": "2026-05-05",
    "effective_date": "2026-05-05",
    "entry_date": "2026-05-05",
    "entry_number": "1001",
    "id": "00000000-0000-0000-0000-000000000000",
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "class_id": "class_1001",
        "credit_amount": "125.00",
        "debit_amount": "125.00",
        "description": "Office supplies",
        "dimensions": {},
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "location_id": "loc_1001",
        "metadata": {}
      }
    ],
    "memo": "Payment received",
    "metadata": {},
    "posting_period": "posting_period_sample",
    "reverses_entry_id": "reverses_entry_id_sample",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "journal_entry"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/journal_entries/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

PUT /v1/journal_entries/{id}

Update a journal entry

Path parameters

Name	Type	Description
id required	string	Resource identifier

Request body required

Field Type Description

approval_status string Approval Status

currency string Currency

dimensions object Dimensions

document_date string (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 string (date) Accounting effective date for reporting, posting, and period cutoffs. Defaults to document_date when omitted.

entry_date string (date) Entry Date

lines array of object Lines

Show lines[] fields

Field	Type	Description
account_code	string	Account Code
account_id required	string	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.
class_id	string	Identifier for the related class record.
credit_amount	string	Credit Amount
debit_amount	string	Debit Amount
description	string	Description
dimensions	object	Dimensions
line_number	integer	One-based display order of the line within the document. Use for ordering and presentation, not stable identity.
line_ref	string	Provider-native line reference. Use it to match the same source line across document versions and related documents.
location_id	string	Identifier for the related location record.
metadata	object	Metadata

memo string Memo

metadata object Metadata

posting_period string Posting Period

reverses_entry_id string Identifier for the related reverses entry record.

status string Status

{
  "approval_status": "draft",
  "currency": "USD",
  "dimensions": {},
  "document_date": "2026-05-05",
  "effective_date": "2026-05-05",
  "entry_date": "2026-05-05",
  "lines": [
    {
      "account_code": "VALIDATION_ERROR",
      "account_id": "acc_1001",
      "class_id": "class_1001",
      "credit_amount": "125.00",
      "debit_amount": "125.00",
      "description": "Office supplies",
      "dimensions": {},
      "line_number": 0,
      "line_ref": "line_ref_sample",
      "location_id": "loc_1001",
      "metadata": {}
    }
  ],
  "memo": "Payment received",
  "metadata": {},
  "posting_period": "posting_period_sample",
  "reverses_entry_id": "reverses_entry_id_sample",
  "status": "draft"
}

Responses

200 Success

Field Type Description

data required JournalEntryRecord A journal_entry record as returned by the API

Show data fields

Field Type Description

approval_status string Approval Status

created_at string (date-time)

currency string Currency

dimensions object Dimensions

document_date string (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 string (date) Accounting effective date for reporting, posting, and period cutoffs. Defaults to document_date when omitted.

entry_date required string (date) Entry Date

entry_number string Entry Number

id string Backfill canonical record ID assigned after persistence. This is distinct from the source-system ID.

lines required array of object Lines

Show lines[] fields

Field	Type	Description
account_code	string	Account Code
account_id required	string	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.
class_id	string	Identifier for the related class record.
credit_amount	string	Credit Amount
debit_amount	string	Debit Amount
description	string	Description
dimensions	object	Dimensions
line_number	integer	One-based display order of the line within the document. Use for ordering and presentation, not stable identity.
line_ref	string	Provider-native line reference. Use it to match the same source line across document versions and related documents.
location_id	string	Identifier for the related location record.
metadata	object	Metadata

memo string Memo

metadata object Metadata

posting_period string Posting Period

reverses_entry_id string Identifier for the related reverses entry record.

source_id required string 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_system required string Connector or provider that supplied the record, such as stripe, shopify, qbo, csv_upload, or manual.

status required string Status

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "dimensions": {},
    "document_date": "2026-05-05",
    "effective_date": "2026-05-05",
    "entry_date": "2026-05-05",
    "entry_number": "1001",
    "id": "00000000-0000-0000-0000-000000000000",
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "class_id": "class_1001",
        "credit_amount": "125.00",
        "debit_amount": "125.00",
        "description": "Office supplies",
        "dimensions": {},
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "location_id": "loc_1001",
        "metadata": {}
      }
    ],
    "memo": "Payment received",
    "metadata": {},
    "posting_period": "posting_period_sample",
    "reverses_entry_id": "reverses_entry_id_sample",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "journal_entry"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X PUT "https://api.backfill.io/v1/journal_entries/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "approval_status": "draft",
  "currency": "USD",
  "dimensions": {},
  "document_date": "2026-05-05",
  "effective_date": "2026-05-05",
  "entry_date": "2026-05-05",
  "lines": [
    {
      "account_code": "VALIDATION_ERROR",
      "account_id": "acc_1001",
      "class_id": "class_1001",
      "credit_amount": "125.00",
      "debit_amount": "125.00",
      "description": "Office supplies",
      "dimensions": {},
      "line_number": 0,
      "line_ref": "line_ref_sample",
      "location_id": "loc_1001",
      "metadata": {}
    }
  ],
  "memo": "Payment received",
  "metadata": {},
  "posting_period": "posting_period_sample",
  "reverses_entry_id": "reverses_entry_id_sample",
  "status": "draft"
}'

PATCH /v1/journal_entries/{id}/memo

Update journal entry memo

Path parameters

Name	Type	Description
id required	string	Journal entry ID

Request body required

Field	Type	Description
memo required	string

{
  "memo": "Payment received"
}

Responses

200 Journal entry

Field Type Description

data required object

Show data fields

Field Type Description

entry_date string (date)

entry_number [string null]

lines array of object

Show lines[] fields

Field	Type	Description
account_code	[string null]
account_id required	string (uuid)
account_name	[string null]
class_id	[string null] (uuid)
credit_amount	[string null]
debit_amount	[string null]
dimensions	object
id required	string (uuid)
line_number required	integer
location_id	[string null] (uuid)
memo	[string null]

memo [string null]

posted_at [string null] (date-time)

status string

totals object

Show totals fields

Field	Type	Description
balanced	boolean
credits	string	Decimal string
debits	string	Decimal string

id required string (uuid)

object required string

{
  "data": {
    "entry_date": "2026-05-05",
    "entry_number": "1001",
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "00000000-0000-0000-0000-000000000000",
        "account_name": "acc_1001",
        "class_id": "00000000-0000-0000-0000-000000000000",
        "credit_amount": "125.00",
        "debit_amount": "125.00",
        "dimensions": {},
        "id": "00000000-0000-0000-0000-000000000000",
        "line_number": 0,
        "location_id": "00000000-0000-0000-0000-000000000000",
        "memo": "Payment received"
      }
    ],
    "memo": "Payment received",
    "posted_at": "2026-05-05T12:00:00Z",
    "status": "draft",
    "totals": {
      "balanced": false,
      "credits": "credits_sample",
      "debits": "debits_sample"
    }
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "journal_entry"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X PATCH "https://api.backfill.io/v1/journal_entries/{id}/memo" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "memo": "Payment received"
}'

DELETE /v1/journal_entries/{id}

Delete a journal entry

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Deleted

Field	Type	Description
deleted required	boolean
id required	string (uuid)
object required	string

{
  "deleted": true,
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "record"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X DELETE "https://api.backfill.io/v1/journal_entries/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/journal_entries/{id}/confirm

Confirm a draft journal entry

Path parameters

Name	Type	Description
id required	string	Resource identifier

Responses

200 Success

Field Type Description

data required JournalEntryRecord A journal_entry record as returned by the API

Show data fields

Field Type Description

approval_status string Approval Status

created_at string (date-time)

currency string Currency

dimensions object Dimensions

document_date string (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 string (date) Accounting effective date for reporting, posting, and period cutoffs. Defaults to document_date when omitted.

entry_date required string (date) Entry Date

entry_number string Entry Number

id string Backfill canonical record ID assigned after persistence. This is distinct from the source-system ID.

lines required array of object Lines

Show lines[] fields

Field	Type	Description
account_code	string	Account Code
account_id required	string	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.
class_id	string	Identifier for the related class record.
credit_amount	string	Credit Amount
debit_amount	string	Debit Amount
description	string	Description
dimensions	object	Dimensions
line_number	integer	One-based display order of the line within the document. Use for ordering and presentation, not stable identity.
line_ref	string	Provider-native line reference. Use it to match the same source line across document versions and related documents.
location_id	string	Identifier for the related location record.
metadata	object	Metadata

memo string Memo

metadata object Metadata

posting_period string Posting Period

reverses_entry_id string Identifier for the related reverses entry record.

source_id required string 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_system required string Connector or provider that supplied the record, such as stripe, shopify, qbo, csv_upload, or manual.

status required string Status

updated_at string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "approval_status": "draft",
    "connection_id": "conn_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "currency": "USD",
    "dimensions": {},
    "document_date": "2026-05-05",
    "effective_date": "2026-05-05",
    "entry_date": "2026-05-05",
    "entry_number": "1001",
    "id": "00000000-0000-0000-0000-000000000000",
    "lines": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "acc_1001",
        "class_id": "class_1001",
        "credit_amount": "125.00",
        "debit_amount": "125.00",
        "description": "Office supplies",
        "dimensions": {},
        "line_number": 0,
        "line_ref": "line_ref_sample",
        "location_id": "loc_1001",
        "metadata": {}
      }
    ],
    "memo": "Payment received",
    "metadata": {},
    "posting_period": "posting_period_sample",
    "reverses_entry_id": "reverses_entry_id_sample",
    "source_id": "src_1001",
    "source_system": "api",
    "status": "draft",
    "updated_at": "2026-05-05T12:00:00Z"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "journal_entry"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

404 Not found

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

409 Conflict

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/journal_entries/{id}/confirm" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

Reports

GET /v1/reports/balance_sheet

Get balance sheet

Query parameters

Name	Type	Description
as_of_date	string (date)	Report as-of date (YYYY-MM-DD)

Responses

200 Balance sheet data

Field Type Description

accounting_method string

as_of_date string (date)

assets object

Show assets fields

Field	Type	Description
name	string
rows	array of object
total	string	Decimal string

Plus user-defined fields (additionalProperties: true).

balanced boolean

equity object

Show equity fields

Field	Type	Description
name	string
rows	array of object
total	string	Decimal string

Plus user-defined fields (additionalProperties: true).

liabilities object

Show liabilities fields

Field	Type	Description
name	string
rows	array of object
total	string	Decimal string

Plus user-defined fields (additionalProperties: true).

object required string

report_type required string

tenant_id required string (uuid)

total_assets string Decimal string

total_equity string Decimal string

total_liabilities string Decimal string

{
  "accounting_method": "acc_1001",
  "as_of_date": "2026-05-05",
  "assets": {
    "name": "Acme Supplies",
    "rows": [
      {}
    ],
    "total": "total_sample"
  },
  "balanced": false,
  "equity": {
    "name": "Acme Supplies",
    "rows": [
      {}
    ],
    "total": "total_sample"
  },
  "liabilities": {
    "name": "Acme Supplies",
    "rows": [
      {}
    ],
    "total": "total_sample"
  },
  "object": "report",
  "report_type": "balance_sheet",
  "tenant_id": "00000000-0000-0000-0000-000000000000",
  "total_assets": "total_assets_sample",
  "total_equity": "total_equity_sample",
  "total_liabilities": "total_liabilities_sample"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/reports/balance_sheet" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

GET /v1/reports/cash_flow

Get cash-flow statement

Query parameters

Name	Type	Description
start_date	string (date)	Period start date
end_date	string (date)	Period end date

Responses

200 Cash-flow statement data

Field Type Description

accounting_method string

actual_change_in_cash string Decimal string

beginning_cash string Decimal string

end_date string (date)

ending_cash string Decimal string

financing object

Show financing fields

Field Type Description

rows array of object

Show rows[] fields

Field	Type	Description
account_code	[string null]
account_id	string (uuid)
account_name	[string null]
account_sub_type	[string null]
account_type	[string null]
amount	string	Decimal string
closing_balance	string	Decimal string
delta	string	Decimal string
opening_balance	string	Decimal string
section	string

total string Decimal string

investing object

Show investing fields

Field Type Description

rows array of object

Show rows[] fields

Field	Type	Description
account_code	[string null]
account_id	string (uuid)
account_name	[string null]
account_sub_type	[string null]
account_type	[string null]
amount	string	Decimal string
closing_balance	string	Decimal string
delta	string	Decimal string
opening_balance	string	Decimal string
section	string

total string Decimal string

net_change_in_cash string Decimal string

net_income string Decimal string

object required string

operating object

Show operating fields

Field Type Description

adjustments array of object

Show adjustments[] fields

Field	Type	Description
account_code	[string null]
account_id	string (uuid)
account_name	[string null]
account_sub_type	[string null]
account_type	[string null]
amount	string	Decimal string
closing_balance	string	Decimal string
delta	string	Decimal string
opening_balance	string	Decimal string
section	string

total string Decimal string

working_capital array of object

Show working_capital[] fields

Field	Type	Description
account_code	[string null]
account_id	string (uuid)
account_name	[string null]
account_sub_type	[string null]
account_type	[string null]
amount	string	Decimal string
closing_balance	string	Decimal string
delta	string	Decimal string
opening_balance	string	Decimal string
section	string

reconciled boolean

reconciliation_difference string Decimal string

report_type required string

start_date string (date)

tenant_id required string (uuid)

{
  "accounting_method": "acc_1001",
  "actual_change_in_cash": "actual_change_in_cash_sample",
  "beginning_cash": "beginning_cash_sample",
  "end_date": "2026-05-05",
  "ending_cash": "ending_cash_sample",
  "financing": {
    "rows": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "00000000-0000-0000-0000-000000000000",
        "account_name": "acc_1001",
        "account_sub_type": "acc_1001",
        "account_type": "acc_1001",
        "amount": "125.00",
        "closing_balance": "125.00",
        "delta": "delta_sample",
        "opening_balance": "125.00",
        "section": "section_sample"
      }
    ],
    "total": "total_sample"
  },
  "investing": {
    "rows": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "00000000-0000-0000-0000-000000000000",
        "account_name": "acc_1001",
        "account_sub_type": "acc_1001",
        "account_type": "acc_1001",
        "amount": "125.00",
        "closing_balance": "125.00",
        "delta": "delta_sample",
        "opening_balance": "125.00",
        "section": "section_sample"
      }
    ],
    "total": "total_sample"
  },
  "net_change_in_cash": "net_change_in_cash_sample",
  "net_income": "net_income_sample",
  "object": "report",
  "operating": {
    "adjustments": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "00000000-0000-0000-0000-000000000000",
        "account_name": "acc_1001",
        "account_sub_type": "acc_1001",
        "account_type": "acc_1001",
        "amount": "125.00",
        "closing_balance": "125.00",
        "delta": "delta_sample",
        "opening_balance": "125.00",
        "section": "section_sample"
      }
    ],
    "total": "total_sample",
    "working_capital": [
      {
        "account_code": "VALIDATION_ERROR",
        "account_id": "00000000-0000-0000-0000-000000000000",
        "account_name": "acc_1001",
        "account_sub_type": "acc_1001",
        "account_type": "acc_1001",
        "amount": "125.00",
        "closing_balance": "125.00",
        "delta": "delta_sample",
        "opening_balance": "125.00",
        "section": "section_sample"
      }
    ]
  },
  "reconciled": false,
  "reconciliation_difference": "reconciliation_difference_sample",
  "report_type": "cash_flow",
  "start_date": "2026-05-05",
  "tenant_id": "00000000-0000-0000-0000-000000000000"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/reports/cash_flow" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

GET /v1/reports/income_statement

Get income statement (profit & loss)

Query parameters

Name	Type	Description
start_date	string (date)	Period start date
end_date	string (date)	Period end date

Responses

200 Income statement data

Field Type Description

accounting_method string

cogs object

Show cogs fields

Field	Type	Description
name	string
rows	array of object
total	string	Decimal string

Plus user-defined fields (additionalProperties: true).

end_date string (date)

expenses object

Show expenses fields

Field	Type	Description
name	string
rows	array of object
total	string	Decimal string

Plus user-defined fields (additionalProperties: true).

gross_profit string Decimal string

income object

Show income fields

Field	Type	Description
name	string
rows	array of object
total	string	Decimal string

Plus user-defined fields (additionalProperties: true).

net_income string Decimal string

object required string

report_type required string

start_date string (date)

tenant_id required string (uuid)

{
  "accounting_method": "acc_1001",
  "cogs": {
    "name": "Acme Supplies",
    "rows": [
      {}
    ],
    "total": "total_sample"
  },
  "end_date": "2026-05-05",
  "expenses": {
    "name": "Acme Supplies",
    "rows": [
      {}
    ],
    "total": "total_sample"
  },
  "gross_profit": "gross_profit_sample",
  "income": {
    "name": "Acme Supplies",
    "rows": [
      {}
    ],
    "total": "total_sample"
  },
  "net_income": "net_income_sample",
  "object": "report",
  "report_type": "income_statement",
  "start_date": "2026-05-05",
  "tenant_id": "00000000-0000-0000-0000-000000000000"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/reports/income_statement" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

GET /v1/reports/trial_balance

Get trial balance report

Query parameters

Name	Type	Description
as_of_date	string (date)	Report as-of date (YYYY-MM-DD)

Responses

200 Trial balance data

Field Type Description

as_of_date required string (date)

balanced boolean

object required string

report_type required string

rows required array of object

Show rows[] fields

Field	Type	Description
account_code	[string null]
account_id required	string (uuid)
account_name required	string
account_type required	string
credit_total required	string	Decimal string
debit_total required	string	Decimal string
net_credit required	string	Decimal string
net_debit required	string	Decimal string

tenant_id required string (uuid)

totals required object

Show totals fields

Field	Type	Description
balanced	boolean
credits	string	Decimal string
debits	string	Decimal string

{
  "as_of_date": "2026-05-05",
  "balanced": false,
  "object": "report",
  "report_type": "trial_balance",
  "rows": [
    {
      "account_code": "VALIDATION_ERROR",
      "account_id": "00000000-0000-0000-0000-000000000000",
      "account_name": "acc_1001",
      "account_type": "acc_1001",
      "credit_total": "credit_total_sample",
      "debit_total": "debit_total_sample",
      "net_credit": "net_credit_sample",
      "net_debit": "net_debit_sample"
    }
  ],
  "tenant_id": "00000000-0000-0000-0000-000000000000",
  "totals": {
    "balanced": false,
    "credits": "credits_sample",
    "debits": "debits_sample"
  }
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/reports/trial_balance" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/reports/balance_sheet/export

Export balance sheet CSV

Query parameters

Name	Type	Description
as_of_date	string (date)	Report as-of date (YYYY-MM-DD)

Responses

201 Balance sheet export

Field	Type	Description
download_url required	string
format	string
id required	string (uuid)
object required	string
report_type	string

{
  "download_url": "download_url_sample",
  "format": "format_sample",
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "export",
  "report_type": "report_type_sample"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/reports/balance_sheet/export" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/reports/balance_sheet/export_pdf

Export balance sheet PDF

Query parameters

Name	Type	Description
as_of_date	string (date)	Report as-of date (YYYY-MM-DD)

Responses

201 Balance sheet PDF export

Field	Type	Description
download_url required	string
format	string
id required	string (uuid)
object required	string
report_type	string

{
  "download_url": "download_url_sample",
  "format": "format_sample",
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "export",
  "report_type": "report_type_sample"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/reports/balance_sheet/export_pdf" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/reports/cash_flow/export

Export cash-flow statement CSV

Query parameters

Name	Type	Description
start_date	string (date)	Period start date
end_date	string (date)	Period end date

Responses

201 Cash-flow statement export

Field	Type	Description
download_url required	string
format	string
id required	string (uuid)
object required	string
report_type	string

{
  "download_url": "download_url_sample",
  "format": "format_sample",
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "export",
  "report_type": "report_type_sample"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/reports/cash_flow/export" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/reports/cash_flow/export_pdf

Export cash-flow statement PDF

Query parameters

Name	Type	Description
start_date	string (date)	Period start date
end_date	string (date)	Period end date

Responses

201 Cash-flow statement PDF export

Field	Type	Description
download_url required	string
format	string
id required	string (uuid)
object required	string
report_type	string

{
  "download_url": "download_url_sample",
  "format": "format_sample",
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "export",
  "report_type": "report_type_sample"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/reports/cash_flow/export_pdf" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/reports/income_statement/export

Export income statement CSV

Query parameters

Name	Type	Description
start_date	string (date)	Period start date
end_date	string (date)	Period end date

Responses

201 Income statement export

Field	Type	Description
download_url required	string
format	string
id required	string (uuid)
object required	string
report_type	string

{
  "download_url": "download_url_sample",
  "format": "format_sample",
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "export",
  "report_type": "report_type_sample"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/reports/income_statement/export" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/reports/income_statement/export_pdf

Export income statement PDF

Query parameters

Name	Type	Description
start_date	string (date)	Period start date
end_date	string (date)	Period end date

Responses

201 Income statement PDF export

Field	Type	Description
download_url required	string
format	string
id required	string (uuid)
object required	string
report_type	string

{
  "download_url": "download_url_sample",
  "format": "format_sample",
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "export",
  "report_type": "report_type_sample"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/reports/income_statement/export_pdf" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/reports/trial_balance/export

Export trial balance CSV

Query parameters

Name	Type	Description
as_of_date	string (date)	Report as-of date (YYYY-MM-DD)

Responses

201 Trial balance export

Field	Type	Description
download_url required	string
format	string
id required	string (uuid)
object required	string
report_type	string

{
  "download_url": "download_url_sample",
  "format": "format_sample",
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "export",
  "report_type": "report_type_sample"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/reports/trial_balance/export" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

Datasets

GET /v1/datasets

List datasets

Query parameters

Name	Type	Description
scope	string	Filter by dataset scope

Responses

200 Dataset list

Field Type Description

data required array of object

Show data[] fields

Field Type Description

data required object

Show data fields

Field	Type	Description
columns	array of string
description	[string null]
filters	object
is_default	boolean
json_schema	object
name	string
schema_version	integer
scope	string
sort	array of object
temporal_params	object

Plus user-defined fields (additionalProperties: true).

id required string (uuid)

object required string

{
  "data": [
    {
      "data": {
        "columns": [
          "columns_sample"
        ],
        "description": "Office supplies",
        "filters": {},
        "is_default": false,
        "json_schema": {},
        "name": "Acme Supplies",
        "schema_version": 0,
        "scope": "scope_sample",
        "sort": [
          {}
        ],
        "temporal_params": {}
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "object": "dataset"
    }
  ],
  "object": "list"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/datasets" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

GET /v1/datasets/{id}

Get dataset metadata

Path parameters

Name	Type	Description
id required	string	Dataset ID

Responses

200 Dataset metadata

Field Type Description

data required object

Show data fields

Field	Type	Description
columns	array of string
description	[string null]
filters	object
is_default	boolean
json_schema	object
name	string
schema_version	integer
scope	string
sort	array of object
temporal_params	object

Plus user-defined fields (additionalProperties: true).

id required string (uuid)

object required string

{
  "data": {
    "columns": [
      "columns_sample"
    ],
    "description": "Office supplies",
    "filters": {},
    "is_default": false,
    "json_schema": {},
    "name": "Acme Supplies",
    "schema_version": 0,
    "scope": "scope_sample",
    "sort": [
      {}
    ],
    "temporal_params": {}
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "dataset"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/datasets/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/datasets/{id}/export

Export dataset CSV

Path parameters

Name	Type	Description
id required	string	Dataset ID

Responses

201 Dataset export

Field Type Description

data required object

Show data fields

Field	Type	Description
dataset_id required	string (uuid)
dataset_name required	string
download_url required	string
row_count required	integer

id required string (uuid)

object required string

{
  "data": {
    "dataset_id": "00000000-0000-0000-0000-000000000000",
    "dataset_name": "Acme Supplies",
    "download_url": "download_url_sample",
    "row_count": 0
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "export"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/datasets/{id}/export" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

GET /v1/datasets/{id}/data

Query dataset data

Path parameters

Name	Type	Description
id required	string	Dataset ID

Query parameters

Name	Type	Description
format	string	Response format: json or csv
limit	integer	Maximum number of rows
offset	integer	Number of rows to skip

Responses

200 Dataset query result

Field Type Description

data required array of object

meta required object

Show meta fields

Field	Type	Description
has_more required	boolean
limit required	integer
offset required	integer
total_count required	integer

object required string

pagination required object

Show pagination fields

Field	Type	Description
has_more required	boolean
limit required	integer
offset required	integer
total_count required	integer

{
  "data": [
    {}
  ],
  "meta": {
    "has_more": false,
    "limit": 0,
    "offset": 0,
    "total_count": 0
  },
  "object": "dataset_query",
  "pagination": {
    "has_more": false,
    "limit": 0,
    "offset": 0,
    "total_count": 0
  }
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/datasets/{id}/data" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

Attachments

GET /v1/attachments

List record attachments

Query parameters

Name	Type	Description
record_type	string	Attached record type
record_id	string	Attached record ID

Responses

200 Attachment list

Field Type Description

count integer

data required array of object

Show data[] fields

Field	Type	Description
base64_content	[string null]
byte_size	integer
content_type	string
description	[string null]
filename	string
id	string (uuid)
kind	[string null]
source	[string null]
title	[string null]

Plus user-defined fields (additionalProperties: true).

object required string

pagination required object

Show pagination fields

Field	Type	Description
has_more required	boolean
limit required	integer
page required	integer
total_count required	integer

{
  "count": 0,
  "data": [
    {
      "base64_content": "base64_content_sample",
      "byte_size": 0,
      "content_type": "content_type_sample",
      "description": "Office supplies",
      "filename": "Acme Supplies",
      "id": "00000000-0000-0000-0000-000000000000",
      "kind": "kind_sample",
      "source": "src_1001",
      "title": "title_sample"
    }
  ],
  "object": "list",
  "pagination": {
    "has_more": false,
    "limit": 0,
    "page": 0,
    "total_count": 0
  }
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/attachments" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/attachments

Create record attachment

Request body required

Field	Type	Description
base64_content required	string
content_type required	string
description	string
filename required	string
kind	string
record_id required	string (uuid)
record_type required	string
source	string
title	string

{
  "base64_content": "base64_content_sample",
  "content_type": "content_type_sample",
  "description": "Office supplies",
  "filename": "Acme Supplies",
  "kind": "kind_sample",
  "record_id": "00000000-0000-0000-0000-000000000000",
  "record_type": "record_type_sample",
  "source": "src_1001",
  "title": "title_sample"
}

Responses

201 Created attachment

Field Type Description

data required object

Show data fields

Field	Type	Description
base64_content	[string null]
byte_size	integer
content_type	string
description	[string null]
filename	string
id	string (uuid)
kind	[string null]
source	[string null]
title	[string null]

Plus user-defined fields (additionalProperties: true).

id required string (uuid)

object required string

{
  "data": {
    "base64_content": "base64_content_sample",
    "byte_size": 0,
    "content_type": "content_type_sample",
    "description": "Office supplies",
    "filename": "Acme Supplies",
    "id": "00000000-0000-0000-0000-000000000000",
    "kind": "kind_sample",
    "source": "src_1001",
    "title": "title_sample"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "attachment"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/attachments" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "base64_content": "base64_content_sample",
  "content_type": "content_type_sample",
  "description": "Office supplies",
  "filename": "Acme Supplies",
  "kind": "kind_sample",
  "record_id": "00000000-0000-0000-0000-000000000000",
  "record_type": "record_type_sample",
  "source": "src_1001",
  "title": "title_sample"
}'

GET /v1/attachments/{id}

Get record attachment

Path parameters

Name	Type	Description
id required	string	Attachment ID

Query parameters

Name	Type	Description
record_type	string	Attached record type
record_id	string	Attached record ID
include_content	boolean	Include base64 file content

Responses

200 Attachment

Field Type Description

data required object

Show data fields

Field	Type	Description
base64_content	[string null]
byte_size	integer
content_type	string
description	[string null]
filename	string
id	string (uuid)
kind	[string null]
source	[string null]
title	[string null]

Plus user-defined fields (additionalProperties: true).

id required string (uuid)

object required string

{
  "data": {
    "base64_content": "base64_content_sample",
    "byte_size": 0,
    "content_type": "content_type_sample",
    "description": "Office supplies",
    "filename": "Acme Supplies",
    "id": "00000000-0000-0000-0000-000000000000",
    "kind": "kind_sample",
    "source": "src_1001",
    "title": "title_sample"
  },
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "attachment"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/attachments/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

DELETE /v1/attachments/{id}

Delete record attachment

Path parameters

Name	Type	Description
id required	string	Attachment ID

Query parameters

Name	Type	Description
record_type	string	Attached record type
record_id	string	Attached record ID

Responses

200 Deleted attachment

Field	Type	Description
deleted required	boolean
id required	string (uuid)
object required	string

{
  "deleted": false,
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "attachment"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X DELETE "https://api.backfill.io/v1/attachments/{id}" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

GET /v1/attachments/{id}/download

Download record attachment

Path parameters

Name	Type	Description
id required	string	Attachment ID

Query parameters

Name	Type	Description
record_type	string	Attached record type
record_id	string	Attached record ID

Responses

200 Attachment bytes

No response body.

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/attachments/{id}/download" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

Extensions

GET /v1/extensions/{key}/versions

List extension versions

Path parameters

Name	Type	Description
key required	string	Extension key

Responses

200 Extension versions

Field Type Description

data required object

Show data fields

Field Type Description

versions array of object

Show versions[] fields

Field	Type	Description
id	string (uuid)
is_active	boolean
mode	string
semver	[string null]
status	string
version	integer

Plus user-defined fields (additionalProperties: true).

message required string

status required string

{
  "data": {
    "versions": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "is_active": false,
        "mode": "mode_sample",
        "semver": "semver_sample",
        "status": "draft",
        "version": 0
      }
    ]
  },
  "message": "Request validation failed",
  "status": "success"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/extensions/{key}/versions" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

GET /v1/extensions/hooks

List extension hooks

Query parameters

Name	Type	Description
extension_key	string	Filter hooks to an extension key

Responses

200 Extension hooks

Field Type Description

data required object

Show data fields

Field Type Description

hooks array of object

Show hooks[] fields

Field	Type	Description
entity_type	string
extension_key	string
id	string (uuid)
operation	string

Plus user-defined fields (additionalProperties: true).

message required string

status required string

{
  "data": {
    "hooks": [
      {
        "entity_type": "entity_type_sample",
        "extension_key": "extension_key_sample",
        "id": "00000000-0000-0000-0000-000000000000",
        "operation": "operation_sample"
      }
    ]
  },
  "message": "Request validation failed",
  "status": "success"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/extensions/hooks" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

GET /v1/extensions/jobs

List extension jobs

Query parameters

Name	Type	Description
extension_key	string	Filter jobs to an extension key

Responses

200 Extension jobs

Field Type Description

data required object

Show data fields

Field Type Description

jobs array of object

Show jobs[] fields

Field	Type	Description
enabled	boolean
id	string (uuid)
name	string
schedule	[string null]

Plus user-defined fields (additionalProperties: true).

message required string

status required string

{
  "data": {
    "jobs": [
      {
        "enabled": false,
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "Acme Supplies",
        "schedule": "schedule_sample"
      }
    ]
  },
  "message": "Request validation failed",
  "status": "success"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/extensions/jobs" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

GET /v1/extensions/logs

List extension execution logs

Query parameters

Name	Type	Description
since	string	ISO 8601 timestamp cursor
extension_key	string	Filter logs to an extension key

Responses

200 Extension logs

Field Type Description

data required object

Show data fields

Field Type Description

cursor string (date-time)

logs array of object

Show logs[] fields

Field	Type	Description
event	string
id	string (uuid)
inserted_at	string (date-time)
status	string

Plus user-defined fields (additionalProperties: true).

message required string

status required string

{
  "data": {
    "cursor": "2026-05-05T12:00:00Z",
    "logs": [
      {
        "event": "event_sample",
        "id": "00000000-0000-0000-0000-000000000000",
        "inserted_at": "2026-05-05T12:00:00Z",
        "status": "draft"
      }
    ]
  },
  "message": "Request validation failed",
  "status": "success"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/extensions/logs" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

GET /v1/extensions/auth

Get extension API auth context

Responses

200 Extension authentication context

Field Type Description

data required object

Show data fields

Field	Type	Description
client_name	string
extensions_deploy	boolean
scopes	array of string
tenant_id	string (uuid)
tenant_name	[string null]

message required string

status required string

{
  "data": {
    "client_name": "Acme Supplies",
    "extensions_deploy": false,
    "scopes": [
      "scopes_sample"
    ],
    "tenant_id": "00000000-0000-0000-0000-000000000000",
    "tenant_name": "Acme Supplies"
  },
  "message": "Request validation failed",
  "status": "success"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X GET "https://api.backfill.io/v1/extensions/auth" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/extensions/deploy

Deploy extension

Request body required

Field	Type	Description
mode	string
source_files required	object

{
  "mode": "live",
  "source_files": {}
}

Responses

201 Deployed extension version

Field Type Description

data required object

Show data fields

Field	Type	Description
id	string (uuid)
is_active	boolean
mode	string
semver	[string null]
status	string
version	integer

Plus user-defined fields (additionalProperties: true).

message required string

status required string

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "is_active": false,
    "mode": "mode_sample",
    "semver": "semver_sample",
    "status": "draft",
    "version": 0
  },
  "message": "Request validation failed",
  "status": "success"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/extensions/deploy" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "live",
  "source_files": {}
}'

POST /v1/extensions/dev-deploy

Deploy mutable development extension

Request body required

Field	Type	Description
mode	string
source_files required	object

{
  "mode": "live",
  "source_files": {}
}

Responses

201 Deployed development extension version

Field Type Description

data required object

Show data fields

Field	Type	Description
id	string (uuid)
is_active	boolean
mode	string
semver	[string null]
status	string
version	integer

Plus user-defined fields (additionalProperties: true).

message required string

status required string

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "is_active": false,
    "mode": "mode_sample",
    "semver": "semver_sample",
    "status": "draft",
    "version": 0
  },
  "message": "Request validation failed",
  "status": "success"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/extensions/dev-deploy" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "live",
  "source_files": {}
}'

POST /v1/extensions/{key}/promote

Promote extension version

Path parameters

Name	Type	Description
key required	string	Extension key

Responses

200 Promoted extension version

Field Type Description

data required object

Show data fields

Field	Type	Description
id	string (uuid)
is_active	boolean
mode	string
semver	[string null]
status	string
version	integer

Plus user-defined fields (additionalProperties: true).

message required string

status required string

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "is_active": false,
    "mode": "mode_sample",
    "semver": "semver_sample",
    "status": "draft",
    "version": 0
  },
  "message": "Request validation failed",
  "status": "success"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/extensions/{key}/promote" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/extensions/{key}/rollback

Roll back extension

Path parameters

Name	Type	Description
key required	string	Extension key

Request body required

Field	Type	Description
version_id required	string (uuid)

{
  "version_id": "00000000-0000-0000-0000-000000000000"
}

Responses

200 Rolled back extension version

Field Type Description

data required object

Show data fields

Field	Type	Description
id	string (uuid)
is_active	boolean
mode	string
semver	[string null]
status	string
version	integer

Plus user-defined fields (additionalProperties: true).

message required string

status required string

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "is_active": false,
    "mode": "mode_sample",
    "semver": "semver_sample",
    "status": "draft",
    "version": 0
  },
  "message": "Request validation failed",
  "status": "success"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/extensions/{key}/rollback" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "version_id": "00000000-0000-0000-0000-000000000000"
}'

POST /v1/extensions/{key}/jobs/{name}/run

Run extension job

Path parameters

Name	Type	Description
key required	string	Extension key
name required	string	Job name

Responses

200 Triggered extension job

Field Type Description

data required object

Show data fields

Field Type Description

job object

Show job fields

Field	Type	Description
enabled	boolean
id	string (uuid)
name	string
schedule	[string null]

Plus user-defined fields (additionalProperties: true).

triggered boolean

message required string

status required string

{
  "data": {
    "job": {
      "enabled": false,
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "Acme Supplies",
      "schedule": "schedule_sample"
    },
    "triggered": false
  },
  "message": "Request validation failed",
  "status": "success"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/extensions/{key}/jobs/{name}/run" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/extensions/trigger

Trigger extension hook

Request body required

Field	Type	Description
entity required	object
hook_id required	string (uuid)

{
  "entity": {},
  "hook_id": "00000000-0000-0000-0000-000000000000"
}

Responses

200 Hook execution result

Field Type Description

data required object

Show data fields

Field	Type	Description
result	object

message required string

status required string

{
  "data": {
    "result": {}
  },
  "message": "Request validation failed",
  "status": "success"
}

401 Unauthorized

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

422 Validation error

Field Type Description

code required string

errors array of object

Show errors[] fields

Field	Type	Description
code	string
field	string
message	string

message required string

status required string

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "name",
      "message": "Request validation failed"
    }
  ],
  "message": "Request validation failed",
  "status": "error"
}

Example request

curl -X POST "https://api.backfill.io/v1/extensions/trigger" \
  -H "Authorization: Bearer $BACKFILL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "entity": {},
  "hook_id": "00000000-0000-0000-0000-000000000000"
}'