List expenses

GET

/api/v1/expenses

curl --request GET \
  --url https://api.stocksmith.io/api/v1/expenses \
  --header 'Authorization: Bearer <token>'

• Production

Requires financial access (view_material_costs permission). Returns 403 if the authenticated user lacks this permission.

Authorizations

• bearer_auth

Parameters

Query Parameters

page

integer

Page number (default: 1)

per_page

integer

Results per page (default: 25, max: 100)

from

string

Filter by purchase date on or after this ISO 8601 date (e.g. 2026-01-01)

to

string

Filter by purchase date on or before this ISO 8601 date (e.g. 2026-12-31)

updated_since

string

Filter by last-modified on or after this ISO 8601 timestamp

supplier_id

integer

Filter by supplier (contact) ID

category_id

integer

Filter by line item category ID

received_status

string

Filter by receipt status. Comma-separated for multiple (e.g. ‘partial,outstanding’). One or more of: received, partial, outstanding.

Responses

200

Paginated list of expenses

Media type application/json

object

expenses

required

Array<object>

object

id

required

integer

code

string

nullable

purchased_at

string format: date-time

nullable

estimated_arrival_at

string format: date

nullable

supplier_id

ID of the supplier contact

integer

nullable

supplier_name

string

nullable

paid

required

boolean

received

required

boolean

received_status

required

Line-item receipt rollup: all lines received, some received, or none received. “received” for a purchase with zero line items.

string

Allowed values: received partial outstanding

notes

string

nullable

amount

Grand total

object

amount

Decimal string, e.g. ‘8.75’

string

currency_code

ISO 4217 code, e.g. ‘USD’

string

item_total

Sum of line item totals

object

amount

Decimal string, e.g. ‘8.75’

string

currency_code

ISO 4217 code, e.g. ‘USD’

string

tax

object

amount

Decimal string, e.g. ‘8.75’

string

currency_code

ISO 4217 code, e.g. ‘USD’

string

shipping

object

amount

Decimal string, e.g. ‘8.75’

string

currency_code

ISO 4217 code, e.g. ‘USD’

string

discount

object

amount

Decimal string, e.g. ‘8.75’

string

currency_code

ISO 4217 code, e.g. ‘USD’

string

line_items

required

Array<object>

object

id

integer

material_id

ID of the material on this line

integer

nullable

material_name

string

nullable

material_expense

True when this line is a material purchase

boolean

received

True when this line has been received

boolean

category_id

integer

nullable

category_name

string

nullable

quantity

Decimal string

string

unit_price

object

amount

Decimal string, e.g. ‘8.75’

string

currency_code

ISO 4217 code, e.g. ‘USD’

string

total_price

object

amount

Decimal string, e.g. ‘8.75’

string

currency_code

ISO 4217 code, e.g. ‘USD’

string

created_at

required

string format: date-time

updated_at

required

string format: date-time

meta

required

object

current_page

required

integer

total_pages

required

integer

total_count

required

integer

per_page

required

integer

Example

{
  "expenses": [
    {
      "received_status": "received"
    }
  ]
}

401

Missing or invalid Bearer token

Media type application/json

object

error

required

Error message

string

Example ^generated

{
  "error": "example"
}

403

User lacks financial access (view_material_costs permission)

Media type application/json

object

error

required

Error message

string

Example ^generated

{
  "error": "example"
}