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 (ISO 639-1 code, 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)
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)

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).

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 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",
    "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,
    "slug": "my-bookstore",
    "name": "My Bookstore",
    "final_domain": "mybookstore.publica.la",
    "lang": "en",
    "timezone": "America/New_York",
    "api_key": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0",
    "support_email": "[email protected]",
    "primary_color": null,
    "secondary_color": null,
    "logo_url": null,
    "icon_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)

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

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
lang	Required, valid language code
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

---

See Also

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