BIbill
reimbursements

Create a reimbursement

Changed on

Create a new reimbursement.

See Reimbursements in the Guides section for more information, sample requests, and responses.

post/v3/spend/reimbursements

Request

  • Base URL
    https://gateway.stage.bill.com/connect
  • URL
    https://gateway.stage.bill.com/connect/v3/spend/reimbursements
  • Auth
    none declared

Headers

apiTokenstring nullable

Access token for Spend & Expense API authentication

Example:{{api_token}}

Request body

userIdstring required

BILL-generated ID of the user to be reimbursed

budgetIdstring required

BILL-generated ID of the budget to be used for the reimbursement

amountnumber required

Reimbursement amount

notestring required

Reimbursement note. Use this field to describe the business purpose for the expense.

merchantNamestring required

Merchant name for the expense

occurredDatestring date required

Expense created date. The value is in the yyyy-MM-dd format.

Example request

{
  "budgetId": "{{se_budget_uuid}}",
  "userId": "{{se_user_uuid}}",
  "occurredDate": "2026-12-25",
  "note": "Team lunch",
  "merchantName": "Jasmine Thai",
  "amount": 50,
  "receipts": [
    {
      "url": "{{se_reimbursement_url}}",
      "filename": "{{file_name_with_extension}}"
    }
  ]
}

Response

Create a reimbursement response

idstring

BILL-generated ID of the reimbursement

uuidstring

BILL-generated UUID of the reimbursement

amountnumber

Reimbursement amount

fulfillmentType'ACH' | 'PAYROLL'

Reimbursement fulfillment type.

fundRequestAmountnumber

Amount that must be added to the user funds for the user to have enough funds for this reimbursement

fundRequestBudgetAmountnumber

Amount that must be added to the budget for the user to have enough funds for this reimbursement

merchantNamestring

Merchant name for the expense

notestring

Reimbursement note. Use this field to describe the business purpose for the expense.

submittedTimestring date-time

Reimbursement request submission date and time

occurredDatestring date

Expense created date. The value is in the yyyy-MM-dd format.

retiredboolean

This field is set as true if the reimbursement has been deleted

status'CREATED' | 'AWAITING_APPROVAL' | 'AWAITING_TIER2_APPROVAL' | 'TIER2_APPROVAL_UNDONE' | 'APPROVAL_UNDONE' | 'DENIAL_UNDONE' | 'APPROVED' | 'CANCEL_PAYMENT' | 'PAID' | 'PAYMENT_FAILED' | 'DENIED' | 'DELETED' | 'ARCHIVED' | 'BUDGET_APPROVAL' | 'ADMIN_APPROVAL' | 'READY_TO_PAY' | 'PAYMENT_PENDING'

Reimbursement status.

type'PURCHASE' | 'MILEAGE'

Reimbursement type.

batchIdstring

ACH batch ID.

You can use batchId to identify the set of reimbursements bundled together when funds are withdrawn from the company bank account. Reimbursements with the same batchId are withdrawn at the same time.

batchAmountnumber

ACH batch amount

budgetIdstring

BILL-generated ID of the budget to be used for the reimbursement

budgetUuidstring

BILL-generated UUID of the budget to be used for the reimbursement

userIdstring

BILL-generated ID of the user to be reimbursed

userUuidstring

BILL-generated UUID of the user to be reimbursed

Changes

  • 54edddceb0a5Revision changes
    • warning

      added the new ADMIN_APPROVAL enum value to the //// response property for the response status

    • warning

      added the new ADMIN_APPROVAL enum value to the ////// response property for the response status

    • warning

      added the new ARCHIVED enum value to the //// response property for the response status

    • warning

      added the new ARCHIVED enum value to the ////// response property for the response status

    • warning

      added the new BUDGET_APPROVAL enum value to the //// response property for the response status

    • warning

      added the new BUDGET_APPROVAL enum value to the ////// response property for the response status

    • warning

      added the new PAYMENT_PENDING enum value to the //// response property for the response status

    • warning

      added the new PAYMENT_PENDING enum value to the ////// response property for the response status

    • warning

      added the new READY_TO_PAY enum value to the //// response property for the response status

    • warning

      added the new READY_TO_PAY enum value to the ////// response property for the response status

    • info

      removed the FUNDING_RECEIVED enum value from the //// response property for the response status

    • info

      removed the FUNDING_RECEIVED enum value from the ////// response property for the response status

    • info

      removed the UNSPECIFIED enum value from the //// response property for the response status

    • info

      removed the UNSPECIFIED enum value from the //// response property for the response status

    • info

      removed the UNSPECIFIED enum value from the ////// response property for the response status