Commerce Gate for Drupal — Getting Started

This guide takes your team from installing Commerce Gate to seeing what your own store's last 90 days reveal. It takes about 30 minutes. Nothing is blocked until you choose to enforce, and the first look runs entirely on your site.

Before you start

Initial beta availability

Local Store X-ray and the existing Shadow journey are available. Enforcement trials, tuned-limit publication, billing-contact confirmation and workspace ownership claims are not yet available in this beta.

Get the module

Step 1 has the installation command. commerce.decionis.com/downloads lists the current release and its requirements, with its ZIP, checksum and provenance. Use the file names shown there; do not substitute an earlier private-beta ZIP.

The official Decionis Commerce Gate project is listed on Drupal.org. Its machine name is decionis and its package is drupal/decionis. Beta releases are not covered by Drupal's security advisory policy.

Your team will need

• Shell access to the server, with Composer and Drush. This guide runs Drush as vendor/bin/drush, which composer require drush/drush adds to your project; a global drush works the same where it is installed. Every step in this guide can also be run by your hosting provider's support team.
• Drupal 10.3 or later with Drupal Commerce 3.3.13 or later for this Fincra-store guide. The downloads page also lists supported Drupal 11 and Commerce 2 combinations.
• PHP with the curl and sodium extensions, which most hosts include.
• An administrator account on the store.
• A scheduled cron job. Most stores already have one; Step 4 shows how to check.

We recommend trying the steps on a staging copy of your store first. Commerce Gate recognises a copied site and keeps it in Shadow Mode, so a copy can never act for your live store.

Step 1: Install the module and add costs

About 10 minutes. Run these from your Drupal project's root folder. If your Drupal root is called docroot rather than web, use that name instead.

1. Install the module with Composer, which also installs its dependencies:

   composer require 'drupal/decionis:^0.1@beta'

   Projects built from drupal/recommended-project already use https://packages.drupal.org/8. If yours does not, first run composer config repositories.drupal composer https://packages.drupal.org/8.

   If upgrading from the private ZIP, first remove its repository override with composer config --unset repositories.decionis. Keep the previous ZIP and composer.lock available for recovery.

   The downloads page has the ZIP alternative, its checksum and provenance. If you use the ZIP, follow that page's checksum and Composer steps; copying the ZIP alone does not install its dependencies.

2. Enable it and apply its recipe:

   vendor/bin/drush en decionis_commerce -y
   cd web
   php core/scripts/drupal recipe modules/contrib/decionis/recipes/decionis_commerce
   cd ..
   vendor/bin/drush cr

3. Commit your updated composer.json and composer.lock, so every deployment installs the same version. Include packages/ only if you used the ZIP installation steps. When upgrading, run vendor/bin/drush updb -y before rebuilding caches.

Add your costs. Margin checks need to know what each product costs you. The recipe adds a Cost field to every product variation type. You can fill it in three ways:

• Type costs into each variation as usual.
• Import a spreadsheet on the Import variation costs page (/admin/commerce/decionis/cost-import). Use the columns sku,cost, or sku,cost,currency. Up to 5,000 rows are checked before anything is saved.
• If you already record cost in another field, choose it under Cost base at /admin/commerce/config/decionis.

Enter each cost in the same currency the variation sells in. Products without a cost are shown as not covered; Commerce Gate never guesses a margin.

Step 2: Run the Store X-ray

About 2 minutes. This is where you see what Commerce Gate would mean for your store, using your own history. No account is needed, and nothing leaves your site.

1. After installing, Drupal shows a message with a link to the Store X-ray. You can also open /admin/commerce/decionis/x-ray directly.
2. Choose a window. We suggest 90 days; anything from 30 to 365 works.
3. Select Run Store X-ray and wait for the progress bar to finish.

You get one headline per currency your store sells in. It shows:

• orders sold below the suggested margin floor, and how far below
• refunds above the suggested refund limit
• promotions that stack discounts past the suggested ceiling
• refunds made outside Drupal that your payment provider reported back
• how many of your products and order lines have a cost recorded

The page is labelled estimate on your site, using suggested limits and nothing left this site. Read it as a starting point for review, not a final account of money lost:

