Expenses API | Genaya API Reference

Sales

Expenses

Recorded expenses with line items and totals.

GET/expenses

List expenses

Returns a cursor-paginated list of expenses for the authenticated organization. Soft-deleted expenses are excluded. Results are ordered by document id for stable, complete cursor coverage; each object still carries createdAt for client-side sorting. Requires scope: expenses:read.

Response 200

No fields.

Errors

400Malformed or missing parameters

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

429Rate limited

500Unexpected server error

curl -X GET https://api.genaya.com/v1/expenses \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "object": "list",
  "data": [
    {
      "id": "exp_8f2c1a9b",
      "object": "expense",
      "vendorName": "Home Depot",
      "date": "2026-06-15T14:30:00.000Z",
      "referenceNo": "INV-4821",
      "paymentMethod": "card",
      "total": 248.75,
      "tax": 18.5,
      "currency": "USD",
      "appointmentId": "appt_5a9d22c4",
      "appointmentUuid": "1c8f2a3b-4d5e-6f70-8192-a3b4c5d6e7f8",
      "appointmentDocId": "7Qx2mF0aBcDeFgHiJkLm",
      "reimburseToId": "usr_3b9e21a7",
      "reimburseToName": "Jordan Avery",
      "organizationCompanyId": "cmp_1a2b3c4d",
      "organizationCompanyName": "Northside HVAC",
      "organizationCompanyLogoUrl": "https://storage.genaya.com/logos/northside.png",
      "items": [
        {
          "id": "itm_7c0d3e1f",
          "name": "PVC pipe",
          "description": "2 inch schedule 40",
          "amount": 42.5,
          "categoryId": "cat_materials",
          "appointmentId": null
        }
      ],
      "status": "created",
      "createdAt": "2026-06-15T14:31:02.000Z",
      "updatedAt": "2026-06-15T14:31:02.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": ""
}

POST/expenses

Create an expense

Creates a new expense for the authenticated organization. You must provide a vendorName or at least one item; otherwise the request is rejected. The expense status is always set to "created" and the actor (createdBy) is the API key's issuing member, never a request body field. Supports idempotent retries via the Idempotency-Key header. Requires scope: expenses:write.

Request body

FieldTypeDescription

vendorName

string

The name of the vendor.

date

string <date-time>

ISO-8601 expense date. Defaults to now when omitted.

referenceNo

string

A reference or invoice number.

paymentMethod

string

The payment method used.

total

number

The total amount. Defaults to 0.

tax

number

The tax portion. Defaults to 0.

currency

string

ISO currency code. Defaults to "USD".

appointmentId

string

The id of an associated appointment.nullable

appointmentUuid

string

The stable UUID of the associated appointment.nullable

appointmentDocId

string

The Firestore document id of the associated appointment.nullable

reimburseToId

string

The id of the team member or external company to reimburse.nullable

reimburseToName

string

The display name of the reimbursement recipient.nullable

organizationCompanyId

string

The id of the organization company this expense is attributed to.nullable

organizationCompanyName

string

The name of the organization company.nullable

organizationCompanyLogoUrl

string

The logo URL of the organization company.nullable

items

array of object

The line items for the expense.

id

string

Optional client-supplied id; generated when omitted.

name

string

The line item name.

description

string

A free-form description.

amount

number

The amount for this line item. Defaults to 0.

categoryId

string

The category id this line item belongs to.

appointmentId

string

An appointment id associated with this line item.nullable

Response 201

FieldTypeDescription

id

string

Unique identifier for the expense.

object

string

The object type. Always "expense".

vendorName

string

The name of the vendor the expense was paid to.

date

string <date-time>

ISO-8601 timestamp of the expense date.nullable

referenceNo

string

A reference or invoice number for the expense.

paymentMethod

string

The payment method used (free-form text).

total

number

The total amount of the expense. Defaults to 0.

tax

number

The tax portion of the expense. Defaults to 0.

currency

string

ISO currency code. Defaults to "USD".

appointmentId

string

The id of an associated appointment, or null if none.nullable

appointmentUuid

string

The stable UUID of the associated appointment, or null if none.nullable

appointmentDocId

string

The Firestore document id of the associated appointment, or null if none.nullable

reimburseToId

string

The id of the team member or external company to reimburse, or null.nullable

reimburseToName

string

The display name of the reimbursement recipient, or null.nullable

organizationCompanyId

string

The id of the organization company this expense is attributed to, or null.nullable

organizationCompanyName

string

The name of the organization company, or null.nullable

organizationCompanyLogoUrl

string

The logo URL of the organization company, or null.nullable

items

array of object

The line items that make up the expense.

id

string

The id of the line item, or null when not set.nullable

name

string

The line item name.

description

string

A free-form description of the line item.

amount

number

The amount for this line item.

categoryId

string

The category id this line item belongs to, or null.nullable

appointmentId

string

An appointment id associated with this line item, or null.nullable

status

string

The expense status. Defaults to "created".

createdAt

string <date-time>

ISO-8601 timestamp of when the expense was created.nullable

updatedAt

string <date-time>

ISO-8601 timestamp of when the expense was last updated.nullable

Errors

400Malformed or missing parameters

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

409Idempotency-Key reused with a different body

422Rejected by a business rule

429Rate limited

500Unexpected server error

curl -X POST https://api.genaya.com/v1/expenses \
  -H "Authorization: Bearer gny_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "vendorName": "Home Depot",
  "date": "2026-06-15T14:30:00.000Z",
  "referenceNo": "INV-4821",
  "paymentMethod": "card",
  "total": 248.75,
  "tax": 18.5,
  "currency": "USD",
  "appointmentId": "appt_5a9d22c4",
  "reimburseToId": "usr_3b9e21a7",
  "reimburseToName": "Jordan Avery",
  "organizationCompanyId": "cmp_1a2b3c4d",
  "organizationCompanyName": "Northside HVAC",
  "items": [
    {
      "name": "PVC pipe",
      "description": "2 inch schedule 40",
      "amount": 42.5,
      "categoryId": "cat_materials"
    }
  ]
}'

