Tenant

Overview

Description

Path /v2/tenants

Handles all requests regarding tenants: creating, updating, deleting.

Tenant Object

An example for a tenant JSON object with id 0L.

{
  "id": 0,
  "name": "myName",
  "label": "myLabel",
  "active": true,
  "showLanguageSwitch": true,
  "authenticationRequired": true,
  "visibility": 10,
  "privacyUrl": "https://www.myDomain.com/privacy.html",
  "webhook": "https://api.myDomain.com/webhookEndpoint",
  "apiKey": "aValidApiKey",
  "packages": [
    {
      "id": "internalId",
      "package": "tenant_free",
      "fromPromocode": false,
      "validFrom": "2000-01-01T00:00:00.000Z",
      "validTill": "2100-01-01T00:00:00.000Z"
    }
  ],
  "links": {
    "plans": "/tenants/0/plans",
    "roles": "/tenants/0/roles/",
    "users": "/tenants/0/users/",
    "catalogs": "/tenants/0/catalogs/",
    "retailerInfos": "/tenants/0/retailerInfos/",
    "visibleCatalogs": "/tenants/0/visibleCatalogs/",
    "shownCatalogs": "/tenants/0/shownCatalogs/",
    "paymentConnections": "/tenants/0/paymentConnections/",
    "billingInformation": "/tenants/0/billingInformation/",
    "usages": "/tenants/0/usages/"
  },
  "allowRegistration": true,
  "branded": true,
  "catalogConnections": [ 
    {
      "id":"aCatalogId",
      "active":true,
      "owner":true,
      "public":false,
      "visibilityLevel":5
    }
  ],
  "modules": [
    "basic_usage",
    "catalog_management"
  ]
}

Responses are usually wrapped in a meta object, which contains additional information about the response and may contain a single tenant or a list of tenants.

{
    "tenant": {tenant Object},
    "tenants": [
        {tenant Object 1},
        {tenant Object 2},
        ...
    ],
    "meta": {
        "lastUpdated": "2018-01-23T09:15:39.000Z",
        "cached": false,
        "total": 1,
        "serverTime": "2019-03-14T12:29:08.549Z"
    }
}

JSON Fields

  • name : tenant name (must be unique within roomle)

  • label : tenant label (used in the UI and email)

  • active : active/inactive tenant

  • showLanguageSwitch : show language switch

  • defaultLanguage : tenant default language

  • authenticationRequired : toggles authentication

  • visibility : visibility level

  • privacyUrl : link to privacy disclaimer page

  • webhook : url to endpoint, to which events will be posted - only visible to users with tenant management rights

  • apiKey : apiKey for authentication with the Roomle API - only visible to users with tenant management rights

  • packages : list of active packages for this tenant. can contain tenant_free, tenant_basic, tenant_premium, tenant_enterprise

  • configurators : tenant configurators

  • links : contains a sequence of links, where to collect additional data connected with the tenant

  • allowRegistration: registration allowed or not

  • branded : branded or not

  • users : users connected with this tenant

  • skin : tenant skin

  • catalogs : list of catalogs owned by this tenant

  • visibleCatalogs : list of visible catalogs for this tenant

  • shownCatalogs : list of shown catalogs for this tenant

  • configuration - tenant configuration

  • modules : modules tenant can access

  • catalogConnections - deprecated since 2.99.1 - list of connection objects for the existing connections to catalogs. this includes owned catalogs and catalogs of other tenants that this tenant has explicit rights to or wants to show them. Use the new catalogConnections endpoints instead.

API Reference

Tenant Endpoints

POST /

Accepts: application/json

Generates: application/json

Creates a new tenant.

  • Must be super admin.

  • The new tenant must be given a unique name.

Response: see Tenant Object

GET /:id

Generates: application/json

Returns the tenant json with requested id.

Response: see Tenant Object

PUT /:id

Accepts: application/json

Generates: application/json

Updates the tenant with the given id

  • can only be called for the current tenant

  • calling user must have tenant management rights

Body: see Tenant Object Response: see Tenant Object

DELETE /:id

Deleting a tenant is currently not possible.

Response: 403 Forbidden

User Connections

The user connections are endpoints where to operate with user data connected with the tenant. This data is collected by the front end when needed and usually asynchronously. For more information about the User object used in this section, please see here

GET /:id/users/

Generates: application/json

Returns the users who are connected to the tenant.

  • can only be called for the current tenant

  • calling user must have user management rights

  • rolesInTenant field in the user states the assigned roles in this tenant

The User objects returned in this endpoint are limited to basic user data. If user has not provided consent on the tenant, the data is further limited to:

  • id

  • email

  • rolesInTenant

Response: UserContainer with a list of user objects see here

POST /:id/users/

Accepts: application/json

Generates: application/json

Creates/adds connections between the given user and the tenant.

  • calling user must have user management rights

  • if user (email) doesn't exist, he will be invited per email to join roomle

  • can only be called for the current tenant

  • only owners can make other users owner or admin

