# 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`	Point Allotment 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 increase or decrease in point value of the point balance
`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`	Point Allotment Type	The internal easyPoints type of the incoming data
`point_balance_uid`	String	The easyPoints uid representing the point balance
`allotment_cascade`	Boolean \| null	Whether this allotment was a cascade belonging to a larger easyPoints action (i.e. orders with multiple allotments)
`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`	Point Allotment Type	Selects only point allotments with the specified point allotment 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 increase or decrease in point value of the point balance
`inserted_at`	String	The current datetime when this customer's points will expire (ISO8601 format)
`type`	Point Allotment Type	The internal easyPoints point allotment 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

The allotment reason will be visible on the admin dashboard

Key	Type	Definition
`reason`	Allotment Reason	A meaningful reason for this allotment

# Returns

This route returns the following data:

Key	Type	Definition
`uid`	String	The EasyPoints ID of the point allotment
`point_value`	Integer	The increase or decrease in point value of the point balance
`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",
  "reason": {
    "type": "test_allotment"
  }
}'

{
  "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"}]}

# Point Allotment 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...)

# Allotment Reason

The allotment reason JSON object is of form:

Key	Type	Definition
`type`	Allotment Reason Type	The reason type of the allotment
`note`	String \| null	Any string (max 255 characters) with more context attached to this reason

# Allotment Reason Types

Type	Meaning
`compensation`	Allotment made for compensation
`coupon`	Allotment made due to a coupon
`expiration`	Allotment to expire points
`fulfillment`	Allotment awarded upon the fulfillment of an order
`refund`	Allotment deducted due to the refund of an order
`reward`	Allotment awarded through reward features such as birthdays or signups
`system_fix`	Allotment made to correct system errors or inconsistencies
`test_allotment`	Allotment for testing purposes

← Point Balances Order History →