Purchase a reward

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

const response = await fetch(
  "https://api.mageloyalty.com/v1/rewards/reward_abc/purchase",
  {
    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/rewards/reward_abc/purchase",
    headers={"Authorization": "<api-key>"},
    json={"customer_identifier": "6789012345"},
)

data = response.json()

<?php
$ch = curl_init("https://api.mageloyalty.com/v1/rewards/reward_abc/purchase");
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": "reward_history_entry",
    "id": "cr_abc123",
    "attributes": {
      "reward_id": "reward_abc",
      "reward_name": "£5 off your next order",
      "reward_discount_type": "fixed",
      "points_spent": 500,
      "loyalty_mode": "points",
      "currency": "GBP",
      "discount_code": "MAGE-XYZ789",
      "status": "active",
      "expires_at": "2024-07-01T00:00:00.000Z"
    }
  }
}

{
  "data": {
    "type": "reward_history_entry",
    "id": "cr_abc123",
    "attributes": {
      "reward_id": "reward_flex",
      "reward_name": "£2.50 off your order",
      "reward_discount_type": "fixed",
      "points_spent": 250,
      "loyalty_mode": "store_credit",
      "currency": "GBP",
      "credit_spent": "2.50",
      "discount_code": "MAGE-XYZ789",
      "status": "active",
      "expires_at": "2024-07-01T00:00:00.000Z"
    }
  }
}

{
  "errors": [
    {
      "status": "403",
      "title": "Forbidden",
      "detail": "This reward cannot be redeemed in store credit mode"
    }
  ]
}

{
  "errors": [
    {
      "status": "400",
      "title": "Bad Request",
      "detail": "Entry rewards cannot be purchased"
    }
  ]
}

{
  "errors": [
    {
      "status": "403",
      "title": "Forbidden",
      "detail": "Customer is not eligible for this reward"
    }
  ]
}

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

{
  "errors": [
    {
      "status": "422",
      "title": "Insufficient Points",
      "detail": "Customer has 200 points but this reward costs 500"
    }
  ]
}

{
  "errors": [
    {
      "status": "422",
      "title": "Invalid Points",
      "detail": "Minimum redemption is 100 points"
    }
  ]
}

{
  "errors": [
    {
      "status": "500",
      "title": "Internal Server Error",
      "detail": "Failed to create discount code. Points have not been deducted."
    }
  ]
}

POST

rewards

{id}

purchase

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

const response = await fetch(
  "https://api.mageloyalty.com/v1/rewards/reward_abc/purchase",
  {
    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/rewards/reward_abc/purchase",
    headers={"Authorization": "<api-key>"},
    json={"customer_identifier": "6789012345"},
)

data = response.json()

<?php
$ch = curl_init("https://api.mageloyalty.com/v1/rewards/reward_abc/purchase");
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": "reward_history_entry",
    "id": "cr_abc123",
    "attributes": {
      "reward_id": "reward_abc",
      "reward_name": "£5 off your next order",
      "reward_discount_type": "fixed",
      "points_spent": 500,
      "loyalty_mode": "points",
      "currency": "GBP",
      "discount_code": "MAGE-XYZ789",
      "status": "active",
      "expires_at": "2024-07-01T00:00:00.000Z"
    }
  }
}

{
  "data": {
    "type": "reward_history_entry",
    "id": "cr_abc123",
    "attributes": {
      "reward_id": "reward_flex",
      "reward_name": "£2.50 off your order",
      "reward_discount_type": "fixed",
      "points_spent": 250,
      "loyalty_mode": "store_credit",
      "currency": "GBP",
      "credit_spent": "2.50",
      "discount_code": "MAGE-XYZ789",
      "status": "active",
      "expires_at": "2024-07-01T00:00:00.000Z"
    }
  }
}

{
  "errors": [
    {
      "status": "403",
      "title": "Forbidden",
      "detail": "This reward cannot be redeemed in store credit mode"
    }
  ]
}

{
  "errors": [
    {
      "status": "400",
      "title": "Bad Request",
      "detail": "Entry rewards cannot be purchased"
    }
  ]
}

{
  "errors": [
    {
      "status": "403",
      "title": "Forbidden",
      "detail": "Customer is not eligible for this reward"
    }
  ]
}

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

{
  "errors": [
    {
      "status": "422",
      "title": "Insufficient Points",
      "detail": "Customer has 200 points but this reward costs 500"
    }
  ]
}

{
  "errors": [
    {
      "status": "422",
      "title": "Invalid Points",
      "detail": "Minimum redemption is 100 points"
    }
  ]
}

{
  "errors": [
    {
      "status": "500",
      "title": "Internal Server Error",
      "detail": "Failed to create discount code. Points have not been deducted."
    }
  ]
}

Purchase a reward on behalf of a customer, deducting the required points from their balance and generating a Shopify discount code.

Request body

