Start here when company or user access work could belong to Management Organizations, Auth Organisations, Merchant Users, Auth Users, attributes, customer groups, or events.

The short model

Choose from the caller model first:

• Organizations are the trusted back-office company records. Use them for server-side administration of organization records, trees, tags, address restrictions, and merchant access.
• Organisations are the Auth API account-context records. Use them when a signed-in account flow reads or changes organisation context.
• Merchant Users are merchant-facing operator accounts managed by trusted Management API routes.
• Users are Auth API account identities. Current-user routes use token context; lookup and user-id routes resolve a user within one app.

Keep adjacent jobs separate. Attributes attach reusable values to a user or organisation. Customer Groups affect buyer pricing and access groups. Events tell another system that organisation or user account data changed.

Choose the right surface

The spelling difference maps to the caller model. Use Organizations for trusted company administration. Use Organisations when a signed-in account flow owns the company context.

Open Organizations reference for trusted company administration: listing, creation, updates, deletion, trees, tags, address restrictions, and user access. Open Organisations reference when the signed-in account context owns registration, reads, patching, deletion, trees, users, or organisation attribute relationships.

Choose Merchant Users reference when the merchant-facing operator account changes. Choose Users reference when an Auth caller reads, updates, deletes, looks up, or attaches attributes to an account identity. For buyer-specific pricing or access groups, go to Customer groups and pricing; customer groups are not organization membership.

For exact methods, paths, request bodies, response fields, enum values, and status codes, use Organizations reference, Organisations reference, Merchant Users reference, and Users reference.

Contract facts to keep in mind

Use these facts to choose the right reference. Use operation pages for exact fields, filters, auth, status codes, and response shapes.

• Organizations handle trusted company records, trees, tags, address restrictions, and merchant-user access.
• Organisations handle account-context lookup, registration, reads, patching, deletion, trees, users, and organisation attribute relationships.
• Merchant Users handle merchant-facing operator accounts. Users handle current-user reads and updates, lookup, user-id reads and updates, current-user deletion, and user attribute relationships.
• Management organization records include the company identity, optional organisation number, parent organisation, status, contact fields, addresses, tags, customer groups, attributes, and attached merchant users.
• Management list supports pagination up to 100 items per page, search, has-merchant-users, status filters, address-country filters, credit-check filtering, and template_key/attribute_key attribute filters.
• When addresses is present, the payload becomes the desired address set. Parent updates reject self-parenting and circular parent relationships.
• Address restrictions require the organization, address, and merchant user to exist; the merchant user must already belong to that organization.
• Creating a new organisation attaches that user as an admin. When a non-empty organisation_number collides, the current behavior attaches the user to that existing organisation with the default level instead of creating a duplicate company account.
• For a normal user, visibility includes directly related organisations and descendant organisations beneath them. Tree reads return the requested organisation's descendant tree plus ordered ancestors.
• A non-super-admin caller must belong to the organisation with admin level before patching, deleting, adding a user, or removing a user. Deleting an organisation is blocked while it has child organisations.
• Before patching, user update normalizes and validates locale/language values.

Keep adjacent jobs separate

Use Attributes when an existing reusable attribute is attached to or removed from a user or organisation. Choose Customer Groups when buyer-specific pricing or access should apply to a user or organisation.

Use Management Organizations when a server-side integration owns the company record. Pick Auth Organisations or Users when the caller is an authenticated account context. Do not expose Management API keys to browser-only account flows.

Events

Use Events after organisation or user account data changes. The Event catalog covers organisation create, update, delete, user membership, address restriction, status, and user-account events.

Use the Event catalog for exact event type strings, schema IDs, required fields, and payload fields. Use Events latest for delivery and retry behavior.

Where to go next

• Need trusted organization administration? Use Organizations reference.
• Need account-context organisation routes? Use Organisations reference.
• Need merchant-facing user administration? Use Merchant Users reference.
• Need Auth user identity routes? Use Users reference.
• Need account-aware pricing? Read Customer groups and pricing.