Update a customer

PATCHhttps://<your-url>/api/v2/customers/{customer}

MCP id customers.updateAlso on this path: GET Read a customer, DELETE Delete a customer

Partially updates a customer: absent keys are untouched and an empty body is a 422.

Token scope: api:write:customers
Without it: 403 insufficient-token-scope.
Permission: customers::update
Without it: 403 insufficient-permission.
Rate cost: 1 unit, write bucket. A write costs the same whatever view you ask for.
Also: Accepts If-Match. Never cached: private, no-store. Unknown body keys are refused, never dropped.

Both are checked, scope first. A token never does more than its user. How access is checked

Request

Example: Mark a customer inactive

curl -X PATCH \
  'https://<your-url>/api/v2/customers/1' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'If-Match: *' \
  -d '{
    "status": "inactive"
  }'

const response = await fetch('https://<your-url>/api/v2/customers/1', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'If-Match': '*',
  },
  body: JSON.stringify({
    "status": "inactive"
  }),
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->withHeader('If-Match', '*')
    ->patch('https://<your-url>/api/v2/customers/1', [
        'status' => 'inactive',
    ]);

import requests
response = requests.request(
    'PATCH',
    'https://<your-url>/api/v2/customers/1',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json', 'Content-Type': 'application/json', 'If-Match': '*'},
    json={'status': 'inactive'},
)

Response

The shape of the response, with sample values.

{
  "data": {
    "id": 1,
    "name": "Acme Industries",
    "code": "ACM",
    "color": "#1d4ed8",
    "status": "inactive",
    "email": "hello@acme.test",
    "phone": "…",
    "address": "Keizersgracht 1",
    "zip": "1015 CJ",
    "city": "Amsterdam",
    "country": "NL",
    "lat": "…"
  }
}

{
  "type": "https://developers.plnnrly.com/api/v2/problems/precondition-failed",
  "title": "Precondition failed",
  "status": 412,
  "detail": "The record changed since the version named in If-Match. Re-read it and retry.",
  "instance": "/api/v2/work-items/812",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S",
  "current_version": 12
}

{
  "type": "https://developers.plnnrly.com/api/v2/problems/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "3 fields failed validation.",
  "instance": "/api/v2/worklogs",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S",
  "errors": [
    {
      "pointer": "/date",
      "code": "date_format",
      "detail": "The date does not match the format Y-m-d."
    },
    {
      "pointer": "/minutes",
      "code": "min",
      "detail": "The minutes must be at least 1."
    },
    {
      "pointer": "/description",
      "code": "required",
      "detail": "The description field is required."
    }
  ]
}

24 more fields, listed under Response

tag_ids replaces the whole tag set, and an empty array clears it. Sending address, zip or city re-geocodes the address and overwrites lat and lng, neither of which is writable. debtor_code additionally requires billing_settings::update. Send If-Match with the ETag from your last read to detect a concurrent edit, which answers 412.

Path parameters

customerintegerRequired

The Customer's numeric id. Accepts a soft-deleted record.

Query parameters

Unknown parameters are refused with 400, naming the parameter.

viewstring

Which field set to render.

summarydetaildefault

trashedstring

Whether soft-deleted rows are included.

withoutdefaultwithonly

Request headers

X-Request-Idstringpattern

A correlation id of your own. It is recorded in our logs next to the server's request id but never returned: the response header always carries the server's id. A value that does not match the pattern is discarded silently, never rejected.

If-Matchstring

The ETag a write is conditional on. A stale validator is 412 precondition-failed.

Request body

Unknown keys are refused with 422, naming the key.

namestring≤ 255

Customer name. This is the default sort key and one of the fields ?q= searches.

codestring≤ 255Unique

Short customer code, e.g. ACM. Prefixes every work item's issue key, is enforced unique on write, and is one of the fields ?q= searches.

Must be unique across Customer.

colorstringpattern

Chip colour as a CSS hex triplet or sextet, e.g. #1d4ed8. A stored value that is not valid hex reads back as #6b7280.

statusstring

Where the customer sits in the sales lifecycle.

suspect: An unqualified lead; nobody has established a need yet.
prospect: A qualified lead being actively pursued towards a first deal.
future-opportunity: A real opportunity, parked until a later moment.
active: A paying customer with work or a subscription running.
inactive: A former customer, kept for history and no longer pursued.

New values may be added.

emailemail or null≤ 255

Primary email address. The third field ?q= searches; not unique.

phonestring or null≤ 255

Phone number.

addressstring or null≤ 255

Street address. Writing this, zip or city re-geocodes lat and lng.

zipstring or null≤ 255

Postal code.

citystring or null≤ 255

City.

countrystring or null≤ 255

Country as an ISO 3166-1 alpha-2 code, e.g. NL, as plnnrly writes it. Older records may hold any string.

Response 200

Returns a Customer in the detail view.

Headers

ETag: A strong validator of exactly this representation.
RateLimit: The IETF httpapi-ratelimit-headers form of your remaining allowance on the tightest bucket this request touched.
RateLimit-Policy: The ceiling and window of that bucket, as <limit>;w=<seconds>.
X-Request-Id: The server-generated ULID correlating this response with our logs.

