Update Aggregate

Modify the configuration of an existing sub-tenant (aggregate). All fields are optional; only include fields you want to change.

Endpoint

PUT /api/v3/aggregates/{id}

Path Parameters

Parameter	Type	Description
`id`	string	Aggregate's tenant ID

Request Body

All fields are optional. Only include fields you want to update. Omitted fields are left unchanged.

Core Fields

Field	Type	Description
`name`	string	Store name (max 255 characters)
`final_domain`	string	Store domain; platform subdomain or custom domain (max 255 characters, must be unique)
`lang`	string	Store language (ISO 639-1 code)
`timezone`	string	Store timezone (IANA format)
`support_email`	string	Support and notifications email address (max 255 characters)
`disable_selling`	boolean	When `true`, disables all e-commerce functionality on the store (checkout, paid plans, paid content).
`landing_enabled`	boolean	When `true`, the public landing page is shown.
`reader_flashcards_enabled`	boolean	Turns flashcards on (`true`) or off (`false`) in the reader for signed-in readers of the store (PDF and EPUB products). Never offered to anonymous readers or on audiobooks.

Flashcards and the dashboard

Store admins can also turn flashcards on or off from the reader settings in their dashboard. The API and the dashboard write the same setting, so the most recent change applies.

Branding Fields

Field	Type	Description
`primary_color`	string	Primary brand color (hex format, e.g., `#336699`)
`secondary_color`	string	Secondary brand color (hex format, e.g., `#FF6600`)
`reader_accent_color`	string	Accent color used in the reader's light and dark themes (hex format, e.g., `#0066CC`). Colors the reader, not the storefront.
`logo_url`	string	Public URL of the store logo, pointing to a JPG, PNG, WEBP, or SVG image (max 2048 characters). The platform downloads and hosts the image; see Logo and Icon Import.
`icon_url`	string	Public URL of the store icon/favicon, pointing to a JPG, PNG, WEBP, or SVG image (max 2048 characters). The platform downloads and hosts the image; see Logo and Icon Import.

Nullable Fields

primary_color, secondary_color, logo_url, and icon_url accept null in the request, but an explicit null is ignored and the stored value is kept. reader_accent_color is the only field that is actually cleared by an explicit null; the reader then falls back to its built-in accent.

Reader Accent Color Scope

reader_accent_color only affects the reader's light and dark themes (buttons, interactive text and links, toolbar icons, the book title, the theme selector, and the reading progress bar). The other reading themes (sepia, cream, cyan, and high contrast) keep their own fixed accent and are not affected. On the dark theme, the platform automatically lightens the configured color so it stays legible against the dark background, so it will not match the configured hex exactly there. The platform does not validate contrast, so a very light color reads poorly against the light theme's white background. reader_accent_color is independent from primary_color and secondary_color, which apply to the storefront only; setting one never affects the others.

Colors on the block-based storefront

When the store runs on the block-based storefront, its colors come from the Theme its admins publish from the dashboard. On those stores an update ignores primary_color and secondary_color without returning an error, while the other fields in the same request are still applied. Responses return the colors of the published theme.

Auth Token (SSO) Fields

Send an external_auth object to configure single sign-on for the sub-tenant. See the Auth Token guide for the token format and login flow.

Field	Type	Description
`external_auth.key`	string	Write-only HMAC secret (minimum 32 characters). Never returned. See the update rules below.
`external_auth.issuer`	string	Your platform identifier. Required when a new `key` is sent.
`external_auth.redirect_url`	string	Where users are sent on auth errors. Required when a new `key` is sent.
`external_auth.login_url`	string	Your platform's login URL.
`external_auth.logout_url`	string	Where users are sent after logging out.
`external_auth.home_url`	string	Your platform's home URL.
`external_auth.account_url`	string	Your platform's account URL.

The key field drives how an update is applied:

