ZenotiHelp

In-place upgrade and downgrade fee queue β€” insert and update operations

ZTZenoti Docs Team Updated November 3, 2026 9 min readGuide

When a guest upgrades or downgrades a membership in place and the action carries a fee greater than zero, Zenoti inserts a pending row into the fee queue. The front-desk operator pays the fee invoice at Point of Sale, and a background job then replays the upgrade or downgrade to completion. This article explains how the fee queue insert and update operations work so that front-desk staff can recognize the pending state, pay the fee invoice, and confirm the action completed successfully.

Audience: Front-desk staff and center administrators who process in-place membership upgrades and downgrades that carry a fee.

Availability: The membership upgrade/downgrade fee works with in-place membership upgrade and downgrade, which is a Beta feature. It must be enabled by Zenoti β€” contact your Customer Success Manager to request access.


On this page


Before you begin

  • The guest must have an active membership that is eligible for an in-place upgrade or downgrade.

  • An upgrade or downgrade fee must apply to the change. When no fee applies, no fee invoice is created and no payment is needed β€” the change is applied on its effective date.

  • You need the following permissions:

    Permission: Upgrade (under Memberships) β€” required to initiate an in-place upgrade to a higher-tier membership.

    Permission: Downgrade (under Memberships) β€” required to initiate an in-place downgrade to a lower-tier membership.

  • The fee invoice must be paid at POS before the background job can replay the membership change. The upgrade or downgrade is not complete until payment is collected.

Steps

Understand the fee queue lifecycle

When a front-desk operator initiates an in-place upgrade or downgrade that carries a fee, the system:

  1. Creates a fee invoice for the upgrade or downgrade amount.
  2. Inserts a Pending row into the fee queue, recording the guest, the current membership, the target membership, the fee invoice, the fee amount, any applicable tax, the effective date, the expiry date of the pending action, the center that initiated the request, and the payload needed to replay the change. The queue row also records whether the action is an upgrade or a downgrade, and captures the fee source, the identity of the staff member who created the row, and the initial status of Pending.
  3. Returns the unique queue row identifier to the calling process so that the fee invoice and the pending action remain linked.
  4. Holds the membership change in the Pending state until the fee invoice is paid.
  5. After the fee invoice is paid, the background job detects the payment and begins processing the queue row β€” recording the processing timestamp, the processed invoice identifier, the job name, and the machine that performed the work β€” and replays the upgrade or downgrade.
  6. On successful completion, the queue row reflects the completed state with all processing metadata populated.

Note: The update operation uses a compare-and-swap guard. When the background job or an inline invoice-close hook attempts to update the queue row, it supplies the status it expects the row to currently hold. If the row's actual status does not match β€” for example, because a concurrent caller already flipped it β€” the update does not execute and the caller receives a result indicating zero rows were affected. This prevents two concurrent processes from both processing the same row.

Note: Nullable fields on the queue row β€” such as the processing timestamp, processed invoice identifier, error message, retry count, job name, and machine identifier β€” retain their existing values when an update does not supply new values for them. Only the fields explicitly included in an update are changed.

Note: The fee invoice must be paid within the payment window β€” 30 minutes by default, counted from when the change is submitted. If it is not paid in time, Zenoti voids the fee invoice and cancels the scheduled change; the guest stays on the original membership and staff can start the upgrade or downgrade again.

Important: The update step only operates on queue rows that have not been voided. A voided queue entry is permanently excluded from processing. The background job, the inline invoice-close hook, and any retry endpoint will not update a voided row, regardless of the row's current status. The update step also returns a count of rows affected so that callers can detect whether the compare-and-swap guard prevented the update.

The table below summarizes the key states a fee queue row can move through:

State Meaning What triggers it
Pending Fee invoice created; awaiting payment System inserts the row when the fee is greater than zero
Processing Background job has picked up the row Fee invoice is paid; job begins replaying the change
Completed Upgrade or downgrade applied successfully Background job finishes; processed invoice and timestamp recorded
Failed Background job encountered an error Job records an error message and increments the retry count
Voided Row has been voided; no further updates allowed Administrative void action; voided rows are never modified

Pay the fee invoice at POS to trigger queue processing

  1. Open the guest's profile from the Appointment Book or the guest search.
  2. Navigate to the Memberships tab on the guest profile.
  3. Confirm that the membership shows a pending upgrade or downgrade. The membership status reflects the current active membership until the background job completes the change.
  4. Navigate to the open fee invoice. The invoice is linked to the pending queue row and reflects the fee amount and any applicable tax.
  5. Select the appropriate payment method and select Pay to collect the fee.
  6. Close the invoice. Once the invoice is closed, the background job detects the payment and begins processing the queue row.

Tip: If the guest's payment method is already on file, you can apply it directly at POS without re-entering card details.

Important: Do not void the fee invoice unless you intend to cancel the pending upgrade or downgrade. Voiding the invoice without canceling the queue row leaves the membership in an inconsistent state.

Verify that the queue row was processed

