Adjust points

curl --request POST \
  --url https://api.mageloyalty.com/v1/customers/6789012345/points \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "adjustment": 500,
  "note": "Goodwill gesture after delayed order",
  "update_lifetime_points": true,
  "send_email": true
}'

const response = await fetch(
  "https://api.mageloyalty.com/v1/customers/6789012345/points",
  {
    method: "POST",
    headers: {
      Authorization: "<api-key>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      adjustment: 500,
      note: "Goodwill gesture after delayed order",
      update_lifetime_points: true,
      send_email: true,
    }),
  }
);

const data = await response.json();

import requests

response = requests.post(
    "https://api.mageloyalty.com/v1/customers/6789012345/points",
    headers={"Authorization": "<api-key>"},
    json={
        "adjustment": 500,
        "note": "Goodwill gesture after delayed order",
        "update_lifetime_points": True,
        "send_email": True,
    },
)

data = response.json()

<?php
$ch = curl_init("https://api.mageloyalty.com/v1/customers/6789012345/points");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: <api-key>",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "adjustment" => 500,
        "note" => "Goodwill gesture after delayed order",
        "update_lifetime_points" => true,
        "send_email" => true,
    ]),
]);
$data = json_decode(curl_exec($ch), true);

{
  "data": {
    "type": "points_adjustment",
    "id": "6789012345",
    "attributes": {
      "shopify_customer_id": "6789012345",
      "adjustment": 500,
      "points_before": 200,
      "points_after": 700,
      "current_points": 700,
      "loyalty_mode": "points",
      "currency": "GBP"
    }
  }
}

{
  "data": {
    "type": "points_adjustment",
    "id": "6789012345",
    "attributes": {
      "shopify_customer_id": "6789012345",
      "adjustment": 500,
      "points_before": 200,
      "points_after": 700,
      "current_points": 700,
      "loyalty_mode": "store_credit",
      "currency": "GBP",
      "credit_adjustment": "5.00",
      "credit_before": "2.00",
      "credit_after": "7.00",
      "credit_balance": "7.00"
    }
  }
}

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

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

POST

customers

{identifier}

points

curl --request POST \
  --url https://api.mageloyalty.com/v1/customers/6789012345/points \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "adjustment": 500,
  "note": "Goodwill gesture after delayed order",
  "update_lifetime_points": true,
  "send_email": true
}'

const response = await fetch(
  "https://api.mageloyalty.com/v1/customers/6789012345/points",
  {
    method: "POST",
    headers: {
      Authorization: "<api-key>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      adjustment: 500,
      note: "Goodwill gesture after delayed order",
      update_lifetime_points: true,
      send_email: true,
    }),
  }
);

const data = await response.json();

import requests

response = requests.post(
    "https://api.mageloyalty.com/v1/customers/6789012345/points",
    headers={"Authorization": "<api-key>"},
    json={
        "adjustment": 500,
        "note": "Goodwill gesture after delayed order",
        "update_lifetime_points": True,
        "send_email": True,
    },
)

data = response.json()

<?php
$ch = curl_init("https://api.mageloyalty.com/v1/customers/6789012345/points");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: <api-key>",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "adjustment" => 500,
        "note" => "Goodwill gesture after delayed order",
        "update_lifetime_points" => true,
        "send_email" => true,
    ]),
]);
$data = json_decode(curl_exec($ch), true);

{
  "data": {
    "type": "points_adjustment",
    "id": "6789012345",
    "attributes": {
      "shopify_customer_id": "6789012345",
      "adjustment": 500,
      "points_before": 200,
      "points_after": 700,
      "current_points": 700,
      "loyalty_mode": "points",
      "currency": "GBP"
    }
  }
}

{
  "data": {
    "type": "points_adjustment",
    "id": "6789012345",
    "attributes": {
      "shopify_customer_id": "6789012345",
      "adjustment": 500,
      "points_before": 200,
      "points_after": 700,
      "current_points": 700,
      "loyalty_mode": "store_credit",
      "currency": "GBP",
      "credit_adjustment": "5.00",
      "credit_before": "2.00",
      "credit_after": "7.00",
      "credit_balance": "7.00"
    }
  }
}

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

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

