Update Semantics (Null Handling)

The Gesvision API follows RFC 7396 (JSON Merge Patch) semantics for update operations. Understanding how null and missing fields are handled is essential for building reliable integrations.

The rule

Field in request body	Effect
Present with a value	The field is updated to the new value
Present with null	The field is cleared (set to null / removed)
Absent (not sent)	The field is left unchanged

Example: updating an invoice

Suppose you have an invoice with this data:

{
  "id": 123,
  "version": 2,
  "externalRef": "PO-2026-100",
  "notes": "Urgent delivery",
  "employeeId": 5
}

Scenario 1: Change one field, keep the rest

Send only the field you want to change:

curl -X PUT https://app.gesvision.com/gesmo/rest/api/v1/invoices/123 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "If-Match: 2" \
  -d '{
    "externalRef": "PO-2026-200"
  }'

Result: externalRef becomes "PO-2026-200", but notes and employeeId remain unchanged.

Scenario 2: Clear a field

Send the field explicitly as null:

curl -X PUT https://app.gesvision.com/gesmo/rest/api/v1/invoices/123 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "If-Match: 2" \
  -d '{
    "notes": null
  }'

Result: notes is cleared (set to null). externalRef and employeeId remain unchanged.

Scenario 3: Update and clear in the same request

curl -X PUT https://app.gesvision.com/gesmo/rest/api/v1/invoices/123 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "If-Match: 2" \
  -d '{
    "externalRef": "PO-2026-300",
    "notes": null,
    "employeeId": 10
  }'

Result:

• externalRef → "PO-2026-300" (updated)
• notes → null (cleared)
• employeeId → 10 (updated)

Applying to the Customers endpoint

The PUT /api/v1/customers/{id} endpoint uses the same patch semantics. Only non-null fields are applied:

curl -X PUT https://app.gesvision.com/gesmo/rest/api/v1/customers/42 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new@example.com",
    "phone": null
  }'

Result: Email is updated, phone is cleared, all other fields remain unchanged.

Lines (array fields)

For array fields like lines and payments, the behavior is different:

Lines in request	Effect
Absent (not sent)	Lines are left unchanged
Empty array []	All lines are removed
Array with items	Lines are replaced entirely with the new list

To update a specific line, include its id:

{
  "lines": [
    { "id": 501, "quantity": 3 },
    { "productId": 2048, "quantity": 1, "unitPrice": 29.90, "vatTypeId": 1 }
  ]
}

• Line with id: 501 is updated (quantity changed to 3)
• Line without id is created as a new line

caution

When sending lines, you must include all lines you want to keep. Lines not included in the array will be deleted. This is a full replacement of the lines collection.

Summary

sent with value  →  field is UPDATED
sent as null     →  field is CLEARED
not sent at all  →  field is LEFT UNCHANGED

This approach lets you perform surgical updates — changing only the fields you care about without needing to send the entire resource body.