@shopify/shopify-api

This library provides support for TypeScript/JavaScript Shopify apps to access the Shopify Admin API, by making it easier to perform the following actions:

• Creating online or offline access tokens for the Admin API via OAuth
• Making requests to the REST API
• Making requests to the GraphQL API
• Register/process webhooks

This library can be used in any application that has a Node.js backend, since it doesn't rely on any specific framework—you can include it alongside your preferred stack and only use the features that you need to build your app.

Requirements

To follow these usage guides, you will need to:

• have a basic understanding of Node.js
• have a Shopify Partner account and development store
• OR have a test store where you can create a private app
• have a private or custom app already set up in your test store or partner account
• use ngrok, in order to create a secure tunnel to your app running on your localhost
• add the ngrok URL and the appropriate redirect for your OAuth callback route to your app settings
• have yarn installed

Getting started

You can follow our getting started guide, which will provide instructions on how to create an app using plain Node.js code, or the Express framework. Both examples are written in Typescript.

• Getting started
  • Install dependencies
  • Set up base files
  • Set up environment
  • Set up Context
  • Running your app
• Performing OAuth
  • Add a route to start OAuth
  • Add your OAuth callback route
  • Fetching sessions
  • Detecting scope changes
• Make a REST API call
• Make a GraphQL API call
• Webhooks
  • Register a Webhook
  • Process a Webhook
• Known issues and caveats
  • Notes on session handling

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and adheres to Semantic Versioning.

Unreleased

[1.2.0] - 2021-03-16

Added

• Allow plain objects to be returned from the loadCallback on CustomSessionStorage #126
• Documentation and example code for CustomSessionStorage #129

Fixed

• Throw a different error for a missing cookie upon OAuth return #131
• Improved documentation for GraphQL and Rest Clients. #123
• Made Docs directory more browseable in GitHub. #136
• Make sure CustomSessionStorage converts the expires field from a string to Date. #132

[1.1.0] - 2021-03-02

• Minor text/doc changes
• Added 2021-01 API version to enum. #117
• Allow retrieving offline sessions using loadCurrentSession. #119

[1.0.0]

• Initial public release

[0.5.0]

Added

• Added AuthScopes value object to allow apps to easily check whether scopes have been updated. #110

Fixed

• GraphQL Proxy attempts to parse the request body as JSON before passing it to the client. #106

[0.4.0] - 2021-02-10

Added

• Webhooks types are now exported outside the library #91
• Added support for private apps #99
• USER_AGENT_PREFIX added to Context, to add agent to all requests #101
• Add link to tutorial on how to rotate credentials if neccesary #107

Fixed

• Export withSession utility method #96
• GraphQL Client appropriately handles queries with variables #97
• Use cryptographically random bytes to generate nonce #98
• Stop using SameSite=none cookies for OAuth, using lax instead #100

[0.3.1] - 2021-02-03

Fixed

• Fixed an issue when deleting the current session for embedded apps #88

[0.3.0] - 2021-01-27

Added

• Add withSession utility method #83

Fixed

• Refactor library public interface #87
• Check if a webhook is registered before calling Shopify #82

[0.2.2] - 2021-01-14

Fixed

• Ensure that the OAuth session expiration matches the cookie expiration #72 / #73

[0.2.0] - 2021-01-13

• Preserve the OAuth cookie session for a few seconds so SPA can perform their initial load using it #70
• Session fetches now return undefined when a session is not available #64
• Add deleteCurrentSession utils method #60

[0.1.0] - 2020-12-17

• Beta release

[0.0.1] - 2020-12-17

• Test releasing scripts
• Start of Changelog