Magento REST API and GraphQL — API Endpoints and Queries Guide

In this tutorial, you'll learn how to work with the Magento REST API and GraphQL endpoints to build integrations, automate store operations, and power headless commerce frontends.

What You'll Learn

• How REST API authentication works with tokens and OAuth
• Core REST endpoints for products, customers, orders, and categories
• How to perform GET, POST, PUT, and DELETE operations
• GraphQL query and mutation syntax for headless commerce
• How to build a simple integration with the Magento API

Why It Matters

Every modern e-commerce operation needs API integrations — for ERP systems, mobile apps, headless frontends, or automated inventory updates. Magento's REST API and GraphQL endpoints let you access every store function programmatically. Without API knowledge, you're limited to manual operations through the admin panel. With it, you can automate anything.

Real-World Use

A retail chain with 50 physical stores runs Magento as its central product catalog. Store managers need to update prices and stock levels from their point-of-sale system in real time. Using the REST API, the POS system sends PUT /V1/products/{sku} requests to update prices and POST /V1/inventory/source-items to adjust stock. A headless mobile app built with React uses GraphQL to fetch product data and submit orders.

Learning Path

flowchart LR
    A[Install Magento] --> B[Admin Dashboard]
    B --> C[Products & Categories]
    C --> D[REST API & GraphQL]
    D --> E[CLI Commands]
    D --> F[Caching & Performance]
    style D fill:#3b82f6,color:#fff

REST API Overview

The Magento REST API follows the standard REST architectural style. Every endpoint starts with /V1/ and returns JSON. You can access resources like products, customers, orders, categories, and carts.

Available Endpoints

Authentication

Before making any API call, you must authenticate. Magento supports two methods: token-based and OAuth 1.0a.

Token-Based Authentication

Token-based authentication is the simplest and most common approach. You send a POST request to the admin token endpoint with your credentials.

curl -X POST https://mystore.com/rest/V1/integration/admin/token \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your_password"}'

The response returns a token string. You include this token in all subsequent requests as a Bearer token in the Authorization header.

curl -X GET https://mystore.com/rest/V1/products/ \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json"

For customer authentication, use /V1/integration/customer/token instead.

OAuth 1.0a

OAuth 1.0a is more complex but doesn't require sending credentials with each request. You need a consumer key, consumer secret, access token, and token secret. This method is useful when third-party services need API access without sharing admin credentials.

GET Endpoints

GET requests retrieve data. They are read-only and safe to call multiple times.

Search Products

curl -X GET "https://mystore.com/rest/V1/products?searchCriteria[filterGroups][0][filters][0][field]=name&searchCriteria[filterGroups][0][filters][0][value]=Running%20Shoe&searchCriteria[filterGroups][0][filters][0][conditionType]=like" \
  -H "Authorization: Bearer YOUR_TOKEN"

The response contains the matching products along with pagination information:

{
  "items": [
    {
      "sku": "RS-100",
      "name": "Running Shoe Pro",
      "price": 129.99,
      "status": 1
    }
  ],
  "search_criteria": {
    "filter_groups": []
  },
  "total_count": 1
}

Get Customer Information

curl -X GET "https://mystore.com/rest/V1/customers/5" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Order History

curl -X GET "https://mystore.com/rest/V1/orders?searchCriteria[filterGroups][0][filters][0][field]=customer_id&searchCriteria[filterGroups][0][filters][0][value]=5&searchCriteria[filterGroups][0][filters][0][conditionType]=eq" \
  -H "Authorization: Bearer YOUR_TOKEN"

POST Endpoints

POST requests create new resources.

Create a Product

curl -X POST https://mystore.com/rest/V1/products \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product": {
      "sku": "TS-BLUE-001",
      "name": "Blue T-Shirt",
      "price": 24.99,
      "attribute_set_id": 4,
      "type_id": "simple",
      "extension_attributes": {
        "stock_item": {
          "qty": 100,
          "is_in_stock": true
        }
      }
    }
  }'

Add Item to Cart

First create an empty cart:

curl -X POST "https://mystore.com/rest/V1/carts/mine" \
  -H "Authorization: Bearer CUSTOMER_TOKEN" \
  -H "Content-Type: application/json"

Then add a product:

curl -X POST "https://mystore.com/rest/V1/carts/mine/items" \
  -H "Authorization: Bearer CUSTOMER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cartItem": {
      "sku": "TS-BLUE-001",
      "qty": 2,
      "quote_id": "QUOTE_ID"
    }
  }'

PUT and DELETE Endpoints

PUT updates existing resources. DELETE removes them.

Update a Product

curl -X PUT "https://mystore.com/rest/V1/products/TS-BLUE-001" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product": {
      "price": 29.99,
      "name": "Blue T-Shirt Premium"
    }
  }'

Delete a Product

