Update bill payment

curl --request PATCH \
  --url https://sandbox.thredfi.com/v1/platform/businesses/{business_id}/bills/payments/{bill_payment_id}/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "pending",
  "failure_reason": "<string>",
  "payment_reference": "<string>",
  "check_number": "<string>",
  "description": "<string>",
  "memo": "<string>",
  "processing_fee_cents": 1,
  "metadata": "<unknown>",
  "allocations": [
    {
      "bill_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "amount_cents": 123,
      "description": "<string>"
    }
  ]
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "business_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "vendor_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "vendor_name": "<string>",
  "payment_reference": "<string>",
  "external_id": "<string>",
  "processor_payment_id": "<string>",
  "check_number": "<string>",
  "amount_cents": 123,
  "currency": "<string>",
  "processing_fee_cents": 123,
  "net_amount_cents": 123,
  "allocated_amount_cents": 123,
  "unallocated_amount_cents": 123,
  "is_fully_allocated": true,
  "payment_method": "<string>",
  "status": "<string>",
  "payment_date": "2023-12-25",
  "value_date": "2023-12-25",
  "submitted_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "failed_at": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "memo": "<string>",
  "failure_reason": "<string>",
  "metadata": "<unknown>",
  "allocations": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "bill_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "bill_number": "<string>",
      "vendor_bill_number": "<string>",
      "bill_status": "<string>",
      "amount_cents": 123,
      "allocation_date": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z",
      "description": "<string>"
    }
  ],
  "vendor_refund_allocations": [
    {
      "vendor_refund_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "amount_cents": 123,
      "allocated_at": "2023-11-07T05:31:56Z",
      "reference_number": "<string>"
    }
  ],
  "reconciled_bank_transactions": [
    {
      "bank_transaction_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "bank_transaction_date": "2023-11-07T05:31:56Z",
      "bank_transaction_amount_cents": 123,
      "bank_transaction_direction": "<string>",
      "reconciled_amount_cents": 123,
      "reconciliation_link_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "reconciled_at": "2023-11-07T05:31:56Z",
      "currency": "<string>",
      "payment_type": "<string>",
      "bank_account_name": "<string>",
      "notes": "<string>"
    }
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

Bill Payments

Update bill payment

Update an existing bill payment’s status or details.

Updatable Fields:

status: Update payment status (with validation)
failure_reason: Required when status is ‘failed’
payment_reference: Update external reference
processing_fee_cents: Update processing fee

Status Transitions:

pending → processing, completed, failed, cancelled
processing → completed, failed
completed → (no transitions allowed)
failed → (no transitions allowed)
cancelled → (no transitions allowed)

PATCH

platform

businesses

{business_id}

bills

payments

{bill_payment_id}

Update bill payment

curl --request PATCH \
  --url https://sandbox.thredfi.com/v1/platform/businesses/{business_id}/bills/payments/{bill_payment_id}/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "pending",
  "failure_reason": "<string>",
  "payment_reference": "<string>",
  "check_number": "<string>",
  "description": "<string>",
  "memo": "<string>",
  "processing_fee_cents": 1,
  "metadata": "<unknown>",
  "allocations": [
    {
      "bill_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "amount_cents": 123,
      "description": "<string>"
    }
  ]
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "business_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "vendor_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "vendor_name": "<string>",
  "payment_reference": "<string>",
  "external_id": "<string>",
  "processor_payment_id": "<string>",
  "check_number": "<string>",
  "amount_cents": 123,
  "currency": "<string>",
  "processing_fee_cents": 123,
  "net_amount_cents": 123,
  "allocated_amount_cents": 123,
  "unallocated_amount_cents": 123,
  "is_fully_allocated": true,
  "payment_method": "<string>",
  "status": "<string>",
  "payment_date": "2023-12-25",
  "value_date": "2023-12-25",
  "submitted_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "failed_at": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "memo": "<string>",
  "failure_reason": "<string>",
  "metadata": "<unknown>",
  "allocations": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "bill_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "bill_number": "<string>",
      "vendor_bill_number": "<string>",
      "bill_status": "<string>",
      "amount_cents": 123,
      "allocation_date": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z",
      "description": "<string>"
    }
  ],
  "vendor_refund_allocations": [
    {
      "vendor_refund_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "amount_cents": 123,
      "allocated_at": "2023-11-07T05:31:56Z",
      "reference_number": "<string>"
    }
  ],
  "reconciled_bank_transactions": [
    {
      "bank_transaction_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "bank_transaction_date": "2023-11-07T05:31:56Z",
      "bank_transaction_amount_cents": 123,
      "bank_transaction_direction": "<string>",
      "reconciled_amount_cents": 123,
      "reconciliation_link_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "reconciled_at": "2023-11-07T05:31:56Z",
      "currency": "<string>",
      "payment_type": "<string>",
      "bank_account_name": "<string>",
      "notes": "<string>"
    }
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization

string

header

required

Business-scoped JWT token. Token payload includes business_id to automatically scope requests. Format: Bearer <your-jwt-token>

Use this for: Business-specific operations where the business context is embedded in the token.

Path Parameters

bill_payment_id

string<uuid>

required

Bill Payment UUID

business_id

string<uuid>

required

Business UUID

Body

Serializer for updating bill payment status and details.

Allows updating payment metadata, references, status transitions, and allocations.

status

enum<string>

Updated payment status (pending, processing, completed, failed, cancelled)

pending - pending
processing - processing
completed - completed
failed - failed
cancelled - cancelled

Available options:

pending,

processing,

completed,

failed,

cancelled

failure_reason

string

Reason for failure (required when status=failed)

payment_reference

string

Updated payment reference

Maximum string length: 100

check_number

string

Updated check number

Maximum string length: 50

description

string

Updated payment description

memo

string

Updated memo or notes

processing_fee_cents

integer

Updated processing fee in cents

Required range: x >= 0

metadata

any

Updated custom key-value pairs

allocations

object[]

Updated bill allocations (replaces existing allocations)

Show child attributes

Response

Detailed response serializer for bill payment with all related data.

Returns payment details along with vendor info and allocations. All amounts in cents.

string<uuid>

required

Unique bill payment identifier

business_id

string<uuid>

required

Business this payment belongs to

vendor_id

string<uuid>

required

Vendor receiving the payment

vendor_name

string

required

Vendor display name

payment_reference

string

required

Payment reference or transaction ID

external_id

string

required

Your external identifier for this payment

processor_payment_id

string

required

Payment processor transaction ID (e.g., Stripe ID)

check_number

string

required

Check number if payment method is check

amount_cents

integer

required

Payment amount in cents

currency

string

required

Payment currency (e.g., GBP, EUR, USD)

processing_fee_cents

integer

required

Processing fee in cents

net_amount_cents

integer

required

Net amount after fees in cents

allocated_amount_cents

integer

required

Allocated amount in cents

unallocated_amount_cents

integer

required

Unallocated amount in cents

is_fully_allocated

boolean

required

Whether payment is fully allocated to bills

payment_method

string

required

Payment method used (bank_transfer, check, wire, etc.)

status

string

required

Payment status (pending, processing, completed, failed, cancelled)

payment_date

string<date>

required

Date payment was made

value_date

string<date>

required

Value date for accounting purposes

submitted_at

string<date-time>

required

When payment was submitted for processing

completed_at

string<date-time>

required

When payment processing completed

failed_at

string<date-time>

required

When payment failed (if applicable)

description

string

required

Payment description

memo

string

required

Additional notes or memo

failure_reason

string

required

Reason for failure (if status=failed)

metadata

any

required

Custom key-value pairs

allocations

object[]

required

Bill allocations for this payment

Show child attributes

vendor_refund_allocations

object[]

required

Vendor refund allocations linked to this payment

Show child attributes

reconciled_bank_transactions

object[]

required

Bank transactions this payment is reconciled to

Show child attributes

created_at

string<date-time>

required

Payment creation timestamp

updated_at

string<date-time>

required

Last update timestamp

Get bill payment details Delete (cancel) bill payment

⌘I

Managing Businesses

Importing Business Activity

Financial Reports

Update bill payment

Authorizations

Path Parameters

Body

Response