Example response

{
  "data": {
    "id": "exp_8f2c1a9b",
    "object": "expense",
    "vendorName": "Home Depot",
    "date": "2026-06-15T14:30:00.000Z",
    "referenceNo": "INV-4821",
    "paymentMethod": "card",
    "total": 248.75,
    "tax": 18.5,
    "currency": "USD",
    "appointmentId": "appt_5a9d22c4",
    "appointmentUuid": "1c8f2a3b-4d5e-6f70-8192-a3b4c5d6e7f8",
    "appointmentDocId": "7Qx2mF0aBcDeFgHiJkLm",
    "reimburseToId": "usr_3b9e21a7",
    "reimburseToName": "Jordan Avery",
    "organizationCompanyId": "cmp_1a2b3c4d",
    "organizationCompanyName": "Northside HVAC",
    "organizationCompanyLogoUrl": "https://storage.genaya.com/logos/northside.png",
    "items": [
      {
        "id": "itm_7c0d3e1f",
        "name": "PVC pipe",
        "description": "2 inch schedule 40",
        "amount": 42.5,
        "categoryId": "cat_materials",
        "appointmentId": null
      }
    ],
    "status": "created",
    "createdAt": "2026-06-15T14:31:02.000Z",
    "updatedAt": "2026-06-15T14:31:02.000Z"
  }
}

GET/expenses/{id}

Retrieve an expense

Returns a single expense by id. A record belonging to another organization returns 404 rather than 403, so this can never confirm cross-tenant existence. Requires scope: expenses:read.

Parameters

Path

idrequired

string

The expense id.

Response 200

FieldTypeDescription

id

string

Unique identifier for the expense.

object

string

The object type. Always "expense".

vendorName

string

The name of the vendor the expense was paid to.

date

string <date-time>

ISO-8601 timestamp of the expense date.nullable

referenceNo

string

A reference or invoice number for the expense.

paymentMethod

string

The payment method used (free-form text).

total

number

The total amount of the expense. Defaults to 0.

tax

number

The tax portion of the expense. Defaults to 0.

currency

string

