Update a Subscription Plan

Before You Begin

Ensure you have:

API Credentials

Valid API credentials and access token for authentication.

Account Setup

Proper account setup for your target country and business verification.

IP Whitelisting

Whitelist your server IP addresses for API access.

Webhook Endpoint

Set up a webhook URL to receive payment notifications.

Step 1: Update a Subscription Plan

To modify an existing subscription plan, send aPATCH request to the Update Subscription Plan endpoint.

Key Request Parameters

The request requires several key parameters:

Parameter	Description	Required
`amount`	Updated billing amount	❌
`autoRecurring`	Updated configuration for automatic recurring billing	❌
`autoRecurring.repetitions`	Updated number of billing cycles (use `0` for recurrence on demand)	❌
`autoRecurring.type`	Updated billing frequency unit (use `custom`for recurrence on demand)	❌

Supported Billing Frequencies

Daily

Update to daily billing. Ideal for services transitioning to daily usage patterns.

Send theautoRecurring.type property with value: day

Monthly

Update to monthly billing. Common for standardizing billing cycles across product lines.

Send theautoRecurring.type property with value: month

Custom (On-demand)

Update to on-demand billing. Suitable for moving to usage-based pricing models.

Send theautoRecurring.type property with value: custom

Example Request

Below is an example using curl:

curl --request PATCH \
  --url 'https://api.stage.localpayment.com/api/subscriptions/plan/{internalId}' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 150,
    "autoRecurring": {
      "repetitions": 1,
      "type": "month"
    }
  }'

See all available parameters in the request.

Step 2: Handle the Response

Successful Response

A successfully updated subscription plan returns confirmation with the current status:

{
    "internalId": "106e9aff-96da-42e9-a9e1-4dee207e6073",
    "status": {
        "code": "100",
        "description": "ACTIVE",
        "detail": "Subscription plan was update"
    }
}

Key Response Fields

Parameter	Description	Use Case
`internalId`	Localpayment's unique plan identifier.	Verify you've updated the correct plan.
`status.code`	Current plan status code.	Confirm the plan remains active after updates.
`status.description`	Human-readable status description.	Display status in administrative interfaces.
`status.detail`	Detailed status information.	Confirm the update operation was successful.

Error Response

When a subscription plan update fails, you'll receive detailed error information:

{
  "status": {
    "code": "400",
    "description": "REJECTED",
    "detail": "amount must be greater than or equal to 1"
  }
}

Step 3: Track Transaction Status

After updating a subscription plan, monitor its status through these methods:

Webhooks (Recommended)

Receive real-time notifications when transaction status changes. Most efficient for production environments.

Status API Endpoint

Query transaction status programmatically. Useful for polling or recovering lost webhook notifications.

Business Portal View

Visual interface for monitoring transactions. Great for manual oversight and detailed transaction analysis.

Common Status Codes

Code	Status	Description
`100`	`ACTIVE`	Plan is active and available for subscription associations.
`400`	`REJECTED`	Plan update failed due to validation errors or invalid parameters.

🗒️
Complete Reference
View all status codes in our Transaction Status Documentation.

Testing Your Integration

Test Scenarios

Verify your integration handles these scenarios:

Successful Amount Update: Modify plan pricing with valid amount values.
Billing Frequency Change: Update from monthly to daily or custom billing.
Partial Updates: Modify only specific fields without sending complete payload.
Validation Errors: Test with invalid amounts, missing required fields, or unsupported frequencies.
Nonexistent Plan: Attempt to update a plan that doesn't exist.
Authentication Failures: Test with invalid or expired access tokens.

Next Steps

After updating a subscription plan, you may need to perform additional actions:

Create a new subscription plan

Set up additional subscription plans for different pricing tiers or service
levels.

Create subscription with updated plan

Create new subscriptions using your updated plan to test the changes.

Get subscription plan details

Retrieve the updated plan information to verify all changes were applied
correctly.