# Organizations

An organization is an independent group that comprises members with assigned [roles](https://docs.commercelayer.io/provisioning/api-reference/roles) and [permissions](https://docs.commercelayer.io/provisioning/api-reference/permissions). A [user](https://docs.commercelayer.io/provisioning/api-reference/user) can manage many companies or clients within a single account using different organizations. With the appropriate permission, members of an organization can create new [merchants](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/merchants), [markets](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/markets), and all the Core API resources they need to manage different business models without any data duplication.

All you need to [create a new organization](https://docs.commercelayer.io/provisioning/api-reference/organizations/create) is to give it a name. The newly created organization is automatically associated with your user's [membership](https://docs.commercelayer.io/provisioning/api-reference/memberships) (created with the `owner` attribute set to `true`), with *Admin* role. The *Admin* role is also used to create two [API credentials](https://docs.commercelayer.io/provisioning/api_credentials#resources-api-credentials) of type `resources` used to manage the organization's [resources](https://app.gitbook.com/o/-Lfu_B3DKew-kvoEWzTk/s/RWJeylueWkzLadK710XZ/) in the two available Core API [environments](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/api-specification#environments) (test/live mode). In addition to the *Admin* role, a *Read-only* role is also created. You can use it to invite other members to the organization with restricted permissions.

[Fetching an organization](https://docs.commercelayer.io/provisioning/api-reference/organizations/retrieve) lets you check some useful information such as the maximum number of concurrent [imports](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/imports) and [promotions](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/promotions) allowed. At any time, you can change the organization's support information (phone, email) and main colors (primary, contrast), add a logo and a favicon, and update other specific parameters (Google Tag Manager IDs, etc.).

{% hint style="warning" %}
Existing organizations cannot be deleted using the Provisioning API. If — for whatever reason — you need to delete one or more of the organizations you created, please ask the organization owner to reach out to our support team and send a specific request to [support@commercelayer.io ](mailto:support@commercelayer.io)specifying the list of the organization slug you want to be deleted.
{% endhint %}

## Subscription information

The creation of some resources (e.g. organizations and memberships) may be limited due to your subscription plan type. You can check your plan type limits and how close you are to hit them by inspecting the `subscription_info` attribute.

## Micro frontends configuration

Commerce Layer provides a set of [micro frontends](https://commercelayer.github.io/drop-in.js) (MFEs) and open-source apps (e.g. [Cart](https://github.com/commercelayer/mfe-cart), [Checkout](https://github.com/commercelayer/mfe-checkout), [Identity](https://github.com/commercelayer/mfe-identity), [My account](https://github.com/commercelayer/mfe-my-account), [Microstore](https://github.com/commercelayer/mfe-microstore)) that handle the main ecommerce functionalities. The Provisioning API lets you partially configure them at the organization level by properly passing the `mfe` object in the `config` attribute (see [example](https://docs.commercelayer.io/provisioning/api-reference/organizations/retrieve)).

{% hint style="info" %}
At the moment the organization configuration is limited to the MFEs URL format and to the Checkout app setup — more to come.
{% endhint %}

* **Links** — use the `links` key to specify the URL format for each of your apps (`cart`, `checkout`, `identity`, `my_account`, `microstore`).
* **Checkout** — use the `checkout` key to set your checkout app thank you page, privacy policy, and terms of service URLs, billing and shipping countries and states, and more.

You can specify the default values in the `default` key and possibly override them in a granular way (e.g. by market) by adding additional specific keys (e.g. `market:id:ZKcv13rT` where `ZKcv13rT` is the ID of the market that has a different configuration from the default one).

## Transferring the ownership

Owners can transfer the ownership of their organization(s) to another member of the same organization. To do that, send a `PATCH` request to the `/api/organizations/:id/transfer_ownership` endpoint, where `:id` is the ID of the organization in question, specifying the new owner email as the only attribute in the payload.

### Example

{% tabs %}
{% tab title="Request" %}
The following request transfers the ownership of the organization identified by the "xYZkjABcde" ID:

```sh
curl -g -X PATCH \
  'https://provisioning.commercelayer.io/api/organizations/xYZkjABcde/transfer_owenership' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "organizations",
      "id": "xYZkjABcde",
      "attributes": {
        "new_owner_email": "john@example.com"
      }
    }
  }'
```

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `202 Accepted` status code.
{% endtab %}
{% endtabs %}