ISO currency code. Defaults to "USD".

appointmentId

string

The id of an associated appointment, or null if none.nullable

appointmentUuid

string

The stable UUID of the associated appointment, or null if none.nullable

appointmentDocId

string

The Firestore document id of the associated appointment, or null if none.nullable

reimburseToId

string

The id of the team member or external company to reimburse, or null.nullable

reimburseToName

string

The display name of the reimbursement recipient, or null.nullable

organizationCompanyId

string

The id of the organization company this expense is attributed to, or null.nullable

organizationCompanyName

string

The name of the organization company, or null.nullable

organizationCompanyLogoUrl

string

The logo URL of the organization company, or null.nullable

items

array of object

The line items that make up the expense.

id

string

The id of the line item, or null when not set.nullable

name

string

The line item name.

description

string

A free-form description of the line item.

amount

number

The amount for this line item.

categoryId

string

The category id this line item belongs to, or null.nullable

appointmentId

string

An appointment id associated with this line item, or null.nullable

status

string

The expense status. Defaults to "created".

createdAt

string <date-time>

ISO-8601 timestamp of when the expense was created.nullable

updatedAt

string <date-time>

ISO-8601 timestamp of when the expense was last updated.nullable

Errors

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

429Rate limited

500Unexpected server error

curl -X GET https://api.genaya.com/v1/expenses/{id} \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "data": {
    "id": "exp_8f2c1a9b",
    "object": "expense",
    "vendorName": "Home Depot",
    "date": "2026-06-15T14:30:00.000Z",
    "referenceNo": "INV-4821",
    "paymentMethod": "card",
    "total": 248.75,
    "tax": 18.5,
    "currency": "USD",
    "appointmentId": "appt_5a9d22c4",
    "appointmentUuid": "1c8f2a3b-4d5e-6f70-8192-a3b4c5d6e7f8",
    "appointmentDocId": "7Qx2mF0aBcDeFgHiJkLm",
    "reimburseToId": "usr_3b9e21a7",
    "reimburseToName": "Jordan Avery",
    "organizationCompanyId": "cmp_1a2b3c4d",
    "organizationCompanyName": "Northside HVAC",
    "organizationCompanyLogoUrl": "https://storage.genaya.com/logos/northside.png",
    "items": [
      {
        "id": "itm_7c0d3e1f",
        "name": "PVC pipe",
        "description": "2 inch schedule 40",
        "amount": 42.5,
        "categoryId": "cat_materials",
        "appointmentId": null
      }
    ],
    "status": "created",
    "createdAt": "2026-06-15T14:31:02.000Z",
    "updatedAt": "2026-06-15T14:31:02.000Z"
  }
}

PATCH/expenses/{id}

Update an expense

Updates an existing expense. Only the fields present in the request body are changed. The post-merge state must still have a vendorName or at least one item, otherwise the request is rejected. Returns 404 if the expense does not exist, belongs to another organization, or has been soft-deleted. Requires scope: expenses:write.

Parameters

Path

idrequired

string

The id of the expense to update.

Request body

FieldTypeDescription

vendorName

string

The name of the vendor.

date

string <date-time>

ISO-8601 expense date.

referenceNo

string

A reference or invoice number.

paymentMethod

string

The payment method used.

total

number

The total amount.

tax

number

The tax portion.

currency

string

ISO currency code.

appointmentId

string

The id of an associated appointment.nullable

appointmentUuid

string

The stable UUID of the associated appointment.nullable

appointmentDocId

string

The Firestore document id of the associated appointment.nullable

reimburseToId

string

The id of the team member or external company to reimburse.nullable

reimburseToName

string

The display name of the reimbursement recipient.nullable

organizationCompanyId

string

The id of the organization company this expense is attributed to.nullable

organizationCompanyName

string

The name of the organization company.nullable

organizationCompanyLogoUrl

string

The logo URL of the organization company.nullable

items

array of object

The line items for the expense (replaces the existing array).

id

string

Optional client-supplied id; generated when omitted.

name

string

The line item name.

description

string

A free-form description.

amount

number

The amount for this line item. Defaults to 0.

