# Managing SIM Subscriptions

## Overview

This journey covers everything a customer can do with an active SIM subscription in the portal. It includes viewing SIM details and data usage, changing plans, topping up data, reissuing a SIM card, managing voice features, viewing call and SMS history, and cancelling the service. SIM operations flow through the Freebit MVNO platform and are tracked in WHMCS for billing.

## Portal Flow

### Viewing a SIM Subscription

1. Go to **Subscriptions** from the sidebar.
2. The subscriptions list shows all services with their name, status, billing amount, cycle, and next due date.
3. Click on a SIM subscription (product name contains "SIM") to open the detail page.
4. The detail page has two tabs at the top: **Overview & Billing** and **SIM Management**.
5. The **Overview & Billing** tab shows four stat cards: Service Status, Billing Amount (with cycle), Next Due Date, and Registration Date. Below that is a Billing History table showing related invoices.
6. Click **SIM Management** to see the full SIM dashboard.

### SIM Management Dashboard

The SIM Management tab is the main hub. It shows:

**Header area:**

- The phone number (MSISDN) as the heading.
- A prominent **Top Up Data** button at the top right.

**Left column (larger):**

- **Action tiles** in a 2x2 grid: Call History, Change Plan, Reissue SIM, and Cancel SIM (shown in red).
- **Voice/Network Status** section with toggle switches for Voice Mail, Network Type (4G/5G), Call Waiting, and International Roaming. If the SIM is a data-only plan, voice features are hidden and a note says "Voice features are not available on data-only plans."

**Right column (smaller):**

- A **circular data usage chart** showing remaining data in MB and how much has been used.
- **Billing summary** rows: Monthly Cost, Next Bill on, and Registered date.
- **Important Notes** box explaining that changes take about 30 minutes, may require a device restart, voice/network/plan changes must be at least 30 minutes apart, and Voice Mail / Call Waiting changes must be requested before the 25th of the month.

### Topping Up Data

1. From the SIM Management dashboard, click the **Top Up Data** button (top right) or click the action tile.
2. This navigates to a dedicated **Top Up Data** page.
3. Enter the amount of data in whole GB (minimum 1 GB, maximum 50 GB).
4. The page shows a real-time cost calculation: 1 GB = 500 JPY. For example, entering "5" shows 5000 MB and a cost of 2,500 JPY.
5. Click **Submit Top Up**.
6. Behind the scenes, the system creates a WHMCS invoice for the calculated amount, captures payment using the customer's stored payment method, and then adds the data quota via Freebit.
7. On success, a green banner confirms the top-up with the amount and cost.
8. If payment fails, no data is added and an error message is shown.

### Changing the SIM Plan

1. From the SIM Management dashboard, click **Change Plan**.
2. This navigates to a dedicated **Change Plan** page.
3. The page shows the **Current Plan** at the top (name, data size, monthly price).
4. Below that, a list of **available plans** is displayed as radio-button cards. Only plans other than the current one are shown. The available plans are:
   - SIM Data-only 5GB (Freebit code: PASI_5G)
   - SIM Data-only 10GB (Freebit code: PASI_10G)
   - SIM Data-only 25GB (Freebit code: PASI_25G)
   - SIM Data-only 50GB (Freebit code: PASI_50G)
5. Each plan card shows the plan name, data size, plan type, and monthly price.
6. Select a plan and click **Confirm Plan Change**.
7. Important rules displayed on the page:
   - Plan changes take effect on the 1st of the following month.
   - Requests must be made before the 25th of the current month.
   - The current data balance will be reset when the new plan activates.
8. On success, a green banner shows a message like "Plan change scheduled for the 1st of next month."

### Reissuing a SIM (Physical or eSIM)

