@pintahub/shopify-api

TypeScript SDK wrapper for Shopify APIs. Supports Admin GraphQL, Storefront GraphQL, REST, and Shop.app APIs with full type safety.

Installation

yarn add @pintahub/shopify-api

Quick Start

Admin API (GraphQL)

import { AdminAPI } from '@pintahub/shopify-api'

const admin = new AdminAPI({
    shop: 'your-store.myshopify.com',
    accessToken: 'shpat_xxx',
    legacy: false, // set true to enable legacy v1 product/order APIs
})

// Search products
const products = await admin.products.search({ query: 'title:T-Shirt' })

// Get product with variants
const product = await admin.products.get({ id: '123456' })

// Create product
const newProduct = await admin.products.create({
    product: { title: 'New Product', productType: 'Apparel' }
})

// Update variants in bulk
await admin.products.updateVariants({
    productId: '123456',
    variants: [
        { id: '111', price: '29.99', compareAtPrice: '39.99' }
    ]
})

Storefront API (GraphQL)

import { StorefrontAPI } from '@pintahub/shopify-api'

const storefront = new StorefrontAPI({
    shop: 'your-store.myshopify.com',
    accessToken: 'your_storefront_public_token',
})

// Get product
const product = await storefront.product.get({ id: '123456' })

// Create cart and add items
const cart = await storefront.cart.create({})
await storefront.cart.addItem({
    cartId: cart.id,
    lines: [{ merchandiseId: 'gid://shopify/ProductVariant/111', quantity: 1 }]
})

REST API

import { RestAPI } from '@pintahub/shopify-api'

const rest = new RestAPI({
    shop: 'your-store.myshopify.com',
    accessToken: 'shpat_xxx',
})

// Get order details
const order = await rest.order.get({ id: '123456' })

// Update tracking
await rest.order.updateTracking({
    fulfillment_id: '789',
    tracking_info: {
        company: 'DHL',
        number: '1234567890',
        url: 'https://tracking-url.com'
    },
    notify_customer: true
})

Shop.app API

import { ShopAppAPI } from '@pintahub/shopify-api'

const shopApp = new ShopAppAPI({
    shop_id: 'your_shop_id',
    cookies: 'your_session_cookies',
})

const reviews = await shopApp.getReviews()

API Reference

AdminAPI

| Module | Method | Description | |--------|--------|-------------| | products | search(args) | Search products | | | get(args) | Get product by ID | | | create(args) | Create product | | | createV2(args) | Create product (alternative) | | | update(args) | Update product | | | delete(args) | Delete product | | | getVariants(args) | Get product variants | | | updateVariants(args) | Bulk update variants | | | getOptions(args) | Get product options | | | createOption(args) | Add new option to product | | | updateOption(args) | Update existing option | | | getMedia(args) | Get product media | | | appendMedia(args) | Add media to product | | | deleteMedia(args) | Remove media | | | reorderMedia(args) | Reorder media | | | publish(args) | Publish product | | orders | search(args?) | Search orders | | | get(args) | Get order by ID | | | getEvents(args) | Get order timeline events | | customers | create(args) | Create customer | | collections | search(args?) | Search collections | | | get(args) | Get collection by ID | | | update(args) | Update collection | | files | searchImages(args) | Search images | | | getImage(args) | Get image by ID | | | getVideo(args) | Get video by ID | | | update(args) | Update file metadata | | | delete(args) | Delete file | | menus | search(args) | Search navigation menus | | | get(args) | Get menu by ID | | metaobjects | search(args) | Search metaobjects | | | get(args) | Get metaobject by ID | | | listBanners(args) | List banner metaobjects | | | listFAQs(args) | List FAQ metaobjects | | payments | searchPayouts(args) | Search payment payouts |

Legacy APIs (when legacy: true): product and order modules provide v1 API access with similar methods.

StorefrontAPI

| Module | Method | Description | |--------|--------|-------------| | product | get(args) | Get product with variants and pricing | | cart | create(args) | Create new cart | | | get(args) | Get cart contents | | | addItem(args) | Add items to cart | | | removeItem(args) | Remove items from cart | | | updateItem(args) | Update item quantity | | | updateBuyer(args) | Update buyer identity | | pages | searchPages(args?) | Search CMS pages | | | getPage(args) | Get page by ID | | posts | search(args) | Search blog posts | | | get(args) | Get blog post by ID | | shop | get(args?) | Get shop information | | | getPolicyPage(args?) | Get policy pages | | customers | create(args) | Create customer account |

RestAPI

| Module | Method | Description | |--------|--------|-------------| | order | get(args) | Get order details | | | getTransaction(args) | Get payment transactions | | | updateTracking(args) | Update shipment tracking |

ShopAppAPI

| Method | Description | |--------|-------------| | getReviews() | Fetch store reviews |

API Versions

| Client | Version | Modules | |--------|---------|---------| | Admin GraphQL | 2025-01 | products, files | | Admin GraphQL | 2026-01 | orders, customers, collections, menus, metaobjects, payments | | Admin GraphQL | 2023-10 | legacy product, legacy order | | Storefront GraphQL | 2025-10 | all storefront modules | | REST | 2024-01 | order |

Environment Variables

| Variable | Description | |----------|-------------| | SHOPIFY_SHOP | Store domain (e.g. your-store.myshopify.com) | | SHOPIFY_ACCESS_TOKEN | Admin API access token (shpat_xxx) | | SHOPIFY_STOREFRONT_TOKEN | Storefront API public access token | | SHOPIFY_SHOP_APP_ID | Shop.app shop ID | | SHOPIFY_SHOP_APP_COOKIES | Shop.app session cookies |

Architecture

The SDK uses the ActionBuilder pattern:

AdminAPI / StorefrontAPI / RestAPI
  -> Module (e.g. AdminProductsAPI)
    -> ActionBuilder (e.g. CreateProduct, SearchProducts)
      -> GraphQL/REST request

Each operation is a separate class extending ActionBuilder<Client, Input, Output>, providing type-safe inputs/outputs and centralized error handling with automatic retry on Shopify API throttling.

Development

# Install dependencies
yarn install

# Development mode (auto-compile on changes)
yarn dev

# Build
npx tsc

# Run a test
node test/create-option.js

License

ISC