*REST API › Endpoint reference › Finance › Proformas*

# Change the commercial status of a proforma

> Moves the OPERATIVE status of the proforma —`pending`, `confirmed` or `cancelled`—, which is the answer of the customer, and leaves an optional note in the history of the document.

Any transition among the three is allowed, and it is undone by calling again. It does NOT touch the tax status (draft / validated): validate and void are for that. Unlike the quote, confirming a proforma does not drag any other along, because proformas have no versions. It requires sales documents in the plan of the account (402 without it). Returns the full proforma, the same projection as its GET.

`PATCH /api/v1/proformas/{proformaId}/status` — scope `invoices:write`

Scope: `invoices:write` · 120/min · Add-on (402) · Idempotency-Key · If-Match · MCP: `filmo_proformas_update_status`

## Authorizations

Bearer API key with the scope below. `invoices:write`

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | string | No | Unique identifier of the request, chosen by the client (a UUID works). Between 1 and 255 characters: an empty header is rejected with 400 `validation_error`, because the client would believe itself protected. Repeating the same key with the SAME body within 24 h returns the stored response without executing again, with the `Idempotent-Replay: true` header. With a DIFFERENT body it returns 422. It is the safe way to retry after a network timeout. |
| `If-Match` | string | No | Optimistic locking: the `ETag` you read from the resource (or `*`). If the resource changed since, the write is rejected with `412 precondition_failed` before doing anything; read it again and retry. Without the header the write always proceeds. |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `proformaId` | string | Yes | Proforma identifier. |

## Body

Body schema: `ProformaStatusBody`

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | Yes | New commercial status: pending (awaiting an answer), confirmed (accepted by the customer) or cancelled (rejected or cancelled). `pending`, `confirmed`, `cancelled` |
| `notes` | string | No | Note stored in the document history alongside the status change. |

## Request examples

*Change the commercial status of a proforma*

**cURL**

```bash
curl https://app.filmo.io/api/v1/proformas/prof_8f2a1c/status \
  --request PATCH \
  --header "Authorization: Bearer $FILMO_API_KEY" \
  --header "Idempotency-Key: $(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)" \
  --header 'Content-Type: application/json' \
  --data '{
  "status": "confirmed",
  "notes": "Confirmada por correo el 4 de septiembre"
}'
```

**Node.js**

```javascript
fetch('https://app.filmo.io/api/v1/proformas/prof_8f2a1c/status', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer YOUR_FILMO_API_KEY',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    status: 'confirmed',
    notes: 'Confirmada por correo el 4 de septiembre'
  })
})
```

**Python**

```python
import uuid
import requests

requests.patch(
    "https://app.filmo.io/api/v1/proformas/prof_8f2a1c/status",
    headers={
      "Authorization": "Bearer YOUR_FILMO_API_KEY",
      "Idempotency-Key": str(uuid.uuid4()),
      "Content-Type": "application/json"
    },
    json={
      "status": "confirmed",
      "notes": "Confirmada por correo el 4 de septiembre"
    }
)
```

## Response

Response schema: `ProformaDto`

| Status | Description |
| --- | --- |
| 200 | Successful response. |
| 400 | Invalid request (validation_error): malformed query or body. `errors[]` lists every offending field with its stable code. |
| 401 | Authentication failed (unauthorized, api_key_invalid, api_key_revoked, api_key_expired, api_key_owner_inactive, api_key_owner_not_admin). |
| 402 | Add-on required (addon_required): the account plan does not include the add-on this operation needs; `requiredAddon` names it. |
| 403 | Not allowed (insufficient_scope: the API key does not have the required scope, named in `requiredScope`; forbidden: the owner of the key lacks the permission the operation requires). `insufficient_scope` is answered before the request counts against the rate limit, so it carries no `RateLimit-*` headers; `forbidden` does. |
| 404 | Resource not found (not_found): it does not exist or is outside the scope of the API key. |
| 409 | Conflict (conflict): the current state of the resource prevents the operation, a request with that Idempotency-Key is already in progress, or another conditional write (`If-Match`) held the resource for more than five seconds. `errors[0].code` says which: `in_progress` and `lock_timeout` are solved by retrying; `invalid_state` is not, because the state of the resource forbids the operation. |
| 412 | Precondition failed (precondition_failed): the `If-Match` entity tag does not match the current representation. Read the resource again and retry. |
| 422 | Idempotency-Key reused (idempotency_key_reused): the same key was used before with a different body. Change the key. |
| 429 | Rate limit exceeded (rate_limited): retry after `Retry-After` seconds; `RateLimit-*` says which quota ran out. |
| 500 | Internal error (internal_error). |

