API references
Search documentation... ⌘K
Open merchant dashboard
Merchant API
All our references

Retrieve current plan

Retrieves the current billing plan for the merchant account. This endpoint returns the plan details including the plan ID, name, tier, and any associated metadata. It is used to check the current subscription status and plan features available to the merchant.

The response includes information about the plan's tier, which indicates the level of service provided. It also reports pending_plan_id, the plan a scheduled change will promote to, or null when no change is scheduled.

Endpoint signature
This endpoint requires an API key. Read our authentication guide for more information.
POST https://api.reservepay.com/merchants/retrieve-current-plan HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer <token>
{}
Returns: object.current_plan
New to Reservepay? Read our guide on how to call endpoints to get started.
Current plan attributes
Attribute Description
id
string

Nullable. The unique identifier of the plan.
tier_code
string

Always present. The code representing the tier this plan belongs to.

Possible values:
  • pay_as_you_go
  • startup
  • professional
  • enterprise
tier_name
string

Always present. The name of the tier (e.g., 'Basic', 'Pro').
features
array<string>

Always present. List of features included in this plan.
revision_time
number

Always present. The date and time when the plan was last revised.
selectable
boolean

Always present. Indicates whether the plan can be selected by the merchant via self-service.
rank
number

Always present. The ordering of the plan's tier. Selecting a plan whose rank is greater than or equal to the current plan's rank takes effect immediately; selecting a lower rank is scheduled for the start of the next billing month.
skus
array<object.plan_sku>

Always present. List of SKUs included in this plan.
pending_plan_id
string

Nullable. The identifier of the plan a scheduled change will promote to, or null when no change is scheduled. Only downgrades are ever scheduled; upgrades are promoted immediately.
Plan sku attributes
Attribute Description
code
string

Always present. The code of the SKU.
category
string

Always present. The category of the SKU. I.e. what type of billable it applies to.

Possible values:
  • DISPUTE
  • INSTALLMENT
  • PLAN
  • PAYOUT
  • REFUND
  • METADATA
  • VIRTUAL_ACCOUNT
  • BANK_ACCOUNT_VALIDATION
  • COMMUNICATION
  • PAYMENT
unit_price
number

Nullable. The unit price of the SKU. Each billable item is charged this amount.
percentage_fee
number

Nullable. The percentage fee of the SKU. Each billable item is charged this percentage of its billable amount. E.g. for payments and payouts, that's the percentage of the payment amount.
fee_calculation_method
string

Always present. How unit_price and percentage_fee are combined into a fee for daily statements.

  • SUM: Both are charged.
  • HIGHER_OF: The higher of the two is charged. I.e. unit_price acts as a minimum. E.g. 3% with a minimum fee of 10 THB.
  • LOWER_OF: The lower of the two is charged. I.e. unit_price acts as a maximum. E.g. 3% with a maximum fee of 10 THB.
Possible values:
  • SUM
  • HIGHER_OF
  • LOWER_OF
discount_unit_price
number

Nullable. The discounted unit price, if any. When present and applicable, replaces unit_price. Conditions may apply.
discount_percentage_fee
number

Nullable. The discounted percentage fee, if any. When present and applicable, replaces percentage_fee. Conditions may apply.
discount_minimum_billable_amount
number

Nullable. The minimum billable amount for the discount to apply. E.g. 0 THB fee on payments over 1000 THB. Null when no minimum applies.
discount_maximum_billable_amount
number

Nullable. The maximum billable amount for the discount to apply. E.g. 0 THB fee on payments under 1000 THB. Null when no maximum applies.
discount_maximum_monthly_uses
number

Nullable. How many times per month this discount can be applied per merchant account. Follows calendar months. Null when no limit applies.
discount_shared_monthly_uses
boolean

Always present. Whether this discount shares its discount_maximum_monthly_uses with other SKUs of the same category.

Possible values:
  • true
  • false
Errors specific to this endpoint
NO_PLAN_SELECTED

The merchant is not currently subscribed to any plan. A plan must be subscribed to via the select-plan endpoint first.

Errors common to all endpoints
UNHANDLED_ERROR

This error occurs when the server encounters an unexpected internal error that it cannot handle gracefully. This typically happens due to bugs, infrastructure issues, or edge cases that weren't anticipated during development.

INVALID_ARGUMENTS

This error occurs when the request contains invalid or missing parameters. Common cases include missing required fields, or values that don't match the expected format or type.

BAD_VERSION

This error occurs when making requests to an API version that does not exist. This commonly happens when using an outdated SDK or when the API version specified in the request URL is incorrect.

Open in Markdown
CODE SAMPLES
curl
curl "https://api.reservepay.com/merchants/retrieve-current-plan" \
  -X POST
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $(RESERVEPAY_API_KEY)" \
  -d '{}'
Learn how to run these code samples in your terminal by reading our guide.