Update a Subscription

PATCH/ps/api/v1/public/subscriptions/{subscription_id}

Updates an existing subscription. You can switch to a new plan or update the end date. A reason is required.

View as Markdown Open in ChatGPT Open in Claude Open in Perplexity

Requires Bearer token. Get token →

Path Parameters

Field	Details
`subscription_id` `string`required	Unique identifier for the subscription. Constraints Maximum length: 50 characters

Header Parameters

Field	Details
`Request-Timestamp` `string`date-time	ISO 8601 UTC timestamp of the request. Used for idempotency and audit.
`Request-ID` `string`	Use a global unique identifier [GUID] for the request. Constraints Minimum length: 1 characterMaximum length: 50 characters

Request Bodyrequired

Field	Details
`new_plan_id` `string`	New plan ID to switch the subscription to.
`new_end_date` `string`date-time	New end date in ISO 8601 UTC.
`reason` `string`required	Reason for the update.

Response

Field	Details
`order_id` `string`	Unique identifier of the order in the Pine Labs Online database.
`subscription_id` `string`	Unique identifier for the subscription. Constraints Maximum length: 50 characters
`merchant_subscription_reference` `string`	Unique identifier of the merchant subscription reference. Constraints Minimum length: 1 characterMaximum length: 50 characters
`enable_notification` `boolean`	Indicates if notifications are enabled.
`plan_details` `object`16 nested fields	Plan object returned in create, get, and update responses.
`plan_id` `string`	Unique identifier for the subscription plan in the Pine Labs database.
`status` `string`	Status of the plan. ACTIVE: Plan creation completed and start time has passed. INACTIVE: Plan is disabled or has exceeded its validity period. CREATED: Plan creation completed but start time is in the future. Allowed values: `ACTIVEINACTIVECREATED`
`plan_name` `string`	Subscription plan name.
`plan_description` `string`	Corresponding description for a plan.
`frequency` `string`	Frequency of recurring transactions for this particular plan. Allowed values: `DayWeekMonthYearBi-MonthlyQuarterlyHalf-YearlyASOTNot Applicable`
`amount` `object`2 nested fields	This is the recurring mandate amount, that would be charged for each frequency. For instance 200 every month. This field is not needed if the mandate frequency is AS
`max_limit_amount` `object`2 nested fields	This is the recurring mandate amount, that would be charged for each frequency. For instance 200 every month. This field is not needed if the mandate frequency is AS
`trial_period_in_days` `integer`	Duration of the trial period in days.
`start_date` `string`date-time	The ISO 8601 UTC Timestamp when the subscription plan is active.
`end_date` `string`date-time	The ISO 8601 UTC Timestamp when the subscription plan expires.
`merchant_metadata` `object`	Key-value pairs for additional information. Max 10 pairs, 256 chars each. Constraints Maximum properties: 10 Additional properties: string · Maximum length: 256 characters
`merchant_plan_reference` `string`	Unique identifier of the merchant plan reference. Constraints Minimum length: 1 characterMaximum length: 50 characters
`created_at` `string`date-timenullable	ISO 8601 UTC Timestamp when the create plan request was received.
`modified_at` `string`date-timenullable	ISO 8601 UTC Timestamp when the plan was last updated.
`initial_debit_amount` `object`2 nested fields	This is the recurring mandate amount, that would be charged for each frequency. For instance 200 every month. This field is not needed if the mandate frequency is AS
`auto_debit_ot` `string`	Indicates whether auto-debit is enabled for one-time payments.
`quantity` `integer`	The quantity of the subscription for the selected plan.
`start_date` `string`date-time	The ISO 8601 UTC Timestamp when the subscription starts.
`end_date` `string`date-time	The ISO 8601 UTC Timestamp when the subscription expires.
`customer_id` `string`	Unique identifier of the customer. Constraints Minimum length: 1 characterMaximum length: 19 characters
`payment_mode` `string`	Payment methods allowed for subscription. Allowed values: `CARDUPI`
`allowed_payment_methods` `string[]`	The type of payment methods offered to customers. Constraints Allowed item values: `CARDUPIPOINTSNETBANKINGWALLET`
`integration_mode` `string`	Type of integration. Allowed values: `SEAMLESSREDIRECT`
`merchant_metadata` `object`	Key-value pairs for additional information. Constraints Maximum properties: 10 Additional properties: string · Maximum length: 256 characters
`status` `string`	Status of the Subscription. Allowed values: `CREATEDTRIALACTIVEPAUSEDRESUMINGRESUMEDDEBIT_FAILEDUPDATINGCOMPLETEDEXPIREDCANCELLEDCANCELLINGHALTEDINACTIVE`
`is_tpv_enabled` `boolean`	Indicates if Third-Party Validation (TPV) is enabled.
`bank_account` `object`3 nested fields	Bank account details for Third-Party Validation (TPV).
`created_at` `string`date-time	ISO 8601 UTC Timestamp when the subscription was created.
`modified_at` `string`date-time	ISO 8601 UTC Timestamp when the subscription was last updated.
`order_amount` `object`2 nested fields	This is the recurring mandate amount, that would be charged for each frequency. For instance 200 every month. This field is not needed if the mandate frequency is AS