**200**

| Name | Type | Description |
| --- | --- | --- |
| `data` | object | Proforma: the advance invoice that is not yet an invoice. |
| `data.id` | string | Proforma identifier. |
| `data.proformaNumber` | string | Proforma number; null while it is a draft. |
| `data.status` | string | Document lifecycle status. |
| `data.operativeStatus` | string | Commercial status: pending (awaiting an answer), confirmed (accepted by the customer) or cancelled; null if not recorded. |
| `data.issueDate` | string<date-time> | Issue date in ISO 8601 UTC; null while it has none. |
| `data.currency` | string | Currency of the amounts, as an ISO 4217 code. |
| `data.contact` | object | Contact the proforma is issued to; null if not recorded. |
| `data.contact.id` | string | Contact identifier. |
| `data.contact.name` | string | Contact name. |
| `data.orderId` | string | Source order of the proforma; null if it does not come from one. |
| `data.orderNumber` | string | Number of that order; null if it does not come from one. |
| `data.projectId` | string | Project linked to the proforma; null if none. |
| `data.subTotal` | string | Subtotal before discounts and taxes, as a decimal string. |
| `data.discountTotal` | string | Total discounts, as a decimal string. |
| `data.taxesPrice` | string | Tax total, as a decimal string. |
| `data.netPrice` | string | Taxable base, as a decimal string. |
| `data.grossPrice` | string | Total including taxes, as a decimal string. |
| `data.totalPaid` | string | Advance payments received against the proforma, as a decimal string; null if none recorded. |
| `data.createdAt` | string<date-time> | Creation date in ISO 8601 UTC. |
| `data.updatedAt` | string<date-time> | Last modification date in ISO 8601 UTC. |
| `meta` | object | Additional information about the response. |
| `meta.warnings` | object[] | Lifecycle warnings; present only when the operation is deprecated. |
| `meta.warnings.code` | string | Stable warning code. `deprecated` |
| `meta.warnings.message` | string | For people: what is deprecated, until when, and what to use. |
| `meta.warnings.sunset` | string | Day (YYYY-MM-DD) the operation stops being served. |
| `meta.warnings.replacement` | string | `operationId` of the operation to use instead, or null if there is none. |
| `meta.warnings.link` | string | Where the deprecation is documented (the changelog). |

*Example response · 200*

```json
{
  "data": {
    "id": "proforma_9f3a2b",
    "proformaNumber": "2026-0001",
    "status": "Example status",
    "operativeStatus": "Example operative status",
    "issueDate": "2026-09-01T08:00:00.000Z",
    "currency": "EUR",
    "contact": {
      "id": "contact_9f3a2b",
      "name": "Example contact"
    },
    "orderId": "order_9f3a2b",
    "orderNumber": "2026-0001",
    "projectId": "project_9f3a2b",
    "subTotal": "120.00",
    "discountTotal": "120.00",
    "taxesPrice": "120.00",
    "netPrice": "120.00",
    "grossPrice": "120.00",
    "totalPaid": "120.00",
    "createdAt": "2026-09-01T08:00:00.000Z",
    "updatedAt": "2026-09-01T08:00:00.000Z"
  }
}
```

## Errors

| Status | Codes | Meaning |
| --- | --- | --- |
| 400 | `validation_error` | Malformed query or body. `errors[]` lists every offending field with its stable code. |
| 402 | `addon_required` | The account plan does not include the add-on this operation needs; `requiredAddon` names it. |
| 404 | `not_found` | It does not exist or is outside the scope of the API key. |
| 409 | `conflict` | The current state of the resource prevents the operation, a request with that Idempotency-Key is already in progress, or another conditional write (`If-Match`) held the resource for more than five seconds. `errors[0].code` says which: `in_progress` and `lock_timeout` are solved by retrying; `invalid_state` is not, because the state of the resource forbids the operation. |
| 412 | `precondition_failed` | The `If-Match` entity tag does not match the current representation. Read the resource again and retry. |
| 422 | `idempotency_key_reused` | The same key was used before with a different body. Change the key. |

## Deprecation

This operation is not deprecated. Deprecations are announced with a Deprecation header and a sunset date.

---

Canonical URL: https://docs.filmo.io/rest-api/endpoint-reference/proformas/change-the-commercial-status-of-a-proforma  
Last updated: 2026-10-25