techrar docs
Home
Solutions
Solutions
  • eCommerce SaaS
  • Meals SaaS
  • Meals Marketplaces
API
API
  • Merchant APIs
  • Customer App APIs
  • Meals APIs
Techrar Connect
Home
Solutions
Solutions
  • eCommerce SaaS
  • Meals SaaS
  • Meals Marketplaces
API
API
  • Merchant APIs
  • Customer App APIs
  • Meals APIs
Techrar Connect
  1. Offerings & Listings
  • GETTING STARTED
    • Marketplaces Overview
    • Account Setup
    • Authentication
    • Webhooks
    • Sales Channel Profile
  • Offerings & Listings
    • Display Providers
    • Plan Categories
    • Plans & Versions
    • Display Menus
  • Customer Profiles
    • Authenticating Customers
    • Customer Profile
    • Customer Location
  • Placing Orders
    • Place Subscription Order
    • Order Payment
  • Subscriptions
    • Subscription Lifecycle
    • Subscription Management
  • Complaints
    • Complaint Lifecycle
    • Complaint Management
  1. Offerings & Listings

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
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.
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

Display Plans in Your App#

1
List Available Plans
Use List Plans to fetch all plans for a specific city. You can filter by:
city_id (required)
restaurant_ids (optional): Filter by specific providers
tag_ids (optional): Filter by plan categories
is_marketplace_featured (optional): Show only featured plans
Request Example:
{
  "city_id": 1,
  "restaurant_ids": [18],
  "tag_ids": [26]
}
2
Display Plan Cards
Show each plan with:
Plan name and description
Provider information (from restaurant object)
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"
3
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)
4
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#

is_marketplace_active: Whether plan is currently available in marketplace
is_marketplace_featured: Whether plan should be highlighted
subscription_type: Type of subscription (e.g., "meals")
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
    }
  ]
}
Modified at 2025-12-04 11:41:42
Previous
Plan Categories
Next
Display Menus
Built with