Purchase orders

Receive material from a purchase order

Declares what arrived and in what quantity, line by line.

POST

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

curl https://app.filmo.io/api/v1/purchase-orders/purc_8f2a1c/receive \
  --request POST \
  --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 '{
  "spaceId": "spc_almacen_central",
  "lines": [
    {
      "lineId": "pol_00317",
      "receivedQuantity": 6,
      "newStockReceived": 4,
      "notes": "Dos vienen con la caja abierta"
    }
  ]
}'

Node.jsfetch('https://app.filmo.io/api/v1/purchase-orders/purc_8f2a1c/receive', { method: 'POST', headers: { Authorization: 'Bearer YOUR_FILMO_API_KEY', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json' }, body: JSON.stringify({ spaceId: 'spc_almacen_central', lines: [ { lineId: 'pol_00317', receivedQuantity: 6, newStockReceived: 4, notes: 'Dos vienen con la caja abierta' } ] }) })Pythonimport uuid import requests requests.post( "https://app.filmo.io/api/v1/purchase-orders/purc_8f2a1c/receive", headers={ "Authorization": "Bearer YOUR_FILMO_API_KEY", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/json" }, json={ "spaceId": "spc_almacen_central", "lines": [ { "lineId": "pol_00317", "receivedQuantity": 6, "newStockReceived": 4, "notes": "Dos vienen con la caja abierta" } ] } )

{
  "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"
  },
  "meta": {
    "receivedLines": 1
  }
}

{
  "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

Send your own Idempotency-Key

A retry without the same key duplicates the effect. Send your own Idempotency-Key and follow the retry table. A 409 or a repeated 500: read the order before retrying.

newStockReceived registers NEW inventory, so always send the Idempotency-Key header: without it, a retry duplicates the stock. The order may end up partially received. The line identifier is lineId. Returns the full purchase order, the same projection as its GET. meta.receivedLines says how many lines the call declared as received. A draft or cancelled order responds 409 conflict.

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: PurchaseOrderReceiveBody

spaceIdstring

Warehouse where the material comes in. Defaults to the warehouse of the account.

linesobject[]Required

Received lines. At least one.

Limits: min 1 items

Show child attributes

lines.lineIdstringRequired

Purchase order line being received.

Limits: min length 1

lines.receivedQuantitynumberRequired

Units received for that line.

Limits: min 0

lines.newStockReceivednumber

Of those received, how many register new inventory.

Limits: min 0

lines.notesstring

Reception notes.

Limits: max length 1000

Response

application/json

Successful response.

Response schema: PurchaseOrderDto

Envelope: ReceivePurchaseOrderResponse. 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".