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.