Skip to main content

Link payments with payment schedules

Zuora

Link payments with payment schedules

The Payment Schedules feature provides the ability to link a payment schedule item to a payment. 

  • You can manually link a payment to a payment schedule item by specifying the payment number on the payment schedule item side.
  • During payment creation or update, you can the payment with a payment schedule. The payment will be automatically linked to a payment schedule item of the specified payment schedule.
  • You can leverage the fuzzy logic for payment mapping to allow automation of linking incoming payments to payment schedule items.

After a payment schedule item was linked to a payment, the status of the payment schedule item will change to Processed. But you can relink the payment schedule item to a new payment, or unlink it.

Link payment schedule items to payments from the payment schedule item side

You can link a payment schedule item to a payment, update the item to be linked to another payment, or unlink it with the payment by editing the payment schedule item.

Note the following when linking payment schedule items to payments:

  • The status of the payment to be linked MUST NOT be Canceled, and the status of the payment schedule item must be Pending or Processed.
  • The payment MUST NOT be linked to another payment schedule item already.
  • If a billing document is specified on the payment schedule item, the billing document must be paid by the linked payment.

To edit the linking relationship between a payment schedule item and a payment :

  1. Go to the payment schedule detail page.
  2. Click edit on the left of the payment schedule item that you want to update.
  3. Enter a payment number in Payment Number, or remove the existing one. 
  4. Click Save Changes.

You can link the payment schedule item to a payment even when the amounts specified on the item and the payment are different.

Link payment schedule items to payments from the payment side

A payment can be linked to an existing payment schedule upon creation or update of the payment. You can use the Payment Schedule Number field to specify the payment schedule to be linked to the payment. The payment will then be automatically linked to a payment schedule item of the specified payment schedule.

See Create a payment for information about payment creation.

Note that only when ALL the following requirements are met, the automatic linking can succeed:

  • The status of the payment schedule item to be linked must be Pending.
  • The payment schedule item must not be linked to any other payment already.
  • The amount on the payment schedule item and the payment must be the same.
  • The billing document associated with the payment schedule must be one of the billing documents that the payment will pay against.
  • The effective date of the payment must be no earlier than “the scheduled date of the payment schedule item - 5 days” AND no later than “the scheduled date of the payment schedule item + 5 days”.
  • The payment schedule status must be Active.
  • The payment must belong to the same account of the payment schedule.

If the payment matches multiple payment schedule items, the payment schedule item with the earliest scheduled date will be linked to that payment.

Note that no error message will be displayed if the automatic link process has failed.

You can also use the Create a payment and Update a payment REST APIs to link payment to a payment schedule.

Enable auto-linking of payments and payment schedule items

The fuzzy logic for payment mapping enables the automatic linking of incoming payments to payment schedule items.

After the fuzzy logic setting is turned on, Zuora will automatically link newly created or imported payments to a payment schedule item. With this setting enabled, you need to specify a time range within which a payment and a payment schedule item are allowed to be linked.

To turn on the Fuzzy Logic setting:

  1. On Zuora UI, navigate to Payments Setting > Payment Schedules
  2. Check the Enable Fuzzy checkbox
  3. Specify a number for the Threshold Days field and click Submit

The fuzzy logic setting is enabled and Zuora will try to link new payments to payment schedules automatically.

Note that a successful linking must meet all the following validation rules:

  • The following formula is satisfied: Collection Date of the payment schedule item - Threshold Value < Payment Date of the payment < Collection Date of the payment schedule item + Threshold Value. For example, suppose the Collection Date of a payment schedule item is 2022/10/1 and the Threshold Value is set to 5, a payment with a Payment Date between 2022/09/26 to 2022/10/6 would be linked to the payment schedule item if all the other validations are passed.
  • The invoice on the payment schedule item and the payment is the same.
  • The amount of the payment schedule item and payment is the same.
  • The status of the payment schedule item to be linked must be Pending and the payment schedule item has not been linked to any other payment.
  • The payment schedule status must be Active.
  • The payment and the payment schedule item must belong to the same account.