--- title: "Create recurring charge plan" method: POST path: "/v1/recurring-charge-plans" tags: ["Recurring charge plans"] --- # Create recurring charge plan `POST /v1/recurring-charge-plans` Create a recurring charge plan. A recurring charge is a charge that is applied on a monthly basis for a fixed number of installments. When you create a recurring charge plan, you specify the number of installments (cycles) and the installment amount. Creating a plan does not activate it. A plan must be linked to an account to activate the charge schedule defined in it. This endpoint generates a [Recurring charge plan created](https://developers.pismo.io/events/docs/balance-recurring-charge-plan-created-1) event. **NOTES:** - To work correctly, you must set the program parameter [504 - RECURRING_CHARGE_FINAL_ACCOUNT_STATUS](https://developers.pismo.io/pismo-docs/docs/multivalue-parameters) to the value for an account status. Usually you use `CANCELLED` for this. When the account enters this status, the system cancels all pending recurring charges. (Note that if you provide more than one value, the system only uses the first one, even though this is a multivalue program parameter.) - This endpoint requires an account token — an access token encoded with an account ID. Tokens can expire quickly, which can result in a **401 Unauthorized** message. ## Headers - `x-cid` string ## Request body - RecurringChargePlanRequest — Body of a request used to create a recurring charge plan - `processing_code` string, required — Processing code for the debit transaction. If `split_transaction` is `false` (the default), each installment payment is recorded as one debit transaction equal to the installment amount minus the discount, and `processing_code` is the processing code for that transaction. If `split_transaction` is `true`, each installment payment is recorded as two transactions: a debit transaction for the installment amount and a credit transaction for the discount. In this case, `processing_code` is the processsing code for the debit transaction, and `second_processing_code` is the processing code for the credit transaction. - `installment_amount` number, double, required — `installment_amount` is the full amount of an installment before any discount is applied. - `description` string — Used if the recurring charge link description is not provided. Use "{counter}" to indicate where the cycle count should be placed. Example: "{counter} Annuity" generates "2/12 Annuity" for the second of twelve installments. If "{counter}" is not present, the counter is placed at the end of the description. If no description is provided, the transaction type's description is used and the counter is not shown. - `split_transaction` boolean — Use separate transactions for the installment amount and the discount? Suppose the installment amount for a cycle is $20 and the discount is $2. If `split_transaction` is `false`, then one debit transaction for $18 ($20 - $2) is posted to the account for that cycle. It also appears as one debit transaction on the statement. If `split_transaction` is `true`, then two transactions are posted to the account — a debit transaction for $20 and a credit transaction for $2 — and those two transactions appear on the statement. When `split_transaction` is `true`, `secondary_processing_code` is used to create the credit transaction. Note: You aren't forced to specify a debit transaction with `processing_code` and a credit transaction with `secondary_processing_code`, but it's highly recommended. It's difficult to think of a scenario where you would want to do something else. - `secondary_processing_code` string — Used to create the transaction for `secondary_installment_amount`. Normally, you should use a processing code for a credit transaction. - `secondary_description` string — Used to create a description for the secondary transaction. Use "{counter}" to indicate where the cycle count should be placed. Example: "{counter} Annuity" generates "2/12 Annuity" for the second of twelve installments. If "{counter}" is not present, the counter is be placed at the end of the description. If no description is provided, the transaction type's description is used and the counter is not shown. - `number_of_cycles` integer, required — Number of cycles to apply the charge plan. In other words, this is the number of installments. Must be greater than `first_cycles_to_discount` if used. Otherwise, it must be greater than 0. - `first_cycles_to_discount` integer — The number of cycles the discount (defined by `discount_percentage`) should be applied to before reverting to the full charge. For example, if `number_of_cycles` is 6 and `first_cycles_to_discount` is 2, then the discount is applied to cycles 1 and 2. The full charge is applied to cycles 3 through 6. If present, `first_cycles_to_discount` must be positive and less than `number_of_cycles`." - `discount_percentage` number, double — Percentage value to be discounted if `first_cycles_to_discount` is configured. Range: 0 to 100. - `minimum_spend_to_charge` number, double — Minimum debit amount on statement to enable cycle charging. If `minimum_spend_to_charge` is not configured, the charge plan does not check the debit statement amount. - `renew_method` 'NO_RENEW' | 'WITHOUT_DISCOUNT' | 'WITH_DISCOUNT' — NO_RENEW: The link does not renew at the end of the cycle. WITHOUT_DISCOUNT: The link is renewed at the end of the cycle, but the discounts registered in the plan are not applied. WITH_DISCOUNT: The link is renewed at the end of the cycle, and the discounts registered in the plan are applied." - `tracking_id` string, required — Customer created tracking ID. Must consist of alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and colons (:), with a length from 1 to 128. The Pismo platform uses this field to implement idempotency and prevent duplicates. ## Response `200` OK - The recurring charge plan was created. - RecurringChargePlan — Recurring charge plan - `recurring_charge_plan_id` integer — ID of recurring charge plan - `org_id` string — Organization ID - `processing_code` string — Processing code for the debit transaction. If `split_transaction` is `false` (the default), each installment payment is recorded as one debit transaction equal to the installment amount minus the discount, and `processing_code` is the processing code for that transaction. If `split_transaction` is `true`, each installment payment is recorded as two transactions: a debit transaction for the installment amount and a credit transaction for the discount. In this case, `processing_code` is the processsing code for the debit transaction, and `second_processing_code` is the processing code for the credit transaction. - `installment_amount` number, double — `installment_amount` is the full amount of an installment before any discount is applied. - `description` string — Used if the recurring charge link description is not provided. Use "{counter}" to indicate where the cycle count should be placed. Example: "{counter} Annuity" generates "2/12 Annuity" for the second of twelve installments. If "{counter}" is not present, the counter is placed at the end of the description. If no description is provided, the transaction type's description is used and the counter is not shown. - `split_transaction` boolean — Use separate transactions for the installment amount and the discount? Suppose the installment amount for a cycle is $20 and the discount is $2. If `split_transaction` is `false`, then one debit transaction for $18 ($20 - $2) is posted to the account for that cycle. It also appears as one debit transaction on the statement. If `split_transaction` is `true`, then two transactions are posted to the account — a debit transaction for $20 and a credit transaction for $2 — and those two transactions appear on the statement. When `split_transaction` is `true`, `secondary_processing_code` is used to create the credit transaction. Note: You aren't forced to specify a debit transaction with `processing_code` and a credit transaction with `secondary_processing_code`, but it's highly recommended. It's difficult to think of a scenario where you would want to do something else. - `secondary_processing_code` string — Used to create the transaction for `secondary_installment_amount`. Normally, you should use a processing code for a credit transaction. - `secondary_description` string — Used to create a description for the secondary transaction. Use "{counter}" to indicate where the cycle count should be placed. Example: "{counter} Annuity" generates "2/12 Annuity" for the second of twelve installments. If "{counter}" is not present, the counter is placed at the end of the description. If no description is provided, the transaction type's description is used and the counter is not shown. - `number_of_cycles` integer — Number of cycles to apply the charge plan. In other words, this is the number of installments. Must be greater than `first_cycles_to_discount` if used. Otherwise, it must be greater than 0. - `first_cycles_to_discount` integer — The number of cycles the discount (defined by `discount_percentage`) should be applied to before reverting to the full charge. For example, if `number_of_cycles` is 6 and `first_cycles_to_discount` is 2, then the discount is applied to cycles 1 and 2. The full charge is applied to cycles 3 through 6. If present, `first_cycles_to_discount` must be positive and less than `number_of_cycles`." - `discount_percentage` number, double — Percentage value to be discounted if `first_cycles_to_discount` is configured. Range: 0 to 100. - `minimum_spend_to_charge` number, double — Minimum debit amount on statement to enable cycle charging. If `minimum_spend_to_charge` is not configured, the charge plan does not check the debit statement amount. - `renew_method` 'NO_RENEW' | 'WITHOUT_DISCOUNT' | 'WITH_DISCOUNT' — NO_RENEW: The link does not renew at the end of the cycle. WITHOUT_DISCOUNT: The link is renewed at the end of the cycle, but the discounts registered in the plan are not applied. WITH_DISCOUNT: The link is renewed at the end of the cycle, and the discounts registered in the plan are applied." - `tracking_id` string — Customer created tracking ID. Must consist of alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and colons (:), with a length from 1 to 128. The Pismo platform uses this field to implement idempotency and prevent duplicates. - `cid` string — The Correlation IDentifier field is used to link related API requests and events. The x-cid can help the Pismo engineering team track everything related to a call. - `created_at` string, date-time — Datetime program calendar strategy was created. Format = YYYY-MM-DDTHH:MM:SS:MM. ## Other responses - `400` — Bad request - `409` — The specified resource status conflicts with the current request. - `500` — Internal server error --- [API](https://skmtc.net/pismo/apis/platform-authentication.md) · [All operations](https://skmtc.net/pismo/apis/platform-authentication/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pismo/platform-authentication/revisions/935b62e16de4/schema)