--- title: "Add payment schedule items to a custom payment schedule" method: POST path: "/v1/payment-schedules/{paymentScheduleKey}/items" tags: ["Payment Schedules"] --- # Add payment schedule items to a custom payment schedule `POST /v1/payment-schedules/{paymentScheduleKey}/items` 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](https://docs.zuora.com?resourceId=payments-enable-manage-payments-settings) in the Knowledge Center. - This operation is only available if you have [Invoice Settlement](https://docs.zuora.com?resourceId=billing-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. ## Path parameters - `paymentScheduleKey` string, required ## Headers - `Idempotency-Key` string - `Accept-Encoding` string - `Content-Encoding` string - `Zuora-Track-Id` string - `Zuora-Entity-Ids` string - `Zuora-Org-Ids` string - `Zuora-Version` string ## Request body - POSTAddItemsToPaymentScheduleRequest — Container for the payment schedule items to be added to the payment schedule. - `items` PaymentScheduleItemCommon[] - `amount` number, required — The amount that needs to be collected by this payment schedule item. - `currency` string — The currency of the payment. **Note**: - This field is optional. If not specified, the default value is the currency set for the account. - For custom payments, if Multi-currency is enabled, the payment currency can be different from the account currency for custom payment. - For recurring payments, if Multi-currency is enabled, the payment currency can be different from the account currency but should be the same as billing currency for a recurring payment. - `description` string — Description of the payment schedule item. - `paymentGatewayId` string — The ID of the payment gateway. **Note**: - This field is optional. If not specified, the default value is the payment gateway id set for the account. - `paymentMethodId` string — The ID of the payment method. **Note**: - This field is optional. If not specified, the default value is the payment method id set for the account. - `paymentOption` PaymentSchedulePaymentOptionFields[] — Container for the paymentOption items, which describe the transactional level rules for processing payments. Currently, only the Gateway Options type is supported. Here is an example: ``` "paymentOption": [ { "type": "GatewayOptions", "detail": { "SecCode":"WEB" } } ] ``` `paymentOption` of the payment schedule takes precedence over `paymentOption` of the payment schedule item. - `detail` object — The field used to pass the transactional payment data to the gateway side in the key-value format. - `key` string — The name of the field. - `value` string — The value of the field. - `type` string — The type of the payment option. Currently, only `GatewayOptions` is supported for specifying Gateway Options fields supported by a payment gateway. - `runHour` string — At which hour of the day in the tenant’s timezone this payment will be collected. Available values:`[0,1,2,~,22,23]`. If the payment `runHour` and `scheduledDate` are backdated, the system will collect the payment when the next runHour occurs. The default value is `0`. - `scheduledDate` string, date, required — The date to collect the payment. ## Response `200` OK - GETPaymentScheduleResponse — Container for custom fields of a Payment Schedule object. - `accountId` string — ID of the account that owns the payment schedule. - `accountNumber` string — Number of the account that owns the payment schedule. - `billingDocument` object, nullable - `id` string — ID of the billing document. for example, `2c9890306fb2121e016fb21a6b550041`. - `number` string — The number of the billing docuemnt, for example, `INV00002345`. - `type` string — Indicates whether the associated billing document is a debit memo or a invoice. - `billingDocuments` object[] — Container array of the multiple billing documents associated with the payment schedule. - `id` string — ID of the billing document. - `number` string — Number of the billing document. If the billing document is a debit memo, it contains the debit memo number. If the billing document is an invoice, it contains the invoice number. - `type` 'Invoice' | 'DebitMemo' — Denotes if the billing document is of the type invoice or debit memo. - `createdById` string — The ID of the user who created this payment schedule. - `createdDate` string, date — The date and time the payment schedule is created. - `cancellationReason` string, nullable — The reason for the cancellation of the payment schedule item. - `cancelledById` string, nullable — The ID of the user who canceled this payment schedule. - `cancelledOn` string, nullable — The date when the payment schedule was canceled. - `cancelDate` string, date, nullable — Specifies the effective date by when the payment schedule will be canceled. - `description` string, nullable — The description of the payment schedule. - `id` string — ID of the payment schedule. - `isCustom` boolean — Indicates if the payment schedule is a custom payment schedule. - `items` PaymentScheduleItemCommonResponse[] — Container for payment schedule items. - `accountId` string — ID of the customer account that owns the payment schedule item, for example `402880e741112b310149b7343ef81234`. - `amount` number, nullable — The total amount of the payment schedule. - `balance` number — The remaining balance of payment schedule item. - `billingDocument` object, nullable - `id` string — ID of the billing document. for example, `2c9890306fb2121e016fb21a6b550041`. - `number` string — Number of the billing docuemnt, for example, `INV00002345`. - `type` string — Indicates whether the associated billing document is a debit memo or a invoice. - `createdById` string, nullable — The ID of the user who created the payment schedule item. - `createdDate` string, date, nullable — The date and time when the payment schedule item was created. - `currency` string, nullable — The currency of the payment. - `description` string, nullable — The description of the payment schedule item. - `errorMessage` string, nullable — The error message indicating if the error is related to configuration or payment collection. - `id` string — ID of the payment schedule item. For example, `412880e749b72b310149b7343ef81346`. - `number` string — Number of the payment schedule item. - `paymentGatewayId` string, nullable — ID of the payment gateway of the payment schedule item. - `paymentMethodId` string, nullable — ID of the payment method of the payment schedule item. - `paymentOption` PaymentSchedulePaymentOptionFields[] — Container for the paymentOption items, which describe the transactional level rules for processing payments. Currently, only the Gateway Options type is supported. `paymentOption` of the payment schedule takes precedence over `paymentOption` of the payment schedule item. - `detail` object — The field used to pass the transactional payment data to the gateway side in the key-value format. - `key` string — The name of the field. - `value` string — The value of the field. - `type` string — The type of the payment option. Currently, only `GatewayOptions` is supported for specifying Gateway Options fields supported by a payment gateway. - `paymentScheduleId` string — ID of the payment schedule that contains the payment schedule item, for example, `ID402880e749b72b310149b7343ef80005`. - `paymentScheduleNumber` string — Number of the payment schedule that contains the payment schedule item, for example, `ID402880e749b72b310149b7343ef80005`. - `psiPayments` LinkedPaymentID[] — Container for payments linked to the payment schedule item. - `paymentId` string — ID of the payment. - `runHour` integer, nullable — At which hour in the day in the tenant’s timezone this payment will be collected. - `scheduledDate` string, date, nullable — The scheduled date when the payment is processed. - `standalone` boolean — Indicates if the payment created by the payment schedule item is a standalone payment or not. - `status` 'Pending' | 'Processed' | 'Error' | 'Canceled', nullable — ID of the payment method of the payment schedule item. - `Pending`: Payment schedule item is waiting for processing. - `Processed`: The payment has been collected. - `Error`: Failed to collect the payment. - `Canceled`: After a pending payment schedule item is canceled by the user, the item is marked as `Canceled`. - `updatedById` string, nullable — The ID of the user who updated the payment schedule item. - `updatedDate` string, date, nullable — The date and time when the payment schedule item was last updated. - `nextPaymentDate` string, date — The date the next payment will be processed. - `occurrences` integer — The number of payment schedule items that are created by this payment schedule. - `paymentOption` PaymentSchedulePaymentOptionFields[] — Container for the paymentOption items, which describe the transactional level rules for processing payments. Currently, only the Gateway Options type is supported. `paymentOption` of the payment schedule takes precedence over `paymentOption` of the payment schedule item. - `detail` object — The field used to pass the transactional payment data to the gateway side in the key-value format. - `key` string — The name of the field. - `value` string — The value of the field. - `type` string — The type of the payment option. Currently, only `GatewayOptions` is supported for specifying Gateway Options fields supported by a payment gateway. - `paymentScheduleNumber` string — Number of the payment schedule. - `period` string, nullable — For recurring payment schedule only. The period of payment generation. Available values include: `Monthly`, `Weekly`, `BiWeekly`. Return `null` for custom payment schedules. - `prepayment` boolean — Indicates whether the payments created by the payment schedule are used as a reserved payment. This field is available only if the prepaid cash drawdown permission is enabled. See [Prepaid Cash with Drawdown](https://docs.zuora.com?resourceId=billing-prepaid-with-drawdown-overview) for more information. - `recentPaymentDate` string, date, nullable — The date the last payment was processed. - `runHour` integer — [0,1,2,~,22,23] At which hour in the day in the tenant’s timezone this payment will be collected. Return `0` for custom payment schedules. - `standalone` boolean — Indicates if the payments that the payment schedule created are standalone payments. - `startDate` string, date — The date when the first payment of this payment schedule is proccessed. - `status` 'Active' | 'Canceled' | 'Completed' — The status of the payment schedule. - Active: There is still payment schedule item to process. - Canceled: After a payment schedule is canceled by the user, the schedule is marked as `Canceled`. - Completed: After all payment schedule items are processed, the schedule is marked as `Completed`. - `success` boolean — Returns `true` if the request was processed successfully. - `totalAmount` number — The total amount that will be collected by the payment schedule. - `totalPaymentsErrored` integer — The number of errored payments. - `totalPaymentsProcessed` integer — The number of processed payments. - `updatedById` string — The ID of the user who last updated this payment schedule. - `updatedDate` string, date — The date and time the payment schedule is last updated. ## Other responses - `500` — Internal Server Error - `4XX` — Request Errors --- [API](https://skmtc.dev/zuora/apis/api-reference.md) · [All operations](https://skmtc.dev/zuora/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/zuora/api-reference/revisions/d11e237f3e54/schema)