Reward Points + Referral program
v3.2.9

GraphQL Objects Reference

The full documentation on GraphQL is available on Magento DevDocs page GraphQL Developer Guide

To use GraphQL in the Reward Points + Referral program module it is mandatory to install Rewards GraphQl module.

Cart object

One of the standard Magento 2 objects is Cart object. The cart is responsible for:

  • tracking each item in the cart
  • tracking item's quantity
  • tracking base cost
  • determining estimated shipping costs
  • calculating subtotals
  • computing additional costs
  • applying coupons
  • determining the payment method

Our module expands Cart object with Reward Points using attribute mstRewardPoints.

The Cart object can contain the following attributes.

Attribute Data Type Description
mstRewardPoints CartPoints Reward points information for cart

Here is the GraphQL request to check Reward points of a new empty cart of a chosen user

query {
    customerCart {
        id
        mstRewardPoints {
            is_applied
            spend_points
            base_spend_amount {
                value
            }
            spend_amount {
                value
            }
            spend_min_points
            spend_max_points
            earn_points
        }
    }
}

Response

{
  "data": {
    "customerCart": {
      "id": "7FaFEP6tXE2SpPULMt4X2JQnImx3MwwS",
      "mstRewardPoints": {
        "is_applied": false,
        "spend_points": null,
        "base_spend_amount": {
          "value": null
        },
        "spend_amount": {
          "value": null
        },
        "spend_min_points": null,
        "spend_max_points": null,
        "earn_points": null
      }
    }
  }
}

CartPoints object

The parameters of the reward points information for a cart from the query response above can be deciphered by the attributes of the CartPoints object.

The CartPoints object can contain the following attributes

Attribute Data Type Description
is_applied Boolean .
spend_points Int The number of points that were added to the cart.
base_spend_amount Money Based Amount of money that was added to the cart.
spend_amount Money the Amount of money that was added to the cart.
spend_min_points Int Min number of points that could be added to the cart.
spend_max_points Int Max number of points that could be added to the cart.
earn_points Int The number of points that were added to the cart.

Attributes base_spent_amount and spend_amount each have two fields: value and currency.

Request

query {
    customerCart {
        id
        mstRewardPoints {
            is_applied
            spend_points
            earn_points
            base_spend_amount {
                value
                currency
            }
            spend_amount {
                value
                currency
            }
            spend_min_points
            spend_max_points
            earn_points
        }
    }
}

Response

{
  "data": {
    "customerCart": {
      "id": "7FaFEP6tXE2SpPULMt4X2JQnImx3MwwS",
      "mstRewardPoints": {
        "is_applied": true,
        "spend_points": 10,
        "earn_points": null,
        "base_spend_amount": {
          "value": null,
          "currency": null
        },
        "spend_amount": {
          "value": null,
          "currency": null
        },
        "spend_min_points": null,
        "spend_max_points": null
      }
    }
  }
}

Customer object

This is another standard Magento object. The customer query returns information about the logged-in customer, store credit history and customer’s wishlist.

To return or modify information about a customer, Magento recommends you use customer authorisation tokens in the header of your GraphQL calls.

This module expands Customer object with Rewards Balance using attribute mstRewardPointsBalance.

The Customer object can contain the following attributes

Attribute Data Type Description
mstRewardPointsBalance RewardsCustomerInfo Reward points information for customer

Here is how to look at the account information of currently logged in customer for which GraphQL session is conducted. The responce will show user's first and last name, e-mail, shipping and billing addresses, phone numbers, etc. The rewards balance, user's reward tier and list of rewards transactions are also available.

Request

query {
    customer {
        mstRewardPointsBalance {
            balance
        }

        firstname
        lastname
        suffix
        email
        addresses {
            firstname
            lastname
            street
            city
            region {
                region_code
                region
            }
            postcode
            country_code
            telephone
        }
    }
}

Response

{
  "data": {
    "customer": {
      "mstRewardPointsBalance": {
        "balance": 90
      },
      "firstname": "Veronica",
      "lastname": "Costello",
      "suffix": null,
      "email": "[email protected]",
      "addresses": [
        {
          "firstname": "Veronica",
          "lastname": "Costello",
          "street": [
            "6146 Honey Bluff Parkway"
          ],
          "city": "Calder",
          "region": {
            "region_code": "MI",
            "region": "Michigan"
          },
          "postcode": "49628-7978",
          "country_code": "US",
          "telephone": "(555) 229-3326"
        },
        {
          "firstname": "Veronica",
          "lastname": "Costello",
          "street": [
            "64 Strawberry Dr",
            "Beverly Hills"
          ],
          "city": "Los Angeles",
          "region": {
            "region_code": "CA",
            "region": "California"
          },
          "postcode": "90210",
          "country_code": "US",
          "telephone": "123-456-0000"
        }
      ]
    }
  }
}

RewardsCustomerInfo object

It contains the customer's reward points information like current balance of the points, spent points, transactions in which those points were spent, etc.

The RewardsCustomerInfo object can contain the following attributes

Attribute Data Type Description
balance Int number of points available for customer
tier_id Int Customer's tier in reward program
transactions [PointsTransaction] List of transactions and their parameters. It is mandatory to specify its fields.

Request

query {
    customer {
        mstRewardPointsBalance {
            balance
            tier_id
            transactions {
                transaction_id
                created_at
            }
        }

        firstname
        lastname
        addresses {
            street
            city
            region {
                region
            }
            postcode
            country_code
        }
    }
}

Response