curl -X DELETE "https://mystore.com/rest/V1/products/TS-BLUE-001" \
  -H "Authorization: Bearer YOUR_TOKEN"

GraphQL Introduction

GraphQL provides a single endpoint at /graphql where you send POST requests with a query string. Unlike REST, where you need multiple endpoints, GraphQL lets you request exactly the data you need in one call.

Basic GraphQL Query

{
  products(search: "running shoe") {
    items {
      sku
      name
      price {
        regularPrice {
          amount {
            value
            currency
          }
        }
      }
    }
  }
}

Send this as a POST request:

curl -X POST https://mystore.com/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"{ products(search: \"running shoe\") { items { sku name price { regularPrice { amount { value currency } } } } } }"}'

Categories Query

{
  category(id: 3) {
    name
    children {
      name
      product_count
    }
  }
}

Customer Cart Query

{
  customerCart {
    items {
      product {
        name
        sku
      }
      quantity
      prices {
        row_total {
          value
        }
      }
    }
    totals {
      grand_total {
        value
        currency
      }
    }
  }
}

GraphQL Mutations

Mutations modify data — they are the GraphQL equivalent of POST, PUT, DELETE.

Add Products to Cart

mutation {
  addProductsToCart(
    cartId: "CART_ID"
    cartItems: [
      {
        sku: "TS-BLUE-001"
        quantity: 2
      }
    ]
  ) {
    cart {
      items {
        product {
          name
          sku
        }
        quantity
      }
    }
  }
}

Place Order

mutation {
  placeOrder(input: { cart_id: "CART_ID" }) {
    order {
      order_id
      order_number
    }
  }
}

Create Customer

mutation {
  createCustomer(
    input: {
      firstname: "John"
      lastname: "Doe"
      email: "john@example.com"
      password: "SecurePass123!"
    }
  ) {
    customer {
      firstname
      lastname
      email
    }
  }
}

Headless Magento

Headless commerce separates the frontend from the backend. Magento serves as the backend engine, while the frontend is built with a JavaScript framework.

PWA Studio

Adobe's PWA Studio is the official tool for building headless Magento storefronts. It uses React and communicates with Magento through GraphQL. The studio provides a Venia theme as a starting point.

Vue Storefront and ScandiPWA

Vue Storefront is a popular alternative built with Vue.js. ScandiPWA is a React-based PWA that integrates with Magento out of the box. Both use the GraphQL API.

Benefits of Headless

Headless architecture gives you complete control over the frontend experience. You can build custom checkout flows, unique product pages, and integrate with content delivery networks without being limited by Magento's template system.

API Rate Limits

Magento does not have built-in Rate Limiting. You should implement rate limiting at the server level using Nginx or a web application firewall. For production systems, monitor API usage and set limits to prevent abuse.

limit_req_zone $binary_remote_addr zone=magento_api:10m rate=30r/s;

server {
    location /rest/ {
        limit_req zone=magento_api burst=50 nodelay;
    }
    location /graphql {
        limit_req zone=magento_api burst=20 nodelay;
    }
}

API Integration Tests

Always test API integrations in a staging environment first. Use tools like Postman or Insomnia to explore endpoints. Check response codes — 200 for success, 400 for bad requests, 401 for authentication errors, 404 for missing resources.

Testing with cURL

Create a test script:

#!/bin/bash
TOKEN=$(curl -s -X POST https://staging.mystore.com/rest/V1/integration/admin/token \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"test_password"}' | tr -d '"')

echo "Token: $TOKEN"

curl -s -X GET "https://staging.mystore.com/rest/V1/products" \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

Common Mistakes

• Forgetting to include the Bearer token in the Authorization header, resulting in a 401 Unauthorized error on every request
• Using admin token for customer operations or customer token for admin operations, when they have separate permission scopes
• Not encoding special characters in search criteria filter values, causing malformed URLs and empty results
• Sending GraphQL queries as GET requests instead of POST, since Magento's GraphQL endpoint only accepts POST
• Ignoring pagination in REST responses and only reading the first page of results, missing data beyond the default limit

Practice Questions

1. What is the difference between REST and GraphQL when fetching a product with its categories?
2. How do you authenticate a third-party ERP system that needs to update inventory every hour?
3. Write the cURL command to update a product's price from $29.99 to $34.99 using the REST API.

Challenge: Build a script that exports all products with stock quantity below 10 into a CSV file, using the REST API with pagination.

FAQ

Mini Project

Build a product synchronization script. The script fetches all products from Magento using the REST API with pagination, compares prices against a local CSV file, and updates any products whose prices have changed. Use the admin token for authentication and log all changes to a file. This is the same pattern used by enterprise ERP integrations.

What's Next

Now that you understand the Magento API, continue with CLI Commands to learn how to manage Magento from the command line. Next, explore Magento Caching to optimize API response times with Varnish and Redis.