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)
Last updated