Get Subscription Plan

Localpayment provides an endpoint to retrieve detailed information about existing subscription plans. This guide explains how to fetch subscription plan details through Localpayment's API, allowing you to verify plan configurations, check status, and use plan information in your application.

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: Get Subscription Plan Details

To retrieve subscription plan information, send aGET request to the Get Subscription Plan endpoint.

Key Request Parameters

The request requires several key parameters:

Parameter	Description	Required
`internalId`	Localpayment's unique plan identifier from the URL path	✅

Example Request

Below is an example using curl:

curl --request GET \
  --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'

See all available parameters in the request.

Step 2: Handle the Response

Successful Response

A successful request returns complete subscription plan details:

{
    "internalId": "b8546575-5d4f-4a56-9e21-522d01cf5992",
    "name": "Plan Básico Mensual",
    "description": "Acceso básico a contenido exclusivo",
    "amount": 50,
    "country": "MEX",
    "currency": "MXN",
    "accountNumber": "170.170.00000004",
    "autoRecurring": {
        "repetitions": 1,
        "type": "hour",
        "frequency": 1
    },
    "status": {
        "code": "100",
        "description": "ACTIVE",
        "detail": "Subscription plan is active"
    }
}

Key Response Fields

Parameter	Description	Use Case
`internalId`	Localpayment's unique plan identifier.	Reference for API operations.
`name`	Descriptive name of the subscription plan.	Display to customers.
`description`	Detailed explanation of plan features.	Customer communication.
`amount`	Billing amount.	Payment processing.
`country`	Country where the plan is available.	Geographic restrictions.
`currency`	Billing currency.	Financial calculations.
`accountNumber`	Associated merchant account number.	Reconciliation.
`autoRecurring.type`	Billing frequency type.	Billing cycle management.
`autoRecurring.repetitions`	Number of billing cycles.	Plan duration tracking.
`autoRecurring.frequency`	Billing frequency value.	Recurring billing setup.
`status.code`	Current plan status code.	Availability checking.

Error Response

When a subscription plan cannot be found or accessed, you'll receive error information:

{
  "status": {
    "code": "400",
    "description": "ERROR",
    "detail": "Plan subscription not found"
  }
}

Step 3: Track Transaction Status

After retrieving a subscription plan, you can determine its availability and current state:

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 retrieval failed due to invalid parameters or plan not found.

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

Testing Your Integration

Test Scenarios

Verify your integration handles these scenarios:

Successful Plan Retrieval: Fetch details for an existing active plan.
Nonexistent Plan: Attempt to retrieve a plan that doesn't exist.
Invalid Plan ID: Test with malformed or incorrect internalId formats.
Authentication Failures: Retrieve plans with invalid or expired access tokens.

Next Steps

Create a subscription plan

Set up new subscription plans for different service tiers or pricing models.

Update subscription plan

Modify existing plan details based on the information retrieved.

Create subscription with plan

Use the plan id to create new customer subscriptions.