Award a custom action

curl --request POST \
  --url https://api.mageloyalty.com/v1/actions \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "action_key": "mobile_app_install",
  "customer_id": "6789012345",
  "idempotency_key": "install-6789012345-ios"
}'

const response = await fetch("https://api.mageloyalty.com/v1/actions", {
  method: "POST",
  headers: {
    Authorization: "<api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    action_key: "mobile_app_install",
    customer_id: "6789012345",
    idempotency_key: "install-6789012345-ios",
  }),
});

const data = await response.json();

import requests

response = requests.post(
    "https://api.mageloyalty.com/v1/actions",
    headers={"Authorization": "<api-key>"},
    json={
        "action_key": "mobile_app_install",
        "customer_id": "6789012345",
        "idempotency_key": "install-6789012345-ios",
    },
)

data = response.json()

<?php
$ch = curl_init("https://api.mageloyalty.com/v1/actions");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: <api-key>",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "action_key" => "mobile_app_install",
        "customer_id" => "6789012345",
        "idempotency_key" => "install-6789012345-ios",
    ]),
]);
$data = json_decode(curl_exec($ch), true);

{
  "data": {
    "type": "earning_history_entry",
    "id": "cer_abc123",
    "attributes": {
      "earning_rule_id": "rule_abc",
      "action": "custom",
      "points": 100,
      "points_balance": 1200,
      "loyalty_mode": "points",
      "currency": "GBP",
      "status": "approved",
      "idempotency_key": "install-6789012345-ios",
      "replayed": false,
      "points_given_at": "2026-06-23T12:00:00.000Z",
      "points_due_at": null,
      "created_at": "2026-06-23T12:00:00.000Z"
    }
  }
}

{
  "data": {
    "type": "earning_history_entry",
    "id": "cer_abc123",
    "attributes": {
      "earning_rule_id": "rule_abc",
      "action": "custom",
      "points": 100,
      "points_balance": 1200,
      "loyalty_mode": "points",
      "currency": "GBP",
      "status": "approved",
      "idempotency_key": "install-6789012345-ios",
      "replayed": true,
      "points_given_at": "2026-06-23T12:00:00.000Z",
      "points_due_at": null,
      "created_at": "2026-06-23T12:00:00.000Z"
    }
  }
}

{
  "errors": [
    {
      "status": "409",
      "title": "Conflict",
      "detail": "Customer has already been awarded points for this action. The action is configured to award once per customer."
    }
  ]
}

POST

actions

curl --request POST \
  --url https://api.mageloyalty.com/v1/actions \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "action_key": "mobile_app_install",
  "customer_id": "6789012345",
  "idempotency_key": "install-6789012345-ios"
}'

const response = await fetch("https://api.mageloyalty.com/v1/actions", {
  method: "POST",
  headers: {
    Authorization: "<api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    action_key: "mobile_app_install",
    customer_id: "6789012345",
    idempotency_key: "install-6789012345-ios",
  }),
});

const data = await response.json();

import requests

response = requests.post(
    "https://api.mageloyalty.com/v1/actions",
    headers={"Authorization": "<api-key>"},
    json={
        "action_key": "mobile_app_install",
        "customer_id": "6789012345",
        "idempotency_key": "install-6789012345-ios",
    },
)

data = response.json()

<?php
$ch = curl_init("https://api.mageloyalty.com/v1/actions");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: <api-key>",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "action_key" => "mobile_app_install",
        "customer_id" => "6789012345",
        "idempotency_key" => "install-6789012345-ios",
    ]),
]);
$data = json_decode(curl_exec($ch), true);

{
  "data": {
    "type": "earning_history_entry",
    "id": "cer_abc123",
    "attributes": {
      "earning_rule_id": "rule_abc",
      "action": "custom",
      "points": 100,
      "points_balance": 1200,
      "loyalty_mode": "points",
      "currency": "GBP",
      "status": "approved",
      "idempotency_key": "install-6789012345-ios",
      "replayed": false,
      "points_given_at": "2026-06-23T12:00:00.000Z",
      "points_due_at": null,
      "created_at": "2026-06-23T12:00:00.000Z"
    }
  }
}

{
  "data": {
    "type": "earning_history_entry",
    "id": "cer_abc123",
    "attributes": {
      "earning_rule_id": "rule_abc",
      "action": "custom",
      "points": 100,
      "points_balance": 1200,
      "loyalty_mode": "points",
      "currency": "GBP",
      "status": "approved",
      "idempotency_key": "install-6789012345-ios",
      "replayed": true,
      "points_given_at": "2026-06-23T12:00:00.000Z",
      "points_due_at": null,
      "created_at": "2026-06-23T12:00:00.000Z"
    }
  }
}

{
  "errors": [
    {
      "status": "409",
      "title": "Conflict",
      "detail": "Customer has already been awarded points for this action. The action is configured to award once per customer."
    }
  ]
}

Custom actions let you award points for things that happen outside Shopify — a mobile app install, an in-app purchase, an event check-in, a completed survey, or any milestone your own systems track. You create a custom action once in the Mage admin (Loyalty Program → Earning rules → Advanced → Custom Action), give it a stable action key, then call this endpoint from your backend whenever the action happens. You can also trigger it with no code using the Shopify Flow action.

Custom actions are available on the Growth plan and above. The customer must already be a loyalty member — a call for someone who is not enrolled returns 404.

Points come from the rule’s configured amount, with any applicable VIP tier and bonus campaign multipliers applied automatically. Each rule is either once per customer or unlimited, depending on how you configured it.

Request body

