Create Aggregate

Provision a new sub-tenant (aggregate) under your aggregator store. The new tenant is created with its own domain, admin user, and store configuration.

---

Endpoint

POST /api/v3/aggregates

---

Request Body

Required Fields

Field	Type	Description
name	string	Store name (max 255 characters)
lang	string	Store language. Must be one of the supported codes (e.g., en, es, pt).
timezone	string	Store timezone (IANA format, e.g., America/New_York)
support_email	string	Support email address (max 255 characters)

Optional Fields

Field	Type	Default	Description
final_domain	string	Auto-generated from name as slug	Store domain (must be unique, max 255 chars)
external_id	string	null	Your own opaque identifier for the sub-tenant (max 255 chars)
primary_color	string	null	Primary brand color (hex, e.g., #336699)
secondary_color	string	null	Secondary brand color (hex, e.g., #FF6600)
logo_url	string	null	URL to the store logo (max 2048 chars)
icon_url	string	null	URL to the store icon/favicon (max 2048 chars)
disable_selling	boolean	false	When true, disables all e-commerce functionality on the store (checkout, paid plans, paid content). Selling is enabled by default.
landing_enabled	boolean	false	When true, the public landing page is shown. Disabled by default for new aggregates.

External ID

external_id lets you reference sub-tenants using an identifier from your own system (e.g., a CRM ID, an ERP code). It must be unique per aggregator and can be used on the get and update endpoints by passing ?id_type=external on the URL.

Domain Format

final_domain supports two formats:

• Platform subdomain: mybookstore.publica.la (accessible at https://mybookstore.publica.la)
• Custom domain: www.mybookstore.com (requires DNS configuration pointing to Publica.la)

If omitted, a domain is auto-generated from the store name (e.g., name "My Bookstore" generates mybookstore.publica.la).

Auth Token (SSO) Fields

Configure single sign-on for the sub-tenant by sending an external_auth object. This is the same JWT (HS256) auth token integration that previously required a manual setup through support; you can now provision it programmatically for any of your sub-tenants. See the Auth Token guide for the token format and login flow.

Field	Type	Default	Description
external_auth.key	string	null	Write-only. The HMAC secret used to sign your JWTs (minimum 32 characters). Sending a valid key enables SSO. Never returned in any response.
external_auth.issuer	string	null	Your platform identifier. Must match the iss claim in your tokens. Required when key is sent.
external_auth.redirect_url	string	null	Where users are sent on auth errors. Required when key is sent.
external_auth.login_url	string	null	Your platform's login URL.
external_auth.logout_url	string	null	Where users are sent after logging out.
external_auth.home_url	string	null	Your platform's home URL.
external_auth.account_url	string	null	Your platform's account URL.

Key is write-only

The key is a shared secret and is never returned by any endpoint (create, get, list, or update). Responses include an external_auth object with every field except key, plus an enabled boolean that reflects whether a key is configured.

Inherited from Aggregator

These values are automatically set from the aggregator and cannot be overridden:

Attribute	Description
Fees	Transaction and sales fee structure
Currencies	Main and secondary currency configuration

---

What Happens on Create

When you create an aggregate, the platform automatically:

1. Creates the tenant with the provided configuration
2. Provisions store infrastructure (library, default shelves, sales settings)
3. Inherits fees and currencies from the aggregator
4. Creates an admin user linked to the email of the authenticated user
5. Returns an api_key to authenticate requests on behalf of the new store

---

Request Examples

Minimal (Auto-Generated Domain)

curl -X POST "https://yourstore.publica.la/api/v3/aggregates" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Bookstore",
    "lang": "en",
    "timezone": "America/New_York",
    "support_email": "[email protected]"
  }'

The domain is auto-generated as mybookstore.publica.la.

With Auth Token (SSO)

curl -X POST "https://yourstore.publica.la/api/v3/aggregates" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Bookstore",
    "lang": "en",
    "timezone": "America/New_York",
    "support_email": "[email protected]",
    "external_auth": {
      "key": "your-32-character-or-longer-secret-key",
      "issuer": "my-platform",
      "redirect_url": "https://my-platform.com/auth-error",
      "logout_url": "https://my-platform.com/logout"
    }
  }'

With Branding and Custom Domain

curl -X POST "https://yourstore.publica.la/api/v3/aggregates" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Bookstore",
    "final_domain": "www.mybookstore.com",
    "external_id": "crm-12345",
    "lang": "en",
    "timezone": "America/New_York",
    "support_email": "[email protected]",
    "primary_color": "#1A237E",
    "secondary_color": "#FF6F00",
    "logo_url": "https://example.com/assets/logo.png",
    "icon_url": "https://example.com/assets/icon.png"
  }'

