Skip to content
Magicline Open API
/
/
Working with idle periods
Last updated

Working with idle periods (Freeze Periods)

Intro

Use case description of how idle periods can be managed via the Open API and how to use Freeze Period endpoints to enable membership freezing and verification via the Open API.

Relevant Endpoints

Freeze Period Configuration in the

The system offers flexible configuration for membership suspensions (Freeze Periods) which is exposed via the Open API. The general setup is designed to allow members to self-manage their contract pauses within defined limits.

An important aspect to note is that the following configuration requirements in the must be met for Freeze Periods to be processed via the Open API:

  • The contract type must allow Freeze Periods - Contracts can be configured to ignore Freeze Periods entirely.
  • Limits on the number of Freeze Periods or total duration must be defined (e.g., "max 12 months per contract lifetime", "max 4 weeks per year").
  • Allowable reasons (e.g., "Vacation", "Illness", "Military Service") must be configured and whitelisted for Open API access.
  • Fees (if applicable) and retroactive booking rules must be set - Some configurations allow free terms, others charge monthly fees.
  • Temporal unit restrictions - Configuration defines whether Freeze Periods are measured in time units (DAY, WEEK, MONTH).
  • Amendment verification requirements - Configuration determines if changes are auto-accepted or require manual approval.

Display, Validation and Creation of Freeze Periods

The UX flow envisioned here follows the following logic:

1. Retrieve Configuration

Get idle period config allows partners to retrieve the rules for a specific customer contract. This includes:

  • The allowed temporalUnit (e.g., DAY, WEEK, MONTH)
  • maxTerms - maximum duration allowed
  • Available idlePeriodReasons with their IDs and whether documents are required
  • Associated idlePeriodFee (amount and currency)
  • firstPossibleStartDate- earliest date the Freeze Period can start
  • unlimitedAllowed - whether unlimited/indefinite Freeze Periods are permitted
  • dayBasedTermShorteningAllowed - whether explicit end dates can be used during updates
  • freeTerms - number of terms that are free of charge
  • idlePeriodCreationStatus - whether changes require verification

Use this data to:

  • Display available reasons in your UI dropdown
  • Show applicable fees to the user
  • Enforce maximum duration limits
  • Show the earliest possible start date

2. Display Existing Freeze Periods

Get idle periods or idle period amendment returns a list of existing future and past Freeze Periods to display the current status.

Use this data to:

  • Show customers their Freeze Period history
  • Display upcoming planned suspensions
  • Indicate which periods are pending approval
  • Allow users to manage (update/withdraw) future Freeze Periods
  • Show associated costs for each period

3. Validate Before Creating

Validate idle period validation request is used to check if a specific date range and reason selected by the user are valid before attempting to submit the change.

Use this to:

  • Overlapping periods with existing Freeze Periods
  • Maximum duration violations (exceeding maxTerms)
  • Invalid start dates (before firstPossibleStartDate)
  • Missing required documents
  • Contract-specific restrictions

4. Create the Freeze Period

Once the request is validated, partners can proceed with the actual suspension using the Create idle period or idle period amendment endpoint. This creates the amendment in the system and adjusts the contract end dates or billing accordingly.

Important: This endpoint uses multipart/form-data format because it may require document uploads for certain reasons.

Modifying and Canceling Freeze Periods

The Open API also supports the management of existing Freeze Periods.

1. Preview Changes Before Updating

Before modifying, use PUT get preview of an updated idle period charges and fees to show customers what charges or refunds will result from the change.

Use this to:

  • Show customers the new end date before they confirm
  • Display any additional charges (extending duration beyond free terms)

Special Case: Day-Based Term Shortening

If dayBasedTermShorteningAllowed is true in the configuration, you can use the endDate field to shorten a freeze Period to a specific date, regardless of the configured temporal unit: This allows ending a freeze period on an arbitrary date rather than rounding to complete months/weeks.

2. Update the Freeze Period

Update a contract idle period allows partners to modify the dates or details of a planned suspension.

Important: This endpoint uses multipart/form-data format because it may require document uploads for certain reasons.

Restrictions:

  • Can only update freeze periods that haven't started yet or are within the modification window.
  • Must respect the same validation rules as creation (max terms, overlaps, etc.)

Common update scenarios:

  • Extend duration - Increase termValue to pause longer (may incur additional fees)
  • Shorten duration - Decrease termValue or use endDate if day-based shortening is allowed
  • Change start date - Move the Freeze Period to a different time window
  • Change reason - Update the reason (may require adding/changing document)

3. Retrieve Specific Freeze Period Details

