Organizations

Overview

Available Operations

list - Get a list of organizations for an instance
create - Create an organization
get - Retrieve an organization by ID or slug
update - Update an organization
delete - Delete an organization
mergeMetadata - Merge and update metadata for an organization
replaceMetadata - Replace metadata for an organization
uploadLogo - Upload a logo for the organization
deleteLogo - Delete the organization's logo.
getBillingSubscription - Retrieve an organization's billing subscription
getBillingCreditBalance - Retrieve an organization's credit balance
adjustBillingCreditBalance - Adjust an organization's credit balance

list

This request returns the list of organizations for an instance. Results can be paginated using the optional limit and offset query parameters. The organizations are ordered by descending creation date. Most recent organizations will be returned first.

Example Usage

package hello.world;

import com.clerk.backend_api.Clerk;
import com.clerk.backend_api.models.errors.ClerkErrors;
import com.clerk.backend_api.models.operations.ListOrganizationsRequest;
import com.clerk.backend_api.models.operations.ListOrganizationsResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ClerkErrors, Exception {

        Clerk sdk = Clerk.builder()
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        ListOrganizationsRequest req = ListOrganizationsRequest.builder()
                .build();

        ListOrganizationsResponse res = sdk.organizations().list()
                .request(req)
                .call();

        if (res.organizations().isPresent()) {
            System.out.println(res.organizations().get());
        }
    }
}

Parameters

Parameter	Type	Required	Description
`request`	ListOrganizationsRequest	✔️	The request object to use for the request.

Response

ListOrganizationsResponse

Errors

Error Type	Status Code	Content Type
models/errors/ClerkErrors	400, 403, 422	application/json
models/errors/SDKError	4XX, 5XX	/

create

Creates a new organization with the given name for an instance. You can specify an optional slug for the new organization. If provided, the organization slug can contain only lowercase alphanumeric characters (letters and digits) and the dash "-". Organization slugs must be unique for the instance. You can provide additional metadata for the organization and set any custom attribute you want. Organizations support private and public metadata. Private metadata can only be accessed from the Backend API. Public metadata can be accessed from the Backend API, and are read-only from the Frontend API. The created_by user will see this as their active organization the next time they create a session, presuming they don't explicitly set a different organization as active before then.

Example Usage

package hello.world;

import com.clerk.backend_api.Clerk;
import com.clerk.backend_api.models.errors.ClerkErrors;
import com.clerk.backend_api.models.operations.CreateOrganizationResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ClerkErrors, Exception {

        Clerk sdk = Clerk.builder()
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        CreateOrganizationResponse res = sdk.organizations().create()
                .call();

        if (res.organization().isPresent()) {
            System.out.println(res.organization().get());
        }
    }
}

Parameters

Parameter	Type	Required	Description
`request`	CreateOrganizationRequestBody	✔️	The request object to use for the request.

Response

CreateOrganizationResponse

Errors

Error Type	Status Code	Content Type
models/errors/ClerkErrors	400, 402, 403, 422	application/json
models/errors/SDKError	4XX, 5XX	/

get

Fetches the organization whose ID or slug matches the provided id_or_slug URL query parameter.

Example Usage

package hello.world;

import com.clerk.backend_api.Clerk;
import com.clerk.backend_api.models.errors.ClerkErrors;
import com.clerk.backend_api.models.operations.GetOrganizationResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ClerkErrors, Exception {

        Clerk sdk = Clerk.builder()
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        GetOrganizationResponse res = sdk.organizations().get()
                .organizationId("<id>")
                .call();

        if (res.organization().isPresent()) {
            System.out.println(res.organization().get());
        }
    }
}

Parameters

Parameter	Type	Required	Description
`organizationId`	String	✔️	The ID or slug of the organization
`includeMembersCount`	Optional<Boolean>	➖	Flag to denote whether or not the organization's members count should be included in the response.
`includeMissingMemberWithElevatedPermissions`	Optional<Boolean>	➖	Flag to denote whether or not to include a member with elevated permissions who is not currently a member of the organization.

Response

GetOrganizationResponse

Errors

