Example of GraphQL API usage. Placing an order with the Reward Points + Referral program module
To use GraphQL it is mandatory to install module Rewards GraphQL. Read how to set it up in Prerequisites.
In addition to REST architecture and SOAP protocol Magento offers for API a GraphQL. It is an open-source data query and manipulation language, released in 2015 by Facebook.
It has such advantage as getting only the needed parameters of the object in store without the any unnecessary connected information. GraphQL queries also execute quicker than similar on REST or SOAP. Request with REST or SOAP can require several queries, while request in GraphQL executes in one query.
Here is an example of using GraphQL queries to place an order when using.
GraphQL in Magento
GraphQL query retrieves data from the Magento server similarly as a REST GET call. The current set of Magento GraphQL queries allow a mobile app or browser to render such information:
-
A set of products to be displayed. This can include the entire catalog, or those that match customer-specified criteria.
-
Customer data. With a customer token, a query can retrieve basic information about a customer as well as billing and shipping addresses, wish lists, order history, and other sensitive data.
-
Shopping cart contents. GraphQL supports both guest and logged-in customer carts.
- Store configuration values, including the theme and CMS settings, the currency code, and supported countries.
Over time, the Magento GraphQL queries will duplicate the functionality of all storefront-facing GET calls, while making it possible to query more data in one request. The main difference will be that GraphQL will support storefront use cases, while REST will support admin use cases.
Magento will not run a query that is too complex. The number of fields, objects, and nodes are the factors in determining the complexity of a query.
Software to access GraphQL
In order to be able to use GraphQL you need an additional software. It can be a GraphQL IDE, like GraphiQL or an extension for a Chrome browser, like ChromeiQL or Altair GraphQL. The latter is also available for Mozilla Firefox.
To begin exploring GraphQL, set in the URL bar of your IDE or extension the GraphQL endpoint by entering http://your-magento2-server-adress/graphql. Check that the POST method is selected.
In this example Altair GraphQL browser extension is used.
Using GraphQL to place an order with the Reward Points module
Let's place an order with reward points of our module for a default Magento user Veronica Costello.
Prerequisites
In order to begin placing order using GraphQL the following preconditions must be completed:
-
Your store should have installed module Rewards GraphQL. It is not available separately, but it can be installed after the purchase of Reward Points + Referral program module. After you have installed this module, open command line interface and go to the directory with your Magento setup.
Run command
composer require mirasvit/module-rewards-graph-qland after it finishes activate Rewards GraphQl module with commandbin/magento module:enable Mirasvit_RewardsGraphQl. In the end runbin/magento setup:upgradeotherwise you will get an error or blank screen -
The customer should be registered and logged in, as the module doesn't work with guest customers
-
You should have at least one configured and enabled Payment method: Stores > Settings > Configuration > Sales > Payment Methods
-
You should have at least one configured and enabled Shipping method: Stores > Settings > Configuration > Sales > Shipping Methods. Skip this requirement for virtual quotes. Your store can have no Shipping method option, use option Delivery method
-
Your customer should have points on his account. Check the points balance: Customers > All customers
- Configure a Spending rule according to your requirements. Go to Marketing > Promotions > Reward Points and click on Earning Rules to call
out the menu where you'll find Spending Rules. Information about parameters of Spending rule is available on Spending Rules page.
Examples of Spending Rules are available on page Spending Rules Examples
Creating cart, adding item, setting shipping and billing address, shipping method
Step 1: Get customer's authorization token
To be able to use GraphQL on behalf of the chosen user firstly you should get this customer's authorization token. Read more on authorization tokens in official Magento Developer Documentation on page Authorization tokens.
By default, a customer token is valid for 1 hour. You can change these values from Admin by selecting Stores > Settings > Configuration > Services > OAuth > Access Token Expiration > Customer Token Lifetime
For generating the token a mutation keyword is used. While GraphQL queries perform read operations, mutations change the data. 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. More on the mutations read in Magento Developer Documentation (Magento DevDocs) on page Using mutations
Send request:
mutation {
generateCustomerToken(
email: "[email protected]"
password: "[email protected]"
) {
token
}
}You will get response:
{
"data": {
"generateCustomerToken": {
"token": "ebsvrn1t4rd4hj31zou6kjbx2babuuqk"
}
}
}
Copy the token, and add it to the header.
Step 2: Create a customer cart
The customer for whom the token has been generated does not have an active cart. The following query creates an empty cart and returns the cart ID.
Send request:
{
customerCart {
id
}
}
You will get response:
{
"data": {
"customerCart": {
"id": "1pFmurBFkwozlAtssXLK9k8jgM3qagtZ"
}
}
}
Step 3. Adding specific product to cart
When we know customer's cart ID, we can add an item to this cart. GraphQL supports all product types, but this tutorial only demonstrates how to add a simple product to the shopping cart. You can find more details how to add other product types on the following pages of Magento DevDocs:
Send request with cart_id value equal to id value obtained in a previous step. Parameter SKU is the identifier of the simple product you want to add to the cart. You can obtain SKU on the product page.
Request:
mutation {
addSimpleProductsToCart(
input: {
cart_id: "1pFmurBFkwozlAtssXLK9k8jgM3qagtZ"
cart_items: [{ data: { quantity: 1, sku: "24-MB04" } }]
}
) {
cart {
items {
id
product {
sku
stock_status
}
quantity
}
}
}
}Response:
{
"data": {
"addSimpleProductsToCart": {
"cart": {
"items": [
{
"id": "5",
"product": {
"sku": "24-MB04",
"stock_status": "IN_STOCK"
},
"quantity": 1
}
]
}
}
}
}
Now previously empty cart has new item, and user can see it in his account.
Step 4. Setting the shipping address
The shipping address is the address where customer wants to receive the items ordered. To set a shipping address for the user a setShippingAddressesOnCart mutation. Its full parameters are available in Magento DevDocs on page setShippingAddressesOnCart mutation
Skip this step for the virtual quotes.
Send request:
mutation {
setShippingAddressesOnCart(
input: {
cart_id: "1pFmurBFkwozlAtssXLK9k8jgM3qagtZ"
shipping_addresses: [
{
address: {
firstname: "Veronica"
lastname: "Costello"
company: "Company Name"
street: ["3320 N Crescent Dr", "Beverly Hills"]
city: "Los Angeles"
region: "CA"
region_id: 12
postcode: "90210"
country_code: "US"
telephone: "123-456-0000"
save_in_address_book: false
}
}
]
}
) {
cart {
shipping_addresses {
firstname
lastname
company
street
city
region {
code
label
}
postcode
telephone
country {
code
label
}
available_shipping_methods {
carrier_code
carrier_title
method_code
method_title
}
}
}
}
}You will get response
{
"data": {
"setShippingAddressesOnCart": {
"cart": {
"shipping_addresses": [
{
"firstname": "Veronica",
"lastname": "Costello",
"company": "Company Name",
"street": [
"3320 N Crescent Dr",
"Beverly Hills"
],
"city": "Los Angeles",
"region": {
"code": "CA",
"label": "California"
},
"postcode": "90210",
"telephone": "123-456-0000",
"country": {
"code": "US",
"label": "US"
},
"available_shipping_methods": [
{
"carrier_code": "flatrate",
"carrier_title": "Flat Rate",
"method_code": "flatrate",
"method_title": "Fixed"
},
{
"carrier_code": "tablerate",
"carrier_title": "Best Way",
"method_code": "bestway",
"method_title": "Table Rate"
}
]
}
]
}
}
}
}
The new shipping adress will be visible when order will be placed.
Step 5. Setting the billing address
The folowing step of setting the billing address is similar to the setting of shipping address.
Request:
mutation {
setBillingAddressOnCart(
input: {
cart_id: "1pFmurBFkwozlAtssXLK9k8jgM3qagtZ"
billing_address: {
address: {
firstname: "Veronica"
lastname: "Costello"
company: "Company Name"
street: ["64 Strawberry Dr", "Beverly Hills"]
city: "Los Angeles"
region: "CA"
region_id: 12
postcode: "90210"
country_code: "US"
telephone: "123-456-0000"
save_in_address_book: true
}
}
}
) {
cart {
billing_address {
firstname
lastname
company
street
city
region {
code
label
}
postcode
telephone
country {
code
label
}
}
}
}
}Response
{
"data": {
"setBillingAddressOnCart": {
"cart": {
"billing_address": {
"firstname": "Veronica",
"lastname": "Costello",
"company": "Company Name",
"street": [
"64 Strawberry Dr",
"Beverly Hills"
],
"city": "Los Angeles",
"region": {
"code": "CA",
"label": "California"
},
"postcode": "90210",
"telephone": "123-456-0000",
"country": {
"code": "US",
"label": "US"
}
}
}
}
}
}
Step 6. Set shipping method
Request
mutation {
setShippingMethodsOnCart(
input: {
cart_id: "1pFmurBFkwozlAtssXLK9k8jgM3qagtZ"
shipping_methods: [{ carrier_code: "flatrate", method_code: "flatrate" }]
}
) {
cart {
shipping_addresses {
selected_shipping_method {
carrier_code
method_code
carrier_title
method_title
}
}
}
}
}Responce
{
"data": {
"setShippingMethodsOnCart": {
"cart": {
"shipping_addresses": [
{
"selected_shipping_method": {
"carrier_code": "flatrate",
"method_code": "flatrate",
"carrier_title": "Flat Rate",
"method_title": "Fixed"
}
},
{
"selected_shipping_method": null
}
]
}
}
}
}
Step 7. Check the order
After the order details and shipping and billing adresses have been set check the order.
Request
{
customerCart {
id
items {
id
product {
name
sku
}
quantity
}
prices {
discount {
label
amount {
value
}
}
subtotal_excluding_tax {
value
}
applied_taxes {
label
amount {
value
}
}
grand_total {
value
}
}
mstRewardPoints {
is_applied
spend_points
base_spend_amount {
value
}
spend_amount {
value
}
spend_min_points
spend_max_points
earn_points
}
}
}Result
{
"data": {
"customerCart": {
"id": "1pFmurBFkwozlAtssXLK9k8jgM3qagtZ",
"items": [
{
"id": "5",
"product": {
"name": "Strive Shoulder Pack",
"sku": "24-MB04"
},
"quantity": 1
}
],
"prices": {
"discount": null,
"subtotal_excluding_tax": {
"value": 32
},
"applied_taxes": [],
"grand_total": {
"value": 37
}
},
"mstRewardPoints": {
"is_applied": false,
"spend_points": 0,
"base_spend_amount": {
"value": 0
},
"spend_amount": {
"value": 0
},
"spend_min_points": 10,
"spend_max_points": 35,
"earn_points": 0
}
}
}
}
Apply reward points to the order
Step 8. Add reward points to the cart
On this step add to the cart the desired number of reward points. Discoint to the order will be applied accordingly to the Spending rule.
Request
mutation {
mstRewardsApplyPointsToCart(
input: { cart_id: "1pFmurBFkwozlAtssXLK9k8jgM3qagtZ", amount: 10 }
) {
cart {
prices {
grand_total {
value
currency
}
}
mstRewardPoints {
is_applied
spend_points
base_spend_amount {
value
}
spend_amount {
value
}
spend_min_points
spend_max_points
earn_points
}
}
}
}Response
{
"data": {
"mstRewardsApplyPointsToCart": {
"cart": {
"prices": {
"grand_total": {
"value": 17.99,
"currency": "USD"
}
},
"mstRewardPoints": {
"is_applied": true,
"spend_points": 10,
"base_spend_amount": {
"value": 20
},
"spend_amount": {
"value": 20
},
"spend_min_points": 10,
"spend_max_points": 20,
"earn_points": 0
}
}
}
}
}
Finishing the order: getting and setting payment method, placing the order
Step 9. Get available payment methods
Check what payment methods are available to the current user.
Request
query {
cart(cart_id: "1pFmurBFkwozlAtssXLK9k8jgM3qagtZ") {
available_payment_methods {
code
title
}
}
}Response
{
"data": {
"cart": {
"available_payment_methods": [
{
"code": "checkmo",
"title": "Check / Money order"
}
]
}
}
}
Step 10. Set payment method
Choose one of the available payment methods obtained on the previous step and set this payment method for the current cart.
Request
mutation {
setPaymentMethodOnCart(
input: {
cart_id: "1pFmurBFkwozlAtssXLK9k8jgM3qagtZ"
payment_method: { code: "checkmo" }
}
) {
cart {
selected_payment_method {
code
}
}
}
}Response
{
"data": {
"setPaymentMethodOnCart": {
"cart": {
"selected_payment_method": {
"code": "checkmo"
}
}
}
}
}
Step 11. Place the order
Up to this moment all required steps for the order are complete and you can place the order. It can take a few minutes.
Request
mutation {
placeOrder(input: { cart_id: "1pFmurBFkwozlAtssXLK9k8jgM3qagtZ" }) {
order {
order_number
}
}
}Response
{
"data": {
"placeOrder": {
"order": {
"order_number": "000000003"
}
}
}
}
User can check his order with applied reward points
The user in his account will get a new order with the same order_number as in the previous step. He will be able to review order details as usual. This order will have reward points applied, and user will see the respective discount.