Omit key: the stored secret is kept, and any other external_auth fields you send are updated. Use this to edit the issuer or URLs without resending the secret.
Send a non-empty key: it replaces the stored secret and (re)activates SSO. issuer and redirect_url are required in this case.
Send key as null: SSO is deactivated and the whole external_auth configuration is cleared.

Key is write-only

Responses never include key. They return an external_auth object with every other field plus an enabled boolean that reflects whether a key is currently configured.

Storefront Redirect Fields

Send a storefront_redirect object to turn the external storefront redirect on or off. See Storefront Redirect Fields on the create endpoint for what the redirect covers.

Field	Type	Description
`storefront_redirect.enabled`	boolean	Turns the redirect on (`true`) or off (`false`). Required when `storefront_redirect` is sent.
`storefront_redirect.url`	string	Where visitors are sent; an `http` or `https` URL (max 2048 characters). Required when `enabled` is `true`.

The fields you send are merged over the stored configuration:

Turn it on: send enabled: true together with url, even if a URL is already stored.
Turn it off: send enabled: false. The stored url is kept and responses keep returning it. Send url as null in the same request to clear it as well.
Change the destination: send enabled: true with the new url.

Request Examples

Update Store Name

curl -X PUT "https://yourstore.publica.la/api/v3/aggregates/42" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Updated Bookstore"
  }'

Update Branding

curl -X PUT "https://yourstore.publica.la/api/v3/aggregates/42" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "primary_color": "#1A237E",
    "secondary_color": "#FF6F00",
    "logo_url": "https://example.com/new-logo.png"
  }'

Set the Reader Accent Color

curl -X PUT "https://yourstore.publica.la/api/v3/aggregates/42" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "reader_accent_color": "#0066CC"
  }'

Clear the Reader Accent Color

curl -X PUT "https://yourstore.publica.la/api/v3/aggregates/42" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "reader_accent_color": null
  }'

Sending reader_accent_color as null clears the stored value and the reader falls back to its built-in accent. This is a deliberate exception: the other branding fields (primary_color, secondary_color, logo_url, icon_url) ignore an explicit null and keep the stored value.

Turn On Flashcards

curl -X PUT "https://yourstore.publica.la/api/v3/aggregates/42" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "reader_flashcards_enabled": true
  }'

Send false to turn them off again.

Update Domain and Language

curl -X PUT "https://yourstore.publica.la/api/v3/aggregates/42" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "final_domain": "new-bookstore-domain.publica.la",
    "lang": "es",
    "timezone": "America/Buenos_Aires"
  }'

Update Support Email

curl -X PUT "https://yourstore.publica.la/api/v3/aggregates/42" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "support_email": "[email protected]"
  }'

Configure or Update Auth Token (SSO)

curl -X PUT "https://yourstore.publica.la/api/v3/aggregates/42" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "external_auth": {
      "key": "your-32-character-or-longer-secret-key",
      "issuer": "my-platform",
      "redirect_url": "https://my-platform.com/auth-error"
    }
  }'

Edit Auth Token Fields Without Resending the Secret

curl -X PUT "https://yourstore.publica.la/api/v3/aggregates/42" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "external_auth": {
      "redirect_url": "https://my-platform.com/new-auth-error"
    }
  }'

Deactivate Auth Token (SSO)

curl -X PUT "https://yourstore.publica.la/api/v3/aggregates/42" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "external_auth": { "key": null }
  }'

Redirect the Storefront to an External Site

curl -X PUT "https://yourstore.publica.la/api/v3/aggregates/42" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "storefront_redirect": {
      "enabled": true,
      "url": "https://discovery.example.com"
    }
  }'

Turn Off the Storefront Redirect

curl -X PUT "https://yourstore.publica.la/api/v3/aggregates/42" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "storefront_redirect": { "enabled": false }
  }'

Combined Update

curl -X PUT "https://yourstore.publica.la/api/v3/aggregates/42" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Rebranded Bookstore",
    "primary_color": "#006341",
    "secondary_color": "#FF6F00",
    "reader_accent_color": "#006341",
    "logo_url": "https://example.com/rebrand-logo.png",
    "support_email": "[email protected]"
  }'

