# Loyalty

When loyalty is enabled for a customer, he/she gets rewarded in points after making an order that meets the loyalty criteria. The points are stored in a read-only Customer attribute named loyalty_balance.

To determine if a customer has loyalty enabled or not, you can check the is_loyalty_enabled attribute on the customer object.

# Loyalty Transactions

For points to be earned, the Order must have a final price that's greater than or equal the loyaltyMinimumOrderPrice setting. In that case a Loyalty Transaction is created that cannot be redeemed unless a certain number of hours has passed since the order was uploaded to the server, the number of hours is stored in the loyaltyDelayInHours setting.

# Loyalty Rewards

After points are redeemed and the total customer points are greater than or equal the loyaltyRewardMinimum settings, customer gets a reward in the form of a discount.

# The Loyalty Transaction Object

# Sample

{
  "customer":
   {
    "id": "8f7bf6f9"
  },
  "order": {
    "id": "8f89b03"
  },
  "id": "8f89b03c",
  "amount": 118.75,
  "business_date": "2020-01-05",
  "redeemable_at": "2020-01-05 09:13:20",
  "is_redeemed": true,
  "returns": [
    "8f91a6e7",
    "8f91a6ff"
  ],
  "created_at": "2020-01-05 09:08:20",
  "updated_at": "2020-01-05 09:14:17"
}

# Attributes

Field	Type	Rule	Description
`id`	`string`		Unique identifier for the loyalty transaction
`business_date`	`string`		The business date of the loyalty transaction
`amount`	`double`		The net amount (see sample below)
`redeemable_at`	`string`		Time `YYYY-MM-DD HH-MM-SS` in UTC where the loyalty transaction will create a redeemable reward
`returns`	`array`	`nullable`	List of Order Return IDs that happened on the original order attached to the loyalty transaction
`is_redeemed`	`boolean`		True if loyalty transaction is redeemed, means it created a loyalty reward for the customer
`customer`	`object`	`includable`	The Customer who attached to the loyalty transaction
`order`	`object`	`includable`	The Order that resulted in the loyalty transaction
`created_at`	`string`	`sortable`	Time `YYYY-MM-DD HH-MM-SS` in UTC at which the object was created.
`updated_at`	`string`	`sortable`	Time `YYYY-MM-DD HH-MM-SS` in UTC at which the object was updated.

Sample on amount:

original order final price = 100

loyalty transaction amount = 100

Customer made a return within allowed return period

Return amount = 40

New loyalty transaction amount = 100 - 40 = 60

# List Loyalty Transactions

GET /loyalty_transactions

# Scope

customers.loyalty.read

# Filters

customer_id
order_id
updated_after

# Response

{
  "data": [
    {
      "customer": {
        "id": "8f7bf6f9"
      },
      "order": {
        "id": "8f89b03"
      },
      "id": "8f89b03c",
      "amount": 118.75,
      "business_date": "2020-01-05",
      "redeemable_at": "2020-01-05 09:13:20",
      "is_redeemed": true,
      "returns": [
        "8f91a6e7",
        "8f91a6ff"
      ],
      "created_at": "2020-01-05 09:08:20",
      "updated_at": "2020-01-05 09:14:17"
    }
  ]
}

# Get Loyalty Transaction

GET /loyalty_transactions/{loyaltyTransactionId}

# Scope

customers.loyalty.read

# Response

{
  "data": {
    "customer": {
      "id": "8f7bf6f9"
    },
    "order": {
      "id": "8f89b03"
    },
    "id": "8f89b03c",
    "amount": 118.75,
    "business_date": "2020-01-05",
    "redeemable_at": "2020-01-05 09:13:20",
    "is_redeemed": true,
    "returns": [
      "8f91a6e7",
      "8f91a6ff"
    ],
    "created_at": "2020-01-05 09:08:20",
    "updated_at": "2020-01-05 09:14:17"
  }
}

# The Loyalty Reward Object

# Sample

{
  "customer": {
    "id": "8f7bf6f9"
  },
  "order": {
    "id": "8f91a4e8"
  },
  "id": "8f89b25c",
  "type": 1,
  "valid_to": "2021-01-04",
  "amount": 15,
  "maximum_discount_amount": 20,
  "code": "MOW4V4",
  "created_at": "2020-01-05 09:14:17",
  "updated_at": "2020-01-05 09:14:17"
}

# Attributes

Field	Type	Rule	Description
`id`	`string`		Unique identifier for the loyalty reward
`type`	`integer`		The type of discount (1: Percentage, 2: Fixed amount)
`valid_to`	`string`		The last date where the loyalty reward can be used
`amount`	`double`		The discount amount
`maximum_discount_amount`	`double`		The maximum allowed discount amount
`code`	`string`		The unique reward code used when redeeming reward
`customer`	`object`	`includable`	The Customer who owns the loyalty reward
`order`	`object`	`nullable` `includable`	The Order that the reward was used in
`created_at`	`string`	`sortable`	Time `YYYY-MM-DD HH-MM-SS` in UTC at which the object was created.
`updated_at`	`string`	`sortable`	Time `YYYY-MM-DD HH-MM-SS` in UTC at which the object was updated.

# List Loyalty Rewards

GET /loyalty_rewards

# Scope

customers.loyalty.read

# Filters

customer_id
order_id
updated_after

# Response

{
  "data": [
    {
      "customer": {
        "id": "8f7bf6f9"
      },
      "order": {
        "id": "8f91a4e8"
      },
      "id": "8f89b25c",
      "type": 1,
      "valid_to": "2021-01-04",
      "amount": 15,
      "maximum_discount_amount": 20,
      "code": "MOW4V4",
      "created_at": "2020-01-05 09:14:17",
      "updated_at": "2020-01-05 09:14:17"
    }
  ]
}

# Get Loyalty Reward

GET /api/loyalty_rewards/{loyaltyRewardId}

# Scope

customers.loyalty.read

# Response

{
  "data": {
    "customer": {
      "id": "8f7bf6f9"
    },
    "order": {
      "id": "8f91a4e8"
    },
    "id": "8f89b25c",
    "type": 1,
    "valid_to": "2021-01-04",
    "amount": 15,
    "maximum_discount_amount": 20,
    "code": "MOW4V4",
    "created_at": "2020-01-05 09:14:17",
    "updated_at": "2020-01-05 09:14:17"
  }
}

# Update Loyalty Reward

GET /api/loyalty_rewards/{loyaltyRewardId}

# Scope

customers.loyalty.write

# Request

{
  "order_id": "8f91a4e8"
}

# Response

{
  "data": {
    "customer": {
      "id": "8f7bf6f9"
    },
    "order": {
      "id": "8f91a4e8"
    },
    "id": "8f89b25c",
    "type": 1,
    "valid_to": "2021-01-04",
    "amount": 15,
    "maximum_discount_amount": 20,
    "code": "MOW4V4",
    "created_at": "2020-01-05 09:14:17",
    "updated_at": "2020-01-05 09:14:17"
  }
}

← House Account Transactions Menu Display →