Skip to content
Puurk Developers

Update an organization user

PATCH
/organizations/{oid}/user/{uid}
curl --request PATCH \
  --url https://apisandbox.puurk.com/organizations/example/user/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "status": "active", "start_date": "2026-04-15T12:00:00Z", "termination_date": "2026-04-15T12:00:00Z", "commission_basis": "profit", "commission_fixed": 1, "commission_rate": 1, "commission_trigger": "sale", "role": "owner" }'

Update a user’s role or membership in an organization. Supplying role makes this a role modification. Setting a role requires one of: an organization role of owner or agencyadmin in this organization; a superadmin claim; or a service token holding the admin scope action on organizations (globally or for this organization). admin is a scope action, not an organization role, and is rejected as a role value with 400. A role modification fails with 403 for a self-update or 409 when it would remove the last owner.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
oid
required
string

Organization ID

uid
required
string

User ID

Request Bodyrequired

Section titled “Request Bodyrequired”

Fields to update. Every field is optional; send only what you are changing. Supplying role makes this a role modification.

Media typeapplication/json

Body for POST /organizations/{oid}/user/{uid} and PATCH /organizations/{oid}/user/{uid}. Every field is optional. On POST, role defaults to read; on PATCH, omitting role leaves it unchanged.

object
status

Membership status.

string
nullable
Allowed values: active terminated
start_date

When the person started with this organization. ISO 8601, or null to clear.

string format: date-time
nullable
termination_date

When the person left. ISO 8601, or null to clear.

string format: date-time
nullable
commission_basis
string
nullable
Allowed values: profit retail
commission_fixed

Fixed commission amount in cents

integer
nullable
commission_rate

Commission rate

number
nullable
commission_trigger
string
nullable
Allowed values: sale service
role

The role to grant. Setting a role requires one of: an organization role of owner or agencyadmin in this organization; a superadmin claim; or a service token holding the admin scope action on organizations (globally or for this organization). admin is a scope action, not an organization role, and is rejected as a role value with 400.

string
Allowed values: owner manager read write provider accountant officeadmin agencyadmin agencyuser none

Responses

Section titled “Responses”

200

Section titled “200”

User updated. The body is the updated organization user record. role is not included: read it from the organization’s roles map (GET /organizations/{oid}).

Media typeapplication/json
object
id

Organization user document ID

string
uid

User ID

string
nullable
oid

Organization ID

string
nullable
status
string
nullable
Allowed values: active terminated
start_date
string format: date-time
nullable
termination_date
string format: date-time
nullable
commission_basis
string
nullable
Allowed values: profit retail
commission_fixed

Fixed commission amount in cents

integer
nullable
commission_rate

Commission rate

number
nullable
commission_trigger
string
nullable
Allowed values: sale service
puurk_trained_at
string format: date-time
nullable
Example
{
  "status": "active",
  "commission_basis": "profit",
  "commission_trigger": "sale"
}

400

Section titled “400”

bad_request — invalid body or date field, or role is not an OrganizationRole (Invalid role. Must be one of: owner, manager, read, write, provider, accountant, officeadmin, agencyadmin, agencyuser, none). admin is rejected here: it is a scope action, not a role.

Media typeapplication/json

The standard error body. error is a stable, machine-readable code — branch on it rather than on message, which is for humans and may change.

object
error

Machine-readable error code.

string
message

Human-readable detail.

string
Example
{
  "error": "merchant_account_missing",
  "message": "The organization has no merchant account. Complete Stripe Connect onboarding for this organization before generating pricing."
}

401

Section titled “401”

Unauthorized

403

Section titled “403”

forbidden — the caller may not change this user’s role. Either the caller is the target user, or the caller holds none of: an organization role of owner or agencyadmin, a superadmin claim, or a service token with the admin scope action on organizations.

Media typeapplication/json

The standard error body. error is a stable, machine-readable code — branch on it rather than on message, which is for humans and may change.

object
error

Machine-readable error code.

string
message

Human-readable detail.

string
Example
{
  "error": "merchant_account_missing",
  "message": "The organization has no merchant account. Complete Stripe Connect onboarding for this organization before generating pricing."
}

404

Section titled “404”

not_found — the organization or user does not exist.

Media typeapplication/json

The standard error body. error is a stable, machine-readable code — branch on it rather than on message, which is for humans and may change.

object
error

Machine-readable error code.

string
message

Human-readable detail.

string
Example
{
  "error": "merchant_account_missing",
  "message": "The organization has no merchant account. Complete Stripe Connect onboarding for this organization before generating pricing."
}

409

Section titled “409”

conflict — this would remove the organization’s last owner.

Media typeapplication/json

The standard error body. error is a stable, machine-readable code — branch on it rather than on message, which is for humans and may change.

object
error

Machine-readable error code.

string
message

Human-readable detail.

string
Example
{
  "error": "merchant_account_missing",
  "message": "The organization has no merchant account. Complete Stripe Connect onboarding for this organization before generating pricing."
}