# Company Benefits add-on - admin guide

> How to set up and use the Company Benefits add-on — API key, campaigns, discount codes, notifications, log and analytics. No technical knowledge needed.

- **Zdroj:** https://www.webmakeria.com/guides/company-benefits/company-benefits-add-on-admin-guide/
- **Doplněk / kategorie:** Company Benefits (https://www.webmakeria.com/guides/firemni-benefity/)
- **Datum:** 2026-06-11
- **Autor:** Webotvůrci (https://www.webotvurci.cz/)

---

This guide is for you if you manage the add-on in the admin. You will find what you can set up, how the add-on works and what to do when something goes wrong. No technical knowledge needed.

## What the add-on does

Company Benefits makes sure corporate discount codes are used only by people who are entitled to them. With every new order the add-on automatically checks the discount code that was used against the rules of your campaign, and based on the result it either approves the order or flags it (or cancels it right away) as unauthorized.

Everything runs in the background — as soon as an order comes in, the add-on evaluates it on its own within moments.

## Quick start

1. **Enter the API key** (one time only) — it connects the add-on to your online store. See the [API key](#api-key) section.
2. **Create a campaign** for a specific company partnership — assign discount codes and set the limits.
3. **Optionally set up notifications** — where the add-on should report problem orders.
4. **Done.** From now on orders are evaluated automatically. You watch the results in the Log and in Analytics.

## API key

For the add-on to see your orders and discount codes, it needs the **Private API token** of your Shoptet.

**Where to get it:**

1. In your Shoptet admin, open the API / add-ons section.
2. Generate a **Private API token**.
3. Copy the token.

**Where to enter it:**

1. In the add-on, open the **API key** page and paste the token.
2. The token is stored securely (encrypted) and is never shown again.

💡 You can swap the token at any time — just paste a new one and save.

⚠️ Never send the token to anyone and never put it in an e-mail. It's the key to your online store.

## Campaigns

**A campaign = one company partnership.** For every company (or group) you give a discount to, you create your own campaign with its own rules.

### What you set up for a campaign

| Setting | What it does |
| --- | --- |
| **Campaign name** | Just for your own orientation (e.g. "Employees of ABC s.r.o."). |
| **Discount codes** | Which codes belong to the campaign. You can assign one code or several. |
| **Limit per customer** | How many times a single customer (e-mail) can use the discount. E.g. 1 = everyone only once. |
| **Limit of unique customers** | How many different customers the campaign can serve in total. Once it's used up, further orders are rejected. |
| **Response to an unauthorized order** | What happens when an order doesn't match the rules — see below. |
| **Status** | Active / paused. A paused campaign is not evaluated. |

### What happens to an unauthorized order

Depending on the campaign settings, the add-on can do this with an order that didn't pass:

- **only flag it** and record it in the log (you then handle it manually), or
- **cancel it** directly in Shoptet and add a note with the reason.

💡 **Recommendation:** until you get used to how the evaluation works, start with "only flag" and turn on automatic cancellation after a few days.

## Discount codes — what to watch out for

The add-on matches the code from the order against the codes you have in the campaign. Here is one important Shoptet detail worth knowing:

Shoptet doesn't store the code the customer typed with the order, only the **name of the discount coupon**, for example:

> "Discount coupon no. **firma-abc** - 30% discount"

That's why the add-on looks for your code in that name as a **separate word**. For the matching to work reliably:

- ✅ Keep the code as a **separate word** in the coupon name (e.g. `firma-abc`). Then the add-on always finds it.
- ✅ It also works across the language versions of your online store.
- ⚠️ If you rename the coupon so that the code "blends" into other text, the matching may not find it.

💡 **Rule of thumb:** if a person read the coupon name, they would have to clearly recognize your code as a separate word. Then the add-on recognizes it too.

## Notifications (optional)

Do you want to be alerted when a problem order comes in? Set up your own address (URL) where the add-on sends a message about the evaluation.

**Where to set it:** in the add-on settings, in the field for the notification URL.

**Requirements for the address:**

- it has to be a public **HTTPS** address (e.g. an endpoint of your internal system, ERP, or a bridge into Slack),
- for security reasons the add-on rejects internal/local addresses (e.g. `localhost`, `192.168.x.x`, `10.x.x.x`) — those aren't reachable from the outside anyway.

**What gets sent:** information about the evaluated order (order code, result, campaign, discount). If the message can't be delivered, the add-on retries automatically (3 attempts in total, with a growing delay).

## Log

The **Log** page is the complete history of all evaluations.

What you see for each record:

- the order code and the customer's e-mail,
- the discount code that was used and the campaign,
- the result (approved / rejected and why),
- the calculated discount,
- the time of the evaluation.

Search and paging are available, so even with a large volume you quickly find a specific order.

💡 The log is there for tracking down individual cases — "why exactly did this order not pass?"

## Analytics

The **Analytics** page shows a summary per campaign — that is, per company partnership.

What you can read from it:

- how many orders in the campaign passed and how many were rejected,
- the total value of the discounts applied,
- the overall picture of how much the partnership is used.

💡 Analytics is your basis for evaluating the partnership with a company — for example when you negotiate about continuing it or about the terms.

## Common situations (FAQ)

**The order wasn't evaluated at all.**
Check that the campaign has the **Active** status and that a valid API key is entered. If you changed the token in Shoptet recently, paste the new one into the add-on.

**The add-on didn't find the discount code even though the customer used it.**
Look at the name of the discount coupon in Shoptet — the code in it has to be a **separate word** (see [Discount codes](#discount-codes-what-to-watch-out-for)).

**I don't want orders to be canceled right away.**
In the campaign settings, switch the response to "only flag and record". You then handle cancellations manually based on the log.

**The same order didn't show up in the log twice even though Shoptet reported two events.**
That's fine — the add-on deliberately evaluates each order only once (it protects you from duplicates).

**The notification didn't arrive.**
Verify that the address is public HTTPS and that your system accepts messages there. The add-on retries delivery 3 times; if it still doesn't go through, you find the event in the log.

## What the add-on can't do (yet) / limitations

- The matching relies on the **coupon name**. If you rename a coupon well outside the standard format, the code may not be found.
- Logs and campaigns are **not deleted when you uninstall** — the history stays.
- Only **new orders** are evaluated, from the moment the campaign is active. Older orders are not recalculated retroactively.

---

*Návod pochází z webu Webotvůrci — Zlatý a Premium partner Shoptetu.*
*Všechny návody: https://www.webmakeria.com/guides/ · Kontakt: jsme@webotvurci.cz*