Services
Update a service
Updates a service (send only the fields to change).
Request examples
curl https://app.filmo.io/api/v1/services/serv_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 '{
"priceConfig": {
"hourlyRate": 45,
"perKmRate": 0.42
},
"breakMinutes": 30,
"travelTimeBefore": 60,
"travelTimeAfter": 60,
"defaultExpenses": {
"catering": {
"price": 18
},
"travel": {
"price": 25
}
}
}'Generated from the schema
It includes the rate, the travel times and the expenses passed on by default —of which only the PRICE goes in, not the cost—. Lists replace the existing one. Returns the updated service.
Authorizations
Bearer API key with the scope below. services:write
Headers
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"
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
Service identifier.
Limits: min length 1
Body
Body schema: ServiceUpdateBody
Customer-facing service name.
Limits: min length 2
Service description; null clears it.
Service type.
Available options: crew, fleet, general
Whether it appears as a plannable service.
Default quantity.
Limits: min 1
Break deducted from the work day, in minutes.
Limits: min 0
Information printed on the order and on the delivery note.
Service rate.
Show child attributesHide child attributes
Price per hour.
Limits: min 0
Fixed price per service.
Limits: min 0
Price per kilometre.
Limits: min 0
Whether its amount counts towards the document total.
How the billable distance is calculated.
Travel time before, in minutes.
Limits: min 0
Travel time after, in minutes.
Limits: min 0
Window in which it is used.
Show child attributesHide child attributes
"order" inherits the dates of the order; "custom" uses the offsets below.
Available options: order, custom
Minutes before the order start.
Limits: min 0
Minutes after the order end.
Limits: min 0
Window in which it is planned.
Show child attributesHide child attributes
"order" inherits the dates of the order; "custom" uses the offsets below.
Available options: order, custom
Minutes before the order start.
Limits: min 0
Minutes after the order end.
Limits: min 0
Expenses passed on by default. Only the price, not the cost. Merged with the stored ones: categories you omit are left unchanged, and each category keeps its stored cost.
Show child attributesHide child attributes
Meal allowances.
Show child attributesHide child attributes
What the customer is charged for this concept.
Travel.
Show child attributesHide child attributes
What the customer is charged for this concept.
Accommodation.
Show child attributesHide child attributes
What the customer is charged for this concept.
Other expenses.
Show child attributesHide child attributes
What the customer is charged for this concept.
Required resources. Replaces the whole list.
Show child attributesHide child attributes
What is needed to provide it: personnel or vehicle.
Available options: personnel, vehicle
How many are needed.
Limits: min 1
Tags the assigned resource must have. E.g.: "Carné C".
Limits: max 20 items, each max length 100
Collection it belongs to.
Service image URLs.
Response
Successful response.
Response schema: ServiceDto
Envelope: ServiceResponse. meta. is present only when the operation is deprecated.
Headers: X-Request-Id · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · ETag · Idempotent-Replay
Sellable line that does not come from inventory: personnel, transport, work days.
Show child attributesHide child attributes
Unique service identifier.
Service name as the customer sees it.
Type: crew (personnel), fleet (vehicles) or general.
Description; null if it has none.
Quantity added to an order by default.
Whether it appears as a plannable service.
Whether its amount counts towards the document total.
Path of the collection it belongs to; null if it is in none.
Resources needed to provide it.
Show child attributesHide child attributes
What is needed to provide it: personnel or vehicle.
Available options: personnel, vehicle
How many are needed.
Limits: min 1
Tags the assigned resource must have. E.g.: "Carné C".
Limits: max 20 items, each max length 100
Creation date in ISO 8601 UTC; null if not recorded.
Last modification date in ISO 8601 UTC; null if not recorded.
Additional information about the response.
Show child attributesHide child attributes
Lifecycle warnings; present only when the operation is deprecated.
Show child attributesHide child attributes
Stable warning code.
Available options: deprecated
For people: what is deprecated, until when, and what to use.
Day (YYYY-MM-DD) the operation stops being served.
operationId of the operation to use instead, or null if there is none.
Where the deprecation is documented (the changelog).
Invalid request (validation_error): malformed query or body. errors[] lists every offending field with its stable code.
Headers: X-Request-Id · Content-Language · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · Idempotent-Replay
Authentication failed (unauthorized, api_key_invalid, api_key_revoked, api_key_expired, api_key_owner_inactive, api_key_owner_not_admin).
Headers: X-Request-Id · Content-Language · Idempotent-Replay
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.
Headers: X-Request-Id · Content-Language · Idempotent-Replay
Resource not found (not_found): it does not exist or is outside the scope of the API key.
Headers: X-Request-Id · Content-Language · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · Idempotent-Replay
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]. says which: in_progress and lock_timeout are solved by retrying; invalid_state is not, because the state of the resource forbids the operation.
Headers: X-Request-Id · Content-Language · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · Idempotent-Replay
Precondition failed (precondition_failed): the If-Match entity tag does not match the current representation. Read the resource again and retry.
Headers: X-Request-Id · Content-Language · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · Idempotent-Replay
Idempotency-Key reused (idempotency_key_reused): the same key was used before with a different body. Change the key.
Headers: X-Request-Id · Content-Language · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · Idempotent-Replay
Rate limit exceeded (rate_limited): retry after Retry-After seconds; RateLimit-* says which quota ran out.
Headers: X-Request-Id · Content-Language · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · Retry-After · Idempotent-Replay
Internal error (internal_error).
Headers: X-Request-Id · Content-Language · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · Idempotent-Replay
Errors
| Status | Codes | Meaning |
|---|---|---|
| 400 | validation_error | Malformed query or body. errors[] lists every offending field with its stable code. |
| 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]. 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. |
401, 403, 429, 500 can be returned by any operation. Errors
Deprecation
This operation is not deprecated. Deprecations are announced with a Deprecation header and a sunset date. Versioning policy
Related pages
Link to this section: Related pagesOperations
Service
Sellable line that does not come from inventory: personnel, transport, work days.
Was this page helpful?