Plans & Versions

Display provider meal plans and their subscription versions in your marketplace.

Overview

Plans are the core subscription offerings from providers. Each plan can have multiple versions with different durations, prices, and off-days, giving customers flexibility in choosing what works best for them.

Understanding Plans & Versions

What is a Plan?

A plan is a meal subscription offering created by a provider (e.g., "Keto Plan", "Family Meals"). Each plan includes:

Plan details (name, description, images)

Daily meal information (number of items, calories)

Associated categories/tags

Multiple versions with different options

What is a Plan Version?

A plan version represents a specific subscription option within a plan. For example, a "Keto Plan" might have:

5-day version (weekdays only) - 500 SAR

7-day version (full week) - 650 SAR

14-day version (2 weeks) - 1200 SAR

Each version has:

num_of_days: Number of subscription days

off_days: Days provider doesn't deliver (e.g., ["Fri", "Sat"])

original_price: Base price before discount

discount_percentage: Discount applied to this version

delivery_price: Delivery fee

min_start_date: Earliest date customer can start subscription

max_start_date: Latest date customer can start subscription

How does the discount_percentage work

discount_percentage only applies to the original_price (aka the meals price) but it doesn't apply to the delivery_price

Why min_start_date matters

min_start_date is calculated using the provider's start_after (cutoff hours) and closed_dates. This ensures customers can't subscribe to dates that are too soon or when the provider is closed (National Day for example).

Display Plans in Your App

List Available Plans

Use List Plans to fetch all plans for a specific city. You can filter by:

city_id (required)

Request Example:

{
  "city_id": 1,
}

Display Plan Cards

Show each plan with:

Plan name and description

Plan image

Plan tags/categories

Starting price (from cheapest version)

Daily information (daily_num_of_items, avg_daily_meal_calories)

Show Starting Price

Display the lowest price from all versions: "Starting from 500 SAR"

Show Plan Versions

When user selects a plan, display all available versions:

Duration (num_of_days days)

Price calculation: original_price - (original_price * discount_percentage / 100)

Off days (e.g., "No delivery on Fridays")

Delivery price (if applicable)

Available start date range (min_start_date to max_start_date)

Get Plan Details

When a customer selects a version, you can show the meal schedule (what customers get each day), using the Plan Details with:

plan_id: The selected plan ID

plan_version_id: The selected version ID

start_date (optional): Specific start date

This returns masters and dates arrays showing the daily meal options.

Populating Daily Options

This step is important to populate customer selections that is required in placing subscription step. More in Place Subscription Orders

Key Fields Explained

Plan Level

start_after: Provider cutoff hours for orders

skip_option_selection: Whether customer must select meal options or receives provider's choice

Version Level

total_num_of_items: Total meals in this subscription

pause_credits: Credits given when subscription is paused (if applicable)

num_of_pause_attempts: How many times customer can pause

min_of_pause_days: Minimum pause duration

Implementation Best Practices

Plan Listing

Cache plan images for faster loading

Show featured plans first

Filter by customer's selected city

Display provider badges/ratings if available

Version Selection

Highlight the best value (usually longest duration)

Show savings clearly (e.g., "Save 15%")

Indicate which version is most popular

Disable versions if min_start_date is too far in the future

Pricing Display

Always show final price after discount

Include delivery price separately

Show price per day for easy comparison

Display "Starting from" for plan cards

Date Validation

Respect min_start_date and max_start_date

Block dates in provider's closed_dates

Block days in version's off_days

Show calendar with available dates only

Example Response Structure

{
  "id": 2445,
  "name_en": "Keto Plan",
  "name_ar": "خطة كيتو",
  "description_en": "High protein, low carb meals",
  "image": "https://cdn.techrar.com/plans/keto.png",
  "daily_num_of_items": 3,
  "avg_daily_meal_calories": 1800,
  "is_marketplace_active": true,
  "is_marketplace_featured": true,
  "restaurant": {
    "id": 18,
    "name_en": "Healthy Kitchen",
    "logo": "https://cdn.techrar.com/logos/healthy-kitchen.png"
  },
  "plan_tags": [
    {
      "id": 26,
      "tag_en": "Keto",
      "tag_ar": "كيتو"
    }
  ],
  "versions": [
    {
      "id": 5001,
      "num_of_days": 5,
      "off_days": ["Fri", "Sat"],
      "original_price": 500,
      "discount_percentage": 10,
      "delivery_price": 0,
      "min_start_date": "2025-11-25",
      "max_start_date": "2025-12-31",
      "total_num_of_items": 15
    },
    {
      "id": 5002,
      "num_of_days": 10,
      "off_days": ["Fri", "Sat"],
      "original_price": 950,
      "discount_percentage": 15,
      "delivery_price": 0,
      "min_start_date": "2025-11-25",
      "max_start_date": "2025-12-31",
      "total_num_of_items": 30
    }
  ]
}

Overview#

Understanding Plans & Versions#

What is a Plan?#

What is a Plan Version?#

Display Plans in Your App#

Key Fields Explained#

Plan Level#

Version Level#

Implementation Best Practices#

Plan Listing#

Version Selection#

Pricing Display#

Date Validation#

Example Response Structure#

Overview

Understanding Plans & Versions

What is a Plan?

What is a Plan Version?

Display Plans in Your App

Key Fields Explained

Plan Level

Version Level

Implementation Best Practices

Plan Listing

Version Selection

Pricing Display

Date Validation

Example Response Structure