Every response also carries Cache-Control, Vary, X-Content-Type-Options, X-Plnnrly-Api-Version, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Headers and versioning

idinteger

Unique identifier.

namestring≤ 255

Customer name. This is the default sort key and one of the fields ?q= searches.

codestring≤ 255

Short customer code, e.g. ACM. Prefixes every work item's issue key, is enforced unique on write, and is one of the fields ?q= searches.

colorstring≤ 255

Chip colour as a CSS hex triplet or sextet, e.g. #1d4ed8. A stored value that is not valid hex reads back as #6b7280.

statusstring

Where the customer sits in the sales lifecycle.

suspectprospectfuture-opportunityactiveinactive

New values may be added.

emailstring or null≤ 255

Primary email address. The third field ?q= searches; not unique.

phonestring or null≤ 255

Phone number.

addressstring or null≤ 255

Street address. Writing this, zip or city re-geocodes lat and lng.

zipstring or null≤ 255

Postal code.

citystring or null≤ 255

City.

countrystring or null≤ 255

Country as an ISO 3166-1 alpha-2 code, e.g. NL, as plnnrly writes it. Older records may hold any string.

latstring or null≤ 255Server-assigned

Latitude, geocoded from the address whenever address, zip or city changes. Not writable.

lngstring or null≤ 255Server-assigned

Longitude, geocoded from the address whenever address, zip or city changes. Not writable.

founded_atdate (YYYY-MM-DD) or null

Day the customer's company was founded.

customer_sincedate (YYYY-MM-DD) or null

Day this customer became a customer.

is_vat_exemptboolean

Whether invoices to this customer are issued without VAT.

payment_daysinteger or nullServer-assigned

Payment term in days, as held by the accounting integration. Read by the invoice composer; written only by the Exact sync.

debtor_codestring or null≤ 255

Debtor number in the accounting system. Writing it requires billing_settings::update.

exact_account_idstring or null≤ 255Server-assigned

Account identifier in Exact Online, written by the sync.

exact_synced_attimestamp (YYYY-MM-DDThh:mm:ssZ) or nullServer-assigned

When the Exact sync last handled this customer, or null if never.

exact_keep_local_addressbooleanServer-assigned

Whether the Exact sync leaves this customer's local address alone although it differs from the one in Exact. Set when a user accepts the difference on the Exact customers screen in plnnrly; not writable.

account_manager_idinteger or null

Responsible account manager. Required on create; unassigned when the user is deleted.

customer_category_idinteger or null

Customer category, or null.

company_type_idinteger or null

Company type, or null. Company types are your organisation's own list, maintained in plnnrly and not exposed as a collection.

company_size_idinteger or null

Company size band, or null. Company sizes are your organisation's own list, maintained in plnnrly and not exposed as a collection.

company_branch_idinteger or null

Industry branch, or null.

created_attimestamp (YYYY-MM-DDThh:mm:ssZ)

Creation timestamp.

updated_attimestamp (YYYY-MM-DDThh:mm:ssZ)

Last-write timestamp; use for incremental sync.

deleted_attimestamp (YYYY-MM-DDThh:mm:ssZ) or null

Soft-delete timestamp, null while live.

customer_categoryRef or CustomerCategorySummary or null

The customer's category. Rendered as {"id": N} until named in ?include=customer_category, and null where none is assigned.

company_branchRef or CompanyBranchSummary or null

The customer's industry branch. Rendered as {"id": N} until named in ?include=company_branch, and null where none is assigned.

projects_countinteger≥ 0

Number of live projects for this customer. Soft-deleted projects are not counted.

contacts_countinteger≥ 0

Number of contacts on this customer.

tags_countinteger≥ 0

Number of tags on this customer.

linksCustomerLinks

Show 3 child fields

links.selfurl

The canonical URI of this record.

links.projectsurl

Projects for this customer.

links.contactsurl

Contacts on this customer.

tagsarray of TagSummary≤ 50Only with include

Tags on this customer. A customer takes at most 50 tags, so the include lists them all. tag_ids replaces the whole set.

Wrapped in { data, meta }; meta.truncated says whether the cap was hit and meta.count is the full count.

Show 2 child fields

tags.idinteger

Unique identifier.

tags.titlestring≤ 255

Tag title as shown in the UI.

Errors

403 Forbidden.

forbidden-by-policy insufficient-permission insufficient-token-scope

412 Precondition failed.

precondition-failed

415 Unsupported media type.

unsupported-media-type

422 Unprocessable content.

unprocessable-relationship validation-failed

7 errors every operation can return: 400, 401, 404, 406, 429, 500, 503

400 Bad request.

idempotency-key-required invalid-cursor invalid-query-parameter malformed-request unsupported-parameter

401 Unauthenticated.

token-expired unauthenticated

404 Not found.

endpoint-not-found resource-not-found

406 Not acceptable.

not-acceptable

429 Too many requests.

rate-limit-exceeded

500 Server error.

internal-error

503 Service unavailable.

tenant-unavailable

This path allows GET, PATCH, DELETE. Anything else answers 405.

Something wrong or missing on this page? Tell us

Access

Path parameters

Query parameters

Request headers

Request body

Response 200

Headers

Errors