Error Type	Status Code	Content Type
models/errors/ClerkErrors	403, 404	application/json
models/errors/SDKError	4XX, 5XX	/

update

Updates an existing organization.

As of API version 2026-05-12, this endpoint no longer accepts public_metadata or private_metadata. Use PATCH /v1/organizations/{organization_id}/metadata to merge updates into existing metadata, or PUT /v1/organizations/{organization_id}/metadata to replace a metadata field entirely.

Example Usage

package hello.world;

import com.clerk.backend_api.Clerk;
import com.clerk.backend_api.models.errors.ClerkErrors;
import com.clerk.backend_api.models.operations.UpdateOrganizationRequestBody;
import com.clerk.backend_api.models.operations.UpdateOrganizationResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ClerkErrors, Exception {

        Clerk sdk = Clerk.builder()
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        UpdateOrganizationResponse res = sdk.organizations().update()
                .organizationId("<id>")
                .requestBody(UpdateOrganizationRequestBody.builder()
                    .build())
                .call();

        if (res.organization().isPresent()) {
            System.out.println(res.organization().get());
        }
    }
}

Parameters

Parameter	Type	Required	Description
`organizationId`	String	✔️	The ID of the organization to update
`requestBody`	UpdateOrganizationRequestBody	✔️	N/A

Response

UpdateOrganizationResponse

Errors

Error Type	Status Code	Content Type
models/errors/ClerkErrors	400, 402, 403, 404, 422	application/json
models/errors/SDKError	4XX, 5XX	/

delete

Deletes the given organization. Please note that deleting an organization will also delete all memberships and invitations. This is not reversible.

After the organization is deleted, any user's active sessions that contain the deleted organization will be cleared.

Example Usage

package hello.world;

import com.clerk.backend_api.Clerk;
import com.clerk.backend_api.models.errors.ClerkErrors;
import com.clerk.backend_api.models.operations.DeleteOrganizationResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ClerkErrors, Exception {

        Clerk sdk = Clerk.builder()
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        DeleteOrganizationResponse res = sdk.organizations().delete()
                .organizationId("<id>")
                .call();

        if (res.deletedObject().isPresent()) {
            System.out.println(res.deletedObject().get());
        }
    }
}

Parameters

Parameter	Type	Required	Description
`organizationId`	String	✔️	The ID of the organization to delete

Response

DeleteOrganizationResponse

Errors

Error Type	Status Code	Content Type
models/errors/ClerkErrors	404	application/json
models/errors/SDKError	4XX, 5XX	/

mergeMetadata

Update organization metadata attributes by merging existing values with the provided parameters. Metadata values will be updated via a deep merge. Deep meaning that any nested JSON objects will be merged as well. You can remove metadata keys at any level by setting their value to null.

Example Usage

package hello.world;

import com.clerk.backend_api.Clerk;
import com.clerk.backend_api.models.errors.ClerkErrors;
import com.clerk.backend_api.models.operations.MergeOrganizationMetadataRequestBody;
import com.clerk.backend_api.models.operations.MergeOrganizationMetadataResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ClerkErrors, Exception {

        Clerk sdk = Clerk.builder()
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        MergeOrganizationMetadataResponse res = sdk.organizations().mergeMetadata()
                .organizationId("<id>")
                .requestBody(MergeOrganizationMetadataRequestBody.builder()
                    .build())
                .call();

        if (res.organization().isPresent()) {
            System.out.println(res.organization().get());
        }
    }
}

Parameters

Parameter	Type	Required	Description
`organizationId`	String	✔️	The ID of the organization for which metadata will be merged or updated
`requestBody`	MergeOrganizationMetadataRequestBody	✔️	N/A

Response

MergeOrganizationMetadataResponse

Errors

Error Type	Status Code	Content Type
models/errors/ClerkErrors	400, 401, 404, 422	application/json
models/errors/SDKError	4XX, 5XX	/

replaceMetadata

Replace an organization's metadata attributes with the provided values. Unlike PATCH /v1/organizations/{organization_id}/metadata (merge semantics), this endpoint replaces the supplied metadata fields entirely — the prior contents of each supplied field are discarded. Fields omitted from the request body are left unchanged. Prefer the PATCH endpoint for partial updates. Use PUT only when you explicitly intend to overwrite a metadata field wholesale.

