Light APIv1.0.0

API / Reference / Expenses

Create expense

POST https://api.light.inc/v1/expenses

Creates an expense synchronously from a receipt uploaded with shouldAutoCreateExpense: false and the given line items. No OCR runs: the fields you send are what is stored. A PDF receipt is kept as-is; JPEG, PNG, HEIC and TIFF receipts are converted to PDF first. The expense is created as a draft for the authenticated user and is included in the next POST /v1/expenses/submit.

Requires a user credential with the reimbursement role; under an API key it fails with USER_NOT_RECOGNIZED. The user needs an active reimbursement configuration first (PUT /v1/users/{userId}/reimbursement-config), or the call fails with MISSING_USER_REIMBURSEMENT_CONFIG.

receiptDocumentKey must be a key from POST /v1/expenses/upload-url with shouldAutoCreateExpense: false, uploaded by the same user: anything else is 404 EXPENSE_RECEIPT_NOT_FOUND. An empty file or one over 10 MB fails with EXPENSE_RECEIPT_INVALID; a key already used by another expense is 409 EXPENSE_RECEIPT_ALREADY_USED. Images are converted to PDF synchronously, so the stored receiptDocumentKey may differ from the one you sent. Validation (EXPENSE_VALIDATION_FAILED, with a path per error): 1 to 50 lines, originalAmount above zero, non-blank descriptions, and each reimbursementCategoryId belonging to the user's own entity. costCenterId is ignored: every line takes the default cost centre from the user's reimbursement configuration. When originalCurrency differs from the user's reimbursement currency and no billingAmount is given, it is derived from the exchange rate on performedDate, and a missing rate fails the whole call with EXPENSE_BILLING_AMOUNT_DERIVATION_FAILED.

X-Idempotency-Key is honoured per user: the same key and body returns the existing expense; the same key with a different body is 409 IDEMPOTENCY_VIOLATION. The expense is created in IN_DRAFT.

Authorization

Send one of these on every request. See Authentication for how to get credentials.

  • API key

    Basic authentication header of the form Basic <api_key>, where <api_key> is your api key.

  • Bearer token

Headers

  • X-Idempotency-Key string

Request body

application/json;charset=UTF-8

  • receiptDocumentKey stringrequired

    Key returned by POST /v1/expenses/upload-url called with shouldAutoCreateExpense=false, once the file has been uploaded. A PDF is attached as-is; JPEG, PNG, HEIC and TIFF files are converted to PDF first.

  • originalCurrency stringrequired

  • performedDate string · daterequired

    Date the expense was incurred; also the date of the exchange rate used when billingAmount is derived

  • detailedDescription string

    Free-text description of the expense as a whole; each line carries its own description

  • lineItems array of objectrequired

    At least one line. The reimbursement category of a line drives the GL account and tax code of the reimbursement.

    • originalAmount integer · int64required

      Amount in minor units of originalCurrency (e.g. 1250 for 12.50)

    • billingAmount integer · int64

      Amount in minor units of the user's reimbursement currency. Optional: equals originalAmount when the currencies match, otherwise derived from the exchange rate of performedDate.

    • description stringrequired

      What the line is for; shown on the expense and on the reimbursement

    • reimbursementCategoryId string · uuidrequired

      Reimbursement category of the line, which decides the GL account and tax code on the reimbursement. Must belong to the user's company entity.

Response

  • id string · uuid

  • receiptDocumentKey string

  • originalCurrency string

  • billingCurrency string

  • status string

    ⚠️ This enum is not exhaustive; new values may be added in the future.

    One of CREATED IN_DRAFT SUBMITTED_FOR_REVIEW CANCELLED

  • userId string · uuid

  • companyId string · uuid

  • performedDate string · date

  • detailedDescription string

  • lineItems array of object

    • id string · uuid

    • expenseId string · uuid

    • originalAmount integer · int64

    • billingAmount integer · int64

    • accountId string · uuid

    • costCenterId string · uuid

    • description string

    • reimbursementCategoryId string · uuid

    • createdAt string · date-time

    • updatedAt string · date-time

  • createdAt string · date-time

  • updatedAt string · date-time