Expenses API (0.1)

Download OpenAPI specification:Download

Admin: developer-support@brex.com URL: https://brex.com

The Expenses API allows you to manage accounting and expenses information.

Card Expenses

View and manage card expenses data.

List card expensesDeprecated

This endpoint is deprecated. Use the "List expenses" (GET /v1/expenses) endpoint instead.

SecurityOAuth2
Request
query Parameters
expand[]
Array of strings or null

Get additional details for the expense, e.g. merchant mcc code, by passing in expand[]=merchant. Query parameters include location, department, merchant, receipts.download_uris, user, budget and payment.

Example: expand[]= ?expand[]=merchant&expand[]=location
user_id[]
Array of strings or null

Get expenses belong to provided user(s).

parent_expense_id[]
Array of strings or null

Get itemized expenses belong to provided parent expenses ID(s).

budget_id[]
Array of strings or null
spending_entity_id[]
Array of strings or null
status[]
Array of strings or null (ExpenseStatus)
Enum: "DRAFT" "SUBMITTED" "APPROVED" "OUT_OF_POLICY" "VOID" "CANCELED" "SPLIT" "SETTLED"
payment_status[]
Array of strings or null (ExpensePaymentStatus)
Enum: "NOT_STARTED" "PROCESSING" "CANCELED" "DECLINED" "CLEARED" "REFUNDING" "REFUNDED" "CASH_ADVANCE" "CREDITED" "AWAITING_PAYMENT" "SCHEDULED"
purchased_at_start
string or null <date-time>

Shows only expenses with a purchased_at on or after this date-time. This parameter is the date-time notation as defined by RFC 3339, section 5.6, e.g. 2022-11-12T23:59:59.999

Example: purchased_at_start= 2023-01-01T23:59:59.999
purchased_at_end
string or null <date-time>

Shows only expenses with a purchased_at on or before this date-time. This parameter is the date-time notation as defined by RFC 3339, section 5.6, e.g. 2022-11-12T23:59:59.999

Example: purchased_at_end= 2023-01-10T23:59:59.999
updated_at_start
string or null <date-time>

Shows only expenses with a updated_at on or after this date-time. This parameter is the date-time notation as defined by RFC 3339, section 5.6, e.g. 2022-11-12T23:59:59.999

Example: updated_at_start= 2023-01-01T23:59:59.999
updated_at_end
string or null <date-time>

Shows only expenses with a updated_at on or before this date-time. This parameter is the date-time notation as defined by RFC 3339, section 5.6, e.g. 2022-11-12T23:59:59.999

Example: updated_at_end= 2023-01-10T23:59:59.999
payment_posted_at_start
string or null <date-time>

Shows only expenses with a payment_posted_at on or after this date-time. This parameter is the date-time notation as defined by RFC 3339, section 5.6, e.g. 2022-11-12T23:59:59.999

Example: payment_posted_at_start= 2023-01-01T23:59:59.999
payment_posted_at_end
string or null <date-time>

Shows only expenses with a payment_posted_at on or before this date-time. This parameter is the date-time notation as defined by RFC 3339, section 5.6, e.g. 2022-11-12T23:59:59.999

Example: payment_posted_at_end= 2023-01-10T23:59:59.999
load_custom_fields
boolean or null

Load custom fields for the expenses.

cursor
string or null

The cursor to use for pagination. This is the next_cursor value returned from the previous response.

limit
integer or null <int32>

Controls the maximum number of expenses returned in the response, can't be greater than 1000

Responses
200

List expenses response.

400

Bad request

401

Unauthorized

403

Forbidden

get/v1/expenses/card
Request samples 
Response samples 
application/json
{
  • "next_cursor": "string",
  • "items": [
    ]
}
Get a card expenseDeprecated
This endpoint is deprecated. Use the "Get an expense" (GET /v1/expenses/{id}) endpoint instead.


SecurityOAuth2 
Request 
path Parameters
expense_id
required
string
 
query Parameters
expand[]
Array of strings or null
Get additional details for the expense, e.g. merchant mcc code, by passing in expand[]=merchant. Query parameters include location, department, merchant, receipts.download_uris, user, budget and payment.


 
 Example:  expand[]=
?expand[]=merchant&expand[]=location

load_custom_fields
boolean or null
Load custom fields for the expense.


 
Responses 
200
Get an expense response.


400
Bad request


401
Unauthorized


403
Forbidden


404
Not found


