Flask-Shopify-Utils

flask-shopify-utils is a Flask extension that provides common building blocks for Shopify custom apps: OAuth routes, HMAC and webhook validation, Shopify session-token checks, GDPR webhook routes, a GraphQL client, starter models, and a scaffold CLI.

• Features
• Installation
• Quick start
• Starter scaffold
• Configuration
• Route bundles
• Authentication decorators
• Models
• GraphQL utilities
• Development
• License

Features

• Shopify OAuth install and callback helpers for embedded custom apps.
• HMAC validation for OAuth callbacks, embedded-app entry points, app proxies, and webhooks.
• Shopify session-token validation through check_session_jwt.
• Optional default blueprints for app entry, admin reference endpoints, GDPR webhooks, and GraphQL schema generation.
• A retrying Shopify GraphQL client based on sgqlc.
• Starter SQLAlchemy models for stores and webhook jobs.
• lazy-dog CLI for copying the example scaffold into a new project.

Installation

Install the package from PyPI:

pip install -U flask-shopify-utils

Or install with uv:

uv pip install -U flask-shopify-utils

The package supports Python 3.9 and newer.

Quick start

Initialize Flask-SQLAlchemy before initializing ShopifyUtil. The extension reads the SQLAlchemy instance from app.extensions['sqlalchemy'] during init_app.

from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_shopify_utils import ShopifyUtil

app = Flask(__name__)
app.config.update(
    SQLALCHEMY_DATABASE_URI="sqlite:///shopify.db",
    SHOPIFY_API_KEY="your-shopify-api-key",
    SHOPIFY_API_SECRET="your-shopify-api-secret",
    SCOPES="read_products,write_products",
)

db = SQLAlchemy()
db.init_app(app)

shopify = ShopifyUtil()
shopify.init_app(app)

# Register only the route bundles your app needs.
shopify.enroll_default_route()
shopify.enroll_gdpr_route()
shopify.enroll_admin_route()
shopify.enroll_graphql_schema_cli()

If you use the bundled models, import them only after ShopifyUtil().init_app(app) has run:

from flask_shopify_utils.model import Store, Webhook

See example/ for complete sample projects.

Starter scaffold

flask-shopify-utils ships a lazy-dog console command that copies the reference scaffold from example/example1 into your current directory. Because it is a project bootstrapper, install it globally so the command is on your PATH from any directory.

Install lazy-dog globally

If you prefer plain pip, install into the global (user) environment:

pip install --user -U flask-shopify-utils

With uv, use uv tool install:

uv tool install flask-shopify-utils

After installation, verify the command is available:

lazy-dog --help

Run the scaffold

Run lazy-dog inside the project directory you want to populate:

lazy-dog

The command downloads the repository archive, copies example/example1/* into the target directory, and prompts before overwriting existing files or directories.

Configuration

ShopifyUtil.init_app() sets defaults for the following Flask config values when they are not already configured:

Set BYPASS_VALIDATE to 0 in production.

Route bundles

Routes are opt-in. Call the enrollment methods you need after init_app().

Authentication decorators

Use the decorator that matches the Shopify surface you are handling. Successful decorators set g.store_key and g.store_id for downstream handlers.

Deprecated JWT helpers such as check_jwt, validate_jwt, and create_admin_jwt_token remain available for backward compatibility, but new admin endpoints should use check_session_jwt.

Models

The bundled flask_shopify_utils.model module provides:

• Store: shop domain, access token, scopes, and JSON-style extra data storage.
• Webhook: webhook job/event records with status helpers.
• BasicMethod: small create/update helper methods shared by the models.

Because the model module uses the SQLAlchemy instance registered by ShopifyUtil, initialize the extension before importing these models.

GraphQL utilities

GraphQLClient wraps sgqlc.endpoint.http.HTTPEndpoint, resolves the Shopify API version through get_version(), and retries throttled or temporary HTTP failures.

from flask_shopify_utils.utils import GraphQLClient

client = GraphQLClient("example.myshopify.com", "shpat_access_token")
operation = ...  # Build an sgqlc Operation from your generated schema.
data = client.fetch_data(operation)

To generate a typed Shopify schema after registering the CLI command:

flask generate_schema --store_id 1

Use flask generate_schema --help to see all available options.

Development

Clone the repository, create a virtual environment, and install development dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements/dev.txt
pip install -e .

With uv:

uv venv
source .venv/bin/activate
uv pip install -r requirements/dev.txt
uv pip install -e .

Run linting and tests:

flake8
pytest

With uv:

uv run flake8
uv run pytest

Run a specific test file or test case:

pytest -vs tests/test_default_routes.py
pytest -vs tests/test_init.py::test_init_app

Dependency locks

Pinned dependencies live in requirements/. Use uv for new dependency workflows:

uv pip compile pyproject.toml --extra=dev --output-file=requirements/dev.txt
uv pip compile pyproject.toml --output-file=requirements/index.txt

Legacy pip-tools commands are still supported:

pip-compile --extra=dev --output-file=requirements/dev.txt pyproject.toml
pip-compile --output-file=requirements/index.txt pyproject.toml

Build and publish

Build the distribution and verify it with Twine:

python -m build
twine check dist/*

Publish to PyPI when you are ready:

twine upload dist/* --skip-existing

The package version is read from __version__ in src/flask_shopify_utils/__init__.py.

License

This project is licensed under the MIT License. See LICENSE for details.

Reference

• Python Packaging User Guide