Example Usage

package hello.world;

import com.clerk.backend_api.Clerk;
import com.clerk.backend_api.models.errors.ClerkErrors;
import com.clerk.backend_api.models.operations.ReplaceOrganizationMetadataRequestBody;
import com.clerk.backend_api.models.operations.ReplaceOrganizationMetadataResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ClerkErrors, Exception {

        Clerk sdk = Clerk.builder()
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        ReplaceOrganizationMetadataResponse res = sdk.organizations().replaceMetadata()
                .organizationId("<id>")
                .requestBody(ReplaceOrganizationMetadataRequestBody.builder()
                    .build())
                .call();

        if (res.organization().isPresent()) {
            System.out.println(res.organization().get());
        }
    }
}

Parameters

Parameter	Type	Required	Description
`organizationId`	String	✔️	The ID of the organization whose metadata will be replaced
`requestBody`	ReplaceOrganizationMetadataRequestBody	✔️	N/A

Response

ReplaceOrganizationMetadataResponse

Errors

Error Type	Status Code	Content Type
models/errors/ClerkErrors	400, 401, 404, 422	application/json
models/errors/SDKError	4XX, 5XX	/

uploadLogo

Set or replace an organization's logo, by uploading an image file. This endpoint uses the multipart/form-data request content type and accepts a file of image type. The file size cannot exceed 10MB. Only the following file content types are supported: image/jpeg, image/png, image/gif, image/webp.

Example Usage

package hello.world;

import com.clerk.backend_api.Clerk;
import com.clerk.backend_api.models.errors.ClerkErrors;
import com.clerk.backend_api.models.operations.UploadOrganizationLogoResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ClerkErrors, Exception {

        Clerk sdk = Clerk.builder()
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        UploadOrganizationLogoResponse res = sdk.organizations().uploadLogo()
                .organizationId("<id>")
                .call();

    }
}

Parameters

Parameter	Type	Required	Description
`organizationId`	String	✔️	The ID of the organization for which to upload a logo
`requestBody`	Optional<UploadOrganizationLogoRequestBody>	➖	N/A

Response

UploadOrganizationLogoResponse

Errors

Error Type	Status Code	Content Type
models/errors/ClerkErrors	400, 403, 404, 413	application/json
models/errors/SDKError	4XX, 5XX	/

deleteLogo

Delete the organization's logo.

Example Usage

package hello.world;

import com.clerk.backend_api.Clerk;
import com.clerk.backend_api.models.errors.ClerkErrors;
import com.clerk.backend_api.models.operations.DeleteOrganizationLogoResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ClerkErrors, Exception {

        Clerk sdk = Clerk.builder()
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        DeleteOrganizationLogoResponse res = sdk.organizations().deleteLogo()
                .organizationId("<id>")
                .call();

        if (res.organization().isPresent()) {
            System.out.println(res.organization().get());
        }
    }
}

Parameters

Parameter	Type	Required	Description
`organizationId`	String	✔️	The ID of the organization for which the logo will be deleted.

Response

DeleteOrganizationLogoResponse

Errors

Error Type	Status Code	Content Type
models/errors/ClerkErrors	404	application/json
models/errors/SDKError	4XX, 5XX	/

getBillingSubscription

Retrieves the billing subscription for the specified organization. This includes subscription details, active plans, billing information, and payment status. The subscription contains subscription items which represent the individual plans the organization is subscribed to.

Example Usage

package hello.world;

import com.clerk.backend_api.Clerk;
import com.clerk.backend_api.models.errors.ClerkErrors;
import com.clerk.backend_api.models.operations.GetOrganizationBillingSubscriptionResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ClerkErrors, Exception {

        Clerk sdk = Clerk.builder()
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        GetOrganizationBillingSubscriptionResponse res = sdk.organizations().getBillingSubscription()
                .organizationId("<id>")
                .call();

        if (res.commerceSubscription().isPresent()) {
            System.out.println(res.commerceSubscription().get());
        }
    }
}

Parameters