Field	Type	Required	Description
`customer_identifier`	string	Yes	Shopify customer ID or email address
`points`	integer	For flexible rewards	How many points to spend. Used only by flexible rewards, where the customer chooses the amount. Must fall within the reward’s `flexible_config` range. On store-credit shops this is a minor-unit amount. Also accepted as `points_to_redeem`

{
  "customer_identifier": "6789012345"
}

Most rewards have a fixed points_cost, so the request only needs customer_identifier. For flexible rewards (redemption_mode: "flexible"), the customer chooses how many points to spend within the reward’s flexible_config range (see List rewards), and the discount is sized to match. Pass points for these:

{
  "customer_identifier": "6789012345",
  "points": 250
}

On store-credit shops, only flexible rewards can be purchased. A standard fixed-cost reward returns 403 Forbidden with This reward cannot be redeemed in store credit mode. See Loyalty modes.

Validations

Customer must exist and not be excluded from the loyalty program
Reward must be active and not deleted
If the reward is restricted to a VIP tier, the customer must be on that tier
Customer must have enough points to cover the reward’s points_cost
For flexible rewards, points is required and must be between the reward’s configured minimum and maximum

Response

Returns 201 Created. The discount_code is the generated Shopify discount code for the customer to use, and expires_at is when that code stops working (null when the reward has no expiry configured). For flexible rewards, reward_name reflects the resolved discount (for example £2.50 off your order) and points_spent is the number of points the customer chose. The response carries loyalty_mode and currency. points_spent is a minor-unit amount on store-credit shops, where the response also includes a credit_spent companion (a major-unit decimal string) that is absent in points mode. See Loyalty modes.

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

const response = await fetch(
  "https://api.mageloyalty.com/v1/rewards/reward_abc/purchase",
  {
    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/rewards/reward_abc/purchase",
    headers={"Authorization": "<api-key>"},
    json={"customer_identifier": "6789012345"},
)

data = response.json()

<?php
$ch = curl_init("https://api.mageloyalty.com/v1/rewards/reward_abc/purchase");
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": "reward_history_entry",
    "id": "cr_abc123",
    "attributes": {
      "reward_id": "reward_abc",
      "reward_name": "£5 off your next order",
      "reward_discount_type": "fixed",
      "points_spent": 500,
      "loyalty_mode": "points",
      "currency": "GBP",
      "discount_code": "MAGE-XYZ789",
      "status": "active",
      "expires_at": "2024-07-01T00:00:00.000Z"
    }
  }
}

{
  "data": {
    "type": "reward_history_entry",
    "id": "cr_abc123",
    "attributes": {
      "reward_id": "reward_flex",
      "reward_name": "£2.50 off your order",
      "reward_discount_type": "fixed",
      "points_spent": 250,
      "loyalty_mode": "store_credit",
      "currency": "GBP",
      "credit_spent": "2.50",
      "discount_code": "MAGE-XYZ789",
      "status": "active",
      "expires_at": "2024-07-01T00:00:00.000Z"
    }
  }
}

{
  "errors": [
    {
      "status": "403",
      "title": "Forbidden",
      "detail": "This reward cannot be redeemed in store credit mode"
    }
  ]
}

{
  "errors": [
    {
      "status": "400",
      "title": "Bad Request",
      "detail": "Entry rewards cannot be purchased"
    }
  ]
}

{
  "errors": [
    {
      "status": "403",
      "title": "Forbidden",
      "detail": "Customer is not eligible for this reward"
    }
  ]
}

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

{
  "errors": [
    {
      "status": "422",
      "title": "Insufficient Points",
      "detail": "Customer has 200 points but this reward costs 500"
    }
  ]
}

{
  "errors": [
    {
      "status": "422",
      "title": "Invalid Points",
      "detail": "Minimum redemption is 100 points"
    }
  ]
}

{
  "errors": [
    {
      "status": "500",
      "title": "Internal Server Error",
      "detail": "Failed to create discount code. Points have not been deducted."
    }
  ]
}

Errors

Status	Scenario
`400`	`customer_identifier` missing, invalid JSON, the reward is an entry reward (`Entry rewards cannot be purchased`), or `points` is missing for a flexible reward (`points is required for flexible rewards`)
`403`	Customer is excluded from the loyalty program, not on the required VIP tier (`Customer is not eligible for this reward`), or the shop runs on store credit and the reward is not flexible (`This reward cannot be redeemed in store credit mode`)
`404`	Customer or reward not found
`422`	Customer does not have enough points (`Customer has X points but this reward costs Y`), or `points` is outside a flexible reward’s range (`Minimum redemption is X points` / `Maximum redemption is X points`). On store-credit shops these amounts are formatted as money, for example `Minimum redemption is £1.00`
`500`	The discount code could not be generated. The points are refunded (`Failed to create discount code. Points have not been deducted.`)
`503`	Unable to connect to Shopify to generate the discount code

List rewards VIP tier object

REST API

API Resources

Webhook Events

Shopify Metafields

Request body

Validations

Response

Errors

​Request body

​Validations

​Response

​Errors

Request body

Validations

Response

Errors