This endpoint accepts also batch upload of users - deprecated

Body: UserContainer with a user object see here. Only email and roles are used from the object

Response: UserContainer with a connected user object see here

PUT /:id/users/:userId/

Accepts: application/json

Generates: application/json

Updates connections between the given user and the tenant.

  • calling user must have user management rights

  • can only be called for the current tenant

  • only owners can make other users owner or admin

Body: UserContainer user object to update see here. Only email and roles are used from the object Response: UserContainer with updated user object see here

Payment Connections

The payment connections are endpoints where to operate with payment data connected with the tenant. This data is collected by the front end when needed and usually asynchronously.

Example PaymentConnection json:

{
  "id": "someUniqueId",
  "user": "someUser",
  "tenant": 0,
  "storeId": "stripe",
  "data": {
    "payment_method_id": "pm_1H8NvA2eZvKYlo2CylNGFDCL",
    "customerId": "cus_HhnVsIbbtTgRwo"
  }
}

GET /:id/paymentConnections/

Accepts: application/json

Generates: application/json

Collects all the paymentConnection Objects for the tenant and serializes them

  • calling user must have tenant_payment rights

Response: PaymentConnectionContainer see example above

POST /:id/paymentConnections/

Accepts: application/json

Generates: application/json

The call accepts a serialized PaymentConnection object, adding/updating the payment connection of the tenant

  • calling user must have tenant_management rights

  • only the current tenant can be updated

Body: PaymentConnectionContainer see example above Response: PaymentConnectionContainer see example above

POST /:id/paymentConnectionSessions/

Accepts: application/json

Generates: application/json

The call checks for a valid paymentConnection for the tenant in the given store and creates a billingPortalSession in the StripeAPI it then returns the sessionId with a created timestamp, serialized in a json

  • calling user must have tenant_management rights

Body: JsonObject:

    {
      "id": "se_vf2v6sdv26s",
      "created": 1358448484
    }

POST /:id/refreshActivePackages/

Accepts: multipart/form-data

Generates: application/json

Syncs the active packages for a tenant from the payment provider and returns the updated package list.

  • calling user must have tenant_payment rights

  • can only be called for the current tenant

Body:

  • Form data fields:

    • storeId: the payment store identifier (e.g., "stripe")

Response: ActivePackagesContainer

{
  "activePackages": [
    {
      "id": "internalId",
      "package": "tenant_free",
      "fromPromocode": false,
      "validFrom": "2000-01-01T00:00:00.000Z",
      "validTill": "2100-01-01T00:00:00.000Z"
    }
  ]
}

POST /:id/promocode

Accepts: application/json

Generates: application/json

Uses the given promocode on the tenant

  • calling user must have tenant_payment rights

  • promocode needs to be active, available and tenant must not have used it already

Body: PromocodeContainer

Response: PurchaseContainer

Tenant Billing Information

The tenant billing information are endpoints where to operate with self service billing data connected with the tenant. This data is collected by the front end when needed and usually asynchronously.

Example Billing Information json:

{
  "billingInformation": {
    "storeId": "stripe",
    "customerId": "cus_IQ8kfKXklJb0lm",
    "email": "[email protected]",
    "name": "customerNameNew",
    "address1": "a new address",
    "address2": null,
    "zip": "999",
    "city": "someWhereElse",
    "country": "at",
    "uid": "ATU87654321",
    "reverseCharge": false,
    "uidVerified": true
  }
}

GET /:id/billingInformation/

Accepts: application/json

Generates: application/json

Collects billingInformation data for the tenant from the Customer Object retrieved from StripeAPI and serializes them

  • allowed for current tenant

Response: BillingInformationContainer see example above

POST /:id/billingInformation/

Accepts: application/json

Generates: application/json

Checks billingInformation data for the tenant ad creates a Customer Object inside the StripeAPI. The returned Stripe Customer object in converted, serialized and returned

  • calling user must have tenant_management rights

Body: BillingInformationContainer see example above

Response: BillingInformationContainer see example above

PUT /:id/billingInformation/

Accepts: application/json

Generates: application/json

Checks billingInformation data for the tenant ad creates a Customer Object inside the StripeAPI. The returned Stripe Customer object in converted, serialized and returned

  • calling user must have tenant_management rights

Body: BillingInformationContainer see example above

Response: BillingInformationContainer see example above

Catalog Connections

The catalog connections are endpoints where to operate with catalog connection data connected with the tenant. This data is collected by the front end when needed and usually asynchronously.

Catalog Connection Object

An example for a catalog connection JSON object.

