Maintain your integration

Mosaic is a continuously evolving platform. As new capabilities are introduced and existing ones are refined, your integration should be designed to accommodate change without disruption. This guide explains how platform updates are delivered, what constitutes a breaking change, and how to build integrations that remain stable as Mosaic evolves.

How Mosaic delivers updates

Mosaic follows a structured release process designed to give you visibility and control over how changes reach your environment.

Release notes announce upcoming changes for each platform version, including any breaking changes, new features, and deprecations.
Sandbox-first deployment. All changes—including breaking changes—are deployed to sandbox environments before reaching production. This gives you a window to review release notes, test your integration, and validate behavior in a safe environment.
Gradual regional rollout. After sandbox, changes are promoted to production regions gradually over the course of several weeks rather than all at once.
Feature flags for breaking changes. When a release introduces a breaking change, it is gated behind a feature flag. This lets you decide when to start testing and adopting the change. Contact your Account Manager to discuss feature flag schedules and coordinate your adoption timeline.

Important

Each feature flag has an expiration date, typically 14–30 days after the release becomes available. After expiration, the new behavior is enabled automatically. Plan your testing and adoption accordingly.

What counts as a breaking change

A breaking change is any modification to a documented interface that can cause an existing, correctly implemented integration to stop working. The table below shows examples of changes that are and aren't considered breaking across different integration surfaces.

Integration surface	Non-breaking (no action needed)	Breaking (requires adoption)
APIs	Adding new fields to JSON responses Adding new optional request parameters Relaxing permission requirements	Changing required request parameters Restricting permissions
Client SDKs	Adding new fields to response objects Adding new optional parameters to function calls Replacing object types with compatible subtypes	Renaming functions Changing required function parameters Altering return types in incompatible ways
Journeys and AuthScript	Adding new optional step properties Adding optional parameters to AuthScript functions Adding properties to AuthScript return values Relaxing parameter validation	Removing step properties Changing required AuthScript parameters Altering function behavior for existing inputs
Import/export formats	Adding new columns or fields to exported files	Removing or renaming columns Changing field data types

Mosaic strives to maintain backward compatibility across all documented interfaces, which include officially documented APIs, client SDK APIs, journey step inputs and outputs, AuthScript function signatures and behavior, and documented import/export file formats.

Note

UI presentation and visual rendering are not considered documented interfaces and may change between releases without prior notification.

Best practices for resilient integrations

Follow these practices to reduce the impact of platform changes and ensure your integration remains stable across releases.

Parse API responses defensively

Configure your systems to ignore unexpected fields in JSON responses. Avoid strict schema validation that rejects responses containing new or unknown properties. This ensures your integration continues to work when Mosaic adds fields to API responses.

Don't hardcode SDK response schemas

SDK response objects may gain new fields or subtypes over time. Your client application should not rely on exact object shapes that break when additional data is present.

Design flexible journey logic

Build your journey and AuthScript logic to handle step outputs that may become richer over time. When processing step results, use field-level access rather than matching against a fixed structure.

Build adaptive import/export scripts

If your integration consumes exported files from Mosaic, ensure your data processing tools handle files with additional fields or columns without failing. Similarly, construct import files so they remain valid when the expected schema grows.

Account for evolving risk models

If you integrate with Fraud Prevention, be aware that risk scoring and recommendations may change over time as detection models are updated. Design your application logic to treat risk scores as relative indicators rather than fixed thresholds.

Monitor release notes

Review release notes before each platform update reaches your environment. Pay particular attention to breaking changes, new feature flags, and deprecation timelines.

Test in sandbox before adopting changes

Use your sandbox environment to validate integration behavior against new platform versions before they reach production. This is especially important when release notes announce breaking changes or when you plan to opt into a feature flag.

Plan around feature flag expiration

When a breaking change is introduced behind a feature flag, plan your testing and code updates within the flag's expiration window. This ensures you adopt the change on your own schedule rather than having it activate automatically.

Next steps

Review the Plan deployment guide to set up your deployment architecture.
Configure a custom domain for first-party integration.