{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/qualpay/json-schema/qualpay-add-recurring-plan-request-schema.json",
  "title": "AddRecurringPlanRequest",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/qualpay-recurring-billing-api-openapi.yml#/components/schemas/AddRecurringPlanRequest",
  "required": [
    "amt_tran",
    "plan_code",
    "plan_desc",
    "plan_duration",
    "plan_frequency",
    "plan_name"
  ],
  "type": "object",
  "properties": {
    "amt_tran": {
      "type": "number",
      "description": "<strong>Format: </strong>Variable length, up to 12,2 N<br><strong>Description: </strong>The plan transaction amount, which is the amount that will be billed each cycle. ",
      "format": "double"
    },
    "plan_code": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 16 AN<br><strong>Description: </strong>A unique alphanumeric code provided by the merchant to identify the plan."
    },
    "plan_desc": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length AN<br><strong>Description: </strong>A short description of the plan."
    },
    "plan_duration": {
      "type": "integer",
      "description": "<strong>Format: </strong>Variable length, up to 4 N<br><strong>Description: </strong> 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.",
      "format": "int32"
    },
    "plan_frequency": {
      "type": "integer",
      "description": "<strong>Format: </strong>Fixed length, 1 N<br><strong>Description: </strong> The billing frequency. Use one of the following codes: <ul> <li>`0` - Weekly</li> <li>`1` - Bi-weekly</li> <li>`3` - Monthly</li> <li>`4` - Quarterly</li> <li>`5` - Bi-annually</li> <li>`6` - Annually</li> <li>`7` - Daily</li> </ul>"
    },
    "plan_name": {
      "type": "string",
      "description": "<strong>Format: </strong>Variable length, up to 64 AN<br><strong>Description: </strong>A unique name assigned to the plan. ",
      "format": "int32"
    },
    "interval": {
      "type": "integer",
      "description": "<strong>Format: </strong>Variable length, up to 2 N<br><strong>Description: </strong>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`. <br><strong>Default: </strong>1",
      "format": "int32"
    },
    "trial_duration": {
      "type": "integer",
      "description": "<strong>Format: </strong>Variable length, up to 2 N<br><strong>Description: </strong>Number of billing cycles in a trial period.",
      "format": "int32"
    },
    "amt_trial": {
      "type": "number",
      "description": "<strong>Format: </strong>Variable length, up to 12,2 N<br><strong>Description: </strong>Amount to be billed during the trial period.",
      "format": "double"
    },
    "amt_setup": {
      "type": "number",
      "description": "<strong>Format: </strong>Variable length, up to 12,2 N<br><strong>Description: </strong>One-time fee amount. When adding a subscription with this plan, a payment gateway sale transaction will be initiated to charge the customer the one-time fee.",
      "format": "double"
    },
    "tran_currency": {
      "type": "string",
      "description": "<strong>Format: </strong>Fixed length, 3 AN<br><strong>Description: </strong>The ISO numeric currency code. 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 <a href=\"/docs/references#currency-codes\" target=\"_blank\">Currency Codes</a> for a list of currency codes.<br><strong>Default: </strong>840"
    },
    "profile_id": {
      "type": "string",
      "description": "<strong>Format: </strong>Fixed length, 20 N<br><strong>Description: </strong>The Payment Gateway profile ID that will 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": {
      "type": "boolean",
      "description": "<strong>Description: </strong>If set to `true`, the customer will be billed on a specific start date.<br><strong>Default: </strong>false"
    },
    "day_of_week": {
      "type": "integer",
      "description": "<strong>Format: </strong>Fixed length, 1 N<br><strong>Description: </strong>This field represents the day of the week on which the system will bill for weekly or biweekly plans.<ul><li>`1` - Sunday</li><li>`2` - Monday</li><li>`3` - Tuesday</li><li>`4` - Wednesday</li><li>`5` - Thursday</li><li>`6` - Friday</li><li>`7` - Saturday</li></ul><p><strong>Conditional Requirement: </strong>Applicable only when `bill_specific_day` is set to `true` (i.e., billing is on a specific day).</p>",
      "format": "int32"
    },
    "day_of_month": {
      "type": "integer",
      "description": "<strong>Format: </strong>Variable length, up to 2 N<br><strong>Description: </strong>Day of the month on which the system will bill for monthly or annual plans. Use `1`-`31` to specify the day of month when the customer will be billed. Use `32` if billing should be on the last day of month. <br><strong>Conditional Requirement: </strong>Applicable only when `bill_specific_day` is set to `true` (i.e., billing is on a specific day).",
      "format": "int32"
    },
    "month": {
      "type": "integer",
      "description": "<strong>Format: </strong>Variable length, up to 2 N<br><strong>Description: </strong>Month in which the system will bill for monthly or annual plans. Use one of the following codes: <ul><li>`1` - January</li><li>`2` - February</li><li>`3` - March</li><li>`4` - April</li><li>`5` - May</li><li>`6` - June</li><li>`7` - July</li><li>`8` - August</li><li>`9` - September</li><li>`10` - October</li><li>`11` - November</li><li>`12` - December</li></ul><p><strong>Conditional Requirement: </strong>Applicable only when `bill_specific_day` is set to `true` (i.e., when billing on a specific day).</p>",
      "format": "int32"
    },
    "prorate_first_pmt": {
      "type": "boolean",
      "description": "<strong>Description: </strong>Set to `true` if the first payment should be prorated. <br><strong>Conditional Requirement: </strong>Applicable only when `bill_specific_day` flag is set to `true` (i.e., when billing is on a specific day)."
    },
    "amt_prorate": {
      "type": "number",
      "description": "<strong>Format: </strong>Variable length, up to 12,2 N<br><strong>Description: </strong>The fixed prorated amount for the 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. <br><strong>Conditional Requirement: </strong>This field is applicable only if `prorate_first_pmt` is set to `true`. ",
      "format": "double"
    },
    "dba_suffix": {
      "type": "string",
      "description": "<strong>Format: </strong>Fixed length, 9 AN<br><strong>Description: </strong>For use by merchants using negative-option marketing.  This field will 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, and the result will appear on the cardholder statement. (If your DBA and suffix contain more that 25 characters, your DBA will be truncated.) Possible values: <ul><li>`END DSCNT`</li><li>`END OFFER`</li><li>`END PROMO`</li><li>`END TRIAL`</li></ul>"
    },
    "merchant_id": {
      "type": "integer",
      "description": "<strong>Format: </strong>Variable length, up to 16 AN<br><strong>Description: </strong>Identifies the merchant to whom this request applies. Optional field, applicable only if the request is sent on behalf of another merchant.<br><strong>Conditional Requirement: </strong>Required if this request is on behalf of another merchant.",
      "format": "int64"
    }
  }
}