Parameter	Type	Required	Description
`organizationId`	String	✔️	The ID of the organization whose subscription to retrieve

Response

GetOrganizationBillingSubscriptionResponse

Errors

Error Type	Status Code	Content Type
models/errors/ClerkErrors	400, 401, 403, 404, 422	application/json
models/errors/ClerkErrors	500	application/json
models/errors/SDKError	4XX, 5XX	/

getBillingCreditBalance

Retrieves the current credit balance for the specified organization. Credits can be applied during checkout to reduce the charge or automatically applied to upcoming recurring charges.

Example Usage

package hello.world;

import com.clerk.backend_api.Clerk;
import com.clerk.backend_api.models.errors.ClerkErrors;
import com.clerk.backend_api.models.operations.GetOrganizationBillingCreditBalanceResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ClerkErrors, Exception {

        Clerk sdk = Clerk.builder()
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        GetOrganizationBillingCreditBalanceResponse res = sdk.organizations().getBillingCreditBalance()
                .organizationId("<id>")
                .call();

        if (res.commerceCreditBalanceResponse().isPresent()) {
            System.out.println(res.commerceCreditBalanceResponse().get());
        }
    }
}

Parameters

Parameter	Type	Required	Description
`organizationId`	String	✔️	The ID of the organization whose credit balance to retrieve

Response

GetOrganizationBillingCreditBalanceResponse

Errors

Error Type	Status Code	Content Type
models/errors/ClerkErrors	400, 401, 403, 404, 422	application/json
models/errors/ClerkErrors	500	application/json
models/errors/SDKError	4XX, 5XX	/

adjustBillingCreditBalance

Increases or decreases the credit balance for the specified organization. Each adjustment is recorded as a ledger entry. The idempotency_key parameter ensures that duplicate requests are safely handled.

Example Usage

package hello.world;

import com.clerk.backend_api.Clerk;
import com.clerk.backend_api.models.components.Action;
import com.clerk.backend_api.models.components.AdjustCreditBalanceRequest;
import com.clerk.backend_api.models.errors.ClerkErrors;
import com.clerk.backend_api.models.operations.AdjustOrganizationBillingCreditBalanceResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws ClerkErrors, Exception {

        Clerk sdk = Clerk.builder()
                .bearerAuth(System.getenv().getOrDefault("BEARER_AUTH", ""))
            .build();

        AdjustOrganizationBillingCreditBalanceResponse res = sdk.organizations().adjustBillingCreditBalance()
                .organizationId("<id>")
                .adjustCreditBalanceRequest(AdjustCreditBalanceRequest.builder()
                    .amount(245081L)
                    .action(Action.INCREASE)
                    .idempotencyKey("<value>")
                    .build())
                .call();

        if (res.commerceCreditLedgerResponse().isPresent()) {
            System.out.println(res.commerceCreditLedgerResponse().get());
        }
    }
}

Parameters

Parameter	Type	Required	Description
`organizationId`	String	✔️	The ID of the organization whose credit balance to adjust
`adjustCreditBalanceRequest`	AdjustCreditBalanceRequest	✔️	Parameters for the credit balance adjustment

Response

AdjustOrganizationBillingCreditBalanceResponse

Errors

Error Type	Status Code	Content Type
models/errors/ClerkErrors	400, 401, 403, 404, 409, 422	application/json
models/errors/ClerkErrors	500	application/json
models/errors/SDKError	4XX, 5XX	/

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Organizations

Overview

Available Operations

list

Example Usage

Parameters

Response

Errors

create

Example Usage

Parameters

Response

Errors

get

Example Usage

Parameters

Response

Errors

update

Example Usage

Parameters

Response

Errors

delete

Example Usage

Parameters

Response

Errors

mergeMetadata

Example Usage

Parameters

Response

Errors

replaceMetadata

Example Usage

Parameters

Response

Errors

uploadLogo

Example Usage

Parameters

Response

Errors

deleteLogo

Example Usage

Parameters

Response

Errors

getBillingSubscription

Example Usage

Parameters

Response

Errors

getBillingCreditBalance

Example Usage

Parameters

Response

Errors

adjustBillingCreditBalance

Example Usage

Parameters

Response

Errors