Purchase orders

Update a purchase order

Changes the header of a purchase order.

PATCH

/api/v1/purchase-orders/{purchaseOrderId}

curl https://app.filmo.io/api/v1/purchase-orders/purc_8f2a1c \
  --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 '{
  "type": "stock_purchase",
  "supplierId": "cont_proveedor_01",
  "poDate": "2026-09-01T00:00:00+02:00",
  "supplierQuoteRef": "PRE-2026-118",
  "reference": "Reposición de trípodes"
}'

Node.jsfetch('https://app.filmo.io/api/v1/purchase-orders/purc_8f2a1c', { method: 'PATCH', headers: { Authorization: 'Bearer YOUR_FILMO_API_KEY', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json' }, body: JSON.stringify({ type: 'stock_purchase', supplierId: 'cont_proveedor_01', poDate: '2026-09-01T00:00:00+02:00', supplierQuoteRef: 'PRE-2026-118', reference: 'Reposición de trípodes' }) })Pythonimport uuid import requests requests.patch( "https://app.filmo.io/api/v1/purchase-orders/purc_8f2a1c", headers={ "Authorization": "Bearer YOUR_FILMO_API_KEY", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/json" }, json={ "type": "stock_purchase", "supplierId": "cont_proveedor_01", "poDate": "2026-09-01T00:00:00+02:00", "supplierQuoteRef": "PRE-2026-118", "reference": "Reposición de trípodes" } )

{
  "data": {
    "id": "purchase_order_9f3a2b",
    "poNumber": "2026-0001",
    "status": "draft",
    "type": "subrental",
    "isDraft": true,
    "poDate": "2026-09-01T08:00:00.000Z",
    "supplierId": "supplier_9f3a2b",
    "reference": "2026-0001",
    "currency": "EUR",
    "subTotal": "120.00",
    "discountTotal": "120.00",
    "taxesPrice": "120.00",
    "netPrice": "120.00",
    "grossPrice": "120.00",
    "totalPaid": "120.00",
    "orderId": "order_9f3a2b",
    "orderNumber": "2026-0001",
    "projectId": "project_9f3a2b",
    "repairTicketId": "repair_ticket_9f3a2b",
    "notes": "Example text.",
    "createdAt": "2026-09-01T08:00:00.000Z",
    "updatedAt": "2026-09-01T08:00:00.000Z"
  }
}

{
  "type": "https://docs.filmo.io/errors/validation_error",
  "title": "Validation error",
  "status": 400,
  "code": "validation_error",
  "detail": "2 validation errors",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "errors": [
    {
      "path": "name",
      "code": "too_small",
      "message": "Must be at least 1 characters long"
    },
    {
      "path": "contactType",
      "code": "invalid_value",
      "message": "Value not allowed; expected company, person"
    }
  ]
}

{
  "type": "https://docs.filmo.io/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "Missing Authorization header: Bearer <api key>",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/addon_required",
  "title": "Add-on required",
  "status": 402,
  "code": "addon_required",
  "detail": "Your plan does not include the add-on this operation requires",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "requiredAddon": "purchases"
}

{
  "type": "https://docs.filmo.io/errors/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API key does not have the required scope (orders:write)",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "requiredScope": "purchase-orders:write"
}

{
  "type": "https://docs.filmo.io/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "Resource not found",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "code": "conflict",
  "detail": "The current state of the resource does not allow the operation",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "errors": [
    {
      "path": "",
      "code": "invalid_state",
      "message": "The current state of the resource does not allow the operation"
    }
  ]
}

{
  "type": "https://docs.filmo.io/errors/precondition_failed",
  "title": "Precondition failed",
  "status": 412,
  "code": "precondition_failed",
  "detail": "The resource changed since you read it: read it again and retry",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/idempotency_key_reused",
  "title": "Idempotency-Key reused",
  "status": 422,
  "code": "idempotency_key_reused",
  "detail": "The Idempotency-Key header was already used with a different body",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/rate_limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limited",
  "detail": "Rate limit exceeded: retry in 30 seconds",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "retryAfter": 30
}

{
  "type": "https://docs.filmo.io/errors/internal_error",
  "title": "Internal error",
  "status": 500,
  "code": "internal_error",
  "detail": "Internal error",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

Generated from the schema

type always goes, even if it does not change: the approval flow and the numbering series depend on it. LINES are not touched from here, because they are not published; the server calculates the totals from them. The supplier snapshot, the numbering series and the custom fields are left out of the public body. It requires the purchases add-on (402 without it); a consignment purchase order —the stored type or the one you send is consignment— also requires the consignments add-on, and without it the response is 402 with requiredAddon: consignments and nothing is written. A cancelled purchase order, or one locked in the app, cannot be edited: 409 conflict and nothing is written. Returns the full purchase order, the same projection as its GET.

Authorizations

Bearer API key with the scope below. purchase-orders:write

Headers

Idempotency-Keystring

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.

Limits: min length 1, max length 255

Example:"9f1c2f4e-3a5b-4f6d-8e7a-0b1c2d3e4f5a"

If-Matchstring

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.

Example:"\"3sT3d9pBvZq4h2N0w8x1YkLmQ7c\""

Path parameters

purchaseOrderIdstringRequired

Purchase order identifier.

Limits: min length 1

Body

application/json

Body schema: PurchaseOrderUpdateBody

typestringRequired

Purchase order type.

Available options: subrental, stock_purchase, resale_purchase, consumable_purchase, technician, transport, repair, consignment

supplierIdstring | null

Supplier of the purchase order; null leaves it without a supplier (drafts only).

poDatestring<date-time> | null

Issue date, in ISO 8601 with offset; null clears it.

supplierQuoteRefstring | null

Reference of the supplier quote; null clears it.

Limits: max length 200

referencestring | null

Internal reference of the document; null clears it.

Limits: max length 200

currencystring

Currency, as an ISO 4217 code.

Limits: min length 3, max length 3

projectIdstring | null

Associated project; null unlinks it.

orderIdstring | null

Associated rental order; null unlinks it.

notesstring | null

Notes; null clears them.

Limits: max length 5000

Response

application/json

Successful response.

Response schema: PurchaseOrderDto

Envelope: PurchaseOrderResponse. meta.warnings is present only when the operation is deprecated.

Headers: X-Request-Id · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · ETag · Idempotent-Replay

dataobject

Purchase order to a supplier. The amounts are COST amounts, because the object is a purchase. The lines are not published, so the expense cannot be attributed to a specific item of a rental.

Show child attributes

data.idstring

Unique purchase order identifier.

data.poNumberstring | null

Purchase order number; null while it is a draft.

data.statusstring

Purchase order status.

Available options: draft, pending, completed, cancelled

data.typestring

Purchase order type.

Available options: subrental, stock_purchase, resale_purchase, consumable_purchase, technician, transport, repair, consignment

data.isDraftboolean

true if the purchase order is still a draft.

data.poDatestring<date-time> | null

Purchase order date in ISO 8601 UTC; null if not set.

data.supplierIdstring | null

Supplier identifier; null while a draft has no supplier. Resolve it against /api/v1/contacts.

data.referencestring | null

Free-form reference of the purchase order; null if it has none.

data.currencystring

Currency of the purchase order, as an ISO 4217 code.

data.subTotalstring

Subtotal before discounts and taxes, as a decimal string "1234.50".