Skip to main content
POST
/
v1
/
rewards
/
{id}
/
purchase
Purchase a reward
curl --request POST \
  --url https://api.mageloyalty.com/v1/rewards/{id}/purchase \
  --header 'Authorization: <api-key>'

Documentation Index

Fetch the complete documentation index at: https://developers.mageloyalty.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Request body

FieldTypeRequiredDescription
customer_identifierstringYesShopify customer ID or email address
{
  "customer_identifier": "6789012345"
}

​
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

​
Side effects

All non-blocking:
  • Generates a Shopify discount code
  • Deducts points from the customer using FIFO logic
  • Creates an activity log entry
  • Fires Klaviyo, Omnisend, and Postscript reward-redeemed events
  • Syncs Shopify metafields for the customer

​
Response

Returns 201 Created: 
{
  "data": {
    "type": "reward_history_entry",
    "id": "cr_abc123",
    "attributes": {
      "reward_id": "reward_abc",
      "reward_name": "£5 off your next order",
      "reward_discount_type": "fixed_amount",
      "points_spent": 500,
      "discount_code": "MAGE-XYZ789",
      "status": "active",
      "is_refunded": false,
      "discount_code_redeemed_at": null,
      "redeemed_at": null,
      "expires_at": "2024-07-01T00:00:00.000Z",
      "created_at": "2024-06-01T12:00:00.000Z",
      "updated_at": "2024-06-01T12:00:00.000Z"
    }
  }
}

​
Errors

StatusScenario
400customer_identifier missing or invalid JSON
403Customer is excluded, or not on the required VIP tier
404Customer or reward not found
422Insufficient points
503Unable to connect to Shopify to generate the discount code
Example 422 response: 
{
  "errors": [
    {
      "status": "422",
      "title": "Insufficient Points",
      "detail": "Customer has 200 points but this reward costs 500"
    }
  ]
}