Shopify APIs Overview

Shopify exposes a rich set of APIs that let you read, write, and extend nearly every aspect of the commerce platform. Choosing the right API for each task is one of the most important skills in Shopify development. This lesson provides a complete map of the API landscape, covering authentication, versioning, rate limits, and the specific use cases for each API.

The API Landscape

Admin API (GraphQL and REST)

The Admin API is the most comprehensive API in the Shopify ecosystem. It provides full CRUD access to store data and is what your app uses for most backend operations.

GraphQL vs REST

Shopify maintains both GraphQL and REST versions of the Admin API, but GraphQL is the primary API going forward. New features are added to GraphQL first, and some features are GraphQL-only.

Aspect	GraphQL	REST
Data fetching	Request exactly what you need	Fixed response shapes
Rate limiting	Cost-based (1,000 points/sec)	Request-based (40 req/sec)
New features	Added first	May lag or never get added
Bulk operations	Supported	Not supported
Mutations	Single endpoint	Resource-specific endpoints
Learning curve	Steeper	Gentler

Prefer GraphQL

Shopify has explicitly stated that GraphQL is the future of their API platform. New resources like metaobjects, markets, and fulfillment orders have limited or no REST support. For new projects, always use GraphQL.

Admin API Authentication

Apps authenticate with the Admin API via OAuth 2.0. The flow works like this:

The access token is scoped to a specific store and has only the permissions (scopes) the merchant approved. Common scopes include:

read_products / write_products -- Product catalog access
read_orders / write_orders -- Order management
read_customers / write_customers -- Customer data
read_inventory / write_inventory -- Inventory levels
read_content / write_content -- Metaobjects and content

Request Minimal Scopes

Only request the scopes your app actually needs. Excessive scope requests reduce installation rates -- merchants are rightfully suspicious of apps that want access to everything. You can always request additional scopes later via a re-authorization flow.

Storefront API

The Storefront API is designed for customer-facing applications. Unlike the Admin API, it uses public access tokens that can be safely included in client-side code.

Use Cases

Hydrogen storefronts: All data fetching in headless storefronts
Custom product pickers: JavaScript widgets on the storefront
Mobile apps: Native iOS/Android shopping apps
Buy Button: Embedding products on external websites
Cart operations: Adding items, applying discount codes, managing the cart

Key Differences from Admin API

Feature	Admin API	Storefront API
Authentication	Private access token	Public access token
Data access	Full read/write	Read-only + cart mutations
Audience	App backends	Customer-facing clients
Rate limits	Per-store	Per-app, per-store
Customer data	Full access	Authenticated customer only

# Storefront API: Fetch products for a collection page
query CollectionProducts($handle: String!, $first: Int!) {
  collection(handle: $handle) {
    title
    products(first: $first) {
      edges {
        node {
          id
          title
          priceRange {
            minVariantPrice {
              amount
              currencyCode
            }
          }
          images(first: 1) {
            edges {
              node {
                url
                altText
              }
            }
          }
        }
      }
    }
  }
}

Payments Apps API

The Payments Apps API lets you build payment gateways that integrate directly with Shopify Checkout. This is a specialized API for payment service providers.

Supports credit card, offsite, and custom onsite payment methods
Requires PCI DSS compliance for credit card processing
Uses a webhook-based flow for payment sessions
Registered through the Partner Dashboard with additional vetting

Payments Apps Are Specialized

Most developers will never need this API. It is relevant only if you are building a payment gateway or alternative payment method. If you just need to accept payments, use Shopify Payments or one of the existing payment gateway apps.

Customer Account API

The Customer Account API enables customer self-service features in the new Customer Account experience (introduced in 2024). It lets authenticated customers:

View and manage their orders
Update their profile information
Manage addresses
Access loyalty and rewards programs
View B2B company information

This API uses customer access tokens obtained through Shopify's new customer authentication system.

Functions API

The Functions API defines how Shopify Functions receive input data and return output. It is not a traditional HTTP API -- instead, it is a contract between your WebAssembly module and the Shopify runtime.

Each Function extension target has a specific input/output schema:

# Input query for a Discount Function
query Input {
  cart {
    lines {
      merchandise {
        ... on ProductVariant {
          product {
            hasAnyTag(tags: ["vip-discount"])
          }
        }
      }
      cost {
        totalAmount {
          amount
        }
      }
    }
  }
}

// Output: Apply a 10% discount to VIP products
{
  "discounts": [
    {
      "value": {
        "percentage": {
          "value": "10.0"
        }
      },
      "targets": [
        {
          "productVariant": {
            "id": "gid://shopify/ProductVariant/123"
          }
        }
      ],
      "message": "VIP 10% Off"
    }
  ]
}

Checkout Extensions API

The Checkout Extensions API lets you build React-based UI components that render within the Shopify checkout. Extension targets define where your UI appears:

