# Point Allotments

# Fetching all Point Allotments

# Route

Use the following GET route to get all point allotments of a store.

GET https://loyalty.slrs.io/api/shopify/point_allotments

# Arguments

This route is paginated.

# Required Parameters

None

# Optional Parameters

The following filters may be used:

Key Type Definition
type Type Selects only point allotments with the specified type
before Timestamp A ISO8601 timestamp, selects only point allotments alloted before this time
after Timestamp A ISO8601 timestamp, selects only point allotments alloted after this time

# Returns

This route returns an array of the following data

Key Type Definition
uid String The EasyPoints ID of the point allotment
point_value Integer The duration the shop waits until a customer's points expire (in months)
inserted_at String The datetime (ISO8601 format) when this allotment entered easyPoints
alloted_at String The datetime (ISO8601 format) when this allotment was fully processed by easyPoints
type Type The internal easyPoints type of the incoming data
point_balance_uid String The easyPoints uid representing the point balance
allotment_cascade Boolean null
app_reference String The source app for this allotment (easyPoints or Smapify)
object String Object assocaited with this allotment. (line_item, rewards, etc...)
parent String Parent item assocaited with this allotment. (order_number, point_story, etc...)
points_deducted Integer Points deducted from allotment

# Example

Example request and result:

curl -X GET \
 'https://loyalty.slrs.io/api/shopify/point_allotments' \
-H 'content-type: application/json' \
-H 'authorization: Basic ${API_CREDENTIALS}'
{
  "data": [
    {

      "action": "fulfillment-1",
      "allotment_cascade": null,
      "allotted_at": "2000-01-01T00:00:00.000000",
      "app_reference": "shopify_integration",
      "event_id": 1,
      "inserted_at": "2023-01-01T00:00:00.000000",
      "object": "line_item-1",
      "parent": "order-1",
      "point_balance_uid": "f715bfd4-de77-11ed-8597-787b8aae8c7a",
      "point_value": 100,
      "points_deducted": 0,
      "type": "fulfillment",
      "uid": "e94d0d42-df50-11ed-bb36-787b8aae8c7a"
    },
    {
      "action": null,
      "allotment_cascade": true,
      "allotted_at": "2023-01-01T00:00:00.000000",
      "app_reference": "shopify_integration",
      "event_id": null,
      "inserted_at": "2023-01-01T00:00:00.000000",
      "object": null,
      "parent": "point_story-2",
      "point_balance_uid": "f70bf33c-de77-11ed-9367-787b8aae8c7a",
      "point_value": 500,
      "points_deducted": 0,
      "type": "manual",
      "uid": "8a6e8036-e305-11ed-a715-787b8aae8c7a"
    }
  ]
}

# Fetching Point Allotments for a Customer

# Route

Use the following GET route to get all point allotments for a specific customer.

GET https://loyalty.slrs.io/api/shopify/point_allotments/:shopify_customer_id

The :shopify_customer_id references the customer's id on Shopify.

For example, in https://admin.shopify.com/store/{store_domain}/customers/1234567890, 1234567890 is the Shopify customer's id.

# Arguments

This route is paginated.

# Required Parameters

None

# Optional Parameters

The following filters may be used:

Key Type Definition
type Type Selects only point allotments with the specified type
before Timestamp A ISO8601 timestamp, selects only point allotments alloted before this time
after Timestamp A ISO8601 timestamp, selects only point allotments alloted after this time

# Returns

This route returns the following data:

Key Type Definition
uid String The EasyPoints ID of the point allotment
point_value Integer The duration the shop waits until a customer's points expire (in months)
inserted_at String The current datetime when this customer's points will expire (ISO8601 format)
type Type The internal easyPoints type of the incoming data
point_balance Point Balance Data from the point balance record.

# Example

Example request and result:

curl -X GET \
 'https://loyalty.slrs.io/api/shopify/point_allotments/1234567890' \
-H 'content-type: application/json' \
-H 'authorization: Basic ${API_CREDENTIALS}'
{
  "data": [
    {
      "action": "fulfillment-1",
      "allotment_cascade": null,
      "allotted_at": "2024-07-01T00:00:00.000000",
      "app_reference": "shopify_integration",
      "event_id": 1,
      "inserted_at": "2023-01-01T00:00:00.000000",
      "object": "line_item-1",
      "parent": "order-1",
      "point_balance_uid": "c5390700-74ce-4381-82a6-1eeac68219b5",
      "point_value": 250,
      "points_deducted": 0,
      "type": "fulfillment",
      "uid": "ed5a7554-c76c-4f82-98bd-83739fa0fd73"
    },
    {
      "action": null,
      "allotment_cascade": true,
      "allotted_at": "2024-07-15T00:00:00.000000",
      "app_reference": "shopify_integration",
      "event_id": null,
      "inserted_at": "2023-01-01T00:00:00.000000",
      "object": null,
      "parent": "point_story-2",
      "point_balance_uid": "c5390700-74ce-4381-82a6-1eeac68219b5",
      "point_value": 900,
      "points_deducted": 0,
      "type": "manual",
      "uid": "b6fdae8b-48b1-48b2-a08c-bb866e1cd195"
    }
  ]
}

# Creating a Point Allotment

# Route

Use the following POST route to create a point allotment of a single customer.

POST https://loyalty.slrs.io/api/shopify/point_allotments

# Arguments

# Required Arguments

Key Type Required Definition
customer_id String ✔️ The Shopify ID of the customer to receive the point allotment
point_value Integer ✔️ The amount of points to award (can be positive or negative)

# Optional Arguments

None

# Returns

This route returns the following data:

Key Type Definition
uid String The EasyPoints ID of the point allotment
point_value Integer The duration the shop waits until a customer's points expire (in months)
inserted_at String The current datetime when this customer's points will expire (ISO8601 format)
point_balance Point Balance Data from the point balance record

# Example

Example request and result:

curl -X POST \
 'https://loyalty.slrs.io/api/shopify/point_allotments' \
-H 'content-type: application/json' \
-H 'authorization: Basic ${API_CREDENTIALS}' \
-d '{
  "point_value": 200,
  "customer_id": "123"
}'
{
  "data": {
    "id": "36ce8920-4a65-11eb-98c6-000c291828e7",
    "inserted_at": "2020-12-30T06:06:53.000000",
    "point_balance": {
      "expiration_delay": 3,
      "expires_at": "2021-03-20T23:51:09.000000Z",
      "id": "123",
      "point_balance": 594
    },
    "point_value": 200
  }
}

When point allotment is successfully created but the point balance couldn't be fetched, we return a status 201 response with a result like below:

{
  "data": {
    "id": "36ce8920-4a65-11eb-98c6-000c291828e7",
    "inserted_at": "2020-12-30T06:06:53.000000",
    "point_value": 200
  }
}

# Error Responses

The following errors can be returned from the point allotment create endpoint:

{"errors": [{"status": "400", "title": "Point allotment would result in a negative balance"}]}
{"errors": [{"status": "404", "title": "Customer was not found"}]}

# Types

The possible types of a point allotment are as follows

Type Meaning
coupon_reimbursement Points returned due to a order cancellation
coupon_cancellation Points returned due to a deleted coupon
csv Point adjustments due to CSV import
deletion Points deleted
expiration Expired Points
manual Manual adjustments by a shop manager
refund Points subtracted due to an order cancellation/refund
api Points adjusted through the API
flow Points adjusted through Shopify Flow
fulfillment Points given at order fulfillment
tax Points rewarded for taxed purchases
reward Points given via reward features (birthday, signup, etc...)