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.

Customers

GET /v1/customers

List customers

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
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 Pagination

Show pagination fields

Field	Type	Description
limit	integer
page	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_ids": [
          {}
        ],
        "updated_at": "2026-05-05T12:00:00Z"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "object": "customer"
    }
  ],
  "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/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_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_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_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_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_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_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_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_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_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_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_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_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
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 Pagination

Show pagination fields

Field	Type	Description
limit	integer
page	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": {
    "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/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
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 Pagination

Show pagination fields

Field	Type	Description
limit	integer
page	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": {
    "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/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
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"

Invoices

GET /v1/invoices

List invoices

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
status	string	Filter by status
customer_id	string	Filter by customer 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 Pagination

Show pagination fields

Field	Type	Description
limit	integer
page	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": {
    "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/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

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}/confirm

Confirm a draft invoice

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"
}

Example request

curl -X POST "https://api.backfill.io/v1/invoices/{id}/confirm" \
  -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

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 Pagination

Show pagination fields

Field	Type	Description
limit	integer
page	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": "draft",
        "updated_at": "2026-05-05T12:00:00Z"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "object": "payment"
    }
  ],
  "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/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": "draft"
}

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": "draft",
    "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": "draft"
}'

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": "draft",
    "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": "draft",
    "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 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

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 Pagination

Show pagination fields

Field	Type	Description
limit	integer
page	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": {
    "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/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

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"

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
status	string	Filter by application status
approval_status	string	Filter by approval 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 Pagination

Show pagination fields