purchase.checkout.block.render -- A block in the main checkout area
purchase.checkout.header.render-after -- After the checkout header
purchase.checkout.footer.render-before -- Before the checkout footer
purchase.thank-you.block.render -- On the thank-you page
purchase.checkout.shipping-option-item.render-after -- After each shipping option

Extensions use a limited set of UI components from the Checkout UI Extensions library (not Polaris).

Flow Triggers and Actions API

Shopify Flow is a visual automation platform for merchants. Your app can integrate with Flow by providing:

Triggers: Events that start a Flow workflow (e.g., "New review submitted")
Actions: Operations that Flow can invoke in your app (e.g., "Send loyalty points")

This is a powerful way to make your app more useful without building a full automation UI yourself.

API Versioning

Shopify uses a calendar-based versioning system. New API versions are released quarterly:

Version	Release	Status
`2025-07`	July 2025	Supported
`2025-10`	October 2025	Supported
`2026-01`	January 2026	Current stable
`2026-04`	April 2026	Release candidate

Versioning Rules

Each version is supported for 12 months after release
Breaking changes only happen between versions, never within a version
You specify the version in your API requests:
- GraphQL: X-Shopify-API-Version: 2026-01 header
- REST: /admin/api/2026-01/products.json URL path
Deprecation notices appear in API responses 9 months before removal

# GraphQL request with explicit version
curl -X POST "https://your-store.myshopify.com/admin/api/2026-01/graphql.json" \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Access-Token: your-token" \
  -d '{"query": "{ shop { name } }"}'

Stay on Current Versions

Set a calendar reminder to update your API version every quarter. Falling behind on versions means missing new features and eventually hitting deprecation walls. The Shopify CLI and Partner Dashboard show warnings when you are using outdated versions.

Rate Limits

Rate limits protect the platform and ensure fair access for all apps on a store.

GraphQL Rate Limits

GraphQL uses a cost-based system:

Each store grants your app 1,000 cost points per second
Points regenerate at 50 points per second (leaky bucket algorithm)
Simple queries cost 1-10 points; complex queries with connections cost more
The response includes a throttleStatus object showing your remaining budget

{
  "extensions": {
    "cost": {
      "requestedQueryCost": 12,
      "actualQueryCost": 8,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 992,
        "restoreRate": 50
      }
    }
  }
}

REST Rate Limits

REST uses a simpler request-based model:

Standard plans: 40 requests per second per store
Shopify Plus: 80 requests per second per store (some endpoints higher)
Tracked via X-Shopify-Shop-Api-Call-Limit response header

Handling Rate Limits

// Retry with exponential backoff
async function shopifyRequest(query, retries = 3) {
  for (let attempt = 0; attempt < retries; attempt++) {
    const response = await admin.graphql(query);

    if (response.status === 429) {
      const retryAfter = parseFloat(
        response.headers.get("Retry-After") || "1"
      );
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue;
    }

    return response.json();
  }
  throw new Error("Rate limit exceeded after retries");
}

Cursor-Based Pagination

Both GraphQL and REST use cursor-based pagination for list endpoints. This is more reliable than offset-based pagination because it handles concurrent data changes correctly.

GraphQL Pagination

query Products($first: Int!, $after: String) {
  products(first: $first, after: $after) {
    edges {
      cursor
      node {
        id
        title
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

To fetch the next page, pass the endCursor value as the after variable. Continue until hasNextPage is false.

REST Pagination

REST APIs return pagination links in the Link header:

Link: <https://store.myshopify.com/admin/api/2026-01/products.json?page_info=abc123&limit=50>; rel="next"

Parse the rel="next" URL and use it for the next request.

Never Use Page Numbers

Shopify deprecated page-number pagination years ago. Always use cursor-based pagination. If you find old tutorials using ?page=2, they are outdated and will not work.

Choosing the Right API

I want to...	Use this API
Manage products, orders, customers from my app backend	Admin API (GraphQL)
Display products on a custom storefront	Storefront API
Build a headless storefront with Hydrogen	Storefront API
Customize discount logic at checkout	Functions API (discount target)
Add UI to the checkout page	Checkout Extensions API
Process payments as a gateway	Payments Apps API
Let customers manage their accounts	Customer Account API
Integrate with Shopify Flow automations	Flow Triggers & Actions API
Export/import large datasets	Admin API Bulk Operations

In the next lesson, we dive deep into GraphQL -- the query language that powers the most important Shopify APIs.

The API Landscape​

Admin API (GraphQL and REST)​

GraphQL vs REST​

Admin API Authentication​

Storefront API​

Use Cases​

Key Differences from Admin API​

Payments Apps API​

Customer Account API​

Functions API​

Checkout Extensions API​

Flow Triggers and Actions API​

API Versioning​

Versioning Rules​

Rate Limits​

GraphQL Rate Limits​

REST Rate Limits​

Handling Rate Limits​

Cursor-Based Pagination​

GraphQL Pagination​

REST Pagination​

Choosing the Right API​