get/v1/expenses/card/{expense_id}
Request samples 
Response samples 
application/json
{
  • "id": "string",
  • "memo": "string",
  • "location_id": "string",
  • "location": {
    },
  • "address": {
    },
  • "department_id": "string",
  • "department": {
    },
  • "updated_at": "2019-08-24T14:15:22Z",
  • "payment_posted_at": "2019-08-24T14:15:22Z",
  • "category": "ADVERTISING_AND_MARKETING",
  • "merchant_id": "string",
  • "merchant": {
    },
  • "receipts": [
    ],
  • "budget_id": "string",
  • "budget": {
    },
  • "expense_type": "CARD",
  • "original_amount": {
    },
  • "billing_amount": {
    },
  • "budget_amount": {
    },
  • "purchased_amount": {
    },
  • "usd_equivalent_amount": {
    },
  • "purchased_at": "2019-08-24T14:15:22Z",
  • "status": "DRAFT",
  • "payment_status": "NOT_STARTED",
  • "user_id": "string",
  • "user": {
    },
  • "payment": {
    },
  • "custom_fields": [
    ],
  • "trip_id": "string",
  • "spending_entity_id": "string",
  • "spending_entity": {
    },
  • "billing_entity_id": "string",
  • "exported_at": "2019-08-24T14:15:22Z",
  • "integration_spending_entity_id": "string",
  • "integration_billing_entity_id": "string",
  • "review": {
    },
  • "repayment": {
    },
  • "approved_at": "2019-08-24T14:15:22Z",
  • "submitted_at": "2019-08-24T14:15:22Z",
  • "completion_date": "2019-08-24T14:15:22Z"
}
Update an expense
Update an expense. Admin and bookkeeper have access to any expense, and regular users can only access their own.


SecurityOAuth2 
Request 
path Parameters
expense_id
required
string
 
Request Body schema: application/json
memo
string or null
Expense memo.


 
Responses 
200
Update an expense response.


400
Bad request


401
Unauthorized


403
Forbidden


404
Not found


put/v1/expenses/card/{expense_id}
Request samples 
application/json
{
  • "memo": "string"
}
Response samples 
application/json
{
  • "id": "string",
  • "memo": "string",
  • "location_id": "string",
  • "department_id": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "category": "ADVERTISING_AND_MARKETING",
  • "merchant_id": "string",
  • "budget_id": "string",
  • "original_amount": {
    },
  • "billing_amount": {
    },
  • "purchased_at": "2019-08-24T14:15:22Z",
  • "status": "DRAFT",
  • "payment_status": "NOT_STARTED"
}
Receipt Match
Upload receipt and match automatically.


Create a new receipt match
The uri will be a pre-signed S3 URL allowing you to upload the receipt securely. This URL can only be used for a PUT operation and expires 30 minutes after its creation. Once your upload is complete, we will try to match the receipt with existing expenses.


Refer to these docs on how to upload to this pre-signed S3 URL. We highly recommend using one of AWS SDKs if they're available for your language to upload these files.


SecurityOAuth2 
Request 
Request Body schema: application/json
receipt_name
required
string
The name of the receipt (with the file extension). It will be used in the matching result email.


 
Responses 
201
Create a new receipt match response.


400
Bad request


401
Unauthorized


post/v1/expenses/card/receipt_match
Request samples 
application/json
{
  • "receipt_name": "string"
}
Response samples 
application/json
{
  • "id": "string",
  • "uri": "string"
}
Expenses
List expenses
List expenses under the same account. Admin and bookkeeper have access to any expense, and regular users can only access their own.


SecurityOAuth2 
Request 
query Parameters
expand[]
Array of strings or null
Get additional details for the expense, e.g. merchant mcc code, by passing in expand[]=merchant. Query parameters include location, department, merchant, receipts.download_uris, user, budget and payment.


 
 Example:  expand[]=
?expand[]=merchant&expand[]=location

user_id[]
Array of strings or null
Get expenses belong to provided user(s).


 
parent_expense_id[]
Array of strings or null
Get itemized expenses belong to provided parent expenses ID(s).


 
budget_id[]
Array of strings or null
 
spending_entity_id[]
Array of strings or null
 
expense_type[]
Array of strings or null (ExpenseType) 
 Enum: "CARD" "BILLPAY" "REIMBURSEMENT" "CLAWBACK" "UNSET"  
status[]
Array of strings or null (ExpenseStatus) 
 Enum: "DRAFT" "SUBMITTED" "APPROVED" "OUT_OF_POLICY" "VOID" "CANCELED" "SPLIT" "SETTLED"  
payment_status[]
Array of strings or null (ExpensePaymentStatus) 
 Enum: "NOT_STARTED" "PROCESSING" "CANCELED" "DECLINED" "CLEARED" "REFUNDING" "REFUNDED" "CASH_ADVANCE" "CREDITED" "AWAITING_PAYMENT" "SCHEDULED"  
purchased_at_start
string or null <date-time> 
Shows only expenses with a purchased_at on or after this date-time. This parameter is the date-time notation as defined by RFC 3339, section 5.6, e.g. 2022-11-12T23:59:59.999


 
 Example:  purchased_at_start=
2023-01-01T23:59:59.999

purchased_at_end
string or null <date-time> 
Shows only expenses with a purchased_at on or before this date-time. This parameter is the date-time notation as defined by RFC 3339, section 5.6, e.g. 2022-11-12T23:59:59.999


 
 Example:  purchased_at_end=
