Services

Update a service

Updates a service (send only the fields to change).

PATCH
/api/v1/services/{serviceId}

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
    }
  }
}'
{
  "data": {
    "id": "service_9f3a2b",
    "name": "Example service",
    "serviceType": "Example service type",
    "description": "Example text.",
    "defaultQty": 1,
    "showInPlanner": true,
    "includeInPrice": true,
    "collectionName": "Example collection name",
    "tags": [
      {
        "id": "tag_9f3a2b",
        "name": "Example tag"
      }
    ],
    "requirements": [
      {
        "requiredResourceType": "personnel",
        "qty": 1,
        "requiredTags": [
          "Example required tags"
        ]
      }
    ],
    "createdAt": "2026-09-01T08:00:00.000Z",
    "updatedAt": "2026-09-01T08:00:00.000Z"
  }
}

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

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

serviceIdstringRequired

Service identifier.

Limits: min length 1

Body

application/json

Body schema: ServiceUpdateBody

namestring

Customer-facing service name.

Limits: min length 2

descriptionstring | null

Service description; null clears it.

serviceTypestring

Service type.

Available options: crew, fleet, general

showInPlannerboolean

Whether it appears as a plannable service.

defaultQtyinteger

Default quantity.

Limits: min 1

breakMinutesinteger

Break deducted from the work day, in minutes.

Limits: min 0

orderInfostring

Information printed on the order and on the delivery note.

priceConfigobject

Service rate.

Show child attributes
priceConfig.hourlyRatenumber

Price per hour.

Limits: min 0

priceConfig.fixedPricenumber

Fixed price per service.

Limits: min 0

priceConfig.perKmRatenumber

Price per kilometre.

Limits: min 0

includeInPriceboolean

Whether its amount counts towards the document total.

distancePolicystring

How the billable distance is calculated.

travelTimeBeforeinteger

Travel time before, in minutes.

Limits: min 0

travelTimeAfterinteger

Travel time after, in minutes.

Limits: min 0

usagePeriodPolicyobject

Window in which it is used.

Show child attributes
usagePeriodPolicy.inheritstringRequired

"order" inherits the dates of the order; "custom" uses the offsets below.

Available options: order, custom

usagePeriodPolicy.offsetBeforeMinutesinteger

Minutes before the order start.

Limits: min 0

usagePeriodPolicy.offsetAfterMinutesinteger

Minutes after the order end.

Limits: min 0

planningPeriodPolicyobject

Window in which it is planned.

Show child attributes
planningPeriodPolicy.inheritstringRequired

"order" inherits the dates of the order; "custom" uses the offsets below.

Available options: order, custom

planningPeriodPolicy.offsetBeforeMinutesinteger

Minutes before the order start.

Limits: min 0

planningPeriodPolicy.offsetAfterMinutesinteger

Minutes after the order end.

Limits: min 0

defaultExpensesobject

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 attributes
defaultExpenses.cateringobject

Meal allowances.

Show child attributes
defaultExpenses.catering.pricenumberRequired

What the customer is charged for this concept.

defaultExpenses.travelobject

Travel.

Show child attributes
defaultExpenses.travel.pricenumberRequired

What the customer is charged for this concept.

defaultExpenses.accommodationobject

Accommodation.

Show child attributes
defaultExpenses.accommodation.pricenumberRequired

What the customer is charged for this concept.

defaultExpenses.otherobject

Other expenses.

Show child attributes
defaultExpenses.other.pricenumberRequired

What the customer is charged for this concept.

requirementsobject[]

Required resources. Replaces the whole list.

Show child attributes
requirements.requiredResourceTypestringRequired

What is needed to provide it: personnel or vehicle.

Available options: personnel, vehicle

requirements.qtyintegerRequired

How many are needed.

Limits: min 1

requirements.requiredTagsstring[]

Tags the assigned resource must have. E.g.: "Carné C".

Limits: max 20 items, each max length 100

collectionIdstring

Collection it belongs to.

tagsstring[]

Tags. Replaces the whole list.

imagesstring[]

Service image URLs.

Response

application/json

Successful response.

Response schema: ServiceDto

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

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

dataobject

Sellable line that does not come from inventory: personnel, transport, work days.

Show child attributes
data.idstring

Unique service identifier.

data.namestring

Service name as the customer sees it.

data.serviceTypestring

Type: crew (personnel), fleet (vehicles) or general.

data.descriptionstring | null

Description; null if it has none.

data.defaultQtyinteger

Quantity added to an order by default.

data.showInPlannerboolean

Whether it appears as a plannable service.

data.includeInPriceboolean

Whether its amount counts towards the document total.

data.collectionNamestring | null

Path of the collection it belongs to; null if it is in none.

data.tagsobject[]

Service tags, with their identifier and name.

Show child attributes
data.tags.idstring

Unique identifier of the tag.

data.tags.namestring

Tag name.

data.requirementsobject[]

Resources needed to provide it.

Show child attributes
data.requirements.requiredResourceTypestring

What is needed to provide it: personnel or vehicle.

Available options: personnel, vehicle

data.requirements.qtyinteger

How many are needed.

Limits: min 1

data.requirements.requiredTagsstring[]

Tags the assigned resource must have. E.g.: "Carné C".

Limits: max 20 items, each max length 100

data.createdAtstring<date-time> | null

Creation date in ISO 8601 UTC; null if not recorded.

data.updatedAtstring<date-time> | null

Last modification date in ISO 8601 UTC; null if not recorded.

metaobject

Additional information about the response.

Show child attributes
meta.warningsobject[]

Lifecycle warnings; present only when the operation is deprecated.

Show child attributes
meta.warnings.codestring

Stable warning code.

Available options: deprecated

meta.warnings.messagestring

For people: what is deprecated, until when, and what to use.

meta.warnings.sunsetstring

Day (YYYY-MM-DD) the operation stops being served.

meta.warnings.replacementstring | null

operationId of the operation to use instead, or null if there is none.

Errors

StatusCodesMeaning
400validation_errorMalformed query or body. errors[] lists every offending field with its stable code.
404not_foundIt does not exist or is outside the scope of the API key.
409conflictThe 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.
412precondition_failedThe If-Match entity tag does not match the current representation. Read the resource again and retry.
422idempotency_key_reusedThe 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

  • Operations

    Service

    Sellable line that does not come from inventory: personnel, transport, work days.