---
title: "Create expense"
method: POST
path: "/v1/expenses"
tags: ["Expenses"]
---

# Create expense

`POST /v1/expenses`

Creates an **approved** expense

## Scopes

| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage expenses (`employment_payments`) | - | Manage expenses (`expense:write`) |

## Headers

- `Authorization` string, required

## Request body

- ParamsToCreateExpense — All the params needed to create an expense. An expense can be created using the `receipt` or `receipts` fields; however, these fields are not allowed together within the same object. For category selection, you can use either: - `category` (legacy enum values, deprecated but supported) - `expense_category_slug` (new hierarchical categories, recommended) If both are provided, `expense_category_slug` takes precedence.
  - `amount` integer, required — The expense amount in the specified currency, in cents.
  - `category` 'car_rental' | 'coworking_office' | 'education_training' | 'entertainment' | 'flight' | 'fuel' | 'gifts' | 'insurance' | 'lodging' | 'meals' | 'other' | 'parking_toll' | 'subscription' | 'tech_equipment' | 'telecommunication' | 'transport' | 'utilities' | 'vaccination_testing' | 'visa' | 'wellness' | 'coworking' | 'home_office' | 'phone_utilities' | 'travel', nullable — Categories allowed for an expense (legacy, deprecated).<br/> Note: `coworking`, `home_office`, `phone_utilities`, `travel` are deprecated and will be removed in the future.
  - `currency` string, required — The three-letter code for the expense currency.<br/> Examples: `"USD"`, `"EUR"`, `"CAD"`
  - `employment_id` string, required — The ID for the employment to which this expense relates.
  - `expense_category_slug` string, nullable — Slug of the expense category from the hierarchical categories system (recommended). Takes precedence over legacy category field.
  - `expense_date` string, required — Date of the purchase, which must be in the past
  - `receipt` Base64File — All the params needed upload a base64 file.
    - `content` string, binary, required — The content in base64 encoding.
    - `name` string, required — The file name.
  - `receipts` Base64File[]
    - `content` string, binary, required — The content in base64 encoding.
    - `name` string, required — The file name.
  - `reviewed_at` string, date-time — The date and time that the expense was reviewed in ISO8601 format. If not provided, it defaults to the current datetime.
  - `reviewer_id` string — If the person reviewing the expense is a user in Remote, you can provide its user id for this field. If a value is not provided, defaults to the user that generated the API token.
  - `tax_amount` integer — The tax portion of the expense amount, in cents. Use 0 if no tax applies.
  - `timezone` string — [TZ identifier](https://www.iana.org/time-zones)
  - `title` string, required — A short description of the expense (e.g., "New keyboard", "Team dinner").

## Response `201`

Success

- ExpenseResponse — Response containing a single expense record.
  - `data` object, required
    - `expense` union, required — An expense or a draft object, depending on the status. Drafts (status `draft` or `archived`) may have incomplete(null) data. The expense status `draft` occurs when users want to save expenses but don't want them to be considered for approval just yet. Only expenses in `pending` status can be approved or declined. It is possible to update a pending expense to status draft, or vice versa. There are no flows that change the status of an expense to `draft` automatically. This is purely a manual action by the employee.
      - object — A submitted expense record with complete data. All monetary amounts are integers in the currency's minor unit (cents).
        - `amount` integer, required — The expense amount in the original currency, in cents.
        - `category` 'car_rental' | 'coworking_office' | 'education_training' | 'entertainment' | 'flight' | 'fuel' | 'gifts' | 'insurance' | 'lodging' | 'meals' | 'mileage' | 'other' | 'parking_toll' | 'per_diem' | 'subscription' | 'tech_equipment' | 'telecommunication' | 'transport' | 'utilities' | 'vaccination_testing' | 'visa' | 'wellness' | 'coworking' | 'home_office' | 'phone_utilities' | 'travel', nullable — Categories allowed for an expense (legacy, deprecated)
        - `converted_amount` integer, required — The expense amount converted to the company's billing currency, in cents.
        - `converted_currency` CurrencyDefinition, required — Currency object without a UUID identifier
          - `code` string, required
          - `name` string, required
          - `symbol` string, required
        - `converted_tax_amount` integer, required — The tax portion converted to the company's billing currency, in cents.
        - `currency` CurrencyDefinition, required — Currency object without a UUID identifier
          - `code` string, required
          - `name` string, required
          - `symbol` string, required
        - `employment_id` string, required — The unique identifier (UUID) of the employment this expense belongs to.
        - `expense_category` object, nullable — New hierarchical expense category (recommended)
          - `code` string — Internal category code (e.g., 'travel.flights')
          - `slug` string — Unique identifier for the category
          - `title` string — Human-readable category name
        - `expense_date` string, date, required — The date the expense was incurred (ISO 8601 format). Must be in the past.
        - `id` string, required — The unique identifier (UUID) of the expense.
        - `invoice_period` string, nullable — The payroll invoice period this expense is associated with, in YYYY-MM format. Null if not yet assigned to a payroll period.
        - `notes` string, nullable — Optional additional notes or context about the expense.
        - `reason` string, nullable — The reason provided when the expense was declined. Null for non-declined expenses.
        - `receipts` File[] — Uploaded receipt files for this expense. Maximum 5 receipts.
          - `id` string, required — The unique identifier (UUID) of the file.
          - `inserted_at` string, date-time, required — UTC date time in [ISO 8601][] format. [ISO 8601]: https://en.wikipedia.org/wiki/ISO_8601
          - `name` string, required — The file name including extension (e.g., "id.pdf", "contract.pdf").
          - `sub_type` string, nullable — A more specific classification of the file within its type (e.g., "personal_id" within type "id", or "ir_35" within type "contract"). Null if no sub-type applies.
          - `type` string, required — The broad category of the file (e.g., "id", "contract", "tax_form").
        - `reviewed_at` string, date, nullable — The date the expense was reviewed. Null if not yet reviewed.
        - `reviewer` object, nullable — The person who reviewed (approved or declined) this expense. Null if not yet reviewed.
          - `user_email` string — The reviewer's email address.
          - `user_id` string — The unique identifier of the reviewer.
          - `user_name` string — The reviewer's full name.
        - `status` 'canceled' | 'pending' | 'declined' | 'approved' | 'processing' | 'reimbursed', required — The current status of the expense. - `pending`: Submitted and awaiting approval. - `approved`: Approved by a reviewer and queued for reimbursement. - `declined`: Declined by a reviewer. See `reason` for details. - `canceled`: Canceled by the employee before approval. - `processing`: Being processed as part of a payroll run. - `reimbursed`: Successfully reimbursed to the employee.
        - `tax_amount` integer, required — The tax portion of the expense amount in the original currency, in cents.
        - `title` string, required — A short description of the expense (e.g., "New keyboard", "Team dinner").
      - object — A draft expense that the employee has saved but not yet submitted for approval. Draft expenses may have incomplete (null) data since the employee hasn't finalized them yet. All monetary amounts are integers in the currency's minor unit (cents) when present.
        - `amount` integer, nullable, required — The expense amount in the original currency, in cents. Null if not yet entered.
        - `category` 'car_rental' | 'coworking_office' | 'education_training' | 'entertainment' | 'flight' | 'fuel' | 'gifts' | 'insurance' | 'lodging' | 'meals' | 'mileage' | 'other' | 'parking_toll' | 'per_diem' | 'subscription' | 'tech_equipment' | 'telecommunication' | 'transport' | 'utilities' | 'vaccination_testing' | 'visa' | 'wellness' | 'coworking' | 'home_office' | 'phone_utilities' | 'travel', nullable — Categories allowed for an expense (legacy, deprecated)
        - `converted_amount` integer, nullable, required — The converted expense amount in the company's billing currency, in cents. Null if not yet calculated.
        - `converted_currency` CurrencyDefinition, required — Currency object without a UUID identifier
          - `code` string, required
          - `name` string, required
          - `symbol` string, required
        - `converted_tax_amount` integer, nullable, required — The converted tax portion, in cents. Null if not yet calculated.
        - `currency` CurrencyDefinition, required — Currency object without a UUID identifier
          - `code` string, required
          - `name` string, required
          - `symbol` string, required
        - `employment_id` string, required — The unique identifier (UUID) of the employment this expense belongs to.
        - `expense_category` object, nullable — New hierarchical expense category (recommended)
          - `code` string — Internal category code (e.g., 'travel.flights')
          - `slug` string — Unique identifier for the category
          - `title` string — Human-readable category name
        - `expense_date` string, date, nullable, required — The date the expense was incurred. May be null in drafts.
        - `id` string, required — The unique identifier (UUID) of the draft expense.
        - `invoice_period` string, nullable — Not applicable for draft expenses. Always null.
        - `notes` string, nullable — Optional additional notes about the expense.
        - `reason` string, nullable — Not applicable for draft expenses. Always null.
        - `receipts` File[] — Uploaded receipt files. May be empty for drafts. Maximum 5 receipts.
          - `id` string, required — The unique identifier (UUID) of the file.
          - `inserted_at` string, date-time, required — UTC date time in [ISO 8601][] format. [ISO 8601]: https://en.wikipedia.org/wiki/ISO_8601
          - `name` string, required — The file name including extension (e.g., "id.pdf", "contract.pdf").
          - `sub_type` string, nullable — A more specific classification of the file within its type (e.g., "personal_id" within type "id", or "ir_35" within type "contract"). Null if no sub-type applies.
          - `type` string, required — The broad category of the file (e.g., "id", "contract", "tax_form").
        - `reviewed_at` string, date, nullable — Not applicable for draft expenses. Always null.
        - `reviewer` object, nullable — Not applicable for draft expenses. Always null.
          - `user_email` string — The reviewer's email address.
          - `user_id` string — The unique identifier of the reviewer.
          - `user_name` string — The reviewer's full name.
        - `status` 'draft' | 'archived', required — The draft status. - `draft`: The expense is saved as a draft by the employee and not submitted for approval. - `archived`: The draft was soft-deleted by the employee.
        - `tax_amount` integer, nullable, required — The tax portion in the original currency, in cents. Null if not yet entered.
        - `title` string, nullable, required — A short description of the expense. May be null in drafts.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not Found
- `422` — Unprocessable Entity
- `429` — Too many requests

---

[API](https://skmtc.net/remote-com/apis/remote.md) · [All operations](https://skmtc.net/remote-com/apis/remote/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/remote-com/remote/revisions/7e6a0c61ac82/schema)