Bills

Approve bill for payment

Changed on

Approve a bill for payment.

What happens

  • The load (carrier bill) or vended service (vendor bill) moves to approved-to-pay, so the bill status changes to APPROVED_TO_PAY
  • Bill is now ready for payment: bill payments only apply to approved bills

Prerequisites

  • Bill must be IN_REVIEW, or AWAITING_INVOICE for organizations that skip the review step
  • Bill must have an amount and a due date

Any other state (already approved, paid, not yet delivered) is a 409.

post/bills/{id}/approve

Request

  • Base URL: https://api.mvmnt.io/v1
  • URL: https://api.mvmnt.io/v1/bills/{id}/approve
  • Auth: HTTP bearer

Path parameters

idstring required

Resource ID (UUID) or client key

Query parameters

by'id' | 'key'

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.

Response

Bill approved successfully

idstring uuid required
friendlyIdstring required

Human-readable bill ID

keystring nullable

Client-defined key

entityType'CARRIER' | 'VENDOR' required

Type of entity the bill is for.

  • CARRIER: Bill for a carrier (LoadCarrier)
  • VENDOR: Bill for a vendor service (VendedService)
loadCarrierIdstring uuid nullable

Associated load carrier ID (if carrier bill)

vendedServiceIdstring uuid nullable

Associated vended service ID (if vendor bill)

loadIdstring uuid nullable
loadKeystring nullable
shipmentIdstring uuid nullable
shipmentKeystring nullable
status'AWAITING_INVOICE' | 'IN_REVIEW' | 'APPROVED_TO_PAY' | 'PAID' 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
invoiceDatestring date nullable

Date of carrier/vendor invoice

dueDatestring date nullable

Payment due date

amountnumber required

Bill amount

currencystring nullable

Currency code

referencestring nullable

Carrier/vendor invoice reference number

amountPaidnumber

Total payments received

amountOwednumber

Outstanding balance

factorJobIdstring nullable

External factoring job ID

factorStatusstring nullable

Current factoring status

qboIdstring nullable

QuickBooks Online bill ID

createdAtstring date-time required
updatedAtstring date-time nullable

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "friendlyId": "BILL-00001",
  "carrier": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-CARRIER-SWIFT",
    "name": "Swift Transportation",
    "phoneNumber": "+1-555-987-6543",
    "email": "dispatch@swifttrans.com",
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T14:30:00Z"
  },
  "vendor": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-VENDOR-ABC-001",
    "friendlyId": "V123456",
    "name": "ABC Warehouse Services",
    "email": "billing@abcwarehouse.com",
    "phone": "+1-555-123-4567",
    "status": "ACTIVE",
    "currency": "USD",
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T14:30:00Z"
  },
  "currency": "USD",
  "paymentTerm": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-PAYTERM-NET30",
    "name": "Net 30",
    "description": "Payment due 30 days from invoice date",
    "days": 30,
    "quickPayFee": 5,
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T14:30:00Z"
  },
  "carrierFactor": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-FACTOR-001",
    "companyName": "Capital Factoring Services Inc",
    "email": "accounting@capitalfactoring.com",
    "phoneNumber": "+1-555-234-5678",
    "currency": "USD",
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T14:30:00Z"
  }
}

Changes

  • 2cd6ecfbeb82Revision changes
    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • info

      media type application/json was changed to a more specific media type application/problem+json for the response status

    • info

      media type application/json was changed to a more specific media type application/problem+json for the response status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status