Field	Type	Description
limit	integer
page	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": [
          {
            "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": {
    "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/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

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": [
    {
      "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

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": [
      {
        "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": [
    {
      "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

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

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": [
      {
        "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

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": [
    {
      "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

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": [
      {
        "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": [
    {
      "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"

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
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)

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 Pagination

Show pagination fields

Field	Type	Description
limit	integer
page	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": {
    "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/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

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"

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

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 Pagination

Show pagination fields

Field	Type	Description
limit	integer
page	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": {
    "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/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

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"

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
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 Pagination

Show pagination fields

Field	Type	Description
limit	integer
page	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": {
    "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/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"

Expenses

GET /v1/expenses

List expenses

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
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)

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 Pagination

Show pagination fields

Field	Type	Description
limit	integer
page	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": {
    "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/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

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"

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
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)

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 Pagination

Show pagination fields

Field	Type	Description
limit	integer
page	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": {
    "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/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

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"

Quotes

GET /v1/quotes

List quotes

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
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)

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 Pagination

Show pagination fields

Field	Type	Description
limit	integer
page	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": {
    "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/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

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"

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
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)

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 Pagination

Show pagination fields

Field	Type	Description
limit	integer
page	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": {
    "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/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

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"

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
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)

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 Pagination

Show pagination fields

Field	Type	Description
limit	integer
page	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": {
    "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/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

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"

Banking

GET /v1/bank/accounts

List banking

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number

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 Pagination

Show pagination fields

Field	Type	Description
limit	integer
page	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": {
    "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/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
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 Pagination

Show pagination fields

Field	Type	Description
limit	integer
page	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": {
    "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/bank/transactions" \
  -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

Responses

200 List of pending transactions

No response body.

401 Unauthorized

No response body.

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

No response body.

401 Unauthorized

No response body.

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"
}

Example request

curl -X POST "https://api.backfill.io/v1/bank/transactions/{id}/categorize" \
  -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"
}

Example request

curl -X POST "https://api.backfill.io/v1/bank/accounts/{id}/sync" \
  -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
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 Pagination

Show pagination fields

Field	Type	Description
limit	integer
page	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": {
    "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/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"

Deposits

GET /v1/deposits

List deposits

Query parameters

Name	Type	Description
limit	integer	Maximum number of records to return
page	integer	Page number
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)

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 Pagination

Show pagination fields

Field	Type	Description
limit	integer
page	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": {
    "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/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

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"

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

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 Pagination

Show pagination fields

Field	Type	Description
limit	integer
page	integer

{
  "data": [
    {
      "data": {
        "account_code": "VALIDATION_ERROR",
        "account_name": "acc_1001",
        "created_at": "2026-05-05T12:00:00Z",
        "credit_amount": "125.00",
        "debit_amount": "125.00",
        "dimensions": {},
        "entry_date": "2026-05-05",
        "entry_number": "1001",
        "line_memo": "Payment received",
        "memo": "Payment received",
        "status": "draft",
        "updated_at": "2026-05-05T12:00:00Z"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "object": "journal_entry"
    }
  ],
  "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/journal_entries" \
  -H "Authorization: Bearer $BACKFILL_TOKEN"

POST /v1/journal_entries

Create a journal entry

Request body required

Field	Type	Description
account_code	string	Account Code
account_name	string	Account Name
credit_amount	string	Credit
debit_amount	string	Debit
dimensions	object	Dimensions
entry_date required	string (date)	Date
line_memo	string	Line Memo
memo	string	Memo
status	string	Status

{
  "account_code": "VALIDATION_ERROR",
  "account_name": "acc_1001",
  "credit_amount": "125.00",
  "debit_amount": "125.00",
  "dimensions": {},
  "entry_date": "2026-05-05",
  "line_memo": "Payment received",
  "memo": "Payment received",
  "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
account_code	string	Account Code
account_name	string	Account Name
created_at	string (date-time)
credit_amount	string	Credit
debit_amount	string	Debit
dimensions	object	Dimensions
entry_date required	string (date)	Date
entry_number required	string	Entry #
line_memo	string	Line Memo
memo	string	Memo
status	string	Status
updated_at	string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "account_code": "VALIDATION_ERROR",
    "account_name": "acc_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "credit_amount": "125.00",
    "debit_amount": "125.00",
    "dimensions": {},
    "entry_date": "2026-05-05",
    "entry_number": "1001",
    "line_memo": "Payment received",
    "memo": "Payment received",
    "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 '{
  "account_code": "VALIDATION_ERROR",
  "account_name": "acc_1001",
  "credit_amount": "125.00",
  "debit_amount": "125.00",
  "dimensions": {},
  "entry_date": "2026-05-05",
  "line_memo": "Payment received",
  "memo": "Payment received",
  "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
account_code	string	Account Code
account_name	string	Account Name
created_at	string (date-time)
credit_amount	string	Credit
debit_amount	string	Debit
dimensions	object	Dimensions
entry_date required	string (date)	Date
entry_number required	string	Entry #
line_memo	string	Line Memo
memo	string	Memo
status	string	Status
updated_at	string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "account_code": "VALIDATION_ERROR",
    "account_name": "acc_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "credit_amount": "125.00",
    "debit_amount": "125.00",
    "dimensions": {},
    "entry_date": "2026-05-05",
    "entry_number": "1001",
    "line_memo": "Payment received",
    "memo": "Payment received",
    "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
account_code	string	Account Code
account_name	string	Account Name
credit_amount	string	Credit
debit_amount	string	Debit
dimensions	object	Dimensions
entry_date	string (date)	Date
line_memo	string	Line Memo
memo	string	Memo
status	string	Status

{
  "account_code": "VALIDATION_ERROR",
  "account_name": "acc_1001",
  "credit_amount": "125.00",
  "debit_amount": "125.00",
  "dimensions": {},
  "entry_date": "2026-05-05",
  "line_memo": "Payment received",
  "memo": "Payment received",
  "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
account_code	string	Account Code
account_name	string	Account Name
created_at	string (date-time)
credit_amount	string	Credit
debit_amount	string	Debit
dimensions	object	Dimensions
entry_date required	string (date)	Date
entry_number required	string	Entry #
line_memo	string	Line Memo
memo	string	Memo
status	string	Status
updated_at	string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "account_code": "VALIDATION_ERROR",
    "account_name": "acc_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "credit_amount": "125.00",
    "debit_amount": "125.00",
    "dimensions": {},
    "entry_date": "2026-05-05",
    "entry_number": "1001",
    "line_memo": "Payment received",
    "memo": "Payment received",
    "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 '{
  "account_code": "VALIDATION_ERROR",
  "account_name": "acc_1001",
  "credit_amount": "125.00",
  "debit_amount": "125.00",
  "dimensions": {},
  "entry_date": "2026-05-05",
  "line_memo": "Payment received",
  "memo": "Payment received",
  "status": "draft"
}'

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
account_code	string	Account Code
account_name	string	Account Name
created_at	string (date-time)
credit_amount	string	Credit
debit_amount	string	Debit
dimensions	object	Dimensions
entry_date required	string (date)	Date
entry_number required	string	Entry #
line_memo	string	Line Memo
memo	string	Memo
status	string	Status
updated_at	string (date-time)

id required string (uuid)

object required string

{
  "data": {
    "account_code": "VALIDATION_ERROR",
    "account_name": "acc_1001",
    "created_at": "2026-05-05T12:00:00Z",
    "credit_amount": "125.00",
    "debit_amount": "125.00",
    "dimensions": {},
    "entry_date": "2026-05-05",
    "entry_number": "1001",
    "line_memo": "Payment received",
    "memo": "Payment received",
    "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 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

No response body.

401 Unauthorized

No response body.

Example request

curl -X GET "https://api.backfill.io/v1/reports/balance_sheet" \
  -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

No response body.

401 Unauthorized

No response body.

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

No response body.

401 Unauthorized

No response body.

Example request

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