Welcome to Xendit’s latest documentation. For legacy content, access the previous documentation here or the previous API reference here.

Get Subscription Plan

Prev Next
Get
/recurring/plans/{id}

Fetches details of a specific subscription plan by its ID.

Header parameters
for-user-id
string

The sub-account user-id to make this transaction for. This header is only used if you have access to xenPlatform. See xenPlatform for more information.

Path parameters
id
stringRequired

The ID of the recurring plan.

Responses
200

Successfully created a recurring plan. A webhook will follow to confirm plan activation.

Expand All
object
reference_id
string

Merchant-provided identifier for the recurring plan.

customer_id
string

Xendit-generated customer ID.

recurring_action
string

The type of action requested for the recurring plan.

Valid values[ "PAYMENT" ]
currency
string

ISO 4217 currency code (e.g., IDR, PHP).

amount
number

Amount to be charged in each recurring cycle.

schedule
object (Xendit_Subscriptions_API_RecurringSchedule)
reference_id
string

Merchant-provided identifier for the schedule.

interval
string

Frequency of the recurring cycles.

Valid values[ "DAY", "WEEK", "MONTH" ]
interval_count
integer

Number of intervals between consecutive cycles.

total_recurrence
integer | null

Total number of cycles (optional; runs indefinitely if null).

anchor_date
string (date-time)

Start date for the recurring schedule (ISO 8601 format).

retry_interval
string

Interval between retry attempts for failed payments.

Valid values[ "DAY" ]
retry_interval_count
integer

Number of retry intervals between consecutive retries.

total_retry
integer

Maximum number of retries for failed cycles.

failed_attempt_notifications
Array of integer

Notifications triggered at specific retry attempts.

integer
payment_methods
Array of object

Array of payment methods that the recurring plan will attempt to make payments with.

object
payment_method_id
string

ID for payment method generated by the Create Payment Method API.

rank
integer

Order in which payment methods will be attempted (1 to 5).

immediate_action_type
string

Action taken upon recurring plan creation. Failing the action will inactivate the plan.

Valid values[ "FULL_AMOUNT" ]
notification_config
object

Notification preferences for the recurring plan.

recurring_created
Array of string

Channels to notify the customer when the plan is created.

string
Valid values[ "WHATSAPP", "EMAIL" ]
recurring_succeeded
Array of string

Channels to notify the customer when a cycle succeeds.

string
Valid values[ "WHATSAPP", "EMAIL" ]
recurring_failed
Array of string

Channels to notify the customer when a cycle fails.

string
Valid values[ "WHATSAPP", "EMAIL" ]
locale
string

Language of notifications sent to the end user.

Valid values[ "en", "id" ]
payment_link_for_failed_attempt
boolean

Whether a payment link is generated for failed cycle attempts.

Defaultfalse
failed_cycle_action
string

Behavior when recurring cycles fail. RESUME continues, STOP inactivates the plan.

Valid values[ "RESUME", "STOP" ]
metadata
object

Additional information provided by the merchant.

property*
string additionalProperties
description
string

Description of the recurring plan, displayed to customers.

Max length1000
items
Array of object

Details of items included in the recurring plan.

object
type
string

Type of item.

Valid values[ "DIGITAL_PRODUCT", "PHYSICAL_PRODUCT", "DIGITAL_SERVICE", "PHYSICAL_SERVICE", "FEE", "DISCOUNT" ]
name
string

Name of the item.

Max length255
net_unit_amount
number

Net amount charged per unit. Negative values for discounts.

quantity
integer

Number of units of the item.

Minimum1.0
url
string (uri)

URL of the item.

category
string

Merchant category for the item.

Max length255
subcategory
string

Subcategory for the item.

Max length255
description
string

Description of the item.

Max length255
metadata
object

Additional item attributes.

property*
string additionalProperties
success_return_url
string (uri)

URL where the end user is redirected after successful account linking. Required when payment_method_id is not provided.

failure_return_url
string (uri)

URL where the end user is redirected if account linking fails. Required when payment_method_id is not provided.

id
string

Xendit-generated recurring plan ID.

status
string

Status of the recurring plan.

Valid values[ "ACTIVE", "INACTIVE", "PENDING" ]
actions
Array of object

Array of objects containing URLs for end users to complete the recurring plan.

object
action
string

Describes the purpose of the action. AUTH triggers payment account linking.

url_type
string

Type of URL, optimized for desktop or web interface.

Valid values[ "WEB" ]
url
string (uri)

Generated URL to perform the action.

method
string

HTTP method for calling the URL.

Valid values[ "GET", "POST" ]
400

Validation errors occurred. Safe to retry.

API_VALIDATION_ERROR

Fields or values in the payload body does not comply with our API specification.

{
  "error_code": "API_VALIDATION_ERROR",
  "message": "Check the specific error message for debugging."
}
object
error_code
string

Error code identifying the issue.

message
string

Description of the error.

401

Invalid API key or unauthorized access. Safe to retry.

object
Example{ "error_code": "INVALID_API_KEY", "message": "API key format is invalid." }
error_code
string
message
string
404

Resource not found. Safe to retry.

DATA_NOT_FOUND

Customer not found.

{
  "error_code": "DATA_NOT_FOUND",
  "message": "Recurring plan_id not found. Please check your query again."
}
object
error_code
string
message
string
415

Unsupported content type. Safe to retry.

object
Example{ "error_code": "UNSUPPORTED_CONTENT_TYPE", "message": "The content type requested is not supported." }
error_code
string
message
string
500

Server error.

object
Example{ "error_code": "SERVER_ERROR", "message": "An unexpected error occurred. Our team has been notified and will troubleshoot the issue." }
error_code
string
message
string