1. From the SIM Management dashboard, click **Reissue SIM**.
2. This navigates to a dedicated **Reissue SIM** page.
3. The page shows the current SIM information: phone number, current SIM type (physical or eSIM), ICCID (for physical), and current EID (for eSIM).
4. Choose a replacement SIM type by clicking one of two large cards:
   - **Physical SIM** -- a new SIM card will be shipped (typically 3-5 business days). The old SIM is deactivated once the new one is activated.
   - **eSIM** -- download a new eSIM profile instantly. Requires entering the new device's 32-digit EID.
5. If eSIM is selected, an EID input field appears. The EID must be exactly 32 digits. A character counter shows progress (e.g., "28/32").
6. Click **Submit Reissue Request**.
7. On success:
   - For eSIM: "You will receive instructions via email to download your new eSIM profile."
   - For Physical SIM: "You will be contacted shortly with shipping details (typically 3-5 business days)."

### Managing Voice Features and Network Type

1. On the SIM Management dashboard, the **Voice/Network Status** section has toggle switches.
2. Available toggles (for voice-enabled plans):
   - **Voice Mail** -- toggle on/off (300 JPY/month when enabled).
   - **Call Waiting** -- toggle on/off (300 JPY/month when enabled).
   - **International Roaming** -- toggle on/off.
   - **Network Type** -- toggle between 4G and 5G.
3. Flip any toggle and the change is sent immediately.
4. Rules and constraints:
   - Changes take effect in approximately 30 minutes.
   - Voice, network, and plan changes must be at least 30 minutes apart. If you try to change too quickly, the portal shows: "Please wait 30 minutes between voice/network/plan changes before trying again."
   - Voice Mail and Call Waiting changes must be requested before the 25th of the month.
   - A device restart is recommended after changes are applied to ensure they take effect.
5. If the SIM is a data-only plan, voice toggles (Voice Mail, Call Waiting, International Roaming) are hidden. Only the Network Type toggle is shown.

### Viewing Call and SMS History

1. From the SIM Management dashboard, click the **Call History** tile.
2. This navigates to a dedicated **Call & SMS History** page.
3. At the top, a banner shows which month's data is displayed (e.g., "Showing data for: September 2025").
4. There are three tabs:
   - **Domestic Calls** -- shows Date, Time, Called To, Call Length, and Call Charge (in JPY).
   - **International Calls** -- shows Date, Start Time, Stop Time, Country, Called To, and Call Charge.
   - **SMS History** -- shows Date, Time, Sent To, and Type (Domestic SMS or International SMS).
5. Each tab shows the total record count in parentheses.
6. Tables are paginated (50 records per page).
7. Important notes at the bottom:
   - History is updated approximately 2 months after calls/messages are made.
   - Approximately 3 months of records are available.
   - Charges are based on carrier billing data.

### MNP -- Mobile Number Portability

MNP allows a customer to bring their phone number from another carrier when activating a new SIM. This happens during the **order activation** flow (not as a standalone action on an existing subscription).

During SIM order activation, the customer can choose "I want to port my number" which reveals the MNP form. The MNP form collects:

- **MNP Reservation Number** -- obtained from the customer's current carrier.
- **Reservation Expiry Date** -- the date by which the port must be completed.
- **Phone Number** -- the number being ported.
- **Current Carrier Account Number** (optional).
- **Porting Person Details** (optional): Last Name, First Name, Last Name (Katakana), First Name (Katakana), Gender, Date of Birth.

These details are sent to Freebit during SIM provisioning. The ported number replaces the default assigned number.

### Cancelling a SIM Subscription

1. From the SIM Management dashboard, click the **Cancel SIM** tile (shown in red).
2. This navigates to the **Cancel SIM Service** page, which uses a multi-step cancellation flow shared with Internet services.
3. If the cancellation is already in progress (Salesforce Opportunity is in "Cancelling" stage), the page shows a "Cancellation In Progress" status with the scheduled end date.
4. Otherwise, the cancellation flow has three steps:

**Step 1 -- Review Service Information:**

- Shows service details: product name, phone number, plan, start date, billing amount.
- Displays cancellation terms and conditions.
- If the subscription is within its minimum contract period, a warning banner appears with the minimum contract end date.