After the fee invoice is paid, the background job processes the queue row. To confirm the upgrade or downgrade completed:

  1. Return to the guest's Memberships tab on the guest profile.
  2. Confirm that the membership now reflects the target membership β€” the new membership name, tier, and benefits should be visible.
  3. If the membership still shows the original membership after several minutes, the queue row may be in a Failed state. See Troubleshooting for resolution steps.

Note: Processing time depends on the background job schedule. In most cases the change is visible within a few minutes of payment.

Cancel a pending upgrade or downgrade

If the guest changes their mind before the fee invoice is paid, you can cancel the pending action.

  1. Open the guest's profile and navigate to the Memberships tab.
  2. Locate the membership with the pending upgrade or downgrade indicator.
  3. To cancel a pending upgrade, select Cancel Upgrade. A confirmation dialog titled Cancel Upgrade / Downgrade appears.
  4. To cancel a pending downgrade, select Cancel Downgrade. The same confirmation dialog appears.
  5. Confirm the cancellation. The pending queue row is voided and the fee invoice is canceled. The membership remains on the original membership with no change applied.

Important: Once the fee invoice is paid and the background job begins processing, the pending action cannot be canceled from the guest profile. Contact your administrator if a reversal is needed after processing has started.

Worked example: A guest on a Standard recurring membership requests an upgrade to a Premium recurring membership. The upgrade carries a fee of $50.00 plus $4.50 tax. The system inserts a Pending queue row recording the guest, the Standard membership, the Premium membership, the $50.00 fee, the $4.50 tax, and today as the effective date. The front-desk operator opens the fee invoice, collects $54.50 from the guest's card on file, and closes the invoice. Within two minutes, the background job updates the queue row to Completed and the guest's Memberships tab shows the Premium membership as Active.

Tips

  • Check the fee amount before initiating the action. The target membership configuration determines whether a pro-rated fee or a flat fee applies. Confirm the amount with the guest before creating the fee invoice to avoid cancellations.
  • Use the guest's saved payment method. If the guest has a card on file, applying it at POS reduces the chance of a payment failure that would leave the queue row in a Pending state longer than expected.
  • Communicate the two-step process to guests. Guests sometimes expect the membership change to take effect immediately. Let them know the new membership benefits become available after the fee is paid and the background job completes β€” typically within a few minutes.
  • Do not create duplicate fee invoices. If the fee invoice already exists for a pending queue row, do not create a second invoice manually. Paying the original invoice is sufficient to trigger processing.
  • Monitor failed rows promptly. If a queue row enters a Failed state, the retry mechanism will attempt processing again automatically. However, if the error persists, the guest's membership remains on the original membership until the issue is resolved.

Troubleshooting

The membership still shows the original membership after payment

The background job may not have run yet, or the queue row may be in a Failed state.

  • Wait two to five minutes and refresh the guest's Memberships tab.
  • If the membership has not changed after five minutes, check whether the fee invoice is fully closed rather than partially paid. An open invoice balance prevents the job from processing the row.
  • If the invoice is closed and the membership has still not changed, contact your administrator to review the queue row for an error message.

The fee invoice shows a different amount than expected

The fee amount is determined by the target membership configuration, including whether a pro-rated charge applies.

  • Confirm that the target membership is configured with the correct fee. Navigate to Master data > Memberships, select the target membership, and review the fee settings.
  • If the pro-rated amount is unexpected, verify that the pro-rated billing setting is enabled for the target membership and that the guest's current billing cycle dates are correct.
  • If the amount is incorrect, void the fee invoice, correct the membership configuration, and re-initiate the upgrade or downgrade.

The Cancel Upgrade or Cancel Downgrade option is not available

The cancel option is only available while the queue row is in the Pending state and the fee invoice has not been paid.

  • If the fee invoice has already been paid and the background job is processing the row, the cancel option is no longer available from the guest profile.
  • Contact your administrator to determine whether a reversal is possible. A reversal after processing requires voiding the completed action and re-selling the original membership.

The queue row shows a Failed status and the membership has not changed

The background job encountered an error when attempting to replay the upgrade or downgrade.

  • The retry mechanism will attempt to process the row again automatically. Check the Memberships tab again after the next retry interval.
  • If the row continues to fail, contact your administrator. The error message recorded on the queue row will indicate the cause β€” for example, a configuration mismatch between the source and target membership or an expired effective date.
  • Do not attempt to manually re-initiate the upgrade or downgrade while a Failed queue row exists for the same membership. This can result in duplicate pending rows.

A concurrent process appears to have already updated the queue row

The compare-and-swap guard prevents two callers from both processing the same row. If the inline invoice-close hook and the background job retry endpoint both attempt to flip the row at the same moment, only one will succeed. The caller whose update affected zero rows did not process the change β€” the successful caller completed the work.

  • If the membership change has already been applied, no further action is needed.
  • If neither caller appears to have completed the change, contact your administrator to inspect the queue row status and determine whether a manual retry is appropriate.
Was this article helpful?
Your feedback helps us improve our documentation.