Shopify App Developer Documentation

https://shopify.dev/docs/apps
Admin
Comprehensive documentation for building and extending Shopify applications with APIs, UI...
Tokens:2,331,376
Snippets:16,306
Trust Score:9.5
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Example OAuth install URL

Source: https://shopify.dev/docs/apps/build/authentication-authorization/app-installation/manage-access-scopes

Example URL with a specific store name, client ID, and requested scopes.

```text
https://admin.shopify.com/store/my-cool-store/oauth/install?client_id=a61950a2cbd5f32876b0b55587ec7a27&optional_scopes=read_discounts,write_products
```

--------------------------------

### Run setup script with npm, yarn, or pnpm

Source: https://shopify.dev/docs/apps/deployment/web

Run the setup script using your preferred package manager. This initializes the app before starting it.

```bash
npm run setup
```

```bash
yarn setup
```

```bash
pnpm run setup
```

--------------------------------

### start.sh: Launch Cloud SQL Proxy and start app

Source: https://shopify.dev/docs/apps/launch/deployment/deploy-to-google-cloud-run

Shell script that starts the Cloud SQL Proxy in the background, waits for it to be ready, then runs the production setup and starts the app. Ensures the database connection is available before Prisma generates the client and syncs the schema.

```bash
#!/bin/sh


# Start Cloud SQL Proxy in background
/cloud-sql-proxy --port 5432 ${INSTANCE_CONNECTION_NAME} &


# Wait for proxy to be ready
sleep 3


# Run production setup and start the app
npm run setup:prod && npm run start
```

--------------------------------

### Example translation JSON file for template localization

Source: https://shopify.dev/docs/apps/build/flow/templates/reference

Shows a JSON file with translated fields for a template, including name, description, preInstallNote, and a custom step description key. The preInstallNote is optional and only needed if setup is required before activating the workflow.

```json
{
  "name": "My Awesome Template!",
  "description": "A template that helps increase merchant productivity",
  "preInstallNote": "You must disable automatic payment capture in the Shopify Admin before using this template",
  "expressShippingCondition": "This step will check if the order uses express shipping"
}
```

--------------------------------

### Ruby signature calculation setup

Source: https://shopify.dev/docs/apps/build/online-store/app-proxies/authenticate-app-proxies

Starts the Ruby example for calculating the digital signature. It requires openssl and rack/utils and defines the shared secret used as the HMAC key.

```ruby
require 'openssl'
require 'rack/utils'
SHARED_SECRET = 'hush'

```

--------------------------------

### Initialize a new Shopify app with the notebook template

Source: https://shopify.dev/docs/apps/build/shopifyql/python-sdk/run-a-query

Run this command in the terminal to create a new app using the Shopify app notebooks template. After running, add the redirect URL http://localhost:4545/callback to your app's settings and start the app; the CLI logs in to your Partner account, connects the app, and writes credentials to a local .env file.

```bash
shopify app init --template=https://github.com/Shopify/shopify-app-notebooks-template
```

--------------------------------

### Install matplotlib for plotting

Source: https://shopify.dev/docs/apps/build/shopifyql/python-sdk/run-a-query

Installs matplotlib, required for the built-in pandas plot() method used in the charting example.

```terminal
pip install matplotlib
```

--------------------------------

### Start the application with npm, yarn, or pnpm

Source: https://shopify.dev/docs/apps/deployment/web

Start the application using your preferred package manager. The start script will fail if the database or environment variables are not set up properly.

```bash
npm run start
```

```bash
yarn start
```

```bash
pnpm run start
```

--------------------------------

### Encoded JWT example

Source: https://shopify.dev/docs/apps/build/functions/network-access/use-network-access

An example encoded JWT from the JWT verification section. It is the token that gets decoded into the header and payload shown in the adjacent decoded JWT example.

