> ## Documentation Index
> Fetch the complete documentation index at: https://docs.filexpress.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Purchases and expenses

> Register and query supplier purchases

**Required permission:** `expenses`

## Register a purchase

```http theme={null}
POST /expenses
```

> [!WARNING]
>
> As with sales, the external system must send the tax breakdowns per line and the calculated totals.

```json theme={null}
{
  "branch_id": "uuid",
  "provider_id": "uuid",
  "document_type": "ccf",
  "date": "2026-10-01",
  "observation": "Compra de insumos",
  "is_credit": false,
  "credit_days": 0,
  "number_control": "DTE-03-M001P001-000000000000123",
  "generation_code": "A1B2C3D4-...",
  "stamp": "2026XYZ...",
  "cost_center_id": "c3a1...",
  "cost_center_distribution_id": null,
  "products": [
    {
      "sku": "INS-001",
      "name": "Insumo A",
      "type": "goods",
      "quantity": 5,
      "price_before_taxes": 8.00,
      "expense_not_suject": 0,
      "expense_exent": 0,
      "expense_taxed": 40.00,
      "subtotal": 40.00,
      "cost_center_id": null
    }
  ],
  "totals": {
    "netTotals": 40.00,
    "charge_1": 0,
    "charge_2": 0,
    "expenseTotalTax": 40.00,
    "totalRent": 0,
    "totalTax": 5.20,
    "totalRetein": 0,
    "expenseTotalToPayment": 45.20
  }
}
```

### Fields

| Field | Type | Required | Description |
| - | - | - | - |
| `branch_id` | uuid | Yes | Branch that registers the purchase. |
| `provider_id` | uuid | Yes | Supplier. See [Suppliers](https://docs.filexpress.app/en/docs/api/facturacion/proveedores.md). |
| `document_type` | string | Yes | `ccf` (Comprobante de Crédito Fiscal, tax credit invoice), `fse` (Factura de Sujeto Excluido, excluded-subject invoice) or `ticket`. |
| `date` | date | Yes | Document date. |
| `is_credit` | boolean | Yes | Purchase on credit. |
| `credit_days` | integer | No | Credit days. |
| `observation` | string | No | Remarks. |
| `number_control` | string | No | Control number of the supplier's DTE. |
| `generation_code` | string | No | Generation code of the supplier's DTE. |
| `stamp` | string | No | Reception stamp of the supplier's DTE. |
| `cost_center_id` | uuid | No | [Cost center](https://docs.filexpress.app/en/docs/api/contabilidad/centros-de-costo.md) of the purchase (must be an active leaf center). |
| `cost_center_distribution_id` | uuid | No | Active [distribution](https://docs.filexpress.app/en/docs/api/contabilidad/centros-de-costo.md#distributions) of the purchase: the expense is split among its centers by percentage. Mutually exclusive with `cost_center_id` at the same level. |
| `products` | array | Yes | Lines (minimum 1). |
| `totals` | object | Yes | Totals. |

### `products[]` (all required, except `cost_center_id` and `cost_center_distribution_id`)

| Field | Type | Description |
| - | - | - |
| `sku` | string | Code of the good or service. |
| `name` | string | Description. |
| `type` | string | `goods` (good) or `services` (service). |
| `quantity` | number | Quantity (minimum 0.01). |
| `price_before_taxes` | number | Unit price before taxes. |
| `expense_not_suject` | number | Non-taxable amount. |
| `expense_exent` | number | Exempt amount. |
| `expense_taxed` | number | Taxed amount. |
| `subtotal` | number | Line total. |
| `cost_center_id` | uuid | Optional. Cost center of the line; if not sent, the purchase's cost center is used. |
| `cost_center_distribution_id` | uuid | Optional. [Distribution](https://docs.filexpress.app/en/docs/api/contabilidad/centros-de-costo.md#distributions) of the line. Mutually exclusive with `cost_center_id` at the same level. If the line has neither a center nor a distribution, the purchase's is used. |

**Cost center**

* The effective center of each line is the line's own or, if it has none, the purchase's.
* A nonexistent or inactive center, or one with subcenters, returns `422` with details in `errors`.
* When posting to accounting, the expense is grouped by account and center: two lines with different centers generate two expense lines. Suppliers, cash and VAT (IVA) are left without a center.
* Payments made after the purchase take their center by default (see [Accounts payable](https://docs.filexpress.app/en/docs/api/cuentas-por-pagar.md#register-payment)).

### `totals` (all required)

| Field | Description |
| - | - |
| `netTotals` | Sum of subtotals before taxes. |
| `charge_1` | Special charge 1 (in El Salvador: COTRANS on fuels). |
| `charge_2` | Special charge 2 (in El Salvador: FOVIAL on fuels). |
| `expenseTotalTax` | Taxable base. |
| `totalRent` | Income tax withheld. |
| `totalTax` | VAT (tax credit). |
| `totalRetein` | VAT withheld / collected. |
| `expenseTotalToPayment` | Total to pay. |

### `200` response

```json theme={null}
{
  "status": true,
  "message": "Expense created successfully",
  "data": {
    "expense_id": "uuid",
    "generation_code": "A1B2C3D4-...",
    "control_number": "DTE-03-M001P001-000000000000123",
    "status": "processed",
    "issue_time": "2026-10-01 10:00:00",
    "total": 45.20
  }
}
```

## Query a purchase

```http theme={null}
GET /expenses/{expense_id}
```

```json theme={null}
{
  "status": true,
  "data": {
    "expense_id": "uuid",
    "generation_code": "A1B2C3D4-...",
    "control_number": "DTE-03-...",
    "document_type": "ccf",
    "status": "processed",
    "issue_time": "2026-10-01 10:00:00",
    "payment_status": "pending",
    "is_credit": true,
    "provider": { "id": "uuid", "legal_name": "Distribuidora XYZ S.A. de C.V.", "provider_name": "Distribuidora XYZ" },
    "totals": { "expense_total": 45.20, "expense_to_payment": 45.20 },
    "products": [
      { "sku": "INS-001", "name": "Insumo A", "quantity": 5, "individual_price": 8.00, "subtotal": 40.00 }
    ]
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.