List earning history

curl --request GET \
  --url https://api.mageloyalty.com/v1/customers/6789012345/earning-history \
  --header 'Authorization: <api-key>'

curl --request GET \
  --url 'https://api.mageloyalty.com/v1/customers/6789012345/earning-history?filter[status]=approved&sort=-points_given_at&page[number]=1&page[size]=20' \
  --header 'Authorization: <api-key>'

const params = new URLSearchParams({
  "filter[status]": "approved",
  sort: "-points_given_at",
  "page[number]": "1",
  "page[size]": "20",
});

const response = await fetch(
  `https://api.mageloyalty.com/v1/customers/6789012345/earning-history?${params}`,
  {
    method: "GET",
    headers: { Authorization: "<api-key>" },
  }
);

const data = await response.json();

import requests

response = requests.get(
    "https://api.mageloyalty.com/v1/customers/6789012345/earning-history",
    headers={"Authorization": "<api-key>"},
    params={
        "filter[status]": "approved",
        "sort": "-points_given_at",
        "page[number]": 1,
        "page[size]": 20,
    },
)

data = response.json()

<?php
$query = http_build_query([
    "filter[status]" => "approved",
    "sort" => "-points_given_at",
    "page[number]" => 1,
    "page[size]" => 20,
]);
$ch = curl_init("https://api.mageloyalty.com/v1/customers/6789012345/earning-history?$query");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: <api-key>"],
]);
$data = json_decode(curl_exec($ch), true);

{
  "data": [
    {
      "type": "earning_history_entry",
      "id": "entry_abc",
      "attributes": {
        "earning_rule_id": "rule_abc",
        "action": "purchase",
        "points": 150,
        "base_points": 100,
        "points_multiplier": 1.5,
        "status": "approved",
        "order_id": "5678901234",
        "order_number": "#1042",
        "points_due_at": null,
        "points_given_at": "2024-06-01T12:05:00.000Z",
        "points_expiry_at": null,
        "created_at": "2024-06-01T12:00:00.000Z",
        "updated_at": "2024-06-01T12:05:00.000Z"
      }
    }
  ],
  "meta": {
    "total": 12,
    "page": 1,
    "per_page": 20,
    "total_pages": 1,
    "loyalty_mode": "points",
    "currency": "GBP"
  }
}

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

GET

customers

{identifier}

earning-history

curl --request GET \
  --url https://api.mageloyalty.com/v1/customers/6789012345/earning-history \
  --header 'Authorization: <api-key>'

curl --request GET \
  --url 'https://api.mageloyalty.com/v1/customers/6789012345/earning-history?filter[status]=approved&sort=-points_given_at&page[number]=1&page[size]=20' \
  --header 'Authorization: <api-key>'

const params = new URLSearchParams({
  "filter[status]": "approved",
  sort: "-points_given_at",
  "page[number]": "1",
  "page[size]": "20",
});

const response = await fetch(
  `https://api.mageloyalty.com/v1/customers/6789012345/earning-history?${params}`,
  {
    method: "GET",
    headers: { Authorization: "<api-key>" },
  }
);

const data = await response.json();

import requests

response = requests.get(
    "https://api.mageloyalty.com/v1/customers/6789012345/earning-history",
    headers={"Authorization": "<api-key>"},
    params={
        "filter[status]": "approved",
        "sort": "-points_given_at",
        "page[number]": 1,
        "page[size]": 20,
    },
)

data = response.json()

<?php
$query = http_build_query([
    "filter[status]" => "approved",
    "sort" => "-points_given_at",
    "page[number]" => 1,
    "page[size]" => 20,
]);
$ch = curl_init("https://api.mageloyalty.com/v1/customers/6789012345/earning-history?$query");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: <api-key>"],
]);
$data = json_decode(curl_exec($ch), true);

{
  "data": [
    {
      "type": "earning_history_entry",
      "id": "entry_abc",
      "attributes": {
        "earning_rule_id": "rule_abc",
        "action": "purchase",
        "points": 150,
        "base_points": 100,
        "points_multiplier": 1.5,
        "status": "approved",
        "order_id": "5678901234",
        "order_number": "#1042",
        "points_due_at": null,
        "points_given_at": "2024-06-01T12:05:00.000Z",
        "points_expiry_at": null,
        "created_at": "2024-06-01T12:00:00.000Z",
        "updated_at": "2024-06-01T12:05:00.000Z"
      }
    }
  ],
  "meta": {
    "total": 12,
    "page": 1,
    "per_page": 20,
    "total_pages": 1,
    "loyalty_mode": "points",
    "currency": "GBP"
  }
}

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

