Award an earning rule

curl --request POST \
  --url https://api.mageloyalty.com/v1/earning-rules/rule_abc/award \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "customer_identifier": "6789012345"
}'

const response = await fetch(
  "https://api.mageloyalty.com/v1/earning-rules/rule_abc/award",
  {
    method: "POST",
    headers: {
      Authorization: "<api-key>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      customer_identifier: "6789012345",
    }),
  }
);

const data = await response.json();

import requests

response = requests.post(
    "https://api.mageloyalty.com/v1/earning-rules/rule_abc/award",
    headers={"Authorization": "<api-key>"},
    json={
        "customer_identifier": "6789012345",
    },
)

data = response.json()

<?php
$ch = curl_init("https://api.mageloyalty.com/v1/earning-rules/rule_abc/award");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: <api-key>",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "customer_identifier" => "6789012345",
    ]),
]);
$data = json_decode(curl_exec($ch), true);

{
  "data": {
    "type": "earning_history_entry",
    "id": "cer_abc123",
    "attributes": {
      "earning_rule_id": "rule_abc",
      "action": "follow_on_instagram",
      "points": 150,
      "base_points": 100,
      "points_multiplier": 1.5,
      "bonus_campaign_multiplier": null,
      "points_balance": 1350,
      "loyalty_mode": "points",
      "currency": "GBP",
      "status": "approved",
      "points_given_at": "2024-06-01T12:00:00.000Z",
      "points_due_at": null,
      "points_expiry_at": null,
      "created_at": "2024-06-01T12:00:00.000Z",
      "updated_at": "2024-06-01T12:00:00.000Z"
    }
  }
}

{
  "data": {
    "type": "earning_history_entry",
    "id": "cer_abc123",
    "attributes": {
      "earning_rule_id": "rule_abc",
      "action": "follow_on_instagram",
      "points": 150,
      "base_points": 100,
      "points_multiplier": 1.5,
      "bonus_campaign_multiplier": null,
      "points_balance": 1350,
      "loyalty_mode": "store_credit",
      "currency": "GBP",
      "credit_earned": "1.50",
      "credit_balance": "13.50",
      "status": "approved",
      "points_given_at": "2024-06-01T12:00:00.000Z",
      "points_due_at": null,
      "points_expiry_at": null,
      "created_at": "2024-06-01T12:00:00.000Z",
      "updated_at": "2024-06-01T12:00:00.000Z"
    }
  }
}

{
  "errors": [
    {
      "status": "403",
      "title": "Forbidden",
      "detail": "Customer is excluded from the loyalty program"
    }
  ]
}

{
  "errors": [
    {
      "status": "404",
      "title": "Not Found",
      "detail": "Customer '6789012345' not found"
    }
  ]
}

{
  "errors": [
    {
      "status": "409",
      "title": "Conflict",
      "detail": "Customer has already been awarded points for this earning rule"
    }
  ]
}

{
  "errors": [
    {
      "status": "422",
      "title": "Unprocessable",
      "detail": "Earning rule category 'purchase' cannot be awarded via the API. Only 'social' and 'engagement' rules are supported."
    }
  ]
}

POST

earning-rules

{id}

award

curl --request POST \
  --url https://api.mageloyalty.com/v1/earning-rules/rule_abc/award \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "customer_identifier": "6789012345"
}'

const response = await fetch(
  "https://api.mageloyalty.com/v1/earning-rules/rule_abc/award",
  {
    method: "POST",
    headers: {
      Authorization: "<api-key>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      customer_identifier: "6789012345",
    }),
  }
);

const data = await response.json();

import requests

response = requests.post(
    "https://api.mageloyalty.com/v1/earning-rules/rule_abc/award",
    headers={"Authorization": "<api-key>"},
    json={
        "customer_identifier": "6789012345",
    },
)

data = response.json()

