Payment plans

See also: Payment plan object

Payment plans allow customers to pay for a booking in instalments.

Creators configure payment plans at the product level. A plan defines:

• Either a minimum and maximum number of instalments (2–12), where the system resolves the optimal count based on the product's start date, or a set number of instalments.
• An optional fixed initial payment amount per item. If not set, the total is split equally across all instalments.
• A schedule type - either monthly intervals or specific due dates chosen by the creator.

The first payment is always collected at the time of booking.

Payment plans can be used with Experiences, Accommodations, and custom-priced Packages.

Availability

Payment plan details are available on each variant through:

variant.payment_plan

This returns a Payment plan object, or nil if no plan is available.

A payment plan is unavailable (returns nil) when:

• The product has no payment plan configured.
• The final scheduled payment would fall on or after the product's start date.
• A specific-date plan has expired (not enough future due dates remain).

A payment plan should not be displayed when:

• The variant price is 0.
• A promotion reduces the price below a fixed initial payment amount.

Slot context

For experience variants, variant.payment_plan is slot-aware. The number of instalments may differ per slot depending on how far away the start date is — slots with closer start dates may resolve to fewer instalments, or return nil if there isn't enough time.

When accessed through experience_slot.variants, the payment plan is scoped to that slot's start date. When accessed through product.variants, the furthest future slot is used.

Displaying a payment plan

Use initial_payment_amount_fractional to get the first instalment amount for one item. This is calculated automatically based on the variant's price — whether the creator set a fixed initial payment or not. At checkout, a fixed initial payment is multiplied by the line item quantity.

{% assign payment_plan = variant.payment_plan %}

{% if payment_plan and variant.price.fractional != 0 %}
  <p>
    Pay {{ payment_plan.initial_payment_amount_fractional | money }} today,
    then {{ payment_plan.number_of_instalments | minus: 1 }} further payments.
  </p>
{% endif %}

Showing the full schedule

Use instalment_schedule to display all payment dates:

{% if payment_plan %}
  <ul>
    {% for item in payment_plan.instalment_schedule %}
      <li>{{ item.due_date | date: "%d %B %Y" }}</li>
    {% endfor %}
  </ul>
{% endif %}

You can check whether the plan uses monthly intervals or specific dates:

{% if payment_plan.monthly %}
  Monthly instalments
{% elsif payment_plan.specific_dates %}
  Payments on specific dates
{% endif %}

Developer considerations

When implementing payment plans:

• Always read payment plan details from variant.payment_plan.
• Use initial_payment_amount_fractional for the first payment amount — it handles both fixed and calculated initial payments.
• Calculate amounts using the final selling price, including any active promotions.
• Don't display payment plans for zero-priced variants.
• Don't display payment plans when a fixed initial payment is greater than the final selling price.
• Use experience_slot.variants for slot-aware instalment counts on experience products.
• Use money filters when displaying payment amounts.