which event(s) would I use for any plan changes, like subscription/renewal and expirations?
Is there a complete list of CBSubs events available along with explanations?
We've a tutorial containing all of CB and various plugin triggers, which you can find below. The variables sent with the triggers are also noted.
www.joomlapolis.com/support/tutorials/120-api-usage/18358-using-cb-triggers
There's no explanation for the triggers as their trigger names often explain what they do. Many are re-usable as well so they could fire in different contexts. Below is a description of the CBSubs triggers.
Trigger: onCPayAfterPlanRenewalSelected
Variables: $plan, $subscription, $action
Description: This fires during renewal, resubscribe, and reactivation of a plan. It fires pretty early in this process so there's potential to alter the plan or subscription (both sent by reference).
Trigger: onCPayEditBasketIntegration
Variables: $integration, $action, $paymentBasket
Description: This is for integrations to integrate a custom save/edit display into the basket. For example CBSubs Promotions uses it to handle validation of coupon code.
Trigger: onCbSubsAfterPaymentBasket
Variables: $paymentBasket, $result, $termsAndConditions
Description: This fires directly after the basket display. This is used to modify the basket content due to $result being sent by reference, which is the current HTML output of the basket. For example CBSubs Promotions uses it to add the coupon code input to the basket.
Trigger: onCPayBeforeDrawSomething
Variables: $subscription, $childrenRendering, $controlButtons, $showRenewButtons, $showUnsubscribeButtons, $now, $user
Description: This is fired when a plan of any kind is displayed. It's pretty early in the display process. So it's possible to modify many aspects of it. For example $subscription, $childrenRendering and $controlButtons are all sent by reference. $controlButtons being the action buttons shown in a subscription (e.g. unsubscribe and renew buttons). For example CBSubs Promotions uses it to adjust the price of the plan dynamically if for example a constant discount is being applied.
Trigger: onCPayAfterDrawSomething
Variables: $subscription, $render, $now, $user
Description: This is basically the same as onCPayBeforeDrawSomething except it's fired after the subscription details have parsed into HTML, which can be modified by adjusting $render (sent by reference). For example CBSubs Promotions uses it for its plan title and description override feature.
Trigger: onCPayBeforeDrawPlan
Variables: $plan, $childrenRendering, $reason, $containerOnly
Description: This is fired directly before a plan is displayed. If using this trigger then anything returned by it is added before the plans price.
Trigger: onCPayAfterDrawPlan
Variables: $plans[$id], $render
Description: This is basically the same as onCPayBeforeDrawPlan except it's fired after the plan display. The HTML is parsed to $render, which you can modify as it's sent by reference.
Trigger: onCPayAfterPlanSelected
Variables: $plan, $integrations, $reason
Description: This is fired very early in the plan selection process. It's after the validation phase of the plan the user selected. Both $plan and $integrations are sent by reference, but I would only add data to them instead of altering existing or removing data. It could be useful to add params to the plan for storage for later or for custom validation.
Trigger: onCPayAfterPaymentStatusUpdateEvent
Variables: $user, $paymentBasket, $subscriptions, $unifiedStatus, $previousUnifiedStatus, $eventType, $notification
Description: This is fired after the payment state of a subscription changes. For example it's used by all our affiliate tracking plugins to track the payment information.
Trigger: onCPayAfterDisplayProductPeriodPrice
Variables: $product, $return, $method, $args
Description: This fires right when a plans price is being displayed. Note this is not the calculation process of the price, but just the display. The $return is sent by reference so the price display can be altered or even replaced. The $args contain information about the calculated price so you can generate your own display.
Trigger: onCPayBeforeComputeTotalizersPaymentBasketUpdated
Variables: $paymentBasket, $paymentItems
Description: This is fired just before a baskets price is being calculated as it'll total all the promotions, taxes, etc.. directly after this fires. Neither variable is sent by reference though so usage is limited.
Trigger: onCPayBeforeStorePaymentBasketUpdated
Variables: $paymentBasket, $paymentItems, $paymentTotalizers
Description: This is fired just after onCPayBeforeComputeTotalizersPaymentBasketUpdated, but after the price has calculated and is about to be stored. Nothing is sent by reference so again limited usage.
Trigger: onCPayAfterPaymentBasketUpdated
Variables: $paymentBasket, $paymentItems, $paymentTotalizers
Description: This is fired after the entire payment basket has calculated and stored. This again is not sent by reference so it has limited usage, but you could do basket stores to alter the basket in database.
Trigger: onCPayPaymentItemEvent
Variables: $event, $something, $paymentBasket, $paymentItem
Description: This is fired for integrations when an item is added to the basket. $something, $paymentBasket, and $paymentItem are all sent by reference so they can be modified. For example CBSubs Tax uses this to add its tax rule to the basket.
Trigger: onCPayBeforeGetProductPrice
Variables: $plan, $subscription, $reason, $currency_code, $price, $occurrence, $startTime, $remainingValue, $quantity
Description: This is fired when the plan price is being used. The $price is sent by reference so this is the trigger to use if you want to alter the price.
Trigger: onCPayAfterGetProductPrice
Variables: $plan, $subscription, $reason, $currency_code, $price, $occurrence, $startTime, $remainingValue, $quantity
Description: Same as onCPayBeforeGetProductPrice except it's fired after the price has been quantity tested and converted.
Trigger: onCPayBeforeDisplaySubscriptionPeriodPrice
Variables: $plan, $subscription, $reason
Description: This fires directly before the subscription period price is displayed. Note this is display purposes and can't be used to alter the price, but can be used to alter how it displays. $plan and $subscription are all sent by reference.
Trigger: onCPayAfterDisplaySubscriptionPeriodPrice
Variables: $plan, $subscription, $htmlText, $reason
Description: Same as onCPayBeforeDisplaySubscriptionPeriodPrice, but fires after the price display has been calculated. $plan, $subscription, and $htmlText are all sent by reference. $htmlText is the calculated price display, which can be altered to change the price display.
Trigger: onCPayUserStateChange
Variables: $user, $status, $plan_id, $replacedPlanId, $integrationParams, $cause, $reason, $now, $subscription, $autorenewed
Description: This is fired when a user state has changed for a plan. For example the sate of a subscription for a plan went from Expired to Active. This is your bread and butter trigger. It's used by nearly all of the CBSubs integrations to implement behavior on subscription state changes.
Trigger: onCPayBeforeDrawSubscription
Variables: $viewModel, $subscription, $insertAfterDescription
Description: This is called just before a subscription plan is drawn. All the variables supplied are sent by reference. Anything returned by this trigger is added just before the plan validity duration. It does not apply to merchandise or donation plans, but strictly subscriptions.
- All subscriptions are recurring.
On the Pricing tab of your plans ensure "Auto-recurring renewals (*):" is set to "Yes: subscribe user to automatic recurring payments (*)" to enforce recurring subscriptions.
- On renewals the time frame should not be extended but the new timeframe of the subscription should start immediately. The 'old' recurring subscription cycle should be cancelled and replaced with the new one.
That's not how auto recurring subscriptions function. They will automatically renew are precisely the correct time. If you're meaning for manual renewals then on the Pricing tab set "Manual renewal extends expiration date as follows" to "Renewal starts at payment date (allows overlap or free gap)".
- On 'cancellation' the plan should not be cancelled but the recurral should be cancelled and the plan run out to the end of the last paid period.
The only way to do that is to use the PayPal gateway and be sure not to specify API credentials so cancellations can't be done from the site directly. This makes the cancellation a 2 step process so the subscription can remain active on the site. Aside from that there's no feature for this at this time, but it is planned.
- I will also not use the CBSubs invoicing system as it is too limited - therefore I will need an event 'onPaymentReceived' or similar where I can create my own invoice in my existing billing system after a payments was received.
Please see my above list of triggers, their variables, and their descriptions. I recommend onCPayAfterPaymentStatusUpdateEvent.
krileon
