Documents

A document is an individual content item within a collection. While collections define the structure, documents contain the actual content that will be displayed to your users. Each document represents a single piece of content like a promotional banner, a coupon, or an announcement.

Document Structure

Every document has both system-managed properties and custom attributes:

System Properties

Key Properties Explained

• documentKey: Unique identifier (UUID), auto-generated or provided for upsert
• slug: Optional user-friendly identifier (e.g., "summer-sale-2024")
• attrs: JSONB object containing your custom content fields
• status: Either "draft" (not visible to clients) or "published" (visible)
• locale: Language/region code ("" for default, "en", "es", etc.)
• fromDate: When the document becomes visible (optional scheduling)
• toDate: When the document becomes hidden (optional scheduling)
• audienceKeys: Array of segment identifiers for targeted content
• createdAt / updatedAt: Automatic timestamps

Document Attributes (attrs)

The attrs object is where your actual content lives. For the Manager App, the standard structure includes:

{
  "attrs": {
    "name": "50% Off Summer Sale",
    "description": "Save big on summer essentials. Limited time offer!",
    "pictureUrl": "https://example.com/images/summer-sale.jpg",
    "pictureAlt": "Summer sale banner with 50% off text",
    "buttonName": "Shop Now",
    "link": "https://shop.example.com/sale",
    "displayOrder": 1
  }
}

Standard Attributes

Attribute	Type	Required	Description
name	string	Yes	Display title
description	string	No	Additional details or body text
pictureUrl	string	Yes	Image URL for visual content
pictureAlt	string	Yes	Accessibility text for the image
buttonName	string	No	Call-to-action button text
link	string	No	External URL for navigation
displayOrder	number	No	Sort order for rendering (lower = first)
couponBookKey	string	No	Link to coupon book (coupon collections only)

Note: The attrs object is flexible and can store any JSON structure. The fields above are specific to the Manager App UI implementation.

Slug Uniqueness

Slugs must be unique within a collection but NOT globally. This means:

• ✅ collection-A/banner-1 and collection-B/banner-1 - Valid (different collections)
• ❌ collection-A/banner-1 and collection-A/banner-1 - Invalid (same collection)

When creating documents in the Manager App, slugs are auto-generated from the name but can be customized. The system validates uniqueness before saving.

Display Order

The displayOrder attribute controls how documents are sorted when displayed to users. Lower numbers appear first:

• displayOrder: 1 - First position
• displayOrder: 2 - Second position
• displayOrder: 3 - Third position

Client applications should always fetch documents with ?sort=displayOrder:asc to maintain the intended order.

Note: In the Manager App UI, collections are limited to a maximum of 5 documents for optimal user experience and performance.

Multi-Locale Support

Documents can exist in multiple language variants:

// Default locale (empty string)
{
  "documentKey": "promo-001",
  "locale": "",
  "attrs": {
    "name": "Summer Sale",
    "description": "Limited time offer!"
  }
}

// Spanish locale
{
  "documentKey": "promo-001",
  "locale": "es",
  "attrs": {
    "name": "Venta de Verano",
    "description": "¡Oferta por tiempo limitado!"
  }
}

Each locale is stored as a separate database row with the same documentKey. Client applications can fetch the appropriate locale using the locale query parameter.

Document Lifecycle

1. Create: Add a new document to a collection
2. Draft: Save changes without making them visible to clients
3. Publish: Make the document available via the API
4. Schedule: Set date ranges for automatic visibility control
5. Update: Modify content while maintaining or changing publish status
6. Soft Delete: Mark as deleted without removing data (audit trail)

Upsert Semantics

The CMS API supports "upsert" operations - create if doesn't exist, update if it does:

• With documentKey: If the key exists, the document is updated; otherwise, it's created
• Without documentKey: Always creates a new document with an auto-generated key

This is particularly useful for batch operations and idempotent content updates.

Examples

Promotional Banner

{
  "documentKey": "banner-summer-2024",
  "slug": "summer-sale",
  "attrs": {
    "name": "Summer Mega Sale",
    "description": "Up to 70% off on selected items",
    "pictureUrl": "https://cdn.example.com/banners/summer.jpg",
    "pictureAlt": "Summer sale banner",
    "buttonName": "Shop Sale",
    "link": "https://shop.example.com/summer-sale",
    "displayOrder": 1
  },
  "status": "published",
  "fromDate": "2024-06-01T00:00:00Z",
  "toDate": "2024-08-31T23:59:59Z",
  "audienceKeys": ["all-members"]
}

Announcement (No Call-to-Action)

{
  "documentKey": "announcement-001",
  "slug": "maintenance-notice",
  "attrs": {
    "name": "Scheduled Maintenance",
    "description": "Our app will be undergoing maintenance on June 15th from 2-4 AM.",
    "pictureUrl": "https://cdn.example.com/icons/maintenance.png",
    "pictureAlt": "Maintenance icon",
    "displayOrder": 1
  },
  "status": "published",
  "fromDate": "2024-06-10T00:00:00Z",
  "toDate": "2024-06-16T00:00:00Z"
}