Create a Subscription Plan

Localpayment enables you to create fixed subscription plans for standardized recurring billing scenarios. This guide details how to set up subscription plans through Localpayment's API, which can then be associated with customer subscriptions for consistent, automated billing.

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.

Country Requirements

Understanding of country-specific requirements and local regulations.

Step 1: Create a Subscription Plan

To create a new subscription plan, send a POST request to the Create Subscription Plan endpoint.

Key Request Parameters

The request requires several key objects:

Parameter	Description	Required
`name`	Descriptive name for the subscription plan	✅
`description`	Detailed explanation of plan features and benefits	❌
`country`	Country code where the plan will be available	✅
`amount`	Fixed billing amount	✅
`currency`	Currency code for billing	✅
`accountNumber`	Your merchant account number	✅
`autoRecurring.repetitions`	Number of billing cycles (use `0` for recurrence on demand)	✅
`autoRecurring.type`	Billing frequency unit (use `custom`for recurrence on demand)

Supported Billing Frequencies

Daily

Bill customers every day. Ideal for services with daily usage or short-term subscriptions.

Send theautoRecurring.type property with value: day

Monthly

Monthly recurring billing for most SaaS products, membership services, and subscription boxes.

Send theautoRecurring.type property with value: month

Custom (On-demand)

On-demand billing for variable usage scenarios. Perfect for pay-as-you-go or usage-based services.

Send theautoRecurring.type property with value: custom

Example Request

Below is an example using curl:

curl --request POST \
  --url https://api.stage.localpayment.com/api/subscriptions/plan \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Plan Básico Mensual",
    "description": "Acceso básico a contenido exclusivo",
    "country": "MEX",
    "amount": 50,
    "currency": "MXN",
    "accountNumber": "{{accountNumber}}",
    "autoRecurring": {
      "repetitions": 1,
      "type": "hour"
    }
  }'

See all available parameters in the request.

Step 2: Handle the Response

Successful Response

A successfully created subscription plan returns complete plan details:

{
    "internalId": "70af52e2-ea99-46a8-a931-65f15f6a3c20",
    "name": "Plan Básico Mensual",
    "description": "Acceso básico a contenido exclusivo",
    "amount": 50,
    "country": "MEX",
    "currency": "MXN",
    "accountNumber": "{{accountNumber}}",
    "autoRecurring": {
        "repetitions": 1,
        "type": "hour"
    },
    "status": {
        "code": "100",
        "description": "ACTIVE",
        "detail": "Subscription plan is active"
    }
}

Key Response Fields

Parameter	Description	Use Case
`internalId`	Localpayment's unique plan identifier.	Use as `planId` when creating subscriptions
`status.code`	Current plan status code.	Status monitoring.
`autoRecurring.type`	Confirmed billing frequency.	Billing cycle verification.
`autoRecurring.repetitions`	Confirmed number of billing cycles.	Plan duration tracking.

Error Response

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

{
    "status": {
        "code": "400",
        "description": "REJECTED",
        "detail": "autoRecurring.type is required"
    }
}

Step 3: Track Transaction Status

After creating 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.

Dashboard 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 creation failed due to validation errors or invalid parameters.

📝
Note: For complete status code reference, see the Transaction Status documentation.

Testing Your Integration

Test Scenarios

Verify your integration handles these scenarios:

Successful Plan Creation: Standard plan creation with valid parameters.
Tiered Pricing Structure: Creating multiple plans at different price points.
Various Billing Frequencies: Testing daily, monthly, and custom on-demand plans.
Validation Errors: Missing required fields, invalid amounts, unsupported countries.
Subscription Association: Testing that plans can be successfully linked to subscriptions

Next Steps

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

Create subscription with plan

Use the plan internalId as planId parameter to create customer subscriptions with your new plan.

Update subscription plan

Modify existing plan details while maintaining associations with active subscriptions.