**Step 2 -- Select Cancellation Month:**

- The customer selects from available cancellation months (dropdown).
- Default is the 1st of next month.
- Must check two confirmation boxes: "I have read the cancellation terms" and "I confirm I want to cancel."
- Optional comments field.

**Step 3 -- Confirm and Submit:**

- Summary of service info and selected cancellation month.
- Any additional notices (e.g., voice SIM billing notes).
- Click **Submit Cancellation**.

5. On success: "Cancellation request submitted. You will receive a confirmation email." The page redirects to the subscription detail after 2 seconds.

## What Happens in WHMCS

| Action                | WHMCS Impact                                                                                                                                                                                                                                                   |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **View subscription** | Subscription data (product name, status, amount, cycle, dates) is read from WHMCS via the client mapping. Cached for 5-10 minutes.                                                                                                                             |
| **Top up data**       | A new Invoice is created with the top-up amount (e.g., "SIM Data Top-Up 5GB" for 2,500 JPY). Payment is captured immediately using the customer's stored payment method.                                                                                       |
| **Change plan**       | The plan change is scheduled in Freebit. The WHMCS product/service record is updated to reflect the new plan once the change takes effect on the 1st of next month.                                                                                            |
| **Reissue SIM**       | No direct WHMCS changes for the reissue itself. The service continues under the same WHMCS service ID.                                                                                                                                                         |
| **Voice features**    | Voice option state is tracked in the portal's database. Freebit is called to apply the changes. WHMCS add-on services for Voice Mail (pid 119) and Call Waiting (pid 123) are updated to reflect the new state.                                                |
| **Call history**      | Read-only. History data comes from Freebit SFTP files, not WHMCS.                                                                                                                                                                                              |
| **Cancel SIM**        | The service continues until the end of the current billing cycle (or the selected cancellation date). No pro-rated refund is issued. The cancellation is scheduled in Freebit, and the WHMCS service status changes to Cancelled when the billing period ends. |

**Where to find SIM services in WHMCS:**

- Go to **Clients > [Client] > Products/Services**.
- SIM services have product names like "SonixNet SIM Service Data-only/5GB (Monthly)" or "SonixNet SIM Service Data+Voice/10GB (Monthly)."
- The Domain field on the WHMCS service often stores the phone number (MSISDN).
- Invoices for top-ups appear under the client's invoice list.

## What Happens in Salesforce

| Action                      | Salesforce Impact                                                                                                                                                                                                                                                 |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **View subscription**       | No Salesforce read for basic subscription display (comes from WHMCS).                                                                                                                                                                                             |
| **Top up data**             | No Salesforce record is created for individual top-ups.                                                                                                                                                                                                           |
| **Change plan**             | The plan change is scheduled in Freebit. No direct Salesforce update is triggered from the portal for plan changes.                                                                                                                                               |
| **Reissue SIM**             | The reissue request is sent to Freebit. The new SIM identifiers (ICCID, EID) are stored by Freebit.                                                                                                                                                               |
| **Cancel SIM**              | The linked Salesforce Opportunity stage changes from "Active" to "△Cancelling" with a scheduled end date. When cancellation completes, it moves to "〇Cancelled". A new internal Case (Origin: "Portal Notification") is also created to notify the support team. |
| **MNP (during activation)** | MNP details are stored on the Salesforce Order record's custom fields (see doc 05 for the full MNP field list).                                                                                                                                                   |

### How Cancellation Links WHMCS to Salesforce

The portal knows which Salesforce Opportunity to cancel by using the **WHMCS Service ID**:

1. The portal reads the WHMCS Service ID from the customer's subscription.
2. It searches Salesforce for the Opportunity where `WHMCS_Service_ID__c` matches that WHMCS Service ID.
3. It updates that Opportunity's stage and cancellation fields.

**Salesforce Opportunity fields updated during SIM cancellation:**