<?php
$ch = curl_init("https://api.mageloyalty.com/v1/earning-rules/rule_abc/award");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: <api-key>",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "customer_identifier" => "6789012345",
    ]),
]);
$data = json_decode(curl_exec($ch), true);

{
  "data": {
    "type": "earning_history_entry",
    "id": "cer_abc123",
    "attributes": {
      "earning_rule_id": "rule_abc",
      "action": "follow_on_instagram",
      "points": 150,
      "base_points": 100,
      "points_multiplier": 1.5,
      "bonus_campaign_multiplier": null,
      "points_balance": 1350,
      "loyalty_mode": "points",
      "currency": "GBP",
      "status": "approved",
      "points_given_at": "2024-06-01T12:00:00.000Z",
      "points_due_at": null,
      "points_expiry_at": null,
      "created_at": "2024-06-01T12:00:00.000Z",
      "updated_at": "2024-06-01T12:00:00.000Z"
    }
  }
}

{
  "data": {
    "type": "earning_history_entry",
    "id": "cer_abc123",
    "attributes": {
      "earning_rule_id": "rule_abc",
      "action": "follow_on_instagram",
      "points": 150,
      "base_points": 100,
      "points_multiplier": 1.5,
      "bonus_campaign_multiplier": null,
      "points_balance": 1350,
      "loyalty_mode": "store_credit",
      "currency": "GBP",
      "credit_earned": "1.50",
      "credit_balance": "13.50",
      "status": "approved",
      "points_given_at": "2024-06-01T12:00:00.000Z",
      "points_due_at": null,
      "points_expiry_at": null,
      "created_at": "2024-06-01T12:00:00.000Z",
      "updated_at": "2024-06-01T12:00:00.000Z"
    }
  }
}

{
  "errors": [
    {
      "status": "403",
      "title": "Forbidden",
      "detail": "Customer is excluded from the loyalty program"
    }
  ]
}

{
  "errors": [
    {
      "status": "404",
      "title": "Not Found",
      "detail": "Customer '6789012345' not found"
    }
  ]
}

{
  "errors": [
    {
      "status": "409",
      "title": "Conflict",
      "detail": "Customer has already been awarded points for this earning rule"
    }
  ]
}

{
  "errors": [
    {
      "status": "422",
      "title": "Unprocessable",
      "detail": "Earning rule category 'purchase' cannot be awarded via the API. Only 'social' and 'engagement' rules are supported."
    }
  ]
}

Award points to a customer for completing an earning rule action, using the rule’s configured points and any applicable VIP tier multiplier. Only social and engagement category rules can be awarded via the API. Rules in other categories (e.g. purchase, birthday, anniversary) are managed automatically by the platform. Each rule can only be awarded once per customer — duplicate requests return 409 Conflict.

Request body

Field	Type	Required	Description
`customer_identifier`	string	Yes	Shopify customer ID or email address

Validations

Customer must exist and not be excluded from the loyalty program
Earning rule must be active
Earning rule category must be social or engagement
Customer must not have already been awarded points for this rule

Response

Returns 201 Created.

Field	Type	Description
`earning_rule_id`	string \| null	The earning rule that was awarded
`action`	string \| null	The rule’s action type
`points`	integer	Final points awarded after the multiplier
`base_points`	integer \| null	Points before any multiplier
`points_multiplier`	number \| null	The applied VIP tier multiplier (`null` when no tier boost applied)
`bonus_campaign_multiplier`	number \| null	The bonus campaign multiplier applied, or `null`
`points_balance`	integer \| null	The customer’s balance after the award. Minor currency units in store-credit mode
`loyalty_mode`	string	Either `points` or `store_credit`
`currency`	string	The shop’s ISO 4217 currency code
`status`	string	`approved` or `pending`
`points_given_at`	string \| null	When points were awarded, or `null` while pending
`points_due_at`	string \| null	When pending points will be approved
`points_expiry_at`	string \| null	When the points expire, or `null`
`created_at`	string	ISO 8601 timestamp
`updated_at`	string	ISO 8601 timestamp