---

Response

Success Response (201 Created)

{
  "data": {
    "id": "42",
    "external_id": null,
    "slug": "my-bookstore",
    "name": "My Bookstore",
    "final_domain": "mybookstore.publica.la",
    "lang": "en",
    "timezone": "America/New_York",
    "api_key": "api-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "support_email": "[email protected]",
    "primary_color": null,
    "secondary_color": null,
    "logo_url": null,
    "icon_url": null,
    "disable_selling": false,
    "landing_enabled": false,
    "external_auth": {
      "enabled": false,
      "issuer": null,
      "redirect_url": null,
      "login_url": null,
      "logout_url": null,
      "home_url": null,
      "account_url": null
    },
    "created_at": "2026-03-24T15:30:00+00:00"
  }
}

The api_key is always included in the create response. To retrieve it later, use ?include=api_key on the get or list endpoints.

API Key Usage

Use the api_key in the X-User-Token header to make API requests directly to the sub-tenant's endpoints (content, orders, etc.).

---

Error Handling

Validation Errors (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "name": ["The name field is required."],
    "final_domain": ["The final domain has already been taken."],
    "support_email": ["The support email must be a valid email address."]
  }
}

Invalid Domain Format (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "final_domain": ["The final_domain format is invalid."]
  }
}

Invalid Color Format (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "primary_color": ["The primary color format is invalid."]
  }
}

Authorization Errors (403)

Returned when the authenticated tenant is not allowed to provision sub-tenants. Two messages are possible:

{
  "message": "Tenant does not have aggregation capabilities."
}

{
  "message": "Aggregated tenants cannot provision tenants."
}

Authentication Errors (401)

{
  "message": "Unauthenticated."
}

---

Validation Rules

Field	Rules
name	Required, string, max 255 characters
final_domain	Optional, string, max 255 characters, unique, valid domain format
external_id	Optional, nullable, string, max 255 characters, unique per aggregator
lang	Required, string, one of the supported language codes
timezone	Required, valid IANA timezone
support_email	Required, valid email, max 255 characters
primary_color	Optional, nullable, hex color format (#RRGGBB)
secondary_color	Optional, nullable, hex color format (#RRGGBB)
logo_url	Optional, nullable, valid URL, max 2048 characters
icon_url	Optional, nullable, valid URL, max 2048 characters
disable_selling	Optional, boolean
landing_enabled	Optional, boolean
external_auth.key	Required when external_auth is sent, string, minimum 32 characters
external_auth.issuer	Required when external_auth is sent, string, max 255 characters
external_auth.redirect_url	Required when external_auth is sent, valid URL, max 2048 characters
external_auth.login_url	Optional, nullable, valid URL, max 2048 characters
external_auth.logout_url	Optional, nullable, valid URL, max 2048 characters
external_auth.home_url	Optional, nullable, valid URL, max 2048 characters
external_auth.account_url	Optional, nullable, valid URL, max 2048 characters

Validation Error (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "external_auth.key": [
      "The external authentication key must be at least 256 bits (32 bytes)."
    ]
  }
}

---

See Also

• List Aggregates - Query your aggregates
• Get Aggregate - Retrieve aggregate details
• Update Aggregate - Modify configuration
• Overview - API overview