Response

Success Response (200 OK)

{
  "data": {
    "id": 42,
    "slug": "my-bookstore",
    "name": "My Updated Bookstore",
    "final_domain": "mybookstore.publica.la",
    "lang": "en",
    "timezone": "America/New_York",
    "support_email": "[email protected]",
    "primary_color": "#1A237E",
    "secondary_color": "#FF6F00",
    "reader_accent_color": "#0066CC",
    "reader_flashcards_enabled": true,
    "logo_url": "https://assets.publica.la/my-bookstore/logo/logo.png",
    "icon_url": null,
    "disable_selling": false,
    "landing_enabled": true,
    "storefront_redirect": {
      "enabled": false,
      "url": null
    },
    "external_auth": {
      "enabled": true,
      "issuer": "my-platform",
      "redirect_url": "https://my-platform.com/auth-error",
      "login_url": null,
      "logout_url": null,
      "home_url": null,
      "account_url": null
    },
    "created_at": "2026-03-24T15:30:00+00:00"
  }
}

Error Handling

Not Found (404)

Returned when the aggregate does not exist or does not belong to your store:

{
  "message": "Not found."
}

Validation Errors (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "final_domain": ["The final domain has already been taken."],
    "primary_color": ["The primary color format is invalid."]
  }
}

Authentication Errors (401)

{
  "message": "Unauthenticated."
}

Authorization Errors (403)

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

Validation Rules

Field	Rules
`name`	Optional, string, max 255 characters
`final_domain`	Optional, string, max 255 characters, unique (excluding current), valid format
`lang`	Optional, valid language code
`timezone`	Optional, valid IANA timezone
`support_email`	Optional, valid email, max 255 characters
`primary_color`	Optional, nullable, hex color format (`#RRGGBB`)
`secondary_color`	Optional, nullable, hex color format (`#RRGGBB`)
`reader_accent_color`	Optional, nullable, hex color format (`#RRGGBB`). An explicit `null` clears the stored value
`reader_flashcards_enabled`	Optional, boolean
`logo_url`	Optional, nullable, `http` or `https` URL, max 2048 characters. Must be reachable and serve a JPG, PNG, WEBP, or SVG image of at most 20,000 KB
`icon_url`	Optional, nullable, `http` or `https` URL, max 2048 characters. Must be reachable and serve a JPG, PNG, WEBP, or SVG image of at most 20,000 KB
`disable_selling`	Optional, boolean
`landing_enabled`	Optional, boolean
`storefront_redirect`	Optional, object
`storefront_redirect.enabled`	Required when `storefront_redirect` is sent, boolean
`storefront_redirect.url`	Required when `storefront_redirect.enabled` is `true`, nullable, `http` or `https` URL, max 2048 characters
`external_auth.key`	Optional, nullable, string with a minimum of 32 characters. Send `null` to clear the configuration
`external_auth.issuer`	Required when a non-empty `key` is sent, string, max 255 characters
`external_auth.redirect_url`	Required when a non-empty `key` 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

Endpoint​

Path Parameters​

Request Body​

Core Fields​

Branding Fields​

Auth Token (SSO) Fields​

Storefront Redirect Fields​

Request Examples​

Update Store Name​

Update Branding​

Set the Reader Accent Color​

Clear the Reader Accent Color​

Turn On Flashcards​

Update Domain and Language​

Update Support Email​

Configure or Update Auth Token (SSO)​

Edit Auth Token Fields Without Resending the Secret​

Deactivate Auth Token (SSO)​

Redirect the Storefront to an External Site​

Turn Off the Storefront Redirect​

Combined Update​

Response​

Success Response (200 OK)​

Error Handling​

Not Found (404)​

Validation Errors (422)​

Authentication Errors (401)​

Authorization Errors (403)​

Validation Rules​

See Also​