```text
eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOjY4NTY4NDE2NTY3LCJleHAiOjE2OTMyMzczOTEsInhfc2hvcGlmeV9yZXF1ZXN0X2lkIjoiZWNhMjEyNDMtYzA1OC00OWZmLThiMzUtYmUxYTAwNjE2MDRkIiwibWV0aG9kIjoiUE9TVCIsInVybF9zaGEyNTYiOiIxYmI1NmMwZGI1NjA4NDExZGJjZGFhOTAyZWVjMjM4NzgxZjU4NjNmMjQxMDA3NGQ4MDRjYTg5MWYwODFiN2RiIiwiaGVhZGVyc19zaGEyNTYiOiIxZjEyM2Q3YTI0MzFmYWVhMmEwMzljM2VmMGZhZDRmYmQxYzRkNzVmYWVlOWY3ZTQ3OTE4OTJiOGVmZjNmNmVmIiwiYm9keV9zaGEyNTYiOiI5Yjk3NzZkODY2ZWU3NTI2ZmNlOTJiYzlmZjI4OGNjYTIxNjg1MGZmNGE0ZmNhMGJlMzc0ZTMzYjAyNzBiMjI3In0.lce8eWBd-EnxZ6fwvasWGODR0S8nKEGv5Qb2s1teNyE
```

--------------------------------

### Migrate DataTable to s-table (Polaris web components) - setup

Source: https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/data-table

Starts the sales table migration example with Polaris web components. Imports useSearchParams, defines sort state from the URL, a money formatter, and updatePage/updateSort helpers that manipulate URL search params. Continues with JSX for the section and table element.

```javascript
import {useSearchParams} from 'react-router';
  

function ProductSalesTable({products, totals, pageInfo, currency, locale}) {
const [searchParams, setSearchParams] = useSearchParams();
const sort = searchParams.get('sort') ?? 'revenue-desc';
const moneyFormatter = new Intl.NumberFormat(locale, {
style: 'currency',
currency,
});
  

function updatePage(patch: Record<string, string>) {
const next = new URLSearchParams(searchParams);
  

for (const [name, value] of Object.entries(patch)) {
next.set(name, value);
}
  

setSearchParams(next);
}
  

function updateSort(value: string) {
const next = new URLSearchParams(searchParams);
next.set('sort', value);
next.delete('cursor');
next.delete('direction');
setSearchParams(next, {replace: true});
}
  

return (
<s-section padding="none" accessibilityLabel="Product sales">
<s-table
paginate
loading={pageInfo.loading}
hasPreviousPage={pageInfo.hasPreviousPage}
hasNextPage={pageInfo.hasNextPage}
onPreviousPage={() =>
```

--------------------------------

### Install Shopify CLI and Initialize App

Source: https://shopify.dev/docs/apps/build/graphql/migrate

Installs the Shopify CLI globally and initializes a new app. Use this to scaffold a Shopify app project.

```bash
npm install -g @shopify/cli@latest
shopify app init
```

--------------------------------

### GET order response example

Source: https://shopify.dev/docs/apps/build/orders-fulfillment/split-carts

Example response from the GET order endpoint, showing order details including line items, pricing, and status fields. The response includes two line items with their IDs, prices, and product information.

