Skip to main content

Redirect Routes

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.

Reader by External ID​

Redirect users directly to the reader for a specific publication using its external identifier (such as ISBN).

Endpoint: GET https://{store-domain}/reader/external-id/{external_id}

Parameters:

  • external_id (path, required) - External identifier for the publication (e.g., ISBN, SKU, or custom ID)

Response:

  • Status: 301 (Permanent Redirect)
  • Redirects to: Reader URL for the publication matching the external ID

Use Cases:

  • Deep linking from external systems using ISBN or other stable identifiers
  • QR codes that open publications directly in the reader
  • Integration with discovery services that use standard identifiers

Example:

GET https://example.publica.la/reader/external-id/978-3-16-148410-0
→ Redirects to: https://example.publica.la/reader/issue/12345

Notes:

Redirect to Latest Issue​

Redirect users to the most recent products in your catalog, with optional filtering support.

Endpoint: GET https://{store-domain}/redirect-to-latest-issue

Parameters:

  • Query parameters for filtering (same as library filters):
    • free_issues - Show only free content
    • years - Filter by year
    • month - Filter by month
    • taxonomy - Filter by taxonomy term (e.g., category, collection, keyword)
    • bisac - Filter by BISAC category
    • author - Filter by contributor/author
    • file_type - Filter by content type (PDF, EPUB, etc.)
    • continue_reading - Show partially read content
    • language - Filter by language code

Response:

  • Status: 302 (Temporary Redirect)
  • Redirects to:
    • Reader URL for the latest/first filtered issue, OR
    • Library home if no issues match the filters

Use Cases:

  • "Read latest issue" buttons on external websites
  • Email campaigns that always link to the newest content
  • Landing pages that automatically open the current issue

Example:

GET https://example.publica.la/redirect-to-latest-issue?years=2024
→ Redirects to: https://example.publica.la/reader/issue/67890

GET https://example.publica.la/redirect-to-latest-issue?free_issues=1
→ Redirects to latest free issue

Notes:

  • Uses 302 (temporary) because the destination changes over time
  • IP-based authentication may apply
  • Falls back to library home if no content found

Latest Issue Cover Image​

Get a redirect to the cover image URL of the most recent publication, with optional filtering.

Endpoint: GET https://{store-domain}/latest-issue-cover-image

Parameters:

  • Query parameters for filtering (same as library filters):
    • free_issues - Show only free content
    • years - Filter by year
    • month - Filter by month
    • taxonomy - Filter by taxonomy term (e.g., category, collection, keyword)
    • bisac - Filter by BISAC category
    • author - Filter by contributor/author
    • file_type - Filter by content type (PDF, EPUB, etc.)
    • continue_reading - Show partially read content
    • language - Filter by language code

Response:

  • Status: 302 (Temporary Redirect)
  • Redirects to: Cover image URL for the latest filtered issue that matches the filters

Use Cases:

  • Dynamic images in email templates that always show the current issue
  • Social media posts with auto-updating cover images
  • External websites displaying "latest issue" covers
  • RSS feeds with current cover art

Example:

<!-- Email template that always shows latest cover -->
<img src="https://example.publica.la/latest-issue-cover-image?years=2024"
     alt="Latest Issue Cover" />
GET https://example.publica.la/latest-issue-cover-image?years=2024
→ Redirects to: https://cdn.publica.la/covers/issue-67890-cover.jpg

Notes:

  • Uses 302 (temporary) because the destination changes when new issues are published
  • Image URLs are served through CDN for optimal performance

Product Page by External ID​

Redirect users to the product page using an external identifier.

Endpoint: GET https://{store-domain}/library/publication/external-id/{external_id}

Parameters:

  • external_id (path, required) - External identifier for the publication (e.g., ISBN, SKU, or custom ID)

Response:

  • Status: 301 (Permanent Redirect)
  • Redirects to: Product page URL for the issue matching the external ID

Use Cases:

  • Deep linking to product pages from external catalogs
  • Marketing campaigns using stable ISBN-based URLs
  • Integration with discovery systems

Example:

GET https://example.publica.la/library/publication/external-id/978-3-16-148410-0
→ Redirects to: https://example.publica.la/library/publication/12345

Notes:

  • Returns 404 if no publication matches the external ID
  • IP-based authentication may apply
  • Use this for publication pages; use /reader/external-id/ for direct reader access

HTTP Status Codes​

301 (Permanent Redirect)​

Used for routes where the mapping is stable and unlikely to change:

  • External ID lookups (ISBN → publication ID mapping is permanent)

302 (Temporary Redirect)​

Used for routes where the destination changes over time:

  • Latest issue redirects (changes when new content is published)
  • Cover image redirects (updates with each new issue)

Automatically Open Checkout​

Automatically redirect users to the checkout flow when accessing product or subscription URLs, bypassing the product page. This feature streamlines the purchase process for marketing campaigns, direct sales links, and integrations.