On store-credit shops the response also includes credit_earned and credit_balance companions with the major-unit decimal strings. These are absent in points mode. See Loyalty modes.

When the rule has an approval delay configured, status will be pending, points_given_at will be null, and points_due_at will reflect when the points will be approved.

Errors

Status	Scenario
`400`	`customer_identifier` missing or invalid JSON
`403`	Customer is excluded from the loyalty program
`404`	Customer or earning rule not found (or rule is inactive)
`409`	Customer has already been awarded points for this earning rule
`422`	Earning rule category cannot be awarded via the API
`429`	Rate limit exceeded (6 requests/second)

curl --request POST \
  --url https://api.mageloyalty.com/v1/earning-rules/rule_abc/award \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "customer_identifier": "6789012345"
}'

const response = await fetch(
  "https://api.mageloyalty.com/v1/earning-rules/rule_abc/award",
  {
    method: "POST",
    headers: {
      Authorization: "<api-key>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      customer_identifier: "6789012345",
    }),
  }
);

const data = await response.json();

import requests

response = requests.post(
    "https://api.mageloyalty.com/v1/earning-rules/rule_abc/award",
    headers={"Authorization": "<api-key>"},
    json={
        "customer_identifier": "6789012345",
    },
)

data = response.json()

<?php
$ch = curl_init("https://api.mageloyalty.com/v1/earning-rules/rule_abc/award");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: <api-key>",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "customer_identifier" => "6789012345",
    ]),
]);
$data = json_decode(curl_exec($ch), true);

{
  "data": {
    "type": "earning_history_entry",
    "id": "cer_abc123",
    "attributes": {
      "earning_rule_id": "rule_abc",
      "action": "follow_on_instagram",
      "points": 150,
      "base_points": 100,
      "points_multiplier": 1.5,
      "bonus_campaign_multiplier": null,
      "points_balance": 1350,
      "loyalty_mode": "points",
      "currency": "GBP",
      "status": "approved",
      "points_given_at": "2024-06-01T12:00:00.000Z",
      "points_due_at": null,
      "points_expiry_at": null,
      "created_at": "2024-06-01T12:00:00.000Z",
      "updated_at": "2024-06-01T12:00:00.000Z"
    }
  }
}

{
  "data": {
    "type": "earning_history_entry",
    "id": "cer_abc123",
    "attributes": {
      "earning_rule_id": "rule_abc",
      "action": "follow_on_instagram",
      "points": 150,
      "base_points": 100,
      "points_multiplier": 1.5,
      "bonus_campaign_multiplier": null,
      "points_balance": 1350,
      "loyalty_mode": "store_credit",
      "currency": "GBP",
      "credit_earned": "1.50",
      "credit_balance": "13.50",
      "status": "approved",
      "points_given_at": "2024-06-01T12:00:00.000Z",
      "points_due_at": null,
      "points_expiry_at": null,
      "created_at": "2024-06-01T12:00:00.000Z",
      "updated_at": "2024-06-01T12:00:00.000Z"
    }
  }
}

{
  "errors": [
    {
      "status": "403",
      "title": "Forbidden",
      "detail": "Customer is excluded from the loyalty program"
    }
  ]
}

{
  "errors": [
    {
      "status": "404",
      "title": "Not Found",
      "detail": "Customer '6789012345' not found"
    }
  ]
}

{
  "errors": [
    {
      "status": "409",
      "title": "Conflict",
      "detail": "Customer has already been awarded points for this earning rule"
    }
  ]
}

{
  "errors": [
    {
      "status": "422",
      "title": "Unprocessable",
      "detail": "Earning rule category 'purchase' cannot be awarded via the API. Only 'social' and 'engagement' rules are supported."
    }
  ]
}

REST API

API Resources

Webhook Events

Shopify Metafields

Request body

Validations

Response

Errors

​Request body

​Validations

​Response

​Errors

Request body

Validations

Response

Errors