Why aren't the referral rewards granted after the order is set to 'Done'?

When an order is placed using a referral URL of a customer a message is added to the Shopware async message queue of type ProcessOrderInReferralProgramMessage. This message will be picked up by the following command "./bin/console message:consume async" leading to the creation of a "Customer Referral". This customer referral can be found in the "zeo_customer_referral" table and will have a value of 0 in the "processed" column.

A scheduled task should be running in the background which periodically reads all unprocessed customer referrals to check if they should be processed. This depends on the following conditions:

1. The plugin and program are set to "Active" for the specific Sales Channel via the plugin configuration
2. The order has reached the status "Done"
3. The order has a value higher than the "Minimum order value for reward" configured via the plugin configuration.

If these conditions are met the referral reward will be granted.

Reasons the reward is not granted

The message queue is stuck or not getting processed.

The message worker is not configured or the message queue has grown to such a size that the ProcessOrderInReferralProgramMessage is never handled. Be sure to configure the message worker following Shopware's production guidelines found here https://developer.shopware.com/docs/guides/hosting/infrastructure/message-queue.html.

TIP! Do not use the crontab to execute the message:consume command, but instead configure a tool like Supervisor to process your message queue. Here is a comprehensive guide on how to install and configure it: https://www.digitalocean.com/community/tutorials/how-to-install-and-manage-supervisor-on-ubuntu-and-debian-vps

The scheduled task is stuck or not running

Check the scheduled_task table for the task with name "zeo_referral_rewards.referral_reward_task" and ensure its last en next execution time are recent and in the near future. If they aren't, force reset the status to "scheduled" and check the task is getting picked up. If it isn't please refer to this documentation to figure out what is going wrong: https://developer.shopware.com/docs/guides/hosting/infrastructure/scheduled-task.html

One of the conditions listed above is not met

Be sure to check the plugin configuration and order details to verify all conditions are met for the order to be processed as a reward. If the order doesn't contain a discount line item it most likely didn't qualify for the referral reward program in the first place and won't be processed for a referral.

Command to Manually Run Referral Rewards

To manually execute the referral reward process, follow these steps:

• Open the Terminal: Connect to the server via SSH.
• Navigate to the Project Directory: Access the directory where the project is hosted.
• Run the Command: Execute the following command to process referral rewards: "bin/console zeo:referral:reward"

By executing this command, you can manually trigger the referral rewards process.