# Publica.la Developers

> Public integration documentation for the Publica.la digital publishing platform.

## When to use these docs

- Integrate a Publica.la store with the supported API v3 contract.
- Configure authentication, content publishing, notifications, redirects, or custom domains.
- Verify Publica.la platform behavior before building or maintaining an integration.

API operations run on the tenant store domain and require the authentication declared by the API contract. The documentation host does not execute API operations.

## Documentation

- [AI Transparency & Data Handling](https://docs.publica.la/ai-transparency.md): Publica.la integrates AI capabilities into the reader experience through a suite of tools that help readers comprehend, interact with, and get more value from digital content. This page documents what AI features exist, how data flows through them, what providers are involved, and what controls publishers have.
- [API Overview and Integration Guidelines](https://docs.publica.la/api-overview.md): Introduction
- [Custom Domains & HTTPS Certificates](https://docs.publica.la/custom-domains-and-https.md): Every Publica.la store comes with a default subdomain like yourstore.app.publica.la. You can replace it with your own domain (for example, store.yourcompany.com) so your customers see your brand in the URL.
- [Instant Payment Notifications (IPNs)](https://docs.publica.la/ipns.md): Instant Payment Notifications (IPNs) allow payment processors to communicate directly with your Publica.la store about transaction events. Unlike webhooks, IPNs are sent directly from the payment provider rather than from the Publica.la platform.
- [Platform IP Addresses](https://docs.publica.la/platform-ip-addresses.md): Outbound IP Addresses
- [Privacy & Data Protection (GDPR)](https://docs.publica.la/privacy-and-data-protection.md): When you run a store or a library on Publica.la, you collect personal data from your readers and buyers. This page explains who is responsible for that data under the GDPR (RGPD in Spanish), how we sign a Data Processing Agreement with you, how data leaves the EU, and which cookies your store uses.
- [Publica.la Developer Documentation](https://docs.publica.la/index.md): This documentation helps developers integrate with and leverage the Publica.la platform, a comprehensive digital publishing ecosystem designed for content creators, distributors, and publishers.
- [Redirect Routes](https://docs.publica.la/redirect-routes.md): Publica.la exposes automatic redirect endpoints and URL parameters that provide convenient access to content and streamlined purchase flows. These features are useful for deep linking, email campaigns, marketing materials, and integrations where you need predictable URLs that automatically resolve to the correct content or initiate purchases.
- [Security & Content Protection](https://docs.publica.la/security-and-content-protection.md): Publica.la provides a B2B2C digital publishing SaaS platform: branded ecommerce storefronts plus a secure reading and listening experience delivered through our web reader and our native applications for iOS, Android, macOS, and Windows. The service is fully cloud-based on AWS, fronted by Cloudflare, with no on-premise component required of you or your content partners.

## auth-integrations

- [Auth Integrations Overview](https://docs.publica.la/auth-integrations/03-integrations.md): Overview
- [Auth LTI Integration](https://docs.publica.la/auth-integrations/auth-lti-integrations.md): What is it?
- [Auth Referrer Integration](https://docs.publica.la/auth-integrations/auth-referrer-integrations-tenants.md): How does it work?
- [Auth Token](https://docs.publica.la/auth-integrations/auth-token.md): Overview
- [Authentication by IP Ranges](https://docs.publica.la/auth-integrations/auth-ip-integrations-tenants.md): Overview
- [Embed the Reader in Your Application](https://docs.publica.la/auth-integrations/reader-embedding.md): Add ?embedded=true to any reader URL to render the Publica.la reader inside an iframe in your application. Embedded mode hides navigation controls that would break the parent page context and adapts the UI to fit within a container.
- [External Auth Embedding](https://docs.publica.la/auth-integrations/external-auth-embedding.md): Integration model for external users authentication
- [OpenID Connect (OIDC)](https://docs.publica.la/auth-integrations/auth-oidc.md): Overview
- [SAML 2.0](https://docs.publica.la/auth-integrations/auth-saml.md): Overview

## content-publishing

- [Content Publishing](https://docs.publica.la/content-publishing/overview.md): This section covers the programmatic ways to get products into your store and keep them up to date. There are three, and they solve different problems:
- [ONIX Intake](https://docs.publica.la/content-publishing/onix-intake.md): An ONIX intake ingests your catalog from an ONIX 3.0 feed. We create an SFTP account and a private storage area for you and send you the password; you upload the feed and the content files there, and we create and update the products in your store from what the feed says. Use it when you are onboarding a large catalog, or when your metadata already flows to distributors and retailers as ONIX.
- [Scheduled Automations](https://docs.publica.la/content-publishing/scheduled-automations.md): A scheduled automation publishes PDF editions from a folder in an S3 bucket on a schedule you define, with no integration to build. Use it when you release on a predictable calendar (a daily newspaper, a weekly magazine) and prefer naming files to a convention over writing code.
- [Smart Zoom Articles](https://docs.publica.la/content-publishing/smart-zoom-articles.md): How does it work?

## rest-api

- [Auth Sessions API Reference](https://docs.publica.la/rest-api/auth-sessions.md): Overview
- [Plans API Reference](https://docs.publica.la/rest-api/plans.md): Overview
- [Reading Permissions](https://docs.publica.la/rest-api/reading-permissions.md): This endpoint is going to be dismissed anytime soon. Use Orders instead.
- [Sessions API Reference](https://docs.publica.la/rest-api/sessions.md): The Sessions API provides insights into user interactions with your content, tracking reading sessions and engagement metrics. This feature allows you to retrieve detailed session data, including reading duration and page changes. This section will help you understand how to leverage session data to enhance user experience and content strategy.
- [Users API Reference](https://docs.publica.la/rest-api/users.md): Overview

## rest-api-v3

- [Add-ons API Overview](https://docs.publica.la/rest-api-v3/add-ons/add-ons-v3-overview.md): Manage the full lifecycle of your products' add-ons: interactive pieces (articles, audio, video, images, links) anchored to a position in a product and shown to readers on top of the content.
- [Aggregates API Overview](https://docs.publica.la/rest-api-v3/aggregates/aggregates-v3-overview.md): 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.
- [Audiobook Tracks](https://docs.publica.la/rest-api-v3/content/content-v3-tracks.md): Manage audio tracks for audiobook content. Tracks are individual audio files (chapters, sections) that make up an audiobook.
- [Bulk Create Add-ons](https://docs.publica.la/rest-api-v3/add-ons/add-ons-v3-bulk.md): Create up to 100 add-ons on one product in a single request. Bulk items are pure database writes: attach images through the single add-on endpoints.
- [Bulk Operations](https://docs.publica.la/rest-api-v3/content/content-v3-bulk.md): Create multiple content items in a single API call. Files are not processed immediately, processing is triggered on-demand when a user accesses the content (product page or reader).
- [Bulk Operations](https://docs.publica.la/rest-api-v3/orders/create-order/orders-v3-bulk.md): Create multiple orders in a single API call. The bulk endpoint processes orders concurrently, making it significantly faster than sequential individual requests.
- [Bulk Share Collections](https://docs.publica.la/rest-api-v3/content/content-v3-bulk-share.md): Share every owned content item that belongs to one or more collections with a list of target tenants in a single API call. The endpoint validates the request synchronously and queues the sharing work in the background.
- [Bundles API Overview](https://docs.publica.la/rest-api-v3/bundles/bundles-v3-overview.md): Create and manage your store's bundles: curated sets of your products sold together as a single unit. A bundle only references its products, so its price and availability are computed live from them. The price is never stored; only the discount percentage is.
- [Content API Overview](https://docs.publica.la/rest-api-v3/content/content-v3-overview.md): Manage your store's digital catalog: list, create, update, and delete content items.
- [Content API v1 → v3 Migration Guide](https://docs.publica.la/rest-api-v3/content/content-v3-migration.md): This document compares Content API v1 and v3 and provides a practical migration guide for integrators. The v3 feed is designed for speed, bandwidth efficiency, and flexibility via cursor pagination and response shaping (fields and includes).
- [Content Sharing](https://docs.publica.la/rest-api-v3/content/content-v3-sharing.md): Distribute content to other tenants' catalogs using the sharewithtenants_ids field. This allows a content owner to make their content available in other tenants' stores without duplicating the content item.
- [Create a Bundle](https://docs.publica.la/rest-api-v3/bundles/bundles-v3-create.md): Create a bundle from 2 to 100 of your products, in a single request.
- [Create Aggregate](https://docs.publica.la/rest-api-v3/aggregates/aggregates-v3-create.md): Provision a new sub-tenant (aggregate) under your aggregator store. The new tenant is created with its own domain, admin user, and store configuration.
- [Create an Add-on](https://docs.publica.la/rest-api-v3/add-ons/add-ons-v3-create.md): Create a single add-on on a product you own. For batches without images, use the bulk endpoint (up to 100 per request).
- [Create Content](https://docs.publica.la/rest-api-v3/content/content-v3-create.md): Add new content items to your catalog. Supports all content types: PDF, EPUB, audiobooks, physical products, and external links.
- [Delete a Bundle](https://docs.publica.la/rest-api-v3/bundles/bundles-v3-delete.md): Remove a bundle from your store, as deleting it from the dashboard does.
- [Delete Content](https://docs.publica.la/rest-api-v3/content/content-v3-delete.md): Remove content items from your catalog. This operation is permanent and irreversible.
- [Get a Bundle](https://docs.publica.la/rest-api-v3/bundles/bundles-v3-get.md): Retrieve a bundle and, when you ask for them, its products, its price per currency and whether it can be sold right now.
- [Get Aggregate](https://docs.publica.la/rest-api-v3/aggregates/aggregates-v3-get.md): Retrieve the details of a specific sub-tenant (aggregate) by its ID.
- [Get Content](https://docs.publica.la/rest-api-v3/content/content-v3-get.md): Retrieve a specific content item by its internal ID or external ID.
- [Get List Items](https://docs.publica.la/rest-api-v3/lists/lists-v3-get-items.md): Read the products a list of the target user holds. Any list of the store can be read, private ones included.
- [Get Order](https://docs.publica.la/rest-api-v3/orders/orders-v3-get.md): Retrieve a specific order by its UUID or external ID.
- [List Add-ons](https://docs.publica.la/rest-api-v3/add-ons/add-ons-v3-list.md): Retrieve every add-on of a product you own, drafts included.
- [List Aggregates](https://docs.publica.la/rest-api-v3/aggregates/aggregates-v3-list.md): Retrieve a paginated list of all sub-tenants (aggregates) under your aggregator store.
- [List Bundles](https://docs.publica.la/rest-api-v3/bundles/bundles-v3-list.md): Retrieve the bundles of your store, newest first, with cursor-based pagination.
- [List Content](https://docs.publica.la/rest-api-v3/content/content-v3-list.md): Retrieve a paginated list of your store's catalog with powerful filtering, sorting, and response shaping capabilities.
- [List Lists](https://docs.publica.la/rest-api-v3/lists/lists-v3-list.md): Read every list the store shows a given user, or find one of them by id or name.
- [List Orders](https://docs.publica.la/rest-api-v3/orders/orders-v3-list.md): Retrieve a paginated list of orders with powerful filtering, sorting, and response shaping capabilities.
- [Lists API Overview](https://docs.publica.la/rest-api-v3/lists/lists-v3-overview.md): Read the reading lists of any user of your store, create, rename and delete them, and manage the products they hold, from your own platform.
- [Manage List Items](https://docs.publica.la/rest-api-v3/lists/lists-v3-items.md): Add and remove products in any list of any user of your store: the favorites list, a custom list the user created, or a list the user collaborates on. What you write here is what the user sees in the storefront and in the reader.
- [Manage Lists](https://docs.publica.la/rest-api-v3/lists/lists-v3-manage.md): Create, rename and delete the custom lists of any user of your store. A list created here is one of the user's lists from then on: it appears in List Lists and takes products through Manage List Items.
- [Migrating from create-article](https://docs.publica.la/rest-api-v3/add-ons/add-ons-v3-migration.md): The legacy POST /integration-api/v1/create-article endpoint is deprecated and will be sunset. The Add-ons API v3 replaces it with a complete resource: listing, creation (single and bulk), correction, deletion and a review lifecycle.
- [Orders API Overview](https://docs.publica.la/rest-api-v3/orders/orders-v3-overview.md): Manage customer purchases and content access on your Publica.la platform.
- [Orders API v1 → v3 Migration Guide](https://docs.publica.la/rest-api-v3/orders/orders-v1-to-v3-migration.md): This document provides a comprehensive migration guide from Orders API v1 to v3, including breaking changes, schema differences, and practical migration steps.
- [Permission Orders](https://docs.publica.la/rest-api-v3/orders/create-order/orders-v3-permission.md): Grant content access without creating payment records. Use when you process payments externally and only need Publica.la for content delivery.
- [Report Orders](https://docs.publica.la/rest-api-v3/orders/create-order/orders-v3-report.md): Assign content access and create payment records in Publica.la's financial system. Required for marketplace content sales or when you need financial tracking for externally processed payments.
- [Sale Orders](https://docs.publica.la/rest-api-v3/orders/create-order/orders-v3-sale.md): Initiate Publica.la's checkout flow where customers pay directly through the platform. Orders start with pending status and transition to approved after successful payment via integrated payment gateways (Stripe, MercadoPago, etc.).
- [Supported Content Languages](https://docs.publica.la/rest-api-v3/content/content-v3-supported-languages.md): Content languages define the language of the content itself (e.g., the language a book is written in). This is different from the store language, which controls the storefront interface.
- [Update & Cancel Orders](https://docs.publica.la/rest-api-v3/orders/orders-v3-update-cancel.md): Manage existing orders by updating expiration dates or canceling access entirely.
- [Update & Delete Add-ons](https://docs.publica.la/rest-api-v3/add-ons/add-ons-v3-update-delete.md): Correct an add-on's content, publish or unpublish it, or remove it.
- [Update a Bundle](https://docs.publica.la/rest-api-v3/bundles/bundles-v3-update.md): Change a bundle's details, replace its products, swap or drop its cover, and publish or unpublish it.
- [Update Aggregate](https://docs.publica.la/rest-api-v3/aggregates/aggregates-v3-update.md): Modify the configuration of an existing sub-tenant (aggregate). All fields are optional; only include fields you want to change.
- [Update Content](https://docs.publica.la/rest-api-v3/content/content-v3-update.md): Modify existing content items. Update metadata, pricing, access settings, files, or any other content attributes.

## webhooks

- [charge.paid](https://docs.publica.la/webhooks/charge-paid.md): Announces that a payment gateway charge was approved: a first purchase, a subscription renewal, a Publica One redemption or any later charge of an order. The payload below goes in the data field of the envelope, and follows the payload conventions.
- [Legacy Sale Webhook](https://docs.publica.la/webhooks/legacy-sale-webhook.md): The JWT sale webhook is deprecated and will be removed. It keeps working until then, but new integrations should use Webhooks. See Migrate to Webhooks. The sale notification email described below is not deprecated.
- [order.paid](https://docs.publica.la/webhooks/order-paid.md): Announces that an order was paid. The payload below goes in the data field of the envelope, and follows the payload conventions.
- [Webhooks](https://docs.publica.la/webhooks/overview.md): Publica.la sends a signed JSON POST request to each of your endpoints when an event it subscribes to happens in your store.