# Approve bill for payment

Approve a bill for payment.

## What happens

- Bill status changes to APPROVED_TO_PAY
- Bill is now ready for payment

## Prerequisites

- Bill must be in IN_REVIEW status

Endpoint: POST /bills/{id}/approve
Version: 1.0.0
Security: BearerAuth

## Path parameters:

  - `id` (string, required)
    Resource ID (UUID) or client key
    Example: "550e8400-e29b-41d4-a716-446655440000"

## Query parameters:

  - `by` (string)
    Specify lookup type for faster retrieval.
If omitted, defaults to looking up by ID first, then falls back to client key if not found.
Use by=key when you know you're providing a client key for best performance.
    Enum: "id", "key"

## Response 200 fields (application/json):

  - `id` (string, required)
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `friendlyId` (string, required)
    Human-readable bill ID
    Example: "BILL-00001"

  - `key` (string,null)
    Client-defined key

  - `entityType` (string, required)
    Type of entity the bill is for.
- CARRIER: Bill for a carrier (LoadCarrier)
- VENDOR: Bill for a vendor service (VendedService)
    Enum: "CARRIER", "VENDOR"

  - `loadCarrierId` (string,null)
    Associated load carrier ID (if carrier bill)

  - `vendedServiceId` (string,null)
    Associated vended service ID (if vendor bill)

  - `carrier` (object)
    Enhanced reference to a carrier resource (returned in responses).
Includes full carrier details in addition to id/key.

Note: Does NOT include nested references (contacts, etc.) to prevent recursion.
Maximum nesting depth: 1 level.

  - `carrier.id` (string, required)
    Carrier UUID
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `carrier.key` (string,null)
    Client-defined reference ID if set
    Example: "ERP-CARRIER-SWIFT"

  - `carrier.name` (string, required)
    Carrier company name
    Example: "Swift Transportation"

  - `carrier.phoneNumber` (string,null)
    Primary phone number
    Example: "+1-555-987-6543"

  - `carrier.email` (string,null)
    Primary email address
    Example: "dispatch@swifttrans.com"

  - `carrier.createdAt` (string, required)
    When the carrier was created
    Example: "2025-01-15T10:00:00Z"

  - `carrier.updatedAt` (string, required)
    When the carrier was last updated
    Example: "2025-01-15T14:30:00Z"

  - `carrier.deletedAt` (string,null)
    When the carrier was soft deleted (null if active)

  - `vendor` (object)
    Enhanced reference to a vendor profile.
Includes full vendor details in addition to id/key.

  - `vendor.id` (string, required)
    Vendor UUID
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `vendor.friendlyId` (string, required)
    Human-readable vendor identifier
    Example: "V123456"

  - `vendor.name` (string, required)
    Vendor legal name
    Example: "ABC Warehouse Services"

  - `vendor.phone` (string,null)
    Primary phone number
    Example: "+1-555-123-4567"

  - `vendor.status` (string,null)
    Vendor status
    Example: "ACTIVE"

  - `vendor.currency` (string,null)
    Preferred currency code (ISO 4217)
    Example: "USD"

  - `vendor.createdAt` (string, required)
    When the vendor was created
    Example: "2025-01-15T10:00:00Z"

  - `vendor.updatedAt` (string, required)
    When the vendor was last updated
    Example: "2025-01-15T14:30:00Z"

  - `loadId` (string,null)

  - `loadKey` (string,null)

  - `shipmentId` (string,null)

  - `shipmentKey` (string,null)

  - `status` (string, required)
    Current status of the bill (AP invoice).
- AWAITING_INVOICE: Waiting for carrier/vendor to submit invoice
- IN_REVIEW: Invoice received, under review
- APPROVED_TO_PAY: Approved and ready for payment
- PAID: Fully paid
    Enum: "AWAITING_INVOICE", "IN_REVIEW", "APPROVED_TO_PAY", "PAID"

  - `invoiceDate` (string,null)
    Date of carrier/vendor invoice

  - `dueDate` (string,null)
    Payment due date

  - `amount` (number, required)
    Bill amount

  - `currency` (string,null)
    Currency code
    Example: "USD"

  - `reference` (string,null)
    Carrier/vendor invoice reference number

  - `amountPaid` (number)
    Total payments received

  - `amountOwed` (number)
    Outstanding balance

  - `payments` (array)
    Payments applied to this bill

  - `payments.paymentGroupId` (string)

  - `payments.amount` (number)
    Amount applied to this bill

  - `payments.paymentDate` (string)

  - `payments.reference` (string,null)
    Check number, transaction ID, etc.

  - `paymentTerm` (object)
    Enhanced reference to a payment term resource (returned in responses).
Includes full payment term details in addition to id/key.

  - `paymentTerm.id` (string, required)
    Payment term UUID
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `paymentTerm.name` (string, required)
    Payment term name
    Example: "Net 30"

  - `paymentTerm.description` (string,null)
    Payment term description or notes
    Example: "Payment due 30 days from invoice date"

  - `paymentTerm.days` (integer,null)
    Number of days until payment is due
    Example: 30

  - `paymentTerm.quickPayFee` (number,null)
    Quick pay fee percentage (e.g., 0.05 for 5%)
    Example: 0.05

  - `paymentTerm.apOnly` (boolean,null)
    Whether this payment term is for accounts payable only

  - `paymentTerm.doNotUse` (boolean,null)
    Flag to prevent using this payment term for new transactions

  - `paymentTerm.createdAt` (string, required)
    When the payment term was created
    Example: "2025-01-15T10:00:00Z"

  - `paymentTerm.updatedAt` (string, required)
    When the payment term was last updated
    Example: "2025-01-15T14:30:00Z"

  - `paymentTerm.deletedAt` (string,null)
    When the payment term was soft deleted (null if active)

  - `carrierFactor` (object)
    Enhanced reference to a carrier factor (factoring company).
Includes full carrier factor details in addition to id/key.

  - `carrierFactor.id` (string, required)
    Carrier factor UUID
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `carrierFactor.companyName` (string, required)
    Factoring company legal name
    Example: "Capital Factoring Services Inc"

  - `carrierFactor.createdAt` (string, required)
    When the carrier factor was created
    Example: "2025-01-15T10:00:00Z"

  - `carrierFactor.updatedAt` (string, required)
    When the carrier factor was last updated
    Example: "2025-01-15T14:30:00Z"

  - `factorJobId` (string,null)
    External factoring job ID

  - `factorStatus` (string,null)
    Current factoring status

  - `qboId` (string,null)
    QuickBooks Online bill ID

  - `createdAt` (string, required)

  - `updatedAt` (string,null)

## Response 401 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 404 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 409 fields (application/problem+json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message