Creates an expense category. The name must be unique across the tenant.

POST /accounting/expense-categories

Group: Accounting › Expense Categories · Operation ID: createExpenseCategory

A reimbursable category must post to at least one account, and omitting accountIds fails with NO_ACCOUNT_SELECTED. At most one active distance category may exist for each reimbursable value, one reimbursable and one not, so a third fails with DUPLICATE_DISTANCE_CATEGORY. Every linked account must use an account subtype enabled for expense reports, and a violation is rejected without one of the error codes below. The response contains only the new category's id. Read the record with GET accounting/expense-categories/:id.

Open in the interactive reference

Parameters

Name In Type Required Description
Api-Version header "v1" yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.
Idempotency-Key header string no An opaque caller-chosen string (1-255 characters) that makes this request safe to retry. Repeating the same key with an identical request body replays the original response instead of re-executing - but only once that original request succeeded; a failed attempt re-executes on retry. Repeating the key with a different body is answered with 422. A key still in flight is answered with 409 - as is a key whose original request was interrupted before it finished, for a few minutes afterwards, until that attempt is presumed dead. A completed response stays replayable for 24 hours. The key is scoped to the caller, not to the action: reusing it for a different action is answered with 409 or 422 rather than treated independently. On read actions this header is ignored. On write actions that cannot offer the guarantee it is answered with 400 IDEMPOTENCY_NOT_SUPPORTED rather than silently ignored.

Request body

Required, application/json: createExpenseCategoryInput.

Field Type Required Description
category string yes The name of the expense category, for example 'Client Entertainment'. Must be unique across the tenant.
categoryType string no The kind of expense. One of 'Pur', 'Dis' or 'PerDiem'. 'Dis' is distance traveled. Omit to leave it unset.
status string no The lifecycle status. Accepted values: 'active', 'inactive'. Defaults to 'active'.
reimbursable boolean no Whether expenses in this category are reimbursed to the employee. Defaults to true. A reimbursable category must have at least one accountId.
requireAttachment boolean no Whether an expense in this category must have a receipt attachment.
requireAttendees boolean no Whether an expense in this category must list attendees.
entityIds array of string no The legal entities this category is available in. This array replaces the whole set. Omit to leave it unchanged. Send an empty array to remove every entity. See id on GET base/entities.
accountIds array of string no The GL accounts this category posts to. This array replaces the whole set. Required unless the category is not reimbursable. See id on GET accounting/accounts/:id.

Example:

{
  "category": "Client Entertainment",
  "categoryType": "Pur",
  "status": "<status>",
  "reimbursable": true,
  "requireAttachment": true,
  "requireAttendees": true,
  "entityIds": [
    "<entityIds>"
  ],
  "accountIds": [
    "7c1a9e40-2b53-4d68-9f01-3a5b7c9d1e24"
  ]
}

Response

200 Success

Under data (createExpenseCategoryOutput):

Field Type Required Description
id string yes The unique identifier for the created expense category.

Response headers

Errors

Code Status
DUPLICATE_CATEGORY 400
DUPLICATE_DISTANCE_CATEGORY 400
NO_ACCOUNT_SELECTED 400
REFERENCE_NOT_FOUND 400
IDEMPOTENCY_KEY_CONFLICT 409
IDEMPOTENCY_PAYLOAD_MISMATCH 422

Statuses