Aggregates API v3

Programmatically provision and manage sub-tenants (aggregates) under your aggregator store. Each aggregate is a fully independent store with its own domain, catalog, and configuration.

---

Prerequisites

Your store must have the store aggregation feature enabled. Contact support to enable aggregation capabilities for your account.

Aggregated Tenants

Only top-level aggregator stores can use this API. Sub-tenants cannot provision other tenants.

---

Authentication

Header	Example	Description
X-User-Token	api-abc123...	API token generated in your dashboard. Header-only for security.

All requests must be performed over HTTPS.

curl -X GET "https://yourstore.publica.la/api/v3/aggregates" \
  -H "X-User-Token: api-abc123..." \
  -H "Accept: application/json"

---

API Endpoints

Operation	Method	Endpoint	Description
List aggregates	GET	/api/v3/aggregates	List all sub-tenants
Get aggregate	GET	/api/v3/aggregates/{id}	Retrieve a specific aggregate
Create	POST	/api/v3/aggregates	Provision a new sub-tenant
Update	PUT	/api/v3/aggregates/{id}	Update aggregate configuration

No Delete

Aggregates cannot be deleted via the API. Contact support for tenant deactivation.

---

What Gets Inherited

When you create an aggregate, the following are automatically inherited from the aggregator:

• Fees: transaction and sales fee structure
• Currencies: main and secondary currency configuration

The aggregate gets its own independent content catalog, user base, and store configuration. Branding (colors, icons, emails) is set during creation or via update.

---

Aggregator vs Sub-Tenant API Usage

The Aggregates API (/api/v3/aggregates) is used by the aggregator to provision and configure sub-tenants (name, domain, branding, support email).

To interact with a sub-tenant's data (content, orders, users), use the sub-tenant's own API endpoints with the api_key obtained during creation or via ?include=api_key on the list and get endpoints.

---

Cursor Pagination

{
  "data": [...],
  "links": {
    "next": "https://yourstore.publica.la/api/v3/aggregates?cursor=eyJjcmVhdGVkX2F0...",
    "prev": null
  },
  "meta": {
    "has_more": true
  }
}

Pagination Workflow

1. Make initial request without cursor
2. Store links.next token
3. Use cursor=<token> for next page
4. Continue until meta.has_more is false

Best Practice

Always use meta.has_more to detect the end of results, not by counting items.

---

Common Response Format

Single Aggregate

{
  "data": {
    "id": 42,
    "slug": "my-bookstore",
    "name": "My Bookstore",
    "final_domain": "mybookstore.publica.la",
    "lang": "en",
    "timezone": "America/New_York",
    "support_email": "[email protected]",
    "primary_color": "#336699",
    "secondary_color": "#FF6600",
    "logo_url": "https://example.com/logo.png",
    "icon_url": "https://example.com/icon.png",
    "created_at": "2026-03-24T15:30:00+00:00"
  }
}

With ?include=api_key

The api_key is always included in the create response. For existing aggregates, request it explicitly with ?include=api_key:

{
  "data": {
    "id": 42,
    "slug": "my-bookstore",
    "name": "My Bookstore",
    "final_domain": "mybookstore.publica.la",
    "lang": "en",
    "timezone": "America/New_York",
    "api_key": "a1b2c3d4e5f6...",
    "support_email": "[email protected]",
    "primary_color": "#336699",
    "secondary_color": null,
    "logo_url": null,
    "icon_url": null,
    "created_at": "2026-03-24T15:30:00+00:00"
  }
}

API Key

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

Authorization Errors (403)

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

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

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."]
  }
}

Authentication Errors (401)

{
  "message": "Unauthenticated."
}

Not Found (404)

{
  "message": "Not found."
}

---

Quick Start Examples

List Your Aggregates

curl -X GET "https://yourstore.publica.la/api/v3/aggregates?per_page=10" \
  -H "X-User-Token: your-api-token" \
  -H "Accept: application/json"

Create a New Aggregate

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]"
  }'

---

Next Steps

• Create Aggregate - Provision a new sub-tenant
• List Aggregates - Query your aggregates
• Get Aggregate - Retrieve aggregate details
• Update Aggregate - Modify aggregate configuration

---

See Also

• API Authentication
• Content API v3 - Manage content catalog
• Orders API v3 - Manage customer purchases