• It uses today's costs and the promotion settings still on your site.
• Refunds are counted per payment, so two partial refunds on one order appear as one total.

If cost coverage is low, add costs and run the X-ray again; the margin figures will sharpen.

Step 3: Review and tune your limits

About 5 minutes. Open the settings page at /admin/commerce/config/decionis. For each currency you sell in, Commerce Gate suggests four limits, drafted from your own history:

Each suggestion shows the findings behind it, for example how many of your refunds fall below the ceiling and what the ones above it add up to. Change a value and the counts update straight away. A suggestion needs at least 20 past examples; with fewer, the page uses a stated starting value and tells you so.

Select Save configuration, then run the X-ray again to see the result with your own limits. Your limits are saved in Drupal's configuration, so they travel with your normal deployments.

These limits always drive the X-ray and the sandbox on your site. When connected, Save configuration also requests publication to your workspace. Each currency says Published as version … only after the service confirms it, or Not yet published. A confirmed version is used for subsequent live checks. If publication is unavailable or needs owner review, your local limits remain saved and the page explains why. Do not assume an unpublished local limit governs a live action.

Step 4: Connect and see your first decisions

About 5 minutes. Connecting creates your Commerce Gate workspace in Shadow Mode: every decision is recorded, and every action still runs exactly as it does today.

Review your allowance before connecting. Connected historical replay is metered against your workspace's governed-action allowance, even in Shadow Mode. The local Store X-ray is free and uses none of that allowance. Check Build pricing before sending a large history.

Check cron first. Shadow checks are sent after each page has finished loading, so they never slow down a shopper or an admin. Some of that work runs on cron. Make sure cron runs on a schedule, not only when someone visits the site. For example, every 15 minutes:

*/15 * * * * cd /path/to/your/project && vendor/bin/drush cron

Allow the connection check. While you connect, Commerce Gate confirms the request really comes from your site by reading a one-time code from /.well-known/decionis-challenge or /decionis/challenge. If the site sits behind a password prompt or a firewall, allow those two addresses for a few minutes. They work during maintenance mode too.

Connect.

1. Open /admin/commerce/config/decionis/connect.
2. Check your business name and billing email; both are filled in for you. The site address is shown for confirmation.
3. Accept the terms and select Connect to Commerce Gate. You never paste an API key.

If the service offers an emailed connection code, enter the six-digit code from Decionis before it expires. Billing confirmation and approval messages come from Decionis services; the optional weekly digest below uses your site's mail setup. A delivery or connection error is shown on the page rather than treated as a successful email.

A progress bar then checks the first part of your last 90 days against your workspace, and opens the Decisions page (/admin/commerce/decionis/decisions). Cron fills in the rest over the next few runs.

On the Decisions page you will see:

• each action's current mode
• your largest catch in each currency, explained in plain words
• a Verify button that checks the decision's signature, shows the key that signed it, and tells you whether the record is complete
• Download Dossier, the full signed record of that decision, which anyone can check without asking us

If our service cannot be reached, the page says so plainly. It never shows a check as verified when it was not.

Every week

Shadow Mode works quietly. These tools make sure your team sees what it finds.

• Nudges. If someone saves a price, promotion or refund that your policy would have refused, they see a short note on their next page. For example: the new price now sells below cost.
• Weekly digest. An optional email to the admins you choose, on the day you choose. It sums up what would have been held or blocked that week, with a link to act on each. Turn it on in the settings page; it uses your site's own email setup.
• Protection checklist (/admin/commerce/decionis/checklist). A score out of 100 across seven checks: connected, checks active, cost coverage, limits tuned, one action enforced, payment key protected, and refunds made outside Drupal visible. Each missing check links to its fix. It is a setup guide, not a certification.
• Owner and agency report (/admin/commerce/decionis/report/xray, or report/shadow for the 90-day Shadow view). A one-page summary you can print to PDF or export as CSV for an owner, finance team or client. The X-ray version is marked as an estimate; the Shadow version links to the signed records behind it.

Schedule a 15-minute review each week: open Decisions, look at the largest catches, and decide whether any limit needs adjusting.

Turning on enforcement