Field	Type	Required	Description
`action_key`	string	Yes	The action key of the custom rule. Lowercase letters, numbers, and underscores only
`customer_id`	string	Conditional	Shopify customer ID (numeric). Required if `customer_email` is not provided
`customer_email`	string	Conditional	Customer email. Required if `customer_id` is not provided
`idempotency_key`	string	No	A unique value for this specific completion. A repeat with the same key returns the original award instead of granting again
`metadata`	object	No	Free-form context stored alongside the earning record

Idempotency

If you pass an idempotency_key, a repeated request with the same key for the same rule returns the original award with 200 OK and replayed: true — points are never granted twice. For an unlimited rule where each completion should count once, set the key to a stable id for that completion, such as an event id or order id.

An unlimited rule awards on every call. Without an idempotency_key there is nothing to deduplicate on, so any retry — a network failure, an app relaunch, a repeated event — awards again and double-grants points. Always send a stable idempotency_key per real completion on unlimited rules.Once-per-customer rules are protected regardless: a second award returns 409, with or without a key.

Validations

Customer must exist and not be excluded from the loyalty program
A custom action with the given action_key must exist and be active
For a once-per-customer rule, the customer must not have already been awarded this action

Response

Returns 201 Created on success, or 200 OK for an idempotent replay. The points and points_balance fields are minor currency units on store-credit shops, and the response carries loyalty_mode and currency. On store-credit shops it also includes credit_earned and credit_balance companions (major-unit decimal strings), which are absent in points mode. See Loyalty modes.

When the rule has an approval delay configured, status is pending, points_given_at is null, points_due_at reflects when the points will be approved, and points_balance excludes the pending points until then.

If the loyalty program is disabled, or test mode is filtering this customer, the request still succeeds with 200 OK but no points are awarded:

{
  "data": null,
  "meta": { "awarded": false, "reason": "program_disabled" }
}

Errors

Status	Scenario
`400`	`action_key` missing or invalid, neither `customer_id` nor `customer_email` provided, or invalid JSON
`403`	Customer is excluded from the loyalty program
`404`	No active custom action matches the `action_key`, or the customer is not a loyalty member
`409`	A once-per-customer rule has already been awarded to this customer
`429`	Rate limit exceeded (6 requests/second)

Example 409 response:

{
  "errors": [
    {
      "status": "409",
      "title": "Conflict",
      "detail": "Customer has already been awarded points for this action. The action is configured to award once per customer."
    }
  ]
}

Trigger from Shopify Flow

If you would rather not write code, add the Award Custom Action action to any Shopify Flow workflow and set:

Action key — the same key from the rule’s setup page
Customer — map a customer from the workflow’s trigger
Idempotency key (optional) — leave blank to use the Flow run id automatically, so a retried run never awards twice

Shopify Flow signs and sends the request for you, so no API key is needed for this path.

curl --request POST \
  --url https://api.mageloyalty.com/v1/actions \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "action_key": "mobile_app_install",
  "customer_id": "6789012345",
  "idempotency_key": "install-6789012345-ios"
}'

const response = await fetch("https://api.mageloyalty.com/v1/actions", {
  method: "POST",
  headers: {
    Authorization: "<api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    action_key: "mobile_app_install",
    customer_id: "6789012345",
    idempotency_key: "install-6789012345-ios",
  }),
});

const data = await response.json();

import requests

response = requests.post(
    "https://api.mageloyalty.com/v1/actions",
    headers={"Authorization": "<api-key>"},
    json={
        "action_key": "mobile_app_install",
        "customer_id": "6789012345",
        "idempotency_key": "install-6789012345-ios",
    },
)

data = response.json()

<?php
$ch = curl_init("https://api.mageloyalty.com/v1/actions");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: <api-key>",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "action_key" => "mobile_app_install",
        "customer_id" => "6789012345",
        "idempotency_key" => "install-6789012345-ios",
    ]),
]);
$data = json_decode(curl_exec($ch), true);

{
  "data": {
    "type": "earning_history_entry",
    "id": "cer_abc123",
    "attributes": {
      "earning_rule_id": "rule_abc",
      "action": "custom",
      "points": 100,
      "points_balance": 1200,
      "loyalty_mode": "points",
      "currency": "GBP",
      "status": "approved",
      "idempotency_key": "install-6789012345-ios",
      "replayed": false,
      "points_given_at": "2026-06-23T12:00:00.000Z",
      "points_due_at": null,
      "created_at": "2026-06-23T12:00:00.000Z"
    }
  }
}

{
  "data": {
    "type": "earning_history_entry",
    "id": "cer_abc123",
    "attributes": {
      "earning_rule_id": "rule_abc",
      "action": "custom",
      "points": 100,
      "points_balance": 1200,
      "loyalty_mode": "points",
      "currency": "GBP",
      "status": "approved",
      "idempotency_key": "install-6789012345-ios",
      "replayed": true,
      "points_given_at": "2026-06-23T12:00:00.000Z",
      "points_due_at": null,
      "created_at": "2026-06-23T12:00:00.000Z"
    }
  }
}

{
  "errors": [
    {
      "status": "409",
      "title": "Conflict",
      "detail": "Customer has already been awarded points for this action. The action is configured to award once per customer."
    }
  ]
}

REST API

API Resources

Webhook Events

Shopify Metafields

Request body

Idempotency

Validations

Response

Errors

Trigger from Shopify Flow

​Request body

​Idempotency

​Validations

​Response

​Errors

​Trigger from Shopify Flow

Request body

Idempotency

Validations

Response

Errors

Trigger from Shopify Flow