Add Manage Premium Subscription Example and Update Examples Section

README.md

@@ -22,7 +22,7 @@ To use the PayPal Subscriptions connector, you must have access to a [PayPal Dev
 
 3. Create a Business account.
    > Note: Some PayPal options and features may vary by region or country; check availability before creating an account.
-   
+
    ![Create business account](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-paypal.subscriptions/main/docs/setup/resources/create-account.png)
 
 ### Step 2: Create a REST API App
@@ -129,6 +129,8 @@ The `PayPal Subscriptions` connector provides practical examples illustrating us
 
 1. [**Create and List Plans**](https://github.com/ballerina-platform/module-ballerinax-paypal.subscriptions/tree/main/examples/create-and-list-plans): Create a subscription plan and list all available plans.
 2. [**Monitor and Manage Subscription Status**](https://github.com/ballerina-platform/module-ballerinax-paypal.subscriptions/tree/main/examples/monitor-and-manage-subscription): Retrieve a subscription’s status and suspend or reactivate it based on its state.
+3. [**Manage Premium Subscription**](https://github.com/ballerina-platform/module-ballerinax-paypal.subscriptions/tree/main/examples/manage-premium-subscription): Create a subscription plan, enroll a customer, and retrieve subscription details for a premium membership.
+
 
 ## Build from the source
 

ballerina/README.md

@@ -16,7 +16,7 @@ To use the PayPal Subscriptions connector, you must have access to a [PayPal Dev
 
 3. Create a Business account.
    > Note: Some PayPal options and features may vary by region or country; check availability before creating an account.
-   
+
    ![Create business account](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-paypal.subscriptions/main/docs/setup/resources/create-account.png)
 
 ### Step 2: Create a REST API App
@@ -123,3 +123,4 @@ The `PayPal Subscriptions` connector provides practical examples illustrating us
 
 1. [**Create and List Plans**](https://github.com/ballerina-platform/module-ballerinax-paypal.subscriptions/tree/main/examples/create-and-list-plans): Create a subscription plan and list all available plans.
 2. [**Monitor and Manage Subscription Status**](https://github.com/ballerina-platform/module-ballerinax-paypal.subscriptions/tree/main/examples/monitor-and-manage-subscription): Retrieve a subscription’s status and suspend or reactivate it based on its state.
+3. [**Manage Premium Subscription**](https://github.com/ballerina-platform/module-ballerinax-paypal.subscriptions/tree/main/examples/manage-premium-subscription): Create a subscription plan, enroll a customer, and retrieve subscription details for a premium membership.

examples/README.md

@@ -4,6 +4,7 @@ The `ballerinax/paypal.subscriptions` connector provides practical examples illu
 
 1. [Create and list plans](https://github.com/ballerina-platform/module-ballerinax-paypal.subscriptions/tree/main/examples/create-and-list-plans/create-and-list-plans.md) - Create a subscription plan and list all available plans for subscription-based services.
 2. [Monitor and manage subscription status](https://github.com/ballerina-platform/module-ballerinax-paypal.subscriptions/tree/main/examples/monitor-and-manage-subscription/monitor-and-manage-subscription.md) - Retrieve a subscription's status and suspend or reactivate it based on its current state.
+3. [**Manage Premium Subscription**](https://github.com/ballerina-platform/module-ballerinax-paypal.subscriptions/tree/main/examples/manage-premium-subscription) - Create a subscription plan, enroll a customer, and retrieve subscription details for a premium membership.
 
 ## Prerequisites
 
@@ -13,7 +14,7 @@ The `ballerinax/paypal.subscriptions` connector provides practical examples illu
     ```toml
     clientId = "<your_client_id>"
     clientSecret = "<your_client_secret>"
-    productId = "<your_product_id>"  # Required for create-and-list-plans
+    productId = "<your_product_id>"  # Required for create-and-list-plans, manage-premium-subscription
     subscriptionId = "<your_subscription_id>"  # Required for monitor-and-manage-subscription
     ```
 

examples/manage-premium-subscription/.github/README.md

@@ -0,0 +1 @@
+../manage-premium-subscription.md

examples/manage-premium-subscription/Ballerina.toml

@@ -0,0 +1,8 @@
+[package]
+org = "wso2"
+name = "manage_premium_subscription"
+version = "0.1.0"
+distribution = "2201.12.7"
+
+[build-options]
+observabilityIncluded = true

examples/manage-premium-subscription/main.bal

@@ -0,0 +1,129 @@
+// Copyright (c) 2025, WSO2 LLC. (http://www.wso2.com).
+//
+// WSO2 LLC. licenses this file to you under the Apache License,
+// Version 2.0 (the "License"); you may not use this file except
+// in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+import ballerina/io;
+import ballerina/time;
+import ballerinax/paypal.subscriptions as paypal;
+
+configurable string clientId = ?;
+configurable string clientSecret = ?;
+configurable string productId = ?;
+
+final paypal:Client paypal = check new paypal:Client({auth: {clientId, clientSecret}});
+
+public function main() returns error? {
+    // Create a subscription plan with trial and regular billing
+    paypal:PlanRequestPOST planPayload = {
+        product_id: productId,
+        name: "Premium Membership",
+        description: "Monthly subscription for premium access with a trial period",
+        status: "ACTIVE",
+        billing_cycles: [
+            {
+                frequency: {
+                    interval_unit: "MONTH",
+                    interval_count: 1
+                },
+                tenure_type: "TRIAL",
+                sequence: 1,
+                total_cycles: 1,
+                pricing_scheme: {
+                    fixed_price: {
+                        value: "1.00",
+                        currency_code: "USD"
+                    }
+                }
+            },
+            {
+                frequency: {
+                    interval_unit: "MONTH",
+                    interval_count: 1
+                },
+                tenure_type: "REGULAR",
+                sequence: 2,
+                total_cycles: 0, // Infinite regular cycles
+                pricing_scheme: {
+                    fixed_price: {
+                        value: "15.00",
+                        currency_code: "USD"
+                    }
+                }
+            }
+        ],
+        payment_preferences: {
+            auto_bill_outstanding: true,
+            setup_fee: {
+                value: "0.00",
+                currency_code: "USD"
+            },
+            setup_fee_failure_action: "CONTINUE",
+            payment_failure_threshold: 3
+        }
+    };
+    paypal:Plan createdPlan = check paypal->/plans.post(planPayload);
+    io:println("Created Plan ID: ", createdPlan.id, ", Name: ", createdPlan.name);
+
+    // Create a subscription for a customer
+    string startTime = time:utcToString(time:utcAddSeconds(time:utcNow(), 120)); // Start in 2 minutes
+    paypal:SubscriptionRequestPost subscriptionPayload = {
+        plan_id: check createdPlan.id.ensureType(string),
+        start_time: startTime,
+        subscriber: {
+            name: {
+                given_name: "Jane",
+                surname: "Smith"
+            },
+            email_address: "jane.smith@example.com",
+            shipping_address: {
+                name: {
+                    full_name: "Jane Smith"
+                },
+                address: {
+                    address_line_1: "123 Main Street",
+                    admin_area_2: "San Francisco",
+                    admin_area_1: "CA",
+                    postal_code: "94105",
+                    country_code: "US"
+                }
+            }
+        },
+        application_context: {
+            brand_name: "SaaS Platform Inc",
+            locale: "en-US",
+            shipping_preference: "SET_PROVIDED_ADDRESS",
+            user_action: "SUBSCRIBE_NOW",
+            payment_method: {
+                payer_selected: "PAYPAL",
+                payee_preferred: "IMMEDIATE_PAYMENT_REQUIRED"
+            },
+            return_url: "https://saasplatform.com/return",
+            cancel_url: "https://saasplatform.com/cancel"
+        }
+    };
+    paypal:Subscription createdSubscription = check paypal->/subscriptions.post(subscriptionPayload);
+    io:println("Created Subscription ID: ", createdSubscription.id, ", Status: ", createdSubscription.status);
+    string createdSubscriptionId = check createdSubscription.id.ensureType(string);
+
+    // Retrieve and display subscription details
+    paypal:Subscription subscriptionDetails = check paypal->/subscriptions/[createdSubscriptionId].get();
+    io:println("\nSubscription Details:");
+    io:println("  ID: ", subscriptionDetails.id);
+    io:println("  Plan ID: ", subscriptionDetails.plan_id);
+    io:println("  Status: ", subscriptionDetails.status);
+    paypal:Subscriber subscriber = check subscriptionDetails.subscriber.ensureType(paypal:Subscriber);
+    io:println("  Subscriber: ", subscriber.name?.full_name ?: "N/A");
+    io:println("  Start Time: ", subscriptionDetails.start_time ?: "N/A");
+}

examples/manage-premium-subscription/manage-premium-subscription.md

@@ -0,0 +1,27 @@
+## Manage Premium Subscription
+
+This example demonstrates how to use the PayPal Subscriptions API to create a subscription plan, enroll a customer in a subscription, and retrieve subscription details. It simulates a real-world SaaS platform managing a "Premium Membership" with a trial period, suitable for applications handling subscription-based services like streaming or software platforms.
+
+## Prerequisites
+
+### 1. Set up PayPal Developer Account
+
+Refer to the [Setup Guide](https://github.com/ballerina-platform/module-ballerinax-paypal.subscriptions#setup-guide) to obtain necessary credentials (`clientId`, `clientSecret`) and create a product to get a `productId`.
+
+### 2. Configuration
+
+Create a `Config.toml` file in the example's root directory and provide your PayPal credentials and product ID as follows:
+
+```toml
+clientId = "<your_client_id>"
+clientSecret = "<your_client_secret>"
+productId = "<your_product_id>"
+```
+
+## Run the Example
+
+Execute the following command to run the example:
+
+```bash
+bal run
+```