Update a Recurring Plan

put

https://api-test.qualpay.com/platform/plan/{plan_code}

Updates an active recurring plan. Only the fields sent in the request body are updated.

If there are subscribers to the specified plan:

The plan is archived and a copy of the plan with a new plan_id is generated.
All updates will be made on the new plan.
You should save the new plan_id and use it to manage the plan.

Path Params

plan_code

string

required

A unique merchant-generated code that identifies the plan to be updated.

Body Params

Recurring Plan Object. Send only the fields that require an update. Read only fields will be ignored

plan_name

string

Format: Variable length, up to 64 AN
Description: A unique name assigned to the plan.

plan_desc

string

Format: Variable length AN
Description: A short description of the plan.

plan_frequency

int32

Format: Fixed length, 1 N
Description: The billing frequency. Use one of the following codes:

0 - Weekly
1 - Bi-weekly
3 - Monthly
4 - Quarterly
5 - Bi-annually
6 - Annually
7 - Daily

interval

int32

Format: Variable length, up to 2 N
Description: Number of months or weeks in a subscription cycle. For example, if plan_frequency is 3 (monthly) and interval is 2, a customer on this plan will be billed every 2 months until the subscription is complete or canceled. Applicable only for monthly or weekly plan_frequency.
Default: 1

plan_duration

int32

Format: Variable length, up to 4 N
Description: Number of billing cycles in the recurring transaction. For example, if plan_frequency is 3 (monthly) and plan_duration is 6, the customer will be billed every month for 6 months. -1 indicates 'bill until canceled.'

trial_duration

int32

Format: Variable length, up to 2 N
Description: Number of billing cycles in a trial period.

amt_trial

double

Format: Variable length, up to 12,2 N
Description: Amount to be billed during the trial period.

amt_setup

double

Format: Variable length, up to 12,2 N
Description: One-time fee amount. When adding a subscription to this plan, a Payment Gateway Sale transaction will be initiated to charge the customer this one-time fee.

amt_tran

double

Format: Variable length, up to 12,2 N
Description: Plan transaction amount. The amount that will be billed each cycle.

tran_currency

string

Format: Fixed length, 3 AN
Description: The ISO numeric currency code for the transaction. This must be a currency code associated with one of your payment profiles; contact Qualpay to add currencies. If profile_id is provided, the currency is determined from the profile. Refer to Currency Codes for a list of currency codes.
Default: 840

profile_id

string

Format: Fixed length, 20 N
Description: The Payment Gateway profile ID to be used for subscriptions on this plan. If profile_id is not provided, tran_currency will be used. If neither profile_id nor tran_currency is provided, the default USD profile is used.

bill_specific_day

boolean

Description: If set to true, the customer will be billed on a specific start date.
Default: false

day_of_week

int32

Format: Fixed length, 1 N
Description: The day of the week on which the system will bill for weekly or biweekly plans:

1 - Sunday
2- Monday
3 - Tuesday
4 - Wednesday
5 - Thursday
6- Friday
7 - Saturday

Conditional Requirement: Applicable only when bill_specific_day flag is set to true (i.e., when billing on a specific day).

day_of_month

int32

Format: Variable length, up to 2 N
Description: The day of the month on which the system will bill for monthly or annual plans. Use 1-31 to specify the day of the month when the customer will be billed. Use 32 if billing on the last day of the month.
Conditional Requirement: Applicable only when bill_specific_day is set to true (i.e., when billing on a specific day).

month

int32

Format: Variable length, up to 2 N
Description: The month in which the system will bill for monthly or annual plans. Use one of the following codes:

1 - January
2 - February
3 - March
4 - April
5 - May
6 - June
7 - July
8 - August
9 - September
10 - October
11 - November
12 - December

Conditional Requirement: Applicable only when bill_specific_day is set to true (i.e., when billing on a specific day).

prorate_first_pmt

boolean

Description: Set this flag to true if the first payment should be prorated.
Conditional Requirement: Applicable only when bill_specific_day is set to true (i.e., when billing on a specific day).

amt_prorate

double

Format: Variable length, up to 12,2 N
Description: The fixed prorated amount for first payment. If set to 0 or undefined, the system will calculate the prorated amount based on the number of days remaining in the first cycle.
Conditional Requirement: This field is applicable only if prorate_first_pmt is set to true.

dba_suffix

string

Format: Fixed length, 9 AN
Description: For use by merchants using negative-option marketing. This field must be used in the first transaction at the conclusion of the free or reduced trial. This suffix will be appended to the end of your DBA on the cardholder statement. (If your DBA and suffix contain more that 25 characters, your DBA will be truncated.) Possible values:

END DSCNT
END OFFER
END PROMO
END TRIAL

merchant_id

int64

Format: Variable length, up to 16 AN
Description: Identifies the merchant to whom this request applies. Optional field, applicable only if the request is sent on behalf of another merchant.
Conditional Requirement: Required if this request is on behalf of another merchant.

Responses

200Success

400Request Validation Failed

500Internal Error