For Products (Retail Purchases)​

Direct users immediately to checkout when accessing a product page.

URL Pattern: GET https://{store-domain}/library/publication/{issue_slug}?automatically_open_checkout=1

Parameters:

  • automatically_open_checkout (query, required) - Set to 1 or true to enable
  • currency (query, optional) - Currency code (e.g., USD, EUR, ARS)
  • coupon (query, optional) - Coupon code to apply at checkout

Behavior:

  1. If user already owns the product → Redirects to reader (with query params preserved)
  2. If guest user → Redirects to login, then to checkout after authentication
  3. If authenticated user without access:
    • Clears existing cart contents (ensures purchase of this specific item)
    • Adds product to cart
    • Redirects to checkout page
    • Automatically initiates payment flow

Use Cases:

  • Marketing campaign "Buy Now" buttons that skip the product page
  • Email newsletter CTAs with direct purchase links
  • QR codes on physical materials for instant purchase
  • Social media ads linking directly to checkout
  • Affiliate links with embedded coupon codes

Examples:

# Basic auto-checkout
https://demo.publica.la/library/publication/summer-edition-2024?automatically_open_checkout=1

# With specific currency
https://demo.publica.la/library/publication/summer-edition-2024?automatically_open_checkout=1&currency=USD

# Marketing campaign with coupon
https://demo.publica.la/library/publication/summer-edition-2024?automatically_open_checkout=1&currency=EUR&coupon=SAVE25

# Email newsletter CTA
<a href="https://store.publica.la/library/publication/latest-magazine?automatically_open_checkout=1&currency=USD&coupon=WELCOME10">
  Buy Now - 10% Off for New Readers!
</a>

Notes:

  • Clears existing cart contents to ensure user purchases the specified product
  • If currency is unsupported, checkout defaults to the main currency
  • Invalid coupon codes are ignored and won't be applied to the purchase

For Plans (Subscriptions)​

Direct users immediately to checkout when accessing a plan page.

URL Pattern: GET https://{store-domain}/subscribe/{plan_id}?automatically_open_checkout=1

Parameters:

  • automatically_open_checkout (query, required) - Set to 1 or true to enable
  • interval (query, optional) - Billing interval: month or annual
  • currency (query, optional) - Currency code (e.g., USD, EUR, ARS)
  • coupon (query, optional) - Coupon code to apply at checkout

Behavior:

  1. If user already subscribed to the plan → Redirects to library with info message
  2. If guest user → Redirects to login, then to checkout after authentication
  3. If authenticated user not subscribed:
    • Normalizes interval selection (falls back to plan's default if invalid)
    • Validates currency (falls back to plan's available currencies)
    • Clears existing cart contents (ensures subscription to this specific plan)
    • Adds plan with selected interval to cart
    • Redirects to checkout page
    • Automatically initiates payment flow

Interval Selection:

  • Uses the requested interval if available for the plan
  • Falls back to plan's default interval if unavailable
  • Valid values: month or annual

Currency Selection:

  • Uses the requested currency if available for the plan
  • Falls back to store's main currency if unavailable

Use Cases:

  • Marketing campaigns with pre-selected billing intervals
  • Annual plan promotions (force annual interval)
  • Email onboarding flows with embedded coupon codes
  • Partner integrations with specific pricing
  • Region-specific campaigns with pre-selected currency

Examples:

# Basic auto-checkout (uses plan's default interval)
https://demo.publica.la/subscribe/premium-plan?automatically_open_checkout=1

# Force annual billing with USD
https://demo.publica.la/subscribe/premium-plan?automatically_open_checkout=1&interval=annual&currency=USD

# Monthly subscription with welcome coupon
https://demo.publica.la/subscribe/basic-plan?automatically_open_checkout=1&interval=month&coupon=WELCOME50

# Private plan with signed URL
https://demo.publica.la/subscribe/corporate-plan?signature=abc123&expires=1234567890&automatically_open_checkout=1&interval=annual

# Email marketing campaign
<a href="https://store.publica.la/subscribe/premium?automatically_open_checkout=1&interval=annual&currency=EUR&coupon=ANNUAL20">
  Subscribe Annual - Save 20%!
</a>

Notes:

  • Clears existing cart contents to ensure user subscribes to the specified plan
  • Works with both public and private plans (private plans require signed URLs)
  • Supports recurring and prepaid plan types
  • Invalid interval falls back to plan's default interval
  • If plan only offers one interval, that interval is always used regardless of parameter

Authentication Flow​

For guest users accessing auto-checkout URLs:

  1. System sets the checkout URL as the "intended" destination
  2. Redirects to login page with action=purchase parameter
  3. After successful login, redirects to intended checkout URL
  4. Shopping cart is preserved via session ID across login
  5. Checkout flow automatically initiates

Login URL format:

/auth/login?intended_url={checkout_url}&action=purchase
X

Graph View