{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"redocly_category":"Guides","type":"markdown"},"seo":{"title":"Maintain your integration","description":"Everything about Mosaic Journeys, SDKs, and APIs","siteUrl":"https://developer.transmitsecurity.com/","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"maintain-your-integration","__idx":0},"children":["Maintain your integration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-mosaic-delivers-updates","__idx":1},"children":["How Mosaic delivers updates"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Mosaic follows a structured release process designed to give you visibility and control over how changes reach your environment."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Release notes"]}," announce upcoming changes for each platform version, including any breaking changes, new features, and deprecations."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Gradual regional rollout"]},". After sandbox, changes are promoted to production regions gradually over the course of several weeks rather than all at once."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Important"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-counts-as-a-breaking-change","__idx":2},"children":["What counts as a breaking change"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"table"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Integration surface"},"children":["Integration surface"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Non-breaking (no action needed)"},"children":["Non-breaking (no action needed)"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Breaking (requires adoption)"},"children":["Breaking (requires adoption)"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["APIs"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Adding new fields to JSON responses"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Adding new optional request parameters"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Relaxing permission requirements"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Changing required request parameters"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Restricting permissions"]}]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client SDKs"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Adding new fields to response objects"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Adding new optional parameters to function calls"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Replacing object types with compatible subtypes"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Renaming functions"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Changing required function parameters"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Altering return types in incompatible ways"]}]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Journeys and AuthScript"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Adding new optional step properties"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Adding optional parameters to AuthScript functions"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Adding properties to AuthScript return values"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Relaxing parameter validation"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Removing step properties"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Changing required AuthScript parameters"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Altering function behavior for existing inputs"]}]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Import/export formats"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Adding new columns or fields to exported files"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Removing or renaming columns"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Changing field data types"]}]}]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["UI presentation and visual rendering are not considered documented interfaces and may change between releases without prior notification."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices-for-resilient-integrations","__idx":3},"children":["Best practices for resilient integrations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Follow these practices to reduce the impact of platform changes and ensure your integration remains stable across releases."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"parse-api-responses-defensively","__idx":4},"children":["Parse API responses defensively"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"dont-hardcode-sdk-response-schemas","__idx":5},"children":["Don't hardcode SDK response schemas"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"design-flexible-journey-logic","__idx":6},"children":["Design flexible journey logic"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"build-adaptive-importexport-scripts","__idx":7},"children":["Build adaptive import/export scripts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"account-for-evolving-risk-models","__idx":8},"children":["Account for evolving risk models"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"monitor-release-notes","__idx":9},"children":["Monitor release notes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Review release notes before each platform update reaches your environment. Pay particular attention to breaking changes, new feature flags, and deprecation timelines."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"test-in-sandbox-before-adopting-changes","__idx":10},"children":["Test in sandbox before adopting changes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"plan-around-feature-flag-expiration","__idx":11},"children":["Plan around feature flag expiration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":12},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Review the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/deployment/plan_deployment"},"children":["Plan deployment"]}," guide to set up your deployment architecture."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Configure a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/deployment/custom_domains"},"children":["custom domain"]}," for first-party integration."]}]}]},"headings":[{"value":"Maintain your integration","id":"maintain-your-integration","depth":1},{"value":"How Mosaic delivers updates","id":"how-mosaic-delivers-updates","depth":2},{"value":"What counts as a breaking change","id":"what-counts-as-a-breaking-change","depth":2},{"value":"Best practices for resilient integrations","id":"best-practices-for-resilient-integrations","depth":2},{"value":"Parse API responses defensively","id":"parse-api-responses-defensively","depth":3},{"value":"Don't hardcode SDK response schemas","id":"dont-hardcode-sdk-response-schemas","depth":3},{"value":"Design flexible journey logic","id":"design-flexible-journey-logic","depth":3},{"value":"Build adaptive import/export scripts","id":"build-adaptive-importexport-scripts","depth":3},{"value":"Account for evolving risk models","id":"account-for-evolving-risk-models","depth":3},{"value":"Monitor release notes","id":"monitor-release-notes","depth":3},{"value":"Test in sandbox before adopting changes","id":"test-in-sandbox-before-adopting-changes","depth":3},{"value":"Plan around feature flag expiration","id":"plan-around-feature-flag-expiration","depth":3},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"markdown":{"toc":{"depth":2}},"seo":{"title":"Maintain your integration"}},"lastModified":"2026-05-12T14:15:13.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/deployment/maintain_integration","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}