Your workspace starts in Shadow Mode. When the service offers an enforcement trial, open Enforce this one, review the effect on that action and confirm. That confirmation starts the server's 14-day trial and enables only the action you selected; opening the page does not start it. Repeated confirmation does not restart the trial.

Review the publication status from Step 3 before enforcing. Live checks use the confirmed workspace policy. If an entitlement or publication service is unavailable, the page explains the remaining step. An absent or expired enforcement entitlement keeps actions in Shadow Mode.

When enforcement is on:

• You choose it one action at a time, starting wherever the Decisions page shows the most value. Each choice shows how many actions it would have stopped and how often an approver would be asked.
• Shoppers are never kept waiting for a person. At checkout, Commerce Gate either lets the order through or, for an order your policy blocks, stops it at the review step with a neutral message, before any payment.
• Refunds and price changes your policy escalates wait on the Pending approvals page (/admin/commerce/decionis/approvals) until an approver confirms that exact action. It then runs once.
• You can switch any action back to Shadow in settings at any time. Your history stays.

After the 14 days, an active Build subscription keeps enforcement available. If the trial expires without one, your actions return to Shadow automatically and your policy, history and records are kept. A server-confirmed payment grace period shows its own deadline; its expiry also returns actions to Shadow. Follow the billing link when it is available for your workspace, or contact Decionis for setup. See pricing.

Notes for stores using Fincra

• Fincra's refund service covers payment discrepancies. Fincra Support confirmed on 4 November 2026 that an underpayment refund returns the full amount received, while an overpayment refund returns only the excess. Other refund requests require a separate payout to the customer outside Drupal. No ordinary full or partial refund API for correctly paid purchases has been confirmed. This module does not execute these customer payouts, and they are not automatically reflected as Drupal refunds. Review who can authorize payouts in the separate payment workflow your team uses.
• Outside refunds are visible only when your site records them. Where a payment provider's integration updates the matching Drupal payment with a refund, the Decisions page can show it as made outside Drupal, with what your policy would have decided. A separate Fincra customer payout does not by itself create that record.
• Start with margin. For your store, the most useful first actions to enforce are orders, prices and promotions. The Decisions page offers those first.
• The margin check happens before payment. Fincra takes payment on its own page, so Commerce Gate checks the order when the customer confirms the review step, before they are sent to Fincra.
• Failed payments are not counted as refunds, even though Fincra can record them that way.
• Protecting your Fincra key (optional, later). Your team and hosting provider can move the Fincra secret key to a separate service, using three small patches to Commerce Fincra. Protection from a compromised Drupal account requires verified root or separate-user custody and enforced gateway rules. A service running as Drupal's own user provides a weaker boundary. Setup starts in Shadow Mode, which records what the rules would do; blocking requires enabling enforcement after verifying the host setup.

Help us shape it, and where to get help

During your evaluation, we would value your team's answers to these:

1. Which hurts most today: refunds, pricing mistakes, or promotions that stack too far?
2. Who issues refunds today, and in which tool?
3. On your server, can your team use sudo, or create a separate system user? This decides how we protect your Fincra key later.
4. Does anything else write to your store, such as a headless front end, an ERP sync or a support chatbot?
5. Did the X-ray headline match what you expected, or surprise you? How long did it take from install to that first headline?

If something does not work

• Connecting says it could not read the one-time code. A password prompt, firewall or server rule is answering instead of Drupal. Allow /.well-known/decionis-challenge and /decionis/challenge, then try again.
• Connecting says it could not use your site's address. A public site must use HTTPS on the standard port. If you are behind a proxy or load balancer, ask your developer to set reverse_proxy in settings.php.
• Your site cannot be reached from the internet, for example staging behind a VPN. Use the emailed-code option when offered. If mail delivery is unavailable, contact us to confirm service setup; do not expose the whole store just to connect.
• Decisions stay "pending". Check that cron runs on a schedule (Step 4). The status report warns when queued Shadow checks are more than an hour old; it does not process them just by opening the page.
• Anything else. The status report at /admin/reports/status shows whether every check is active.

Reach us at decionis.com/contact. Include your site address and, if you can, a screenshot of the status report.