Skip to main content
POST
/
v1
/
earning-rules
/
{id}
/
award
Award an earning rule
curl --request POST \
  --url https://api.mageloyalty.com/v1/earning-rules/{id}/award \
  --header 'Authorization: <api-key>'
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

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

​
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

​
Side effects

All non-blocking:
  • Creates a CustomerEarningRule record with points awarded (or pending if approval_time > 0)
  • Logs the activity
  • Syncs customer to Klaviyo, Omnisend, and Postscript
  • Syncs Shopify metafields for the customer

​
Response

Returns 201 Created: 
{
  "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,
      "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"
    }
  }
}
When approval_time > 0 is configured on the rule, status will be pending, points_given_at will be null, and points_due_at will reflect when the points will be approved.

​
Errors

StatusScenario
400customer_identifier missing or invalid JSON
403Customer is excluded from the loyalty program
404Customer or earning rule not found (or rule is inactive)
409Customer has already been awarded points for this earning rule
422Earning rule category cannot be awarded via the API