Organizations

The organization object and the allowed CRUD operations on the related resource endpoint

An organization is an independent group that comprises members with assigned roles and permissions. A 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, 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 is to give it a name. The newly created organization is automatically associated with your user's membership (created with the owner attribute set to true), with Admin role. The Admin role is also used to create two API credentials of type resources used to manage the organization's resources in the two available Core API 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 lets you check some useful information such as the maximum number of concurrent imports and 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.).

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 [e-mail] specifying the list of the organization slug you want to be deleted.

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 (MFEs) and open-source apps (e.g. Cart, Checkout, Identity, My account, 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).

At the moment the organization configuration is limited to the MFEs URL format and to the Checkout app setup — more to come.

• 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

Request

The following request transfers the ownership of the organization identified by the "xYZkjABcde" ID:

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": "[e-mail]"
      }
    }
  }'

Response

On success, the API responds with a 202 Accepted status code.