Status Codes

`200`	Subscription updated successfully.
`404`	The requested resource does not exist.
`500`	An unexpected error occurred on the server.

Run

Request

curl --request PATCH \
  --url https://pluraluat.v2.pinepg.in/ps/api/v1/public/subscriptions/v1-sub-4405071524-aa-qlAtAf \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Request-ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  --header 'Request-Timestamp: 2024-10-01T10:30:00Z' \
  --data '{
  "new_plan_id": "v1-plan-4405071524-aa-newPlan",
  "new_end_date": "2025-12-31T23:59:59Z",
  "reason": "Switching to annual plan"
}'

Status:

{
  "order_id": "v1-4405071524-aa-qlAtAf",
  "subscription_id": "v1-sub-4405071524-aa-qlAtAf",
  "merchant_subscription_reference": "1234567890",
  "enable_notification": true,
  "plan_details": {
    "plan_id": "v1-plan-4405071524-aa-qlAtAf",
    "status": "ACTIVE",
    "plan_name": "Monthly Plan",
    "plan_description": "Diwali dhammaka plan intended to attract customers on diwali time",
    "frequency": "Day",
    "amount": {
      "value": 1000,
      "currency": "INR"
    },
    "max_limit_amount": {
      "value": 1000,
      "currency": "INR"
    },
    "trial_period_in_days": 1,
    "start_date": "2022-02-01T17:32:28Z",
    "end_date": "2022-10-21T17:32:28Z",
    "merchant_metadata": {
      "key1": "DD",
      "key2": "XOF"
    },
    "merchant_plan_reference": "1234567890",
    "created_at": "2022-10-21T17:32:28Z",
    "modified_at": "2022-10-21T17:32:28Z",
    "initial_debit_amount": {
      "value": 1000,
      "currency": "INR"
    },
    "auto_debit_ot": "false"
  },
  "quantity": 1,
  "start_date": "2022-07-21T17:32:28Z",
  "end_date": "2022-09-21T17:32:28Z",
  "customer_id": "123456",
  "payment_mode": "UPI",
  "allowed_payment_methods": [
    "UPI"
  ],
  "integration_mode": "SEAMLESS",
  "merchant_metadata": {
    "key1": "DD",
    "key2": "XOF"
  },
  "status": "ACTIVE",
  "is_tpv_enabled": true,
  "bank_account": {
    "account_number": "12345678912345",
    "name": "Kevin Bob",
    "ifsc": "HDFC0001234"
  },
  "created_at": "2022-10-21T17:32:28Z",
  "modified_at": "2022-10-21T17:32:28Z",
  "order_amount": {
    "value": 1000,
    "currency": "INR"
  }
}