# Payment Schedules Use payment schedules to split invoice or account balances into several installments and automatically process payments for the installments. For more information about payment schedules, see Payment Schedules. ## Retry failed payment schedule items - [POST /v1/payment-schedule-items/retry-payment](https://developer.zuora.com/v1-api-reference/api/payment-schedules/post_retrypaymentscheduleitem.md): Retries failed payment schedule items. The payment method and payment gateway of the failed payment can be updated to new values before the retry. Note that you can retry a payment schedule item only when the payment schedule item is either in the Error or Pending status. Note: - To manage and access this feature through the self-service interface, see Manage Features in the Knowledge Center. - This operation is only available if you have Invoice Settlement enabled. ## Cancel a payment schedule item - [PUT /v1/payment-schedule-items/{item-id}/cancel](https://developer.zuora.com/v1-api-reference/api/payment-schedules/put_cancelpaymentscheduleitem.md): Cancels a payment schedule item by ID. Note: - The Payment Schedules feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see Manage Features in the Knowledge Center. - This operation is only available if you have Invoice Settlement enabled. ## Skip a payment schedule item - [PUT /v1/payment-schedule-items/{item-id}/skip](https://developer.zuora.com/v1-api-reference/api/payment-schedules/put_skippaymentscheduleitem.md): Skips a payment schedule item by ID. The skipped payment schedule item will turn to the canceled status, and a new item will be scheduled on the next recurring date after the last existing scheduled date. Note: - Only payment schedule items in recurring payment schedules can be skipped, and the item must be in the pending status. - The Payment Schedules feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see Manage Features in the Knowledge Center. - This operation is only available if you have Invoice Settlement enabled. ## Retrieve a payment schedule item - [GET /v1/payment-schedule-items/{psi-id}](https://developer.zuora.com/v1-api-reference/api/payment-schedules/get_paymentscheduleitem.md): Retrieves a payment schedule item by ID. Note: - The Payment Schedules feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see Manage Features in the Knowledge Center. - This operation is only available if you have Invoice Settlement enabled. ## Update a payment schedule item - [PUT /v1/payment-schedule-items/{psi-id}](https://developer.zuora.com/v1-api-reference/api/payment-schedules/put_paymentscheduleitem.md): Updates a payment schedule item by ID. Note: - The Payment Schedules feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manag](https://knowledgecenter.zuora.com/Zuora_Payments/Payments_Settings/Manage_Features). - This operation is only available if you have Invoice Settlement enabled. - To link or unlink multiple payments with the item, specify the linkPayments and unlinkPayments field in the request body. - When the Multi-currency and Standalone Payments features are not enabled, you can create and update a payment schedule and payment schedule item in a currency other than the account currency. - The maximum number of payments that are allowed to be linked to a payment schedule item is 10. - When unlinking and linking payments with the payment schedule item in one request, Zuora will first unlink the linked payments, and then link new payments to the item. ## Delete a payment schedule item - [DELETE /v1/payment-schedule-items/{psi-id}](https://developer.zuora.com/v1-api-reference/api/payment-schedules/deletepaymentscheduleitem.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Deletes a payment schedule item. You can delete a payment schedule item with the Canceled status. ## List payment schedules by customer account - [GET /v1/payment-schedules](https://developer.zuora.com/v1-api-reference/api/payment-schedules/get_paymentschedules.md): Retrieves payment schedules of a customer account. Note: - The Payment Schedules feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see Manage Features in the Knowledge Center. - This operation is only available if you have Invoice Settlement enabled. ## Create a payment schedule - [POST /v1/payment-schedules](https://developer.zuora.com/v1-api-reference/api/payment-schedules/post_paymentschedule.md): Creates a payment schedule. You can create either recurring payment schedules or custom payment schedules. Note: - This operation is only available if you have Invoice Settlement enabled. - You can choose to use payment schedules to process payments associated with billing documents or unapplied payments. If Standalone Payment is enabled, you can also use payment schedules to process standalone payments. - If multiple billing documents are associated to a payment schedule, when collecting the payment schedule item, the payment belongs to the payment schedule item will be applied to billing documents based on the due date of the billing document, in the ascending order. - When the Multi-currency and Standalone Payments features are not enabled, you can create and update a payment schedule and payment schedule item in a currency other than the account currency. - This operation is version controlled. If you set Zuora-Version to 329.0, when creating custom payment schedules associated with billing documents, you need to specify the billing document for each payment schedule item; If Zuora-Version is set to 330.0 or a later available version, when creating custom payment schedules associated with billing documents, you only need to specify the billing documents at the payment schedule level. The default version number is 329.0. However, we recommend that you specify the version to 330.0 or a later version. ## Create multiple payment schedules at once - [POST /v1/payment-schedules/batch](https://developer.zuora.com/v1-api-reference/api/payment-schedules/post_paymentschedules.md): Creates multiple payment schedules at once. You can create both recurring payment schedules and custom payment schedules in one request. The maximum number of payment schedules that can be created by a single request is 50. The maximum number of payment schedule items that each payment schedule can contain is 1000, i.e., you must specify less than 1000 items for a custom payment schedule, and the occurrences field must be less than 1000 for a recurring payment schedule. Note: - This operation is only available if you have Invoice Settlement enabled. - If multiple billing documents are associated to a payment schedule, when collecting the payment schedule item, the payment belongs to the payment schedule item will be applied to billing documents based on the due date of the billing document, in the ascending order. - If Standalone Payment is enabled, you can choose to use payment schedules to process payments associated with billing documents, standalone payments, or unapplied payments. If Standalone Payment is not enabled, you can only use payment schedules to process unapplied payments or payments associated with billing documents. - This operation is version controlled. If you set Zuora-Version to 329.0, when creating custom payment schedules associated with billing documents, you need to specify the billing document for each payment schedule item; If Zuora-Version is set to 330.0, when creating custom payment schedules associated with billing documents, you only need to specify the billing documents at the payment schedule level. The default version number is 329.0. However, we recommend that you specify the version to 330.0. 329.0 will be deprecated soon. ## Retrieve payment schedule statistic of a date - [GET /v1/payment-schedules/statistics/{yyyy-mm-dd}](https://developer.zuora.com/v1-api-reference/api/payment-schedules/get_paymentschedulestatistic.md): Retrieves the payment schedule statistic of a specific date. Note: - The Payment Schedules feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see Manage Features in the Knowledge Center. ## Retrieve a payment schedule - [GET /v1/payment-schedules/{paymentScheduleKey}](https://developer.zuora.com/v1-api-reference/api/payment-schedules/get_paymentschedule.md): Retrieves a payment schedule by payment schedule key. Note: - The Payment Schedules feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see Manage Features in the Knowledge Center. - This operation is only available if you have Invoice Settlement enabled. ## Update a payment schedule - [PUT /v1/payment-schedules/{paymentScheduleKey}](https://developer.zuora.com/v1-api-reference/api/payment-schedules/put_paymentschedule.md): Updates a payment schedule. For custom payment schedules, only the custom fields on the payment schedules can be udpated. Use the Update a payment schedule item operation to update payment schedule items of custom payment schedule. Note the following rules for the periodStartDate, period, and occurrences: - If periodStartDate is specified, all pending payment schedule items will be rescheduled using this new periodStartDate. If period is changed, we recommend passing in periodStartDate. Otherwise, the system would use the original start date if there is no processed or canceled items, or the last processed or canceled 'scheduleDate + 1 period' as the new periodStartDate. - If only occurrences is updated, the new item will start with the last processed or canceled 'scheduleDate + 1 period'. Note: - The Payment Schedules feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see Manage Features in the Knowledge Center. - This operation is only available if you have Invoice Settlement enabled. - When the Multi-currency and Standalone Payments features are not enabled, you can create and update a payment schedule and payment schedule item in a currency other than the account currency. ## Delete a payment schedule - [DELETE /v1/payment-schedules/{paymentScheduleKey}](https://developer.zuora.com/v1-api-reference/api/payment-schedules/deletepaymentschedule.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Deletes a payment schedule. You can delete a payment schedule with the Canceled status. ## Cancel a payment schedule - [PUT /v1/payment-schedules/{paymentScheduleKey}/cancel](https://developer.zuora.com/v1-api-reference/api/payment-schedules/put_cancelpaymentschedule.md): Cancels a payment schedule. Note: - All pending payment schedule items will be canceled, effective from cancelDate. - The Payment Schedules feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see Manage Features in the Knowledge Center. - This operation is only available if you have Invoice Settlement enabled. - For more information on the payment schedule cancellation use case, see Payment schedules use cases in the Knowledge Center. ## Add payment schedule items to a custom payment schedule - [POST /v1/payment-schedules/{paymentScheduleKey}/items](https://developer.zuora.com/v1-api-reference/api/payment-schedules/post_additemstocustompaymentschedule.md): Adds payment schedule items to a custom payment schedule. You cannot use this operation to add payment schedule items to recurring payment schedules. Note: - The Payment Schedules feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see Manage Features in the Knowledge Center. - This operation is only available if you have Invoice Settlement enabled. - When the Multi-currency and Standalone Payments features are not enabled, you can create and update a payment schedule and payment schedule item in a currency other than the account currency. ## Preview the result of payment schedule updates - [PUT /v1/payment-schedules/{paymentScheduleKey}/preview](https://developer.zuora.com/v1-api-reference/api/payment-schedules/put_paymentscheduleupdatepreview.md): Preview the result of a payment schedule update. This operation only provides a preview. No changes will be made to the database. For custom payment schedules, only the custom fields on the payment schedules can be udpated. Use the Update a payment schedule item operation to update payment schedule items of custom payment schedule. Note the following rules for the periodStartDate, period, and occurrences: - If periodStartDate is specified, all pending payment schedule items will be rescheduled using this new periodStartDate. If period is changed, we recommend passing in periodStartDate. Otherwise, the system would use the original start date if there is no processed or canceled items, or the last processed or canceled 'scheduleDate + 1 period' as the new periodStartDate. - If only occurrences is updated, the new item will start with the last processed or canceled 'scheduleDate + 1 period'. Note: - The Payment Schedules feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see Manage Features in the Knowledge Center.