Get contract idle period by id allows you to fetch the current state of a specific Freeze Period.

Use this to:

  • Refreshing the data after an update
  • Checking if a pending period has been verified
  • Retrieving the document URL if it has expired

4. Cancel a Freeze Period

Withdraw idle period or idle period amendment is used to cancel a scheduled freeze period that has not yet started or is within the cancellation window.

Use this to:

  • Customer changes their mind and no longer needs the suspension
  • Cancel a pending verification request before it's approved

Important:

  • Withdrawn Freeze Periods cannot be reactivated - a new one must be created
  • Withdrawal is typically only allowed for future Freeze Periods or those within a grace period

Handling Unlimited Freeze Periods

Unlimited (indefinite) Freeze Periods allow members to freeze contracts without specifying an end date. This must be enabled in the configuration (unlimitedAllowed: true).

Use this where:

  • Members have long-term circumstances preventing usage (e.g., extended travel, pregnancy, chronic injury)
  • The business model allows open-ended suspensions with monthly fees
  • Members can later specify an end date when they're ready to return

Creating an Unlimited Freeze Period

To create an unlimited Freeze Period, set unlimited: true in the request and omit the temporalUnit and termValue fields.

Ending an Unlimited Freeze Period

There are three ways to end an unlimited Freeze Period:

Option 1: Update to a Fixed Duration

Convert the unlimited period to a fixed-term.

Option 2: Use Day-Based Term Shortening (if enabled)

If dayBasedTermShorteningAllowed: true in the configuration, you can specify an exact end date. This ends the Freeze Period on the exact date, regardless of temporal unit configuration.

Option 3: Withdraw the Freeze Period

Cancel the unlimited Freeze Period entirely, which immediately reactivates the contract.

Complete Workflow Examples

Example 1: Simple 1-Month Freeze

Scenario: Customer going on vacation for 1 month

1. GET /v1/memberships/12345/self-service/idle-periods/config
  → Check maxTerms (≥1), temporalUnit (MONTH), firstPossibleStartDate
2. POST /v1/memberships/12345/self-service/idle-periods/validate
  {
    "startDate": "2026-02-01",
    "temporalUnit": "MONTH",
    "termValue": 1,
    "reasonId": 101
  }
3. POST /v1/memberships/12345/self-service/idle-periods
  (multipart with same data)

Example 2: Create Unlimited, Then End After 2 Months

Scenario: Customer unsure of return date, decides after 2 months

1. GET config → unlimitedAllowed: true
2. POST /v1/memberships/12345/self-service/idle-periods
  {
    "startDate": "2026-02-01",
    "reasonId": 101,
    "unlimited": true
  }
[2 months later, customer ready to return]
3. PUT /v1/memberships/12345/self-service/idle-periods/5004/preview
  {
    "startDate": "2026-02-01",
    "endDate": "2026-03-31",
    "reasonId": 101,
    "unlimited": false
  }
4. PUT /v1/memberships/12345/self-service/idle-periods/5004

Example 3: Extend Existing Freeze Period

Scenario: Customer needs to extend vacation by 1 more month

1. GET /v1/memberships/12345/idle-periods
  → Find existing: { "id": 5003, "endDate": "2026-02-28", "termValue": 1 }
2. PUT /v1/memberships/12345/self-service/idle-periods/5003/preview
  {
    "startDate": "2026-02-01",
    "temporalUnit": "MONTH",
    "termValue": 2,
    "reasonId": 101
  }
3. Customer confirms → PUT /v1/memberships/12345/self-service/idle-periods/5003
  (same data)

Example 4: Cancel Future Freeze Period

Scenario: Customer changes mind before Freeze Period starts

1. GET /v1/memberships/12345/idle-periods
  → Find future period: { "id": 5003, "startDate": "2026-03-01" }
2. DELETE /v1/memberships/12345/self-service/idle-periods/5003

Example 5: Document-Required Freeze Period with Verification

Scenario: Medical leave requiring doctor's note and staff approval

1. GET config → Find reasonId 102 with documentRequired: true
2. POST /v1/memberships/12345/self-service/idle-periods
  (multipart with medical certificate PDF)
  {
    "startDate": "2026-02-01",
    "temporalUnit": "MONTH",
    "termValue": 2,
    "reasonId": 102
  }
[Staff approves]
[Alternative: rejection]

Idle periods collection webhook events

In order to inform partners about changes to idle period statuses, the system offers relevant webhook events. When an idle period is created, updated, or cancelled, partners can use the corresponding contract amendment events to keep their local systems in sync.

Full list of events can be found here: Event types

Previous page
Next page