2023-01-10T23:59:59.999

updated_at_start
string or null <date-time> 
Shows only expenses with a updated_at on or after this date-time. This parameter is the date-time notation as defined by RFC 3339, section 5.6, e.g. 2022-11-12T23:59:59.999


 
 Example:  updated_at_start=
2023-01-01T23:59:59.999

updated_at_end
string or null <date-time> 
Shows only expenses with a updated_at on or before this date-time. This parameter is the date-time notation as defined by RFC 3339, section 5.6, e.g. 2022-11-12T23:59:59.999


 
 Example:  updated_at_end=
2023-01-10T23:59:59.999

payment_posted_at_start
string or null <date-time> 
Shows only expenses with a payment_posted_at on or after this date-time. This parameter is the date-time notation as defined by RFC 3339, section 5.6, e.g. 2022-11-12T23:59:59.999


 
 Example:  payment_posted_at_start=
2023-01-01T23:59:59.999

payment_posted_at_end
string or null <date-time> 
Shows only expenses with a payment_posted_at on or before this date-time. This parameter is the date-time notation as defined by RFC 3339, section 5.6, e.g. 2022-11-12T23:59:59.999


 
 Example:  payment_posted_at_end=
2023-01-10T23:59:59.999

load_custom_fields
boolean or null
Load custom fields for the expenses.


 
cursor
string or null
The cursor to use for pagination. This is the next_cursor value returned from the previous response.


 
limit
integer or null <int32> 
Controls the maximum number of expenses returned in the response, can't be greater than 1000


 
Responses 
200
List expenses response.


400
Bad request


401
Unauthorized


403
Forbidden


get/v1/expenses
Request samples 
Response samples 
application/json
{
  • "next_cursor": "string",
  • "items": [
    ]
}
Get an expense
Get an expense by its ID.


SecurityOAuth2 
Request 
path Parameters
id
required
string
 
query Parameters
expand[]
Array of strings or null
Get additional details for the expense, e.g. merchant mcc code, by passing in expand[]=merchant. Query parameters include location, department, merchant, receipts.download_uris, user, budget and payment.


 
 Example:  expand[]=
?expand[]=merchant&expand[]=location

load_custom_fields
boolean or null
Load custom fields for the expense.


 
Responses 
200
Get an expense response.


400
Bad request


401
Unauthorized


403
Forbidden


404
Not found


get/v1/expenses/{id}
Request samples 
Response samples 
application/json
{
  • "id": "string",
  • "memo": "string",
  • "location_id": "string",
  • "location": {
    },
  • "address": {
    },
  • "department_id": "string",
  • "department": {
    },
  • "updated_at": "2019-08-24T14:15:22Z",
  • "payment_posted_at": "2019-08-24T14:15:22Z",
  • "category": "ADVERTISING_AND_MARKETING",
  • "merchant_id": "string",
  • "merchant": {
    },
  • "receipts": [
    ],
  • "budget_id": "string",
  • "budget": {
    },
  • "expense_type": "CARD",
  • "original_amount": {
    },
  • "billing_amount": {
    },
  • "budget_amount": {
    },
  • "purchased_amount": {
    },
  • "usd_equivalent_amount": {
    },
  • "purchased_at": "2019-08-24T14:15:22Z",
  • "status": "DRAFT",
  • "payment_status": "NOT_STARTED",
  • "user_id": "string",
  • "user": {
    },
  • "payment": {
    },
  • "custom_fields": [
    ],
  • "trip_id": "string",
  • "spending_entity_id": "string",
  • "spending_entity": {
    },
  • "billing_entity_id": "string",
  • "exported_at": "2019-08-24T14:15:22Z",
  • "integration_spending_entity_id": "string",
  • "integration_billing_entity_id": "string",
  • "review": {
    },
  • "repayment": {
    },
  • "approved_at": "2019-08-24T14:15:22Z",
  • "submitted_at": "2019-08-24T14:15:22Z",
  • "completion_date": "2019-08-24T14:15:22Z"
}
Receipt Upload
Create a new receipt upload
The uri will be a pre-signed S3 URL allowing you to upload the receipt securely. This URL can only be used for a PUT operation and expires 30 minutes after its creation. Once your upload is complete, we will try to match the receipt with existing expenses.


Refer to these docs on how to upload to this pre-signed S3 URL. We highly recommend using one of AWS SDKs if they're available for your language to upload these files.


SecurityOAuth2 
Request 
path Parameters
expense_id
required
string
 
Request Body schema: application/json
receipt_name
required
string
The name of the receipt (with the file extension).


 
Responses 
201
Upload a new receipt response.


400
Bad request


401
Unauthorized


403
Forbidden


404
Not found


post/v1/expenses/card/{expense_id}/receipt_upload
Request samples 
application/json
{
  • "receipt_name": "string"
}
Response samples 
application/json
{
  • "id": "string",
  • "uri": "string"
}
Copyright © Brex 2019–2025. All rights reserved.