--- 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` ## Request - Base URL: `https://sandbox.pismolabs.io/recurring-charge` - URL: `https://sandbox.pismolabs.io/recurring-charge/v1/recurring-charge-plans` - Auth: HTTP bearer Create a recurring charge plan. A recurring charge is a charge that is applied on a monthly basis for a fixed number of cycles. When you create a recurring charge plan, you specify the number of cycles and the amount of the monthly charge. Creating a plan does not activate it. You must link the plan 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:** - If an account is canceled while it has an active recurring charge attached to it, you want the recurring charge to be canceled, too, so that charges don't continue to accrue. To ensure this, set the multivalue program parameter [504 - RECURRING_CHARGE_FINAL_ACCOUNT_STATUS](doc: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 recurring payment is recorded as one debit transaction equal to the payment amount minus the discount, and `processing_code` is the processing code for that transaction. If `split_transaction` is `true`, each recurring payment is recorded as two transactions: a debit transaction for the payment 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 a recurring charge 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 recurring charges. 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 amount of the recurring charge and the discount? Suppose the recurring charge 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 recurring charges. 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: Tracking ID ## 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 recurring payment is recorded as one debit transaction equal to the payment amount minus the discount, and `processing_code` is the processing code for that transaction. If `split_transaction` is `true`, each recurring payment is recorded as two transactions: a debit transaction for the payment 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 a recurring charge 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 amount of the recurring charge and the discount? Suppose the recurring charge 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 recurring charges. 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 recurring charges. 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: Tracking ID - `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 (GMT-3) that asset was registered on Pismo platform ## Other responses - `400`: Bad Request - `409`: The specified resource status conflicts with the current request. - `500`: Internal server error --- [API](https://skmtc.dev/pismo/apis/revolving-credit-recurring-charges.md) - [All operations](https://skmtc.dev/pismo/apis/revolving-credit-recurring-charges/llms.txt) - [OpenAPI document](https://skmtc.dev/pismo/apis/revolving-credit-recurring-charges/revisions/a5fea1d82e51?raw)