Show Plan - Singapay PG

Overview

Returns the latest snapshot of a subscription plan owned by the authenticated merchant, including live schedule progress (current_interval, previous_payment_at, next_payment_at), the resolved retry policy, and plan lineage (parent_plan_id, created_from) when the plan was produced by an upgrade.

Use this to:

Reconcile plan state between your system and SingaPay.
Resolve the current next_payment_at before sending customer communications.
Follow an upgrade chain via parent_plan_id when auditing a subscription’s history.

Information

Method	Path	Format	Authentication
GET	`/api/v2.0/recurring/plans/{id}`	json	OAuth 2.0 with Access Token

Request Details

Path Parameters

Parameter	Type	Mandatory	Description	Example
id	String	Required	Subscription Plan ID (26-char ULID returned at creation)	01JAB3CD4E5F6G7H8J9K0M1N2

Headers Structure

Field	Value	Type	Mandatory	Description	Example
Authorization	Bearer {access_token}	Alphanumeric	Mandatory	Bearer token obtained from the access token endpoint.	Bearer eyJ0eXAiOiJKV1{…}
X-PARTNER-ID		Alphanumeric	Mandatory	Your API Key from the merchant dashboard.	pk_live_abc123def456

Request Example

GET /api/v2.0/recurring/plans/01JAB3CD4E5F6G7H8J9K0M1N2

cURL Example:

curl -X GET "https://your-domain.com/api/v2.0/recurring/plans/01JAB3CD4E5F6G7H8J9K0M1N2" \
  -H "X-PARTNER-ID: {api_key}" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."

Response Details

Response Structure

Same shape as the Create response. See the Create Plan reference for the full field-by-field breakdown.

Field	Type	Mandatory	Description	Example
response_code	String	Mandatory	`SP000` on success.	SP000
response_message	String	Mandatory	Human-readable response message.	Successfully
data	Object	Mandatory	Plan payload.	-
> id	String	Mandatory	Subscription Plan ID.	01JAB3CD4E5F6G7H8J9K0M1N2
> name	String	Mandatory	Plan display name.	Premium Monthly
> amount	String	Mandatory	Current per-cycle charge (string).	“150000”
> currency	String	Mandatory	Currency code.	IDR
> created_at	String	Mandatory	Plan creation timestamp (ISO 8601).	2026-04-20T10:00:00+07:00
> schedule	Object	Mandatory	Schedule configuration + live progress.	-
>> schedule.current_interval	Integer	Mandatory	Cycles produced so far.	2
>> schedule.previous_payment_at	String/Null	Optional	Last successful charge timestamp (ISO 8601).	2026-05-01T00:00:00+07:00
>> schedule.next_payment_at	String/Null	Optional	Next scheduled charge timestamp (ISO 8601).	2026-07-01T00:00:00+07:00
> status	String	Mandatory	Current plan status.	active
> retry_policy	Object	Mandatory	Resolved retry policy.	-
> payment_link_url	String/Null	Optional	Card-linking URL. `null` once card linking is complete.	null
> parent_plan_id	String/Null	Optional	ID of the plan this one superseded via upgrade.	01JA001122334455667788999
> created_from	String/Null	Optional	`upgrade`, `downgrade`, or `null`.	upgrade

Response Example — Active Plan (HTTP 200)

Success: Plan is active, card linked, and on cycle 2 of 12.

{
    "response_code": "SP000",
    "response_message": "Successfully",
    "data": {
        "id": "01JAB3CD4E5F6G7H8J9K0M1N2",
        "name": "Premium Monthly",
        "amount": "150000",
        "currency": "IDR",
        "created_at": "2026-04-20T10:00:00+07:00",
        "schedule": {
            "interval": 1,
            "interval_unit": "month",
            "current_interval": 2,
            "total_interval": 12,
            "start_time": "2026-05-01T00:00:00+07:00",
            "previous_payment_at": "2026-06-01T00:00:15+07:00",
            "next_payment_at": "2026-07-01T00:00:00+07:00"
        },
        "status": "active",
        "payment_type": "credit_card",
        "retry_policy": {
            "max_attempts": 3,
            "interval_days": 3,
            "failed_payment_action": "continue_plan"
        },
        "metadata": {
            "description": "Premium monthly subscription",
            "extra": {
                "payment_type": "credit_card",
                "return_url": "https://merchant.com/callback",
                "api_created": true
            }
        },
        "subscription_id": "PLAN-20260420-001",
        "merchant_reff_no": "SUB-CUST-ACME-001",
        "payment_link_url": null,
        "parent_plan_id": null,
        "created_from": null
    }
}

Response Example — Upgraded Plan (HTTP 200)

Plans produced by a PATCH upgrade carry lineage pointers so you can walk the chain back to the original plan.

{
    "response_code": "SP000",
    "response_message": "Successfully",
    "data": {
        "id": "01JBK9PZ123456789ABCDEFGHJ",
        "name": "Premium Monthly",
        "amount": "180000",
        "currency": "IDR",
        "status": "active",
        "parent_plan_id": "01JAB3CD4E5F6G7H8J9K0M1N2",
        "created_from": "upgrade"
    }
}

Error Response — Plan Not Found (HTTP 404)

Error: Plan not found or does not belong to the authenticated merchant.

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

Important Notes

Merchant Scoping: Plans are scoped to the authenticated merchant. Requests for plans owned by another merchant return SP100 (Not Found) rather than leaking ownership information.
Lineage: Walk the chain by repeatedly fetching parent_plan_id until it is null — that is the original plan. This is useful for audit / customer support.
Payment Link URL: payment_link_url is only returned while the plan is in pending_card_linking. Once the customer completes card linking it is set to null.

On this page