Skip to main content

Set Up the Custom Action Earning Rule

Reward customers for actions outside Shopify, such as a mobile app install or an event check-in, by triggering a Custom Action earning rule from the REST API or Shopify Flow.

Written by Kris James

Custom actions let you reward customers for things that happen outside Shopify. If your own systems know that something happened, you can tell Mage to award points for it.

Common examples:

  • A customer installs your mobile app

  • A customer makes a purchase inside your app

  • Someone attends an event or scans a QR code

  • A customer completes a survey or leaves feedback

Custom actions are available on the Growth plan and above.

How it works

You create a custom action once in Mage and give it a short action key (for example mobile_app_install). That key is the link between Mage and your systems. Whenever the action happens, you trigger it from your own backend with the REST API, or with no code using Shopify Flow. Either way, Mage awards the points you configured on the action.

Create the custom action

  1. Go to Loyalty Program > Earning rules and select Add earning rule.

  2. Open the Advanced tab and choose Custom Action.

  3. Fill in the fields:

    • Name: a friendly name, for example "Installed our mobile app".

    • Action key: generated from the name, and you can edit it. Use lowercase letters, numbers and underscores only, for example mobile_app_install. This is the value you reference when you trigger the action.

    • Points reward: how many points to award each time.

    • How often can a customer earn this: choose Once per customer or Every time (unlimited). See the settings below.

    • Approval time: leave at 0 for instant points, or set a delay. See the settings below.

  4. Save and turn the action on with the Status toggle.

Keep the action key somewhere handy. You will use it when you set up the trigger.

Custom action settings

These options control how your custom action behaves. You set them when you create or edit the action.

Once per customer or unlimited

  • Once per customer awards the points a single time. A second call for the same customer is rejected and does not award again, with or without an idempotency key. This is the safest setting and the right one for things like an app install.

  • Every time (unlimited) awards points on every call. This means a retry or an accidental repeat will award the points again. To stay safe, send an idempotency key that is unique to each real completion, for example an event id or an order id. Repeat calls with the same key return the original award and never grant points twice.

Important for unlimited actions: if you do not send an idempotency key, every call adds points, including any retry your system makes after a network error. Always send a stable idempotency key per completion on an unlimited action. Once per customer actions do not have this risk.

Approval timing

If you set an approval time above 0, points are held as pending and approved automatically after the delay. This is useful as a short anti fraud window. Set it to 0 for instant points.

Advanced settings

Hide on storefront

A custom action is shown in your loyalty displays by default. Because the points are awarded by your systems rather than by a customer clicking a button, you can hide an action that runs purely in the background by ticking Hide on storefront. This keeps it out of your loyalty widget, sidebar and rewards pages.

Storefront button link

When an action is shown, you can also add an optional button link, so its tile points to a page you choose, for example your app store listing. Clicking the tile only opens your link. It never awards points on its own, which keeps the action secure.

Trigger your custom action

Once your action is set up, trigger it whenever the behavior happens. Use the REST API from your own backend, or Shopify Flow for a no code option.

REST API

  1. Generate an API key under Settings > Developer.

  2. From your backend (not the browser), send a POST request to https://api.mageloyalty.com/v1/actions. Put your API key in the Authorization header exactly as it is, with no Bearer prefix, and send a JSON body like this:

{"action_key": "mobile_app_install", "customer_id": "6789012345", "idempotency_key": "install-6789012345-ios"}

You can identify the customer by their Shopify customer id (customer_id) or by customer_email. The customer must already be a loyalty member. Full request and response details are in the developer API reference.

Shopify Flow

  1. In Shopify, open Flow and create or edit a workflow.

  2. Add the Award Custom Action step from Mage.

  3. Set the fields:

    • Action key: the key from your custom action.

    • Customer: choose the customer from the workflow's trigger.

    • Idempotency key (optional): leave this blank. Mage uses the Flow run id automatically so a retried run never awards twice.

  4. Turn the workflow on.

Shopify Flow signs and sends the request for you, so you do not need an API key for this path.

FAQ

Can a customer earn the same action more than once?
It depends on the frequency you set. Once per customer awards a single time. Every time (unlimited) awards on each call, so you use an idempotency key to control repeats.

What is the best way to handle an idempotency key?
Use a value that is unique to each real completion, and send the exact same value if you retry. For a once per customer action like an app install, a key such as install_app_6789012345 (the action plus the customer id) works well. For an unlimited action, key it to the specific occurrence, for example the event id or the order id. Do not generate a new random value on every call, or a retry will not be recognised and you may award the points twice.

Should I send the Shopify customer id or the email?
Either works. The Shopify customer id is the most reliable. Whichever you send, the customer must already be enrolled in your loyalty program.

Can my mobile app call the API directly?
No. Keep your API key on your server. Your app should call your own backend, and your backend calls Mage with the key. An API key shipped inside a mobile app can be extracted and misused.

Do custom action points get VIP tier and bonus campaign multipliers?
Yes. A customer's VIP tier multiplier and any active bonus campaign apply automatically.

What happens if I change the action key later?
Any REST API calls or Shopify Flow steps that still use the old key will stop working. Update your integrations to the new key whenever you change it.

How can I test a custom action before it goes live to my store?
A custom action only awards points when your own system triggers it, so you can test it without affecting other customers. Create the action and keep it hidden from the storefront while you work (tick Hide on storefront), then fire one call, by REST API or Shopify Flow, for a single account that is enrolled in your loyalty program, such as a staff account. Confirm the response is a 201, or that the Flow run completes, and check that account's points in the admin. If you want to undo the test award, adjust that account's points manually, then show the action when you are ready.

If you have not launched your loyalty program yet, you can instead use test mode, which limits earning to your test customers while you try things out. Avoid test mode on a store that is already live, because it pauses earning for all of your other customers. A staging or development store is also an option if you already have one.

I triggered the action but no points were awarded. What should I check?
Check that the action is turned on, the action key matches exactly, your loyalty program is enabled, and the customer is already enrolled. A call for someone who is not a loyalty member returns a "customer not found" error.

Did this answer your question?