| Field                      | API Name                                 | Value                                        |
| -------------------------- | ---------------------------------------- | -------------------------------------------- |
| Stage                      | `StageName`                              | Changes to "△Cancelling", then "〇Cancelled" |
| SIM Cancellation Notice    | `SIMCancellationNotice__c`               | Updated with cancellation status             |
| SIM Scheduled Cancellation | `SIMScheduledCancellationDateAndTime__c` | The selected cancellation date               |

**Where to find SIM data in Salesforce:**

- **Opportunity**: Look for Opportunities on the Account where `CommodityType__c` = "SIM". Check `WHMCS_Service_ID__c` to verify it matches the WHMCS service. The `StageName` shows the lifecycle state.
- **Order**: SIM orders have `Type` = "SIM". Check the SIM-specific fields listed in doc 05.
- **Product2**: SIM products have `SIM_Data_Size__c` and `SIM_Plan_Type__c` fields. `WH_Product_ID__c` maps to the WHMCS product.

## Key Things to Verify

### Subscription Detail Page

- [ ] SIM subscriptions show both "Overview & Billing" and "SIM Management" tabs.
- [ ] Non-SIM subscriptions (Internet, VPN) do not show the SIM Management tab.
- [ ] The four stat cards display correct values matching WHMCS.
- [ ] Billing history shows invoices related to this subscription.

### SIM Management Dashboard

- [ ] Phone number (MSISDN) is displayed correctly as the heading.
- [ ] The circular data usage chart shows correct remaining and used values from Freebit.
- [ ] Monthly cost, next bill date, and registration date match WHMCS data.
- [ ] All four action tiles (Call History, Change Plan, Reissue SIM, Cancel SIM) are present and clickable.
- [ ] For data-only plans, voice toggles are hidden and the note about data-only plans appears.
- [ ] For voice-enabled plans, all four toggles (Voice Mail, Call Waiting, International Roaming, Network Type) are visible.

### Top Up Data

- [ ] The cost calculator updates in real time as the GB amount is typed.
- [ ] Minimum 1 GB, maximum 50 GB, whole numbers only.
- [ ] On success, a WHMCS invoice is created and paid.
- [ ] Data is added to the SIM (takes a few minutes to reflect in the usage display).
- [ ] If payment fails, no data is added and the user sees an error.

### Change Plan

- [ ] Current plan is highlighted at the top with correct details.
- [ ] Only plans other than the current plan are listed.
- [ ] The important notice about the 25th deadline and 1st-of-month activation is visible.
- [ ] After submitting, the success message mentions the scheduled date.

### Reissue SIM

- [ ] Current SIM details (number, type, ICCID/EID) are shown.
- [ ] Physical SIM option shows shipping info (3-5 business days).
- [ ] eSIM option requires a valid 32-digit EID.
- [ ] The submit button is disabled until a SIM type is selected (and EID entered for eSIM).

### Voice Features

- [ ] Toggling a feature sends the change and the toggle updates optimistically.
- [ ] If a change is rejected (e.g., too soon after a previous change), the toggle reverts and an error is displayed.
- [ ] The 30-minute spacing rule between changes is enforced.

### Call and SMS History

- [ ] All three tabs load their respective data.
- [ ] Tables show correct columns (domestic: Date, Time, Called To, Call Length, Charge; international: Date, Start/Stop Time, Country, Called To, Charge; SMS: Date, Time, Sent To, Type).
- [ ] Pagination works when there are more than 50 records.
- [ ] The "2 months delay" note is displayed.

### Cancellation

- [ ] If already cancelling, the "Cancellation In Progress" status page appears.
- [ ] The cancellation month dropdown offers future months.
- [ ] Both confirmation checkboxes must be ticked before the submit button is enabled.
- [ ] Minimum contract warning appears when applicable.
- [ ] After submission, the Salesforce Opportunity moves to "Cancelling" stage.
- [ ] The confirmation email is sent to the customer's email address.
