Update / Upgrade Plan

​Overview

PATCH behaves differently depending on which fields you include:

• Soft update — When only name, merchant_reff_no, or metadata.description are present, the existing plan is patched in place. No new plan is created and no charge is made.
• Upgrade flow — When amount or items is present, SingaPay closes the existing plan and creates a new plan with parent_plan_id pointing at the old one. Proration is applied (auto by default), and a fresh payment_link_url is issued for the prorated charge when one is required. The response surfaces the new plan plus an upgrade block with the full lineage.

This mirrors the dashboard “Upgrade Plan” feature 1:1, so plans created via the API and plans managed via the dashboard share a consistent history model.

---

​Information

​Request Details

​Path Parameters

​Headers Structure

​Body Structure

All fields are optional individually, but the request must contain at least one recognized field to have any effect.

​Request Example — Soft Update (Cosmetic Only)

Updates the plan in place. No new plan is created, no charge is made.

{
    "name": "Premium Monthly v2",
    "metadata": {
        "description": "Updated description for the premium plan"
    }
}

​Request Example — Upgrade (Amount Change, Auto-Prorate)

Triggers the full upgrade flow: closes the existing plan and creates a new one with parent_plan_id linking back. Proration is computed automatically for the remainder of the current cycle.

{
    "amount": 180000
}

​Request Example — Upgrade (Itemized, Manual Proration)

Replaces the line items of an itemized plan. prorated_charge_amount: 0 skips the immediate prorated charge (useful for customer-friendly mid-cycle adjustments).

{
    "items": [
        {
            "item_name": "Premium Seat",
            "item_type": "service",
            "quantity": 5,
            "unit_price": 75000
        },
        {
            "item_name": "Premium Support",
            "item_type": "service",
            "quantity": 1,
            "unit_price": 50000
        }
    ],
    "prorated_charge_mode": "manual",
    "prorated_charge_amount": 0
}

cURL Example:

curl -X PATCH "https://your-domain.com/api/v2.0/recurring/plans/01JAB3CD4E5F6G7H8J9K0M1N2" \
  -H "X-PARTNER-ID: {api_key}" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": 180000 }'

​Response Details

​Response Structure — Soft Update

When no upgrade is triggered, the response is the same shape as Show Plan: the plan’s id is unchanged and the patched fields are reflected.

​Response Structure — Upgrade

When amount or items is present, the response carries the new plan (with created_from: "upgrade" and parent_plan_id set to the old plan ID) plus an upgrade block summarizing the operation.

​Response Example — Soft Update (HTTP 200)

{
    "response_code": "SP000",
    "response_message": "Successfully",
    "data": {
        "id": "01JAB3CD4E5F6G7H8J9K0M1N2",
        "name": "Premium Monthly v2",
        "amount": "150000",
        "currency": "IDR",
        "status": "active",
        "merchant_reff_no": "SUB-CUST-ACME-001",
        "parent_plan_id": null,
        "created_from": null,
        "metadata": {
            "description": "Updated description for the premium plan"
        }
    }
}

​Response Example — Upgrade with Prorated Charge (HTTP 200)

{
    "response_code": "SP000",
    "response_message": "Successfully",
    "data": {
        "id": "01JBK9PZ123456789ABCDEFGHJ",
        "name": "Premium Monthly",
        "amount": "180000",
        "currency": "IDR",
        "created_at": "2026-04-20T11:30:00+07:00",
        "schedule": {
            "interval": 1,
            "interval_unit": "month",
            "current_interval": 0,
            "total_interval": 10,
            "start_time": "2026-04-20T11:30:00+07:00",
            "previous_payment_at": null,
            "next_payment_at": "2026-05-20T11:30:00+07:00"
        },
        "status": "active",
        "payment_type": "credit_card",
        "retry_policy": {
            "max_attempts": 3,
            "interval_days": 3,
            "failed_payment_action": "continue_plan"
        },
        "subscription_id": "PLAN-20260420-001",
        "merchant_reff_no": "SUB-CUST-ACME-001",
        "payment_link_url": null,
        "parent_plan_id": "01JAB3CD4E5F6G7H8J9K0M1N2",
        "created_from": "upgrade",
        "upgrade": {
            "previous_plan_id": "01JAB3CD4E5F6G7H8J9K0M1N2",
            "direction": "upgrade",
            "difference": {
                "amount": 30000,
                "percentage": 20
            },
            "prorated_charge": {
                "bill_id": 98765,
                "amount": 25000,
                "status": "pending"
            },
            "payment_link_url": "https://pay.singapay.id/link/xyz789"
        }
    }
}

​Error Response — Amount / Items in Same Request (HTTP 422)

{
    "message": "The amount field prohibits items from being present.",
    "errors": {
        "amount": [
            "The amount field prohibits items from being present."
        ],
        "items": [
            "The items field prohibits amount from being present."
        ]
    }
}

​Error Response — Wrong Shape for Plan Type (HTTP 409)

{
    "response_code": "SP102",
    "response_message": "This plan is amount-only. Send `amount` to change the cycle charge, not `items`.",
    "data": {}
}

​Error Response — Plan Not Upgradeable (HTTP 409)

{
    "response_code": "SP102",
    "response_message": "Plan cannot be updated in its current state.",
    "data": {}
}

​Error Response — Plan Not Found (HTTP 404)

{
    "response_code": "SP100",
    "response_message": "Subscription Plan Not Found",
    "data": {}
}

---

​Proration Rules

When an upgrade fires, the service decides whether an immediate prorated charge is needed:

Condition	Behavior
direction = upgrade (new amount higher), mode auto	Service computes the remaining days in the current cycle × per-day price difference and issues a prorated bill.
direction = upgrade, mode manual	prorated_charge_amount is used as-is. Must clear the card channel minimum or be 0.
direction = downgrade (new amount lower)	No immediate charge. The lower amount takes effect on the next scheduled cycle.
prorated_charge_amount = 0	Explicitly skips the immediate charge. The new amount takes effect on the next scheduled cycle.

---

​Important Notes

• New Plan ID: An upgrade returns a new plan ID. Store data.id from the response and use it for all subsequent operations. The old plan ID is available on upgrade.previous_plan_id and parent_plan_id.
• Idempotent Soft Updates: Sending the same cosmetic PATCH twice is a no-op.
• What Cannot Be Updated: currency, customer_*, schedule.*, and retry_policy cannot be changed via the API. Use the merchant dashboard for those changes.
• Card Linking: Upgrades reuse the tokenized card from the previous plan — the customer does not need to re-enter card details. The prorated charge (when present) uses the same saved card.
• Status Requirements: The plan must be in active, paused, or similar non-terminal status. Plans in cancelled or completed cannot be updated.