{
  "data": {
    "customer": {
      "mstRewardPointsBalance": {
        "balance": 90,
        "tier_id": 1,
        "transactions": [
          {
            "transaction_id": 1,
            "created_at": "2021-02-26 12:40:43"
          },
          {
            "transaction_id": 2,
            "created_at": "2021-03-01 11:38:19"
          }
        ]
      },
      "firstname": "Veronica",
      "lastname": "Costello",
      "addresses": [
        {
          "street": [
            "6146 Honey Bluff Parkway"
          ],
          "city": "Calder",
          "region": {
            "region": "Michigan"
          },
          "postcode": "49628-7978",
          "country_code": "US"
        },
        {
          "street": [
            "64 Strawberry Dr",
            "Beverly Hills"
          ],
          "city": "Los Angeles",
          "region": {
            "region": "California"
          },
          "postcode": "90210",
          "country_code": "US"
        }
      ]
    }
  }
}

PointsTransaction object

The transactions (PointsTransaction object) can contain the following fields regarding reward points transactions

Field Data Type Description
transaction_id Int ID of the specific transaction in user's account
created_at String Time when transaction was created
activated_at String Time when transaction will be activated
amount Int Amount of earned points
amount_used Int Amount of spent points
code String Transaction code
comment String Transaction description
is_activated Boolean Is transaction activated
is_expiration_email_sent Boolean Is expiration email was sent to customer
is_expired Boolean Is transaction expired

Request

query {
    customer {
        mstRewardPointsBalance {
            balance
            tier_id
            transactions {
                transaction_id
                created_at
                amount
                amount_used
                activated_at
                code
                comment
                is_activated
                is_expiration_email_sent
                is_expired
            }
        }

        firstname
        lastname
        addresses {
            street
            city
            region {
                region
            }
            postcode
            country_code
        }
    }
}

Response

{
  "data": {
    "customer": {
      "mstRewardPointsBalance": {
        "balance": 90,
        "tier_id": 1,
        "transactions": [
          {
            "transaction_id": 1,
            "created_at": "2021-02-26 12:40:43",
            "amount": 100,
            "amount_used": null,
            "activated_at": null,
            "code": "",
            "comment": null,
            "is_activated": true,
            "is_expiration_email_sent": false,
            "is_expired": false
          },
          {
            "transaction_id": 2,
            "created_at": "2021-03-01 11:38:19",
            "amount": -10,
            "amount_used": null,
            "activated_at": null,
            "code": "order_spend-5",
            "comment": "Spent 10 Reward Points for the order #000000005.",
            "is_activated": true,
            "is_expiration_email_sent": false,
            "is_expired": false
          }
        ]
      },
      "firstname": "Veronica",
      "lastname": "Costello",
      "addresses": [
        {
          "street": [
            "6146 Honey Bluff Parkway"
          ],
          "city": "Calder",
          "region": {
            "region": "Michigan"
          },
          "postcode": "49628-7978",
          "country_code": "US"
        },
        {
          "street": [
            "64 Strawberry Dr",
            "Beverly Hills"
          ],
          "city": "Los Angeles",
          "region": {
            "region": "California"
          },
          "postcode": "90210",
          "country_code": "US"
        }
      ]
    }
  }
}

Mutation object

A mutation can create, update, or delete objects and fields. In REST terminology, queries operate like GET requests, while mutations are similar to POST, PUT, and DELETE.

A mutation contains the following elements:

  • The keyword mutation
  • An operation name for your local implementation. This name is required if you include variables. Otherwise, it is optional.
  • The mutation name
  • The input object or attributes. Most mutations require an input object that contains data or individual attributes for the Magento server to process. However, some mutations, such as createEmptyCart, do not require an input object.
  • The output object, which specifies which data the mutation returns.

The Mutation object in this module can contain the following attributes.

Attribute Data Type Description
mstRewardsApplyPointsToCart ApplyPointsToCartInput Add reward points to the cart

To set a number of reward points to the current cart the following mutation of mstRewardsApplyPointsToCart method is used. This method requires two parameters: cart_id and amount of applied points.

ApplyPointsToCartInput object

It defines the input object of the applyToCart mutation.

The mstRewardsApplyPointsToCart object can contain the following attributes.

Attribute Data Type Description
amount Int The number of reward points
cart_id String! The unique ID that identifies the customer's cart

Request

mutation {
    mstRewardsApplyPointsToCart(
        input: { cart_id: "7FaFEP6tXE2SpPULMt4X2JQnImx3MwwS", amount: 10 }
    ) {
        cart {
            prices {
                grand_total {
                    value
                    currency
                }
            }
            mstRewardPoints {
                is_applied
                spend_points
            }
        }
    }
}

Response

{
  "data": {
    "mstRewardsApplyPointsToCart": {
      "cart": {
        "prices": {
          "grand_total": {
            "value": 0,
            "currency": "USD"
          }
        },
        "mstRewardPoints": {
          "is_applied": true,
          "spend_points": 10
        }
      }
    }
  }
}

ApplyPointsToCartOutput object

This object shows the result of the mutations above which were applied to cart. It does not make any mutations by itself.

The ApplyPointsToCartOutput object returns data with the following attributes

Attribute Data Type Description
cart Cart! Describes the contents of the specified shopping cart.

In the above mutation request it is the following part of code (this piece will work only inside a code above)

 {
        cart {
            prices {
                grand_total {
                    value
                    currency
                }
            }
            mstRewardPoints {
                is_applied
                spend_points
            }
        }
    }
}

The ApplyPointsToCartOutput prints out those parameters that are applied to the cart, which allows you to check if mstRewardsApplyPointsToCart worked correctly.