categoryId

string

The category id this line item belongs to.

appointmentId

string

An appointment id associated with this line item.nullable

Response 200

FieldTypeDescription

id

string

Unique identifier for the expense.

object

string

The object type. Always "expense".

vendorName

string

The name of the vendor the expense was paid to.

date

string <date-time>

ISO-8601 timestamp of the expense date.nullable

referenceNo

string

A reference or invoice number for the expense.

paymentMethod

string

The payment method used (free-form text).

total

number

The total amount of the expense. Defaults to 0.

tax

number

The tax portion of the expense. Defaults to 0.

currency

string

ISO currency code. Defaults to "USD".

appointmentId

string

The id of an associated appointment, or null if none.nullable

appointmentUuid

string

The stable UUID of the associated appointment, or null if none.nullable

appointmentDocId

string

The Firestore document id of the associated appointment, or null if none.nullable

reimburseToId

string

The id of the team member or external company to reimburse, or null.nullable

reimburseToName

string

The display name of the reimbursement recipient, or null.nullable

organizationCompanyId

string

The id of the organization company this expense is attributed to, or null.nullable

organizationCompanyName

string

The name of the organization company, or null.nullable

organizationCompanyLogoUrl

string

The logo URL of the organization company, or null.nullable

items

array of object

The line items that make up the expense.

id

string

The id of the line item, or null when not set.nullable

name

string

The line item name.

description

string

A free-form description of the line item.

amount

number

The amount for this line item.

categoryId

string

The category id this line item belongs to, or null.nullable

appointmentId

string

An appointment id associated with this line item, or null.nullable

status

string

The expense status. Defaults to "created".

createdAt

string <date-time>

ISO-8601 timestamp of when the expense was created.nullable

updatedAt

string <date-time>

ISO-8601 timestamp of when the expense was last updated.nullable

Errors

400Malformed or missing parameters

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

422Rejected by a business rule

429Rate limited

500Unexpected server error

curl -X PATCH https://api.genaya.com/v1/expenses/{id} \
  -H "Authorization: Bearer gny_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "total": 260,
  "paymentMethod": "cash"
}'

Example response

{
  "data": {
    "id": "exp_8f2c1a9b",
    "object": "expense",
    "vendorName": "Home Depot",
    "date": "2026-06-15T14:30:00.000Z",
    "referenceNo": "INV-4821",
    "paymentMethod": "card",
    "total": 248.75,
    "tax": 18.5,
    "currency": "USD",
    "appointmentId": "appt_5a9d22c4",
    "appointmentUuid": "1c8f2a3b-4d5e-6f70-8192-a3b4c5d6e7f8",
    "appointmentDocId": "7Qx2mF0aBcDeFgHiJkLm",
    "reimburseToId": "usr_3b9e21a7",
    "reimburseToName": "Jordan Avery",
    "organizationCompanyId": "cmp_1a2b3c4d",
    "organizationCompanyName": "Northside HVAC",
    "organizationCompanyLogoUrl": "https://storage.genaya.com/logos/northside.png",
    "items": [
      {
        "id": "itm_7c0d3e1f",
        "name": "PVC pipe",
        "description": "2 inch schedule 40",
        "amount": 42.5,
        "categoryId": "cat_materials",
        "appointmentId": null
      }
    ],
    "status": "created",
    "createdAt": "2026-06-15T14:31:02.000Z",
    "updatedAt": "2026-06-15T14:31:02.000Z"
  }
}

DELETE/expenses/{id}

Delete an expense

Soft-deletes an expense. The record is retained internally but no longer appears in list or retrieve responses. Returns 404 if the expense does not exist, belongs to another organization, or was already soft-deleted. Requires scope: expenses:write.

Parameters

Path

idrequired

string

The id of the expense to delete.

Response 200

FieldTypeDescription

id

string

The id of the deleted expense.

object

string

deleted

boolean

Errors

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

429Rate limited

500Unexpected server error

curl -X DELETE https://api.genaya.com/v1/expenses/{id} \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "data": {
    "id": "",
    "object": "expense",
    "deleted": true
  }
}