```json
HTTP/1.1 200 OK
{
  "order": {
    "id": 3,
    "cancel_reason": null,
    "checkout_id": 3,
    "closed_at": null,
    "confirmation_number": "HYXXAJK3G",
    "confirmed": true,
    "contact_email": "abc@example.com",
    "created_at": "2024-07-08T19:06:30-04:00",
    "currency": "CAD",
    "current_subtotal_price": "57.00",
    "line_items": [
      {
        "id": 5,
        "admin_graphql_api_id": "gid://shopify/LineItem/5",
        "attributed_staffs": [],
        "current_quantity": 1,
        "fulfillable_quantity": 1,
        "fulfillment_service": "manual",
        "fulfillment_status": null,
        "gift_card": false,
        "grams": 0,
        "name": "Fragile product",
        "price": "15.00",
        "price_set": {
          "shop_money": {
            "amount": "15.00",
            "currency_code": "CAD"
          },
          "presentment_money": {
            "amount": "15.00",
            "currency_code": "CAD"
          }
        },
        "product_exists": true,
        "product_id": 4,
        "properties": [],
        "quantity": 1,
        "requires_shipping": true,
        "sku": "",
        "taxable": true,
        "title": "Fragile product",
        "total_discount": "0.00",
        "total_discount_set": {
          "shop_money": {
            "amount": "0.00",
            "currency_code": "CAD"
          },
          "presentment_money": {
            "amount": "0.00",
            "currency_code": "CAD"
          }
        },
        "variant_id": 9,
        "variant_inventory_management": "shopify",
        "variant_title": null,
        "vendor": "Shop 1",
        "tax_lines": [],
        "duties": [],
        "discount_allocations": []
      },
      {
        "id": 6,
        "admin_graphql_api_id": "gid://shopify/LineItem/6",
        "attributed_staffs": [],
        "current_quantity": 1,
        "fulfillable_quantity": 1,
        "fulfillment_service": "manual",
        "fulfillment_status": null,
        "gift_card": false,
        "grams": 0,
        "name": "Black boots",
        "price": "42.00",
        "price_set": {
          "shop_money": {
            "amount": "42.00",
            "currency_code": "CAD"
          },
          "presentment_money": {
            "amount": "42.00",
            "currency_code": "CAD"
          }
        },
        "product_exists": true,
        "product_id": 3,
        "properties": [],
        "quantity": 1,
        "requires_shipping": true,
        "sku": "",
        "taxable": true,
        "title": "Black boots",
        "total_discount": "0.00",
        "total_discount_set": {
          "shop_money": {
            "amount": "0.00",
            "currency_code": "CAD"
          },
          "presentment_money": {
            "amount": "0.00",
            "currency_code": "CAD"
          }
        },
        "variant_id": 7,
        "variant_inventory_management": "shopify",
        "variant_title": null,
        "vendor": "Shop 1",
        "tax_lines": [],
        "duties": [],
        "discount_allocations": []
      }
    ],
    "current_subtotal_price_set": {
      "shop_money": {
        "amount": "57.00",
        "currency_code": "CAD"
      },
      "presentment_money": {
        "amount": "57.00",
        "currency_code": "CAD"
      }
    },
    "current_total_discounts": "0.00",
    "current_total_discounts_set": {
      "shop_money": {
        "amount": "0.00",
        "currency_code": "CAD"
      },
      "presentment_money": {
        "amount": "0.00",
        "currency_code": "CAD"
      }
    },
    "current_total_price": "57.00",
    "current_total_price_set": {
      "shop_money": {
        "amount": "57.00",
        "currency_code": "CAD"
      },
      "presentment_money": {
        "amount": "57.00",
        "currency_code": "CAD"
      }
    },
    "current_total_tax": "0.00",
    "current_total_tax_set": {
      "shop_money": {
        "amount": "0.00",
        "currency_code": "CAD"
      },
      "presentment_money": {
        "amount": "0.00",
        "currency_code": "CAD"
      }
    },
    "discount_codes": [],
    "email": "abc@example.com",
    "estimated_taxes": false,
    "financial_status": "paid",
    "fulfillment_status": null,
    "landing_site": "/",
    "landing_site_ref": null,
    "location_id": null,
    "merchant_of_record_app_id": null,
    "name": "#1003",
    "note": null,
    "note_attributes": [],
    "number": 3,
    "order_number": 1003,
    "original_total_additional_fees_set": null,
    "original_total_duties_set": null,
    "payment_gateway_names": [
      "bogus"
    ],
    "phone": null,
    "po_number": null,
    "presentment_currency": "CAD",
    "processed_at": "2024-07-08T19:06:27-04:00",
    "reference": "210c757a104fe6ef413f3bd8056089f4",
    "referring_site": ""
  }
}
```

--------------------------------

### Get current app installation ID

Source: https://shopify.dev/docs/apps/build/custom-data/metafields

Retrieves the ID of the current app installation, which is required as the ownerId when creating app-data metafields.

```graphql
query {
  currentAppInstallation {
    id
  }
}
```

--------------------------------

### Set up extension target (JavaScript)

Source: https://shopify.dev/docs/apps/build/b2b/create-checkout-ui

Set up the entry point for the extension using the purchase.checkout.block.render target with the ORDER_SUMMARY4 placement. The callback receives root and context objects.

```js
// Set up the entry point for the extension
export default extension("purchase.checkout.block.render", (root, { metafields, purchasingCompany, checkoutSettings }) => {
  // App logic goes here
})
```

--------------------------------

### instructions.md example for Sidekick

Source: https://shopify.dev/docs/apps/build/sidekick/build-app-actions

Example `instructions.md` file that defines when to use the `design_email` tool and important guidelines. The file is optional but recommended. The `description` field has a 256-token limit, and the `instructions.md` file has a 2,048-token limit.

```markdown
## When to Use the Design Email Tool


Use the `design_email` tool when the merchant asks to:
- Change the background color or layout of the email they're editing
- Update the visual styling or font of the current campaign
- Switch to a different email layout template


## Important Guidelines


- Only use `design_email` while the merchant has an email campaign open
- When updating the design, confirm changes with the merchant before applying
- Refer to layouts as "single-column", "two-column", or "hero-image"
```

