Guides
Start typing to search…

Add a Recurring Plan

Create a new plan with Recurring Billing.

The guide below shows you how to create a new recurring plan that you can use for customer subscriptions. See the Recurring Billing page for more information on using recurring plans. See Add a Recurring Plan in API Reference for field definitions.


Prerequisites


Implement

Write a POST request to send to the /platform/plan endpoint. In the body, include your sandbox merchant ID and set the amount, frequency, and duration of billing. Each field below is required for this request. See the following sample code:

curl --request POST \
     --url https://api-test.qualpay.com/platform/plan \
     --header 'accept: application/json' \
     --header 'authorization: Basic OjllZZZjMjFhMzFjMjMjFhMzFjMzjMjFhMzFjME2YWJjMTIz' \
     --header 'content-Type: application/json' \
     --data '
{
     "merchant_id": 210000000289,
     "amt_tran": 19.99,
     "plan_frequency": 0,
     "plan_duration": 10
}
'

Now you can add optional configurations to your request. The sections below describe the types of data you can include in your request. See Add a Recurring Plan in API Reference for field definitions.

Frequency Customization

Add fields to the body of your request to further customize when to bill your customers.

  • If you've set plan_frequency to weekly or monthly, use interval to change the number of weeks or months in a billing cycle. For example, set it to 3 to bill every 3 weeks.
  • To bill the customer on a specific start date, set bill_specific_day to true.
  • Use the other fields below to bill on a specific day or month.

See the code below:

{
     "interval": 3,
     "bill_specific_day": true,
     "day_of_week": 1,
     "day_of_month": 1,
     "month": 0
}

Initial Payment Settings

Add fields to the body of your request to configure settings for your customer's initial payment. For example, you can charge a one-time startup fee or prorate the customer's first payment. See the sample code below:

{
     "amt_setup": 50,
     "prorate_first_pmt": true,
     "amt_prorate": 10
}

Trial Period

Add fields to the body of the request to create a trial period, setting the amount to bill during the trial and the number of billing cycles for the trial period. See the sample code below:

{
     "amt_trial": 9.99,
     "trial_duration": 1,
     "dba_suffix": "END PROMO"
}

Merchant Information

Add one of the fields below to the request body for additional transaction specifications.

  • To specify a Payment Gateway profile for this plan, include profile_id. This includes a currency specification.
  • If you don't include profile_id but want to specify a currency other than USD, use tran_currency.
{
     "profile_id": "21200000000100000840",
     "tran_currency": "840"
}

Example Request

Once configured, the code for your request will resemble the following sample:

curl --request POST \
     --url https://api-test.qualpay.com/platform/plan \
     --header 'accept: application/json' \
     --header 'authorization: Basic OjllZZZjMjFhMzFjMjMjFhMzFjMzjMjFhMzFjME2YWJjMTIz' \
     --header 'content-Type: application/json' \
     --data '
{
     "merchant_id": 210000000289,
     "plan_code": "1234",
     "plan_name": "Your Plan",
     "plan_desc": "ABC Monthly Billing Plan",
     "amt_tran": 19.99,
     "plan_frequency": 0,
     "interval": 3,
     "plan_duration": 10,
     "bill_specific_day": true,
     "day_of_week": 1,
     "amt_setup": 50,
     "prorate_first_pmt": true,
     "amt_prorate": 0,
     "amt_trial": 9.99,
     "trial_duration": 1,
     "dba_suffix": "END PROMO",
     "profile_id": "21200000000100000840"
}
'

Integrate

Send a POST request to the /platform/plan endpoint with your configurations in the body.

Qualpay will return a response like the code below:

{
  "code": 0,
  "message": "Success",
  "data": {
    "merchant_id": 210000000289,
    "plan_id": 1234,
    "plan_code": "1234",
    "plan_name": "Your Plan",
    "plan_desc": "ABC Monthly Billing Plan",
    "plan_frequency": 0,
    "interval": 3,
    "plan_duration": 10,
    "status": "E",
    "trial_duration": 1,
    "amt_trial": 9.99,
    "amt_setup": 50,
    "amt_tran": 19.99,
    "profile_id": "21200000000100000840",
    "bill_specific_day": true,
    "day_of_week": 1,
    "prorate_first_pmt": true,
    "amt_prorate": 0,
    "db_timestamp": "2025-07-10T09:55:30.000Z",
    "mod_timestamp": "2025-07-19T21:15:39.000Z"
  }
}

Check the code field: 0 confirms a successful transaction. If the value is something other than 0, check Platform API Response Codes in Reference.

A Success response means that you have created a new recurring plan. You can now subscribe customers to this plan through the Add a Subscription request.

Check the plan_id field and save its value to your records. You will use this plan_id to add subscriptions and submit other requests relating to this plan. The plan_id is required to delete the plan.

See Add a Recurring Plan in API Reference for field definitions.

🚧

Save Your Plan ID

Be sure to save the plan_id value that appears in your request response. You will need it to interact with this plan using the API.


Test and Go Live

See our Test and Go Live guide to test your API integration and to start transacting with an active production account.


Updated about 1 month ago