List a customer’s point earning history. The identifier can be a Shopify customer ID or email.

Query parameters

Parameter	Type	Description
`filter[status]`	string	Filter by status: `pending`, `approved`, `rejected`
`sort`	string	Sort field. Prefix with `-` for descending. Options: `created_at`, `points`, `points_given_at`. Default: `-created_at`
`page[number]`	integer	Page number (default: `1`)
`page[size]`	integer	Results per page (default: `20`, max: `100`)

Response

Returns a data array of earning_history_entry objects alongside a paginated meta. Each entry has these attributes:

Field	Type	Description
`earning_rule_id`	string \| null	The earning rule that produced this entry
`action`	string \| null	The rule action, for example `purchase` or `birthday`
`points`	integer	Points awarded. Minor currency units in store-credit mode (see Loyalty modes)
`base_points`	integer \| null	Points before tier and campaign multipliers
`points_multiplier`	number \| null	The combined multiplier applied
`status`	string	`pending`, `approved`, or `rejected`
`order_id`	string \| null	The originating Shopify order ID, if any
`order_number`	string \| null	The originating order number, if any
`points_due_at`	string \| null	When pending points become available
`points_given_at`	string \| null	When the points were awarded
`points_expiry_at`	string \| null	When the points expire, if applicable
`created_at`	string	ISO 8601 timestamp
`updated_at`	string	ISO 8601 timestamp

The meta object includes loyalty_mode and currency so you can read the points values correctly.

Errors

Status	Scenario
`404`	Customer not found
`429`	Rate limit exceeded (6 requests/second)

curl --request GET \
  --url https://api.mageloyalty.com/v1/customers/6789012345/earning-history \
  --header 'Authorization: <api-key>'

curl --request GET \
  --url 'https://api.mageloyalty.com/v1/customers/6789012345/earning-history?filter[status]=approved&sort=-points_given_at&page[number]=1&page[size]=20' \
  --header 'Authorization: <api-key>'

const params = new URLSearchParams({
  "filter[status]": "approved",
  sort: "-points_given_at",
  "page[number]": "1",
  "page[size]": "20",
});

const response = await fetch(
  `https://api.mageloyalty.com/v1/customers/6789012345/earning-history?${params}`,
  {
    method: "GET",
    headers: { Authorization: "<api-key>" },
  }
);

const data = await response.json();

import requests

response = requests.get(
    "https://api.mageloyalty.com/v1/customers/6789012345/earning-history",
    headers={"Authorization": "<api-key>"},
    params={
        "filter[status]": "approved",
        "sort": "-points_given_at",
        "page[number]": 1,
        "page[size]": 20,
    },
)

data = response.json()

<?php
$query = http_build_query([
    "filter[status]" => "approved",
    "sort" => "-points_given_at",
    "page[number]" => 1,
    "page[size]" => 20,
]);
$ch = curl_init("https://api.mageloyalty.com/v1/customers/6789012345/earning-history?$query");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: <api-key>"],
]);
$data = json_decode(curl_exec($ch), true);

{
  "data": [
    {
      "type": "earning_history_entry",
      "id": "entry_abc",
      "attributes": {
        "earning_rule_id": "rule_abc",
        "action": "purchase",
        "points": 150,
        "base_points": 100,
        "points_multiplier": 1.5,
        "status": "approved",
        "order_id": "5678901234",
        "order_number": "#1042",
        "points_due_at": null,
        "points_given_at": "2024-06-01T12:05:00.000Z",
        "points_expiry_at": null,
        "created_at": "2024-06-01T12:00:00.000Z",
        "updated_at": "2024-06-01T12:05:00.000Z"
      }
    }
  ],
  "meta": {
    "total": 12,
    "page": 1,
    "per_page": 20,
    "total_pages": 1,
    "loyalty_mode": "points",
    "currency": "GBP"
  }
}

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

REST API

API Resources

Webhook Events

Shopify Metafields

Query parameters

Response

Errors

​Query parameters

​Response

​Errors

Query parameters

Response

Errors