{
  "catalogConnection": {
    "id": "connectionId",
    "tenant": 123,
    "catalog": "catalogExtId",
    "visibilityLevel": 5,
    "active": true,
    "owner": false,
    "created": "2023-01-01T00:00:00.000Z",
    "updated": "2023-01-01T00:00:00.000Z"
  },
  "catalogConnections": [
    {
      "id": "connectionId",
      "tenant": 123,
      "catalog": "catalogExtId",
      "visibilityLevel": 5,
      "active": true,
      "owner": false,
      "created": "2023-01-01T00:00:00.000Z",
      "updated": "2023-01-01T00:00:00.000Z"
    },
    ...
  ],
    "meta": {
        "lastUpdated": "2018-01-23T09:15:39.000Z",
        "cached": false,
        "total": 1,
        "serverTime": "2019-03-14T12:29:08.549Z"
    }
}

Fields:

  • id : unique identifier of the connection

  • tenant : id of the tenant owning the connection

  • catalog : external id of the connected catalog

  • visibilityLevel : visibility level of the connection (0-10)

  • active : connection active or not

  • owner : true if the tenant owns the catalog, false otherwise

  • created : creation date of the connection

  • updated : last update date of the connection

GET /:id/catalogConnections/

Generates: application/json

Returns all catalog connections for the tenant.

  • calling user must have CMS rights

  • only visible for the current tenant

Response: List of catalog connection objects see example above

POST /:id/catalogConnections/:catalogExtId/

Accepts: application/json

Generates: application/json

Creates a new catalog connection for the tenant.

  • calling user must have CMS rights

  • calling user must have tenant management rights

  • can only be called for the current tenant

Body: CatalogConnectionContainer with the connection object see example above. Only visibilityLevel and active are used for the update.

Response: CatalogConnectionContainer with the created connection object see example above

PUT /:id/catalogConnections/:catalogExtId/

Accepts: application/json

Generates: application/json

Updates an existing catalog connection for the tenant.

  • calling user must have CMS rights

  • calling user must have tenant management rights

  • can only be called for the current tenant

Body: CatalogConnectionContainer with the connection object see example above. Only visibilityLevel and active are used for the update.

Response: CatalogConnectionContainer with the updated connection object see example above

DELETE /:id/catalogConnections/:catalogExtId/

Generates: application/json

Deletes a catalog connection for the tenant.

  • calling user must have CMS rights

  • calling user must have tenant management rights

  • can only be called for the current tenant

  • cannot delete connections to catalogs you own

Response: 204 No Content

Links

The following endpoint provide lists of objects connected to the tenant

GET /:id/roles/

Generates: application/json

User must have User management rights.

Response: User2TenantContainer object containing the user/tenant connections of this tenant.

GET /:id/catalogs/

Generates: application/json

User must have Catalog management rights. Only visible for the current tenant.

Response: CatalogContainer object with catalogs owned by the tenant see Catalog Object.

GET /:id/visibleCatalogs/

Generates: application/json

User must have Catalog management rights. Only visible for the current tenant.

Response: CatalogContainer object with catalogs visible by the tenant see Catalog Object.

GET /:id/shownCatalogs/

Generates: application/json

User must have Catalog management rights. Only visible for the current tenant.

Response: CatalogContainer object with catalogs shown in the tenant see Catalog Object.

GET /:id/enabledTags/

Generates: application/json

Tags are only visible for the current tenant.

Response: TagContainer object containing the enabled Tags in this tenant see Tag Object.

GET /:id/retailerInfos/

Generates: application/json

Returns retailer information objects for the tenant.

  • only visible for the current tenant

Response:

{
  "retailerInfos": [
    {
      "id": "retailerInfoId",
      "tenant": 123,
      "retailerData": {
        "name": "Example Retailer",
        "address": "123 Main St"
      }
    }
  ]
}

GET /me/

Generates: application/json

Returns the tenant ID based on the subdomain from the Origin header.

  • public endpoint, no authentication required

  • resolves tenant from request origin domain

Response: tenant ID as plain text (e.g., "9" for Roomle main tenant)

GET /:id/assetProcessings/

Collects all the triggered assetProcessings for the tenant in the given time span - default is last 30 days

Accepts: application/json Generates: application/json

Query parameters:

  • from (String): has to be a date string with timezone. This string has to match following example 2016-06-01T07:54:07.000Z.

  • to (String): has to be a date string with timezone. This string has to match following example 2016-06-01T07:54:07.000Z.

  • calling user must have tenant_statistics rights

Response: AssetProcessingContainer containing a list of asset processing objects see here

Tenant Usages

GET /:id/usages/

Accepts: application/json

Generates: application/json

Collects all the paymentConnection Objects for the tenant and serializes them

  • calling user must have tenant_payment rights

Response: TenantUsagesContainer

{
  "tenantUsages": [
    {
      "id": "123:uploadProduct",
      "type": "uploadProduct",
      "used": 123,
      "limit": 250
    }
  ]
}

Fields:

  • id : unique identifier of the usage (combination of tenantId and type)

  • type : type of usage (e.g., uploadProduct, configureProduct, renderImage)

  • used : number of used units

  • limit : number of allowed units (based on the active package)

PreviousTagControllerNextTextureController

Last updated