Circulars API

The Circulars API provides access to digital flyers and promotional circulars with complete layout data for rendering.

Endpoints

Method	Endpoint	Description
GET	/api/v1/public/circulars	List available circulars
GET	/api/v1/public/circulars/{id}	Get circular with full layout

List Circulars

Retrieve a paginated list of ready and in-use circulars.

GET /api/v1/public/circulars

Query Parameters

Parameter	Type	Default	Description
per_page	integer	20	Number of items per page (1-50)
page	integer	1	Page number
format	string	-	Filter by paper format

Format Values

Format	Description
tabloid	Tabloid size (11" x 17")
letter	Letter size (8.5" x 11")
custom	Custom dimensions

Visibility Rules

Only circulars with the following statuses are returned:

• ready - Circular is complete and ready for use
• in_use - Circular is currently active

Draft and archived circulars are not accessible via the public API.

Example Request

const response = await fetch(
  'https://cdn.engagehq.retailsuccessplatform.com/api/v1/public/circulars?format=tabloid&per_page=5',
  {
    headers: {
      'Authorization': `Bearer ${token}`,
    },
  }
);

Response

{
  "success": true,
  "message": "Circulars retrieved",
  "data": [
    {
      "id": "cir_00000a1B2c3D4e5",
      "name": "Weekly Ad - June 1-7",
      "description": "This week's best deals on groceries and household items",
      "status": "in_use",
      "total_pages": 8,
      "format": "tabloid",
      "dimensions": {
        "width": 800,
        "height": 1000
      },
      "thumbnail_url": "https://cdn.example.com/circulars/weekly-jun-1/thumb.jpg",
      "last_used_at": "2024-06-01T08:00:00+00:00",
      "created_at": "2024-05-25T14:30:00+00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 2,
    "per_page": 5,
    "total": 8
  }
}

Response Fields (List)

Field	Type	Description
id	string	Unique circular identifier (hashkey)
name	string	Circular name
description	string	Brief description
status	string	Current status (ready or in_use)
total_pages	integer	Number of pages
format	string	Paper format
dimensions	object	Size in pixels
dimensions.width	integer	Width in pixels
dimensions.height	integer	Height in pixels
thumbnail_url	string	Preview thumbnail URL
last_used_at	string	ISO 8601 timestamp of last use
created_at	string	ISO 8601 creation timestamp

Sort Order

Results are sorted by:

1. Most recently used (last_used_at descending)
2. Most recently created (created_at descending)

Caching

Cache	TTL
Browser (max-age)	60 seconds
CDN	24 hours (invalidated on publish)
Stale-while-revalidate	300 seconds

---

Get Circular

Retrieve a single circular with full layout data for rendering.

GET /api/v1/public/circulars/{id}

Path Parameters

Parameter	Type	Description
id	string	The circular hashkey (e.g., cir_00000a1B2c3D4e5)

Example Request

const response = await fetch(
  'https://cdn.engagehq.retailsuccessplatform.com/api/v1/public/circulars/cir_00000a1B2c3D4e5',
  {
    headers: {
      'Authorization': `Bearer ${token}`,
    },
  }
);

Response

{
  "success": true,
  "message": "Circular retrieved",
  "data": {
    "id": "cir_00000a1B2c3D4e5",
    "name": "Weekly Ad - June 1-7",
    "description": "This week's best deals on groceries and household items",
    "status": "in_use",
    "total_pages": 8,
    "format": "tabloid",
    "dimensions": {
      "width": 800,
      "height": 1000
    },
    "thumbnail_url": "https://cdn.example.com/circulars/weekly-jun-1/thumb.jpg",
    "last_used_at": "2024-06-01T08:00:00+00:00",
    "created_at": "2024-05-25T14:30:00+00:00",
    "layout_data": {
      "pages": [
        {
          "page_number": 1,
          "regions": [
            {
              "id": "region_1",
              "position": { "x": 0, "y": 0 },
              "dimensions": { "width": 400, "height": 300 },
              "content": {
                "type": "image",
                "url": "https://cdn.example.com/images/hero.jpg",
                "alt": "Summer savings"
              }
            },
            {
              "id": "region_2",
              "position": { "x": 0, "y": 300 },
              "dimensions": { "width": 200, "height": 200 },
              "content": {
                "type": "product",
                "product_id": "prd_00000x1Y2z3A4b5",
                "price": "$2.99",
                "sale_price": "$1.99"
              }
            }
          ]
        }
      ],
      "fonts": ["Arial", "Helvetica", "Open Sans"],
      "colors": {
        "primary": "#FF0000",
        "secondary": "#0066CC",
        "background": "#FFFFFF"
      }
    },
    "metadata": {
      "created_by": "jane.doe@example.com",
      "version": 3,
      "last_modified": "2024-05-30T16:45:00+00:00",
      "effective_date": "2024-06-01",
      "end_date": "2024-06-07"
    }
  }
}

Additional Response Fields (Detail)

The detail response includes all list fields plus:

Field	Type	Description
layout_data	object	Complete layout for rendering
layout_data.pages	array	Array of page objects
layout_data.fonts	array	Fonts used in the circular
layout_data.colors	object	Color palette
metadata	object	Extended metadata

Layout Data Structure

Page Object

Field	Type	Description
page_number	integer	Page number (1-indexed)
regions	array	Array of region objects

Region Object

Field	Type	Description
id	string	Unique region identifier
position	object	X/Y coordinates
dimensions	object	Width/height in pixels
content	object	Region content (varies by type)

Rendering Tips

Scaling

Use the dimensions to calculate proper scaling ratios. The layout is designed for the specified width/height in pixels.

Fonts

Ensure fonts listed in layout_data.fonts are loaded before rendering to prevent layout shifts.

Caching

Cache	TTL
Browser (max-age)	300 seconds
CDN	24 hours (invalidated on publish)
Stale-while-revalidate	300 seconds

---

Error Responses

400 Bad Request

{
  "success": false,
  "message": "Organization context required",
  "errors": null
}

404 Not Found

{
  "success": false,
  "message": "Circular not found",
  "errors": null
}

The circular either:

• Doesn't exist
• Is not in ready or in_use status
• Belongs to a different organization

---

Changelog

Date	Change
2026-02-23	Updated for CloudFront CDN delivery.
2026-01-28	Expanded documentation.
2026-01-15	Initial publication.