Manually add or deduct points for a customer. Useful for CS teams handling complaints, migrations from another platform, or any bespoke earning scenario not covered by earning rules.

Request body

Field	Type	Required	Description
`adjustment`	integer	Yes	Points to add (positive) or deduct (negative). Cannot be zero. On store-credit shops this is a minor-unit amount, so `500` means 5.00 of credit (see Loyalty modes).
`note`	string	No	Internal note stored on the audit record
`update_lifetime_points`	boolean	No	Whether to also adjust lifetime points. Default: `true`
`send_email`	boolean	No	Whether to notify the customer of the adjustment. This gates both the points-earned email and the events sent to connected marketing integrations. Default: `true`

{
  "adjustment": 500,
  "note": "Goodwill gesture after delayed order",
  "update_lifetime_points": true,
  "send_email": true
}

Behaviour

Points balance floors at 0 — deductions will never produce a negative balance
Customer tier is recalculated automatically after the adjustment
Creates an audit trail entry in the customer’s earning history

Response

Returns 200 OK with a points_adjustment object.

Field	Type	Description
`shopify_customer_id`	string	The customer’s Shopify ID
`adjustment`	integer	The applied adjustment (minor units in store-credit mode)
`points_before`	integer	Balance before the adjustment
`points_after`	integer	Balance after the adjustment
`current_points`	integer	Balance after the adjustment (same as `points_after`)
`loyalty_mode`	string	Either `points` or `store_credit`
`currency`	string	The shop’s ISO 4217 currency code

On store-credit shops the response also includes credit_* companions with the major-unit decimal strings: credit_adjustment, credit_before, credit_after, and credit_balance. These are absent in points mode. See Loyalty modes.

Errors

Status	Scenario
`400`	`adjustment` missing, zero, or not an integer
`403`	Customer is excluded from the loyalty program
`404`	Customer not found
`500`	The points adjustment could not be applied

curl --request POST \
  --url https://api.mageloyalty.com/v1/customers/6789012345/points \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "adjustment": 500,
  "note": "Goodwill gesture after delayed order",
  "update_lifetime_points": true,
  "send_email": true
}'

const response = await fetch(
  "https://api.mageloyalty.com/v1/customers/6789012345/points",
  {
    method: "POST",
    headers: {
      Authorization: "<api-key>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      adjustment: 500,
      note: "Goodwill gesture after delayed order",
      update_lifetime_points: true,
      send_email: true,
    }),
  }
);

const data = await response.json();

import requests

response = requests.post(
    "https://api.mageloyalty.com/v1/customers/6789012345/points",
    headers={"Authorization": "<api-key>"},
    json={
        "adjustment": 500,
        "note": "Goodwill gesture after delayed order",
        "update_lifetime_points": True,
        "send_email": True,
    },
)

data = response.json()

<?php
$ch = curl_init("https://api.mageloyalty.com/v1/customers/6789012345/points");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: <api-key>",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "adjustment" => 500,
        "note" => "Goodwill gesture after delayed order",
        "update_lifetime_points" => true,
        "send_email" => true,
    ]),
]);
$data = json_decode(curl_exec($ch), true);

{
  "data": {
    "type": "points_adjustment",
    "id": "6789012345",
    "attributes": {
      "shopify_customer_id": "6789012345",
      "adjustment": 500,
      "points_before": 200,
      "points_after": 700,
      "current_points": 700,
      "loyalty_mode": "points",
      "currency": "GBP"
    }
  }
}

{
  "data": {
    "type": "points_adjustment",
    "id": "6789012345",
    "attributes": {
      "shopify_customer_id": "6789012345",
      "adjustment": 500,
      "points_before": 200,
      "points_after": 700,
      "current_points": 700,
      "loyalty_mode": "store_credit",
      "currency": "GBP",
      "credit_adjustment": "5.00",
      "credit_before": "2.00",
      "credit_after": "7.00",
      "credit_balance": "7.00"
    }
  }
}

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

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

Update a customer Get birthday

REST API

API Resources

Webhook Events

Shopify Metafields

Request body

Behaviour

Response

Errors

​Request body

​Behaviour

​Response

​Errors

Request body

Behaviour

Response

Errors