Skip to content

Installing Store Credit

This guide covers installing Store Credit with Composer, both with a license key and via the Hyvä Commerce GitLab repositories for agency and technology partners.

Pre-release Feature

Store Credit has not been tagged for release yet, so Composer needs a relaxed stability constraint to resolve it. Follow the beta upgrade notes for what your root composer.json needs, and install it in a development environment before anywhere else.

Installation

For prerequisites, see Hyvä Commerce Installation Page.

Installation via Hyvä Commerce Metapackage Recommended

The below steps are for installing Store Credit only. While this is supported to provide greater flexibility and control over installed features, in most cases, we recommend installing all Hyvä Commerce features using our metapackage.

  1. Require the hyva-themes/commerce-module-store-credit package:

    composer require hyva-themes/commerce-module-store-credit

  2. (Optional) Require the hyva-themes/commerce-module-store-credit-graph-ql package for the GraphQL API:

    composer require hyva-themes/commerce-module-store-credit-graph-ql

  3. Run a setup upgrade:

    bin/magento setup:upgrade

  4. Clear your browser cache.

Installing as an Agency or Technology Partner

If you have access to the Hyvä Commerce GitLab repositories as a Gold/Platinum Agency Partner or a Technology Partner, you can install Hyvä Commerce in development environments using SSH key authentication.

You can configure the Git repositories in your root composer.json and use them directly as Git repos beneath your vendor directory. This lets you check out tags and branches, make commits, and push contributions.

Development Environments Only

This installation method is not suited for deployments, because GitLab requires SSH key authorization and project changes can break production deployments.

  1. Make sure your public SSH key is added to your account on gitlab.hyva.io.

  2. Set minimum-stability to dev in the Magento composer.json:

    composer config minimum-stability dev

  3. Add the Store Credit and base Hyvä Commerce module repositories to the Magento composer.json:

    composer config repositories.hyva-themes/commerce-module-commerce git git@gitlab.hyva.io:hyva-commerce/module-commerce.git
composer config repositories.hyva-themes/commerce-module-store-credit git git@gitlab.hyva.io:hyva-commerce/module-store-credit.git

  4. (Optional) Add the Store Credit GraphQL repository to the Magento composer.json:

    composer config repositories.hyva-themes/commerce-module-store-credit-graph-ql git git@gitlab.hyva.io:hyva-commerce/module-store-credit-graph-ql.git

  5. Require the hyva-themes/commerce-module-store-credit package using the dev-main branch:

    composer require --prefer-source 'hyva-themes/commerce-module-store-credit:dev-main'

  6. (Optional) Require the hyva-themes/commerce-module-store-credit-graph-ql package using the dev-main branch:

    composer require --prefer-source 'hyva-themes/commerce-module-store-credit-graph-ql:dev-main'

  7. Run a setup upgrade:

    bin/magento setup:upgrade

  8. Clear your browser cache.

Installing the module creates two database tables (hyva_store_credit_ledger and hyva_store_credit_balance), a hyva_store_credit_balance_view SQL view, and the store credit columns on the quote, order, invoice, and credit memo tables.

Additional Setup

Installation alone does not make store credit visible. Three things still need attention.

Enable Store Credit per Website

Store credit ships disabled: hyva_store_credit/general/enabled defaults to No. Until you switch it on, no balances are spendable, the My Account page redirects away, and the cart and checkout panels do not render.

Go to Stores → Settings → Configuration → Hyvä Commerce → Store Credit, set Enable Store Credit to Yes, and save. The setting is scoped per website, so switch it on for each website that should offer store credit. See Configuring Store Credit for the rest of the settings.

Keep Zero Subtotal Checkout Enabled

When a customer's store credit covers an order in full, the order total drops to zero and Store Credit hides every payment method except Zero Subtotal Checkout. If that method is disabled, a fully covered order cannot be placed at all.

Check that Stores → Settings → Configuration → Sales → Payment Methods → Zero Subtotal Checkout is enabled for the same websites. See Zero Subtotal Checkout for how Hyvä Checkout handles zero-total orders.

Theme Requirements

Store Credit is only supported on storefronts that run both Hyvä Theme and Hyvä Checkout. The storefront templates and Tailwind config are built for Hyvä Theme, and the checkout panel is a Hyvä Checkout price summary component. There is no Luma integration, so the module is not supported with Luma or any other theme or checkout.

Neither the Hyvä theme package nor Hyvä Checkout is declared as a Composer requirement of the module, which means Composer will not warn you if either is missing. Make sure both are installed before you enable store credit.