Subscriptions

With the shop you're able to provide a subscription system for frontend user using Stripe. For this you need insert the Subscription-Table plugin on your website. This offers you a listing of avaiable subscription products, which needs to be configured in Stripe, and handles the redirect when the user starts a new subscription. You're optionally able to insert the Stripe sunscription-prices in regualar product-records, so that you've a subscription-button attached to this products.

Defining Subscriptions

1. Log-in on dashboard.stripe.com and switch to the Products section. Here you need to create a product for each subscription you offer - for example Basic-Plan and Premium-Plan. Products must be created separately in sandbox and live mode, although products can be copied from sandbox to live mode. This products needs the following data:
   • Name: Product names are visible to customers at checkout, in receipts, invoices, and the customer portal.
   • Description: Product descriptions appear at checkout, in the customer portal, and on quotes.
   • Insert a price and ensure Recurring payment is selected.
   • Add a meta tag with the key category to the product. Products can be filtered by the value of this tag in SubscriptionTable plugin (See section "Display table of subscription products").
   • Add a meta tag to the product with the key usergroups. Set the value of this tag to a comma-separated list of frontend user group ids. These user groups are automatically added to the frontend user who purchases a subscription that includes this product. When a subscription ends, these user groups are automatically removed from the frontend user. The frontend-user and frontend-usergroups must be in the same record-storage!
   • Add an optional meta tag with the key trial_period_days, which can define the amount of days for a trial period for the first subscription of a user. This will be only used, if the fe_users.tx_shop_stripe_trial_period_end field is empty.
   • Add an optional meta tag with the key sorting_index, which can change the display ordering of products.
   • Configure webhooks (See section "Configure stripe webhooks").

Attention:

When using Stripe customers the frontend user needs the short iso-code of his country in his user record (for example: DE)!

Setup-Fee

If you've a setup-fee on your subscription, just create a separate Stripe product for this. This product contains only the name, which appears in checkout and invoice, and a one-time price. Copy the price-id (price_xyz…) and insert it into your subscripion-product in meta-data with key setup_fee. By having this relation, the shop-extension adds this price on a new subscription in checkout. If you need an additional notice about the setup-fee in the subscription-table, just use the meta-data key setup_fee_description with .

Meta field overview

Configure stripe webhooks

A webhook for receiving Stripe events is fundamentally required to automatically assign or remove the user groups linked to a Stripe product and to correctly handle actions such as subscription changes.

For ease of configuration, a Short URL can be set up for the page with a SubscriptionTable or Subscriptions plugin.

  ShopSubscriptionsPlugin:
    type: Extbase
    limitToPages:
      - {page uid with the Subscriptions plugin}
    extension: ShopPro
    plugin: Subscriptions
    routes:
      - routePath: '/stripe-subscription-callback'
        _controller: 'Subscription::stripeSubscriptionCallback'
    defaultController: 'Subscription::list'

or

  ShopSubscriptionsPlugin:
    type: Extbase
    limitToPages:
      - {page uid with the SubscriptionTable plugin}
    extension: ShopPro
    plugin: SubscriptionTable
    routes:
      - routePath: '/stripe-subscription-callback'
        _controller: 'Subscription::stripeSubscriptionCallback'
    defaultController: 'Subscription::list'

Configuration of the webhook in the Stripe dashboard

1. Go to the https://dashboard.stripe.com/webhooks page and click Add Endpoint.
2. Enter the URL of the page that was set up in step "Setup of the webhook page".
3. Select "Select Events" and select checkout.session.completed, customer.subscription.created, customer.subscription.updated and customer.subscription.deleted.
4. Click "Add Endpoint".
5. Click on the newly created webhook entry and copy the endpoint secret for signature.
6. Paste the key into the subscriptionEndpointSecretTypoScript constant

Local webhook usage

1. Install the Stripe CLI Download the official Debian package and install it:

   # Example for Debian/Ubuntu
   wget https://stripe.jfrog.io/artifactory/deb-local/pool/main/s/stripe-cli/stripe-cli_<version>_amd64.deb
   sudo dpkg -i stripe-cli_<version>_amd64.deb

   Replace <version> with the latest version available on the Stripe repository page.

2. Connect your Stripe account

   stripe login

   – This will open a browser window where you log in to Stripe and authorize access.

3. Forward webhooks Back in your terminal, start the listener and forward events to your DDEV URL:

   stripe listen \
     --forward-to https://typo3-12-13.shop13.ddev.site/subscription/your-subscriptions/stripe-subscription-callback

   – The listener will subscribe to Stripe events (e.g., invoice.paid, customer.subscription.updated) and send them to your local callback endpoint. Make sure that the local usage gets its own webhook secret, which is displayed on the CLI when starting: Your webhook signing secret is whsec_03b75a…

4. Verify the callback endpoint in TYPO3 – Ensure your TYPO3 project is reachable at the DDEV URL and that your callback controller correctly processes the incoming JSON. – If needed, make sure HTTPS is enabled in DDEV (it is by default) and adjust your config.yaml accordingly.

PSR-14 Events

If

• the webhook is set up correctly
• one of the supported events arrives at the webhook
  • https://stripe.com/docs/api/events/types#event_types-customer.subscription.created
  • https://stripe.com/docs/api/events/types#event_types-customer.subscription.updated
  • https://stripe.com/docs/api/events/types#event_types-customer.subscription.deleted
• a user exists in the database with the corresponding Stripe-customer id

a PSR-14 event is emitted.

Add the following to Configuration/Services.yaml to react to the events:

services:
  Vendor\MyExtension\EventListener\SubscriptionCreatedEventListener:
    tags:
      - name: event.listener
        identifier: 'SubscriptionCreatedEventListener'
        event: CodingMs\ShopPro\Event\Stripe\Subscriptions\StripeSubscriptionCreatedEvent
  Vendor\MyExtension\EventListener\SubscriptionUpdatedEventListener:
    tags:
      - name: event.listener
        identifier: 'SubscriptionUpdatedEventListener'
        event: CodingMs\ShopPro\Event\Stripe\Subscriptions\StripeSubscriptionUpdatedEvent
  Vendor\MyExtension\EventListener\SubscriptionDeletedEventListener:
    tags:
      - name: event.listener
        identifier: 'SubscriptionDeletedEventListener'
        event: CodingMs\ShopPro\Event\Stripe\Subscriptions\StripeSubscriptionDeletedEvent

This event contains the Stripe subscription object and the associated frontend user.

You can find more information about registering an event listener here: https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/Events/EventDispatcher/Index.html#registering-the-event-listener

Display table of subscription products

• use the plugin SubscriptionTable
• during product creation insert a Metadata information category and set a custom identifier (for example: subscription). This allows you to display specific subscription products in your tables.

Display list of subscriptions

This plugin displays all available subscriptions.

If a user is logged in, he is able to supscribe an subscription. If no user is logged-in, the subscription buttons won't be visible and the user get's only information.

• use the plugin Subscriptions

The user has the possibility to view the list of his active and already expired subscriptions and to cancel the subscriptions immediately or at the end of the subscription period. For each subscription, the user has the possibility to view the list of invoices and download them.

Side note: User sync

Stripe requires to have a Stripe-Customer record for each of our frontend user. For solving this requirement, our frontend user has a field Stripe-Customer ID. When a frontend user is logged-in and the Stripe-Customer ID is emtpy, the Shop tries to create a new Stripe-Customer and inserts the Stipe-Customer ID within the user. If the frontend user address data will be changed, the changes data will be synchronized automatically to the Stripe-Customer.

It is very important to keep the Stripe-Customer is up-to-date when using some third-party tools or scripts for changing frontend user data. If necessary, the user synchronization can be called manually. An example can be found in EXT:shop_pro/Classes/EventListener/AfterProfileUpdateEventListener.php

public function __invoke(AfterProfileUpdatedEvent $event): void
{
    $frontendUserRepository = GeneralUtility::makeInstance(FrontendUserRepository::class);
    $frontendUser = $frontendUserRepository->findOneByUid($event->getFrontendUser()->getUid() ?? 0);
    if(!isset($frontendUser)) {
        return;
    }
    $routing = $GLOBALS['TYPO3_REQUEST']->getAttribute('routing');
    $pageId = $routing->getPageId();
    $subscriptionServiceSettings = TypoScriptService::getTypoScript(
        $pageId
    )['plugin']['tx_shop']['settings']['basketOrder']['orderOptions']['stripe'];
    $subscriptionService = GeneralUtility::makeInstance(SubscriptionService::class, $subscriptionServiceSettings);
    $subscriptionService->updateStripeCustomer($frontendUser);
}

Notice:

All Stripe elements will be used in language which the user uses on the website right now. This language is fetched from the site configuration.

Troubleshooting

If the redirect to Stripe for subscription completion isn't working, please enable logging (see How-To Debugging). This logs helpful information that can help you troubleshoot the issue.