--------------------------------

### Initialize a Shopify app with shopify app init

Source: https://shopify.dev/docs/apps/app-extensions/extension-only-apps

Run this command to create a new Shopify app. When prompted, choose 'Build an extension-only app'.

```bash
shopify app init
```

--------------------------------

### Install agent skills with npx

Source: https://shopify.dev/docs/apps/build/ai-toolkit

Installs the 'shopify' skill for AI tools that don't support plugins. Skills installed this way don't update automatically; run 'npx skills update' to get latest versions.

```terminal
npx skills add Shopify/shopify-ai-toolkit
```

--------------------------------

### package.json: Add setup:prod script

Source: https://shopify.dev/docs/apps/launch/deployment/deploy-to-google-cloud-run

Adds a 'setup:prod' script to package.json to run Prisma migrations in production. This script is invoked by start.sh before starting the app.

```bash
"setup:prod": "prisma generate && prisma db push"
```

--------------------------------

### Set up targets in shopify.extension.toml

Source: https://shopify.dev/docs/apps/build/customer-accounts/pre-auth-order-status-page-extensions/build-pre-auth-order-status-page-extensions

Configuration example for defining targets in the extension's shopify.extension.toml file. Each target specifies where the extension renders and the module path.

```toml
[[extensions.targeting]]
target = "customer-account.order.action.menu-item.render"
module = "./src/OrderActionMenuItem.jsx"

[[extensions.targeting]]
target = "customer-account.order.action.render"
module = "./src/OrderActionModal.jsx"
```

--------------------------------

### GraphQL query to get current app installation ID

Source: https://shopify.dev/docs/apps/build/custom-data/ownership

Use this query to retrieve the ID of the current app installation, which is needed as the ownerId when creating app-owned metafields. The response returns the installation ID in the format gid://shopify/AppInstallation/...

```graphql
query {
currentAppInstallation {
id
}
}
```

```json
{
"data": {
"currentAppInstallation": {
"id": "gid://shopify/AppInstallation/123456"
}
}
}
```

--------------------------------

### Response for currentAppInstallation access scopes query

Source: https://shopify.dev/docs/apps/build/authentication-authorization/manage-access-scopes

Example JSON response showing the structure of the accessScopes field, with description and handle for each granted scope.

```json
{
  "data": {
    "currentAppInstallation": {
      "accessScopes": [
        {
          "description": "Modify products, variants, and collections",
          "handle": "write_products"
        },
        {
          "description": "Read products, variants, and collections",
          "handle": "read_products"
        }
      ]
    }
  }
}
```

--------------------------------

### Initialize payment customizations sample app

Source: https://shopify.dev/docs/apps/build/checkout/payments

Initializes a new Shopify app using the payment customizations sample app template. Run this command to clone the sample code for the tutorial series.

```bash
shopify app init --template https://github.com/Shopify/function-examples/sample-apps/payment-customizations
```

--------------------------------

### Install Polaris and App Bridge type packages

Source: https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react

Installs the type-only packages for the global web components and App Bridge APIs. Include both packages in the TypeScript project, for example by adding them to compilerOptions.types.

```terminal
npm install --save-dev @shopify/polaris-types@latest @shopify/app-bridge-types@latest
```

--------------------------------

### Fetch data before first paint with shopify.query()

Source: https://shopify.dev/docs/apps/build/customer-accounts/extension-performance

Use this example to fetch data before first paint, so the extension's loading state holds during the wait and it renders once with no loading flash. It uses shopify.query() to fetch products and renders them in a stack.

```JavaScript
import '@shopify/ui-extensions/preact';
import {render} from 'preact';
  

export default async function extension() {
const {data} = await shopify.query(
`{ products(first: 3) { nodes { id title } } }`,
);
  

render(<Extension products={data.products.nodes} />, document.body);
}
  

function Extension({products}) {
return (
<s-stack direction="block">
{products.map((product) => (
<s-text key={product.id}>{product.title}</s-text>
))}
</s-stack>
);
}
```

--------------------------------

### Response for currentAppInstallation query

Source: https://shopify.dev/docs/apps/build/custom-data/metafields

Example response from the currentAppInstallation query, showing the app installation ID in the format gid://shopify/AppInstallation/123456.

```json
{
  "data": {
    "currentAppInstallation": {
      "id": "gid://shopify/AppInstallation/123456"
    }
  }
}
```
Tokens:
Raw