12/9/2025, 12:00:48 AM
The API now includes a new returnReasonDefinitions query that returns the entire library of available return reason definitions, allowing clients to query by ID, handle, and paginate with sorting and filter options. Several core queries such as abandonedCheckouts, app, appByHandle, and appByKey have updated descriptions to clarify returned data and scope, improving understanding of installed apps, checkout states, and return reasons. The currentAppInstallation and currentBulkOperation descriptions have been refined to better explain their purpose, including permission checks and bulk operation status handling. Content‑related queries like articles, blogs, carrierServices, channels, and markets now include more descriptive summaries and filtering capabilities, enhancing discoverability of blogs, carrier services, and market configurations. Additional queries such as giftCard, giftCards, deliveryProfile, and deliveryProfiles have expanded descriptions detailing balance history, delivery zone data, and filtering mechanisms. Overall, the changes aim to clarify returned fields, improve pagination and filtering details, and provide guidance on related mutations and documentation links.
Returns a full library of available return reason definitions.
Returns a list of abandoned checkouts. A checkout is considered abandoned when a customer adds contact information but doesn't complete their purchase. Includes both abandoned and recovered checkouts.
Each checkout provides Customer details, AbandonedCheckoutLineItem objects, pricing information, and a recovery URL for re-engaging customers who didn't complete their purchase.
Retrieves an App by its ID. If no ID is provided, returns details about the currently authenticated app. The query provides access to app details including title, icon, and pricing information.
If the app isn't installed on the current shop, then the installation field will be null.
Retrieves an app by its unique handle. The handle is a URL-friendly identifier for the app.
Returns the App if found, or null if no app exists with the specified handle.
Retrieves an App by its client ID (API key). Returns the app's configuration, installation status, AccessScope objects, and developer information.
Returns null if no app exists with the specified client ID.
Retrieves an AppInstallation by ID. If no ID is provided, returns the installation for the currently authenticated App. The query provides essential data for validating installation state and managing app functionality within a store.
Use this query to access installation details including granted AccessScope objects, active AppSubscription objects, AppCredit objects, AppPurchaseOneTime objects, and app-specific metadata.
Learn more about app installation.
A paginated list of AppInstallation objects across multiple stores where your app is installed. Use this query to monitor installation status, track billing and subscriptions through AppSubscription objects, and review granted AccessScope objects.
Filter by AppInstallationCategory to find specific types of installations (such as POS or channel apps) and by AppInstallationPrivacy to scope to public or private installations.
Returns a paginated list of articles from the shop's blogs. Article objects are blog posts that contain content like text, images, and tags.
Supports cursor-based pagination to control the number of articles returned and their order. Use the query argument to filter results by specific criteria.
Returns a list of automatic discounts that are applied in the cart and at checkout without requiring a discount code.
The geographic regions that you can set as the Shop's backup region. The backup region serves as a fallback when the system can't determine a buyer's actual location.
Returns all locales that Shopify supports. Each Locale includes an ISO code and human-readable name. Use this query to discover which locales you can enable on a shop with the shopLocaleEnable mutation.
Returns a paginated list of the shop's Blog objects. Blogs serve as containers for Article objects and provide content management capabilities for the store's editorial content.
Supports cursor-based pagination to control the number of blogs returned and their order. Use the query argument to filter results by specific criteria.
A paginated list of carrier services configured for the shop. Carrier services provide real-time shipping rates from external providers like FedEx, UPS, or custom shipping solutions. Use the query parameter to filter results by attributes such as active status.
Returns active channels where merchants sell products and collections. Each channel is an authenticated link to an external platform such as marketplaces, social media platforms, online stores, or point-of-sale systems.
Returns the visual customizations for checkout for a given checkout profile.
To update checkout branding settings, use the checkoutBrandingUpsert mutation. Learn more about customizing checkout's appearance.
Returns a CheckoutProfile. Checkout profiles define the branding settings and UI extensions for a store's checkout experience. Stores can have one published profile that renders on their live checkout and multiple draft profiles for testing customizations in the checkout editor.
Retrieves a code discount by its discount code. The search is case-insensitive, enabling you to find discounts regardless of how customers enter the code.
Returns a DiscountCodeNode that contains the underlying discount details, which could be a basic amount off discount, a "Buy X Get Y" (BXGY) discount, a free shipping discount, or an app-provided discount.
Learn more about working with Shopify's discount model.
A paginated list of companies in the shop. Company objects are business entities that purchase from the merchant.
Use the query argument to filter companies by attributes like name or externalId. Sort and paginate results to handle large datasets efficiently. Learn more about Shopify API search syntax.
A paginated list of CompanyLocation objects for B2B customers. Company locations represent individual branches or offices of a Company where B2B orders can be placed.
Each location can have its own billing and shipping addresses, tax settings, PaymentTerms, and Catalog assignments with custom pricing. Use the query parameter to search locations by name or other attributes.
Learn more about managing company locations.
Returns the AppInstallation for the currently authenticated app. Provides access to granted access scopes, active AppSubscription objects, and billing information for your app.
Use this query to check which permissions your app has, monitor subscription status, or retrieve AppCredit objects. Learn more about managing access scopes, subscription billing, and app credits.
Returns the current app's most recent BulkOperation. Apps can run one bulk query and one bulk mutation operation at a time per shop.
The operation type parameter determines whether to retrieve the most recent query or mutation bulk operation. Use this query to check the operation's status, track its progress, and retrieve the result URL when it completes.
A paginated list of customers that belong to an individual Segment. Segments group customers based on criteria defined through ShopifyQL queries. Access segment members with their profile information and purchase summary data. The connection includes statistics for analyzing segment attributes (such as average and sum calculations) and a total count of all members.
The maximum page size is 1000.
Retrieves a DeliveryProfile by ID. Delivery profiles group shipping settings for specific Product objects that ship from selected Location objects to [delivery zones](https://shopify.dev/docs/api/admin-graphql/latest/objects/DeliveryZone with defined rates.
Learn more about delivery profiles.
Returns a paginated list of DeliveryProfile objects for the shop. Delivery profiles group Product and ProductVariant objects that share shipping rates and zones.
Each profile contains DeliveryLocationGroup objects that organize fulfillment Location objects and their associated delivery zones. DeliveryZone objects define geographic regions with specific shipping methods and rates. Use the merchantOwnedOnly filter to exclude profiles that third-party apps manage.
Learn more about delivery profiles.
Retrieves a single event by ID. Events chronicle activities in your store such as resource creation, updates, or staff comments. The query returns an Event interface of type BasicEvent or CommentEvent.
A paginated list of events that chronicle activities in the store. Event is an interface implemented by types such as BasicEvent and CommentEvent that track actions such as creating Article objects, fulfilling Order objects, adding Product objects, or staff comments on timelines.
The query supports filtering and sorting to help you find specific events or audit store activity over time.
Retrieves a GiftCard by its ID. Returns the gift card's balance, transaction history, Customer information, and whether it's enabled.
Additional fields include the initial value, expiration date, deactivation timestamp (if applicable), and the associated Order if the gift card was purchased by a customer through checkout. Gift cards that merchants create manually won't have an associated order.
Returns a paginated list of GiftCard objects issued for the shop.
You can filter gift cards by attributes such as status, last characters of the code, balance status, and other values using the query parameter. You can also apply SavedSearch objects to filter results.
Returns a paginated list of Market objects configured for the shop. Markets match buyers based on defined conditions to deliver customized shopping experiences.
Filter markets by MarketType and MarketStatus, search by name, and control sort order. Retrieve market configurations including MarketCurrencySettings, MarketWebPresence objects, and MarketConditions.
Learn more about Shopify Markets.
Retrieves a MetafieldDefinition by its identifier. You can identify a definition using either its owner type, namespace, and key, or its global ID.
Use this query to inspect a definition's configuration, including its data type, validations, access settings, and the count of metafields using it.
The available metafield types that you can use when creating MetafieldDefinition objects. Each type specifies what kind of data it stores (such as boolean, color, date, or references), its category, and which validations it supports.
For a list of supported types and their capabilities, refer to the metafield types documentation.
Retrieves a single Metaobject by its global ID. Metaobjects store custom structured data based on defined schemas. The returned metaobject includes its fields with values, display name, handle, and associated metadata like update timestamps and capabilities.
Retrieves a Metaobject by its handle and type. Handles are unique identifiers within a metaobject type.
Retrieves a MetaobjectDefinition by its global ID. Metaobject definitions provide the structure and fields for metaobjects.
The definition includes field configurations, access settings, display preferences, and capabilities that determine how metaobjects of this type behave across the Shopify platform.
Retrieves a MetaobjectDefinition by its type. The type serves as a unique identifier that distinguishes one metaobject definition from another.
Returns a paginated list of all MetaobjectDefinition objects configured for the store. Metaobject definitions provide the schema for creating custom data structures composed of individual fields. Each definition specifies the field types, access permissions, and capabilities for Metaobject entries of that type. Use this query to discover available metaobject types before creating or querying metaobject entries.
Learn more about managing metaobjects.
Returns a paginated list of Metaobject entries for a specific type. Metaobjects are custom data structures that extend Shopify's data model with merchant or app-specific data types.
Filter results using the query parameter with a search syntax for metaobject fields. Use fields.{key}:{value} to filter by field values, supporting any field previously marked as filterable. The sortKey parameter accepts id, type, updated_at, or display_name to control result ordering.
Learn more about querying metaobjects by field value.
Returns saved searches for orders in the shop. Saved searches store search queries with their filters and search terms.
A paginated list of pages from the online store. Page objects are content pages that merchants create to provide information to customers, such as "About Us", "Contact", or policy pages.
The query supports filtering with a search query and sorting by various criteria. Advanced filtering is available through saved searches using the savedSearchId argument.
Retrieves a Product using its handle. A handle is a unique, URL-friendly string that Shopify automatically generates from the product's title.
Returns null if no product exists with the specified handle.
Returns tags added to Product objects in the shop. Provides a paginated list of tag strings.
The maximum page size is 5000 tags per request. Tags are returned as simple strings through a StringConnection.
The maximum page size is 5000.
Retrieves a customer Segment by ID. Segments are dynamic groups of customers that meet specific criteria defined through ShopifyQL queries.
Use segments for targeted marketing campaigns, analyzing customer behavior, or creating personalized experiences. Each segment includes its name, creation date, and the query that defines which Customer objects belong to it.
Returns a paginated list of Segment objects for the shop. Segments are dynamic groups of customers that meet specific criteria defined through ShopifyQL queries. You can filter segments by search query and sort them by creation date or other criteria.
The query supports standard pagination arguments and returns a SegmentConnection containing segment details including names, creation dates, and the query definitions that determine segment membership.
The shop's billing preferences, including the currency for paying for apps and services. Use this to create app charges in the merchant's local billing currency, helping them budget their app spend without exposure to exchange rate fluctuations.
Returns the locales enabled on a shop. Each locale represents a language for translations and determines how content displays to customers in different markets.
Use the optional published argument to filter for only the locales that are visible to customers. The response includes the ISO locale code, whether it's the shop's primary locale, and which MarketWebPresence objects use each locale.
Returns Shopify Functions owned by the querying API client installed on the shop. Functions enable you to customize
Shopify's backend logic at specific points in the commerce loop, such as discounts,
checkout validation, and fulfillment.
You can filter the results by API type to find specific function implementations,
or by whether they provide a merchant configuration interface in the Shopify Admin.
The response includes details about each function's configuration, including its
title, description, API version, and the input query used to provide data to the function logic.
Learn more about building functions.
Executes a ShopifyQL query to analyze store data and returns results in a tabular format.
The response includes column metadata with names, data types, and display names, along with the actual data rows. If the query contains syntax errors, then the response provides parse error messages instead of table data.
Retrieves a staff member by ID. If no ID is provided, the query returns the staff member that's making the request. A staff member is a user who can access the Shopify admin to manage store operations.
Provides staff member details such as email, name, and shop owner status. When querying the current user (with or without an ID), additional private data becomes available.
Returns a paginated list of StaffMember objects for the shop. Staff members are users who can access the Shopify admin to manage store operations.
Supports filtering by account type, email, and name, with an option to sort results. The query returns a StaffMemberConnection for cursor-based pagination.
Retrieves preset metafield definition templates for common use cases. Each template provides a reserved namespace and key combination for specific purposes like product subtitles, care guides, or ISBN numbers. Use these templates to create standardized metafields across your store. Filter templates by constraint status or exclude those you've already activated.
See the list of standard metafield definitions for available templates.
Retrieves a StoreCreditAccount by ID. Store credit accounts hold monetary balances that account owners can use at checkout. The owner is either a Customer or a CompanyLocation.
Transactions representing a movement of money between customers and the shop. Each transaction records the amount, payment method, processing details, and the associated Order.
Positive amounts indicate customer payments to the merchant. Negative amounts represent refunds from the merchant to the customer. Use the query parameter to filter transactions by attributes such as transaction ID, processing date, and point-of-sale device ID.
Returns an OnlineStoreTheme by its ID. Use this query to retrieve theme metadata and access the theme's files, which include templates, assets, translations, and configuration files.
Returns a paginated list of OnlineStoreTheme objects for the online store. Themes control the appearance and layout of the storefront.
You can filter themes by role to find specific theme types, such as MAIN for the published theme and UNPUBLISHED for draft themes.
Retrieves a resource that has translatable fields. Returns the resource's Translation objects for different locales and markets, along with the original TranslatableContent and digest values needed to register new translations. Provides access to existing translations, translatable content with digest hashes for translation registration, and nested translatable resources like ProductVariant objects or Metafield objects.
Learn more about managing translated content.
Returns a paginated list of TranslatableResource objects for a specific resource type. Each resource provides translatable content and digest values needed for the translationsRegister mutation.
Learn more about managing translated content.
Learn more about [managing translated content](https://shopify.dev/docs/apps/build/markets/manage-translated-content).
Returns a paginated list of TranslatableResource objects for the specified resource IDs. Each resource provides translatable content and digest values needed for the translationsRegister mutation.
Learn more about managing translated content.
Retrieves a paginated list of webhook subscriptions created using the API for the current app and shop.
Note: Returns only shop-scoped subscriptions, not app-scoped subscriptions configured in TOML files.
Subscription details include event topics, endpoint URIs, filtering rules, field inclusion settings, and metafield namespace permissions. Results support cursor-based pagination that you can filter by topic, format, or custom search criteria.
Building an app? If you only use app-specific webhooks, you won't need this. App-specific webhook subscriptions specified in your shopify.app.toml may be easier. They are automatically kept up to date by Shopify & require less maintenance. Please read About managing webhook subscriptions.
Duplicates a collection.
An existing collection ID and new title are required.
Publications may be excluded by passing copyPublications: false in the input.
Metafield values are not duplicated if the unique values capability is enabled.
Creates a recurring or usage-based AppSubscription that charges merchants for app features and services. The subscription includes one or more AppSubscriptionLineItem objects that define the pricing structure, billing intervals, and optional AppSubscriptionDiscount values.
Returns a confirmation URL where the merchant approves or declines the charges. After approval, the subscription becomes active and billing begins after any trial period expires. You can specify AppSubscriptionReplacementBehavior to control how this subscription interacts with existing active subscriptions.
Learn more about creating app subscriptions.
Updates the capped amount on usage-based billing for an AppSubscriptionLineItem. Enables you to modify the maximum charge limit that prevents merchants from exceeding a specified threshold during their billing period.
The mutation returns a confirmation URL where the merchant must approve the new pricing limit before it takes effect. Use this when adjusting usage limits based on merchant needs or changing pricing models.
Learn more about updating the maximum charge for a subscription.
Extends the trial period for an existing app subscription. Trial extensions give merchants additional time to use the app before committing to paid billing.
Requires the subscription ID and the number of days to extend (between one and 1000). The extension modifies the existing trial end date, allowing continued access to subscription features without immediate billing. Returns the updated AppSubscription.
Learn more about offering free trials.
Uninstalls an App from a shop. Apps use this mutation to uninstall themselves programmatically, removing their AppInstallation from the merchant's store.
When an app uninstalls, Shopify automatically performs cleanup tasks, such as deleting WebhookSubscription objects and admin links associated with the app.
Learn more about app lifecycle management.
Caution:
This action is irreversible. You can't restore an uninstalled app's configuration or data. Before you uninstall an app, make sure that you no longer need to make API calls for the store in which the app has been installed.
Creates a usage charge for an app subscription with usage-based pricing. The charge counts toward the capped amount limit set when creating the subscription.
Usage records track consumption of app features or services on a per-use basis. You provide the charge amount, a description of what you consumed, and the subscription line item ID. The optional idempotencyKey parameter prevents duplicate charges if you send the same request multiple times.
If the new charge would cause total usage charges in the current billing interval to exceed the capped amount, then the mutation returns an error.
Learn more about creating usage-based subscriptions.
Creates an Article. Articles are content pieces that include a title, body text, and author information.
You can publish the article immediately or schedule it with a specific publish date. You can customize the article's URL handle, apply custom templates for rendering, and add optional fields like tags, an image, and Metafield objects.
The mutation validates article content and ensures proper blog association. Error handling provides specific feedback for content requirements.
Permanently deletes a blog article from a shop's blog. This mutation removes the article and all associated metadata.
For example, when outdated product information or seasonal content needs removal, merchants can use this mutation to clean up their blog.
Use the articleDelete mutation to:
The deletion is permanent and returns the deleted article's ID for confirmation.
Updates an existing Article. You can modify the article's content, metadata, publication status, and associated properties like author information and tags.
If you update the handle, then you can optionally create a redirect from the old URL to the new one by setting redirectNewHandle to true.
Creates a new blog within a shop, establishing a container for organizing articles.
For example, a fitness equipment retailer launching a wellness blog would use this mutation to create the blog, enabling them to publish workout guides and nutrition tips.
Use the blogCreate mutation to:
The mutation validates blog settings and establishes the structure for article publishing.
Permanently deletes a blog from a shop. This mutation removes the blog container and its organizational structure.
For example, when consolidating multiple seasonal blogs into a single year-round content strategy, merchants can use this mutation to remove unused blogs.
Use the blogDelete mutation to:
The deletion is permanent and returns the deleted blog's ID for confirmation.
Updates an existing blog's configuration and settings. This mutation allows merchants to modify blog properties to keep their content strategy current.
For example, a merchant might update their blog's title from "Company News" to "Sustainability Stories" when shifting their content focus, or modify the handle to improve URL structure.
Use the blogUpdate mutation to:
The mutation returns the updated blog with any validation errors.
Creates and runs a bulk operation to import data asynchronously. This mutation executes a specified GraphQL mutation multiple times using input data from a JSONL file that you've uploaded to Shopify.
The operation processes each line in your JSONL file as a separate mutation execution. The operation delivers results in a JSONL file when it completes. You can run one bulk mutation operation at a time per shop, though a bulkOperationRunQuery operation can run simultaneously.
Learn more about bulk importing data.
Creates and runs a bulk operation to fetch data asynchronously. The operation processes your GraphQL query in the background and returns results in a JSONL file when complete.
Apps can run one bulk query operation and one bulk mutation operation at a time per shop. The query must include at least one connection field and supports up to five connections with a maximum nesting depth of two levels.
Note: Results remain available for seven days after completion.
For more information, see the bulk operations guide.
Creates a carrier service that provides real-time shipping rates to Shopify. Carrier services provide real-time shipping rates from external providers like FedEx, UPS, or custom shipping solutions. The carrier service connects to your external shipping rate calculation system through a callback URL.
When customers reach checkout, Shopify sends order details to your callback URL and displays the returned shipping rates. The service must be active to provide rates during checkout.
Updates the visual branding for a CheckoutProfile, customizing how checkout displays to customers. Creates new branding settings if none exist, or modifies existing settings.
The mutation accepts two levels of customization through the CheckoutBrandingInput input object. designSystem defines foundational brand attributes like colors, typography, and corner radius that apply consistently throughout checkout. customizations defines styles for specific parts of the UI, individual components, or groups of components like the header, buttons, form fields, and sections.
Changes to a published checkout profile display immediately in the store's checkout. You can preview draft profiles in the Shopify admin's checkout editor before publishing.
Learn more about checkout styling.
Approves a pending comment, making it visible to store visitors on the associated blog article.
For example, when a customer submits a question about a product in a blog post, merchants can approve the comment to make it publicly visible.
Use the commentApprove mutation to:
Once approved, the comment becomes visible to all store visitors.
Permanently removes a comment from a blog article.
For example, when a comment contains spam links or inappropriate language that violates store policies, merchants can delete it entirely.
Use the commentDelete mutation to:
Deletion is permanent and can't be undone.
Reverses a spam classification on a comment, restoring it to normal moderation status. This mutation allows merchants to change their decision when a comment has been manually marked as spam.
For example, when a merchant reviews comments marked as spam and finds a legitimate customer question, they can use this mutation to restore the comment's normal status and make it eligible for approval.
Use the commentNotSpam mutation to:
This action changes the comment's status from spam back to pending, where it can then be approved or managed according to standard moderation practices.
Marks a comment as spam, removing it from public view. This mutation enables merchants to quickly handle unwanted promotional content, malicious links, or other spam that appears in blog discussions.
For example, when a comment contains suspicious links to unrelated products or services, merchants can mark it as spam to immediately hide it from customers.
Use the commentSpam mutation to:
Spam-marked comments can be reviewed later and potentially restored using the commentNotSpam mutation if they were incorrectly classified.
Adds an existing Customer as a contact to a Company. Companies are business entities that make purchases from the merchant's store. Use this mutation when you have a customer who needs to be associated with a B2B company to make purchases on behalf of that company.
The mutation returns the newly created CompanyContact that links the customer to the company. After assignment, the customer becomes a company contact who can place orders on behalf of the company with access to any catalogs, pricing, and payment terms configured for the company's locations.
Creates a Company for B2B commerce. This mutation creates the company and can optionally create an initial CompanyContact and CompanyLocation in a single operation. Company contacts are people who place orders on behalf of the company. Company locations are branches or offices with their own billing and shipping addresses.
Note: Creating a company without a
namereturns an error.
Learn more about creating companies for B2B.
Creates a new location for a Company. Company locations are branches or offices where B2B customers can place orders with specific pricing, catalogs, and payment terms.
Creates a company location. Each location can have its own billing and shipping addresses, tax settings, and buyer experience configuration. You can assign staff members and CompanyContact objects to manage the location.
Updates a company location's information and B2B checkout settings. Company locations are branches or offices where CompanyContact members place orders on behalf of the company. Contacts must be assigned to a location through roleAssignments to place orders.
The mutation modifies details such as the location's name, contact information, preferred locale, and internal notes. You can also configure the B2B checkout experience through BuyerExperienceConfiguration settings that control whether orders require merchant review, PaymentTermsTemplate settings, shipping address editing permissions, and DepositConfiguration requirements.
Learn more about managing company locations.
Updates a Company with new information. Companies represent business customers that can have multiple contacts and locations with specific pricing, payment terms, and checkout settings.
The mutation accepts the company's ID and an input object containing the fields to update. You can modify the company name, add or update internal notes, set an external ID for integration with other systems, or adjust the customer relationship start date.
Learn more about building B2B features.
Creates a new MailingAddress for a Customer. You can optionally set the address as the customer's default address.
You can only add addresses to existing customers. Each customer can have multiple addresses.
Updates a Customer's MailingAddress. You can modify any field of the address and optionally set it as the customer's default address.
Creates a new Customer in the store.
Accepts customer details including contact information, marketing consent preferences, and tax exemptions through the CustomerInput input object. You can also associate metafields and tags to organize and extend customer data.
Apps using protected customer data must meet Shopify's protected customer data requirements.
Deletes a Customer from the store. You can only delete customers who haven't placed any orders.
Apps using protected customer data must meet Shopify's protected customer data requirements.
Updates a Customer's email marketing consent information. The customer must have an email address to update their consent. Records the marketing state (such as subscribed, pending, unsubscribed), opt-in level, and when and where the customer gave or withdrew consent.
Generates a one-time activation URL for a Customer whose legacy customer account isn't yet enabled. Use this after importing customers or creating accounts that need activation.
The generated URL expires after 30 days and becomes invalid if you generate a new one.
Note: The generated URL only works when legacy customer accounts are enabled on the shop. It only works for customers with disabled or invited
account states. Attempting to generate a URL for an already-enabled customer returns an error.
Creates a customer payment method using identifiers from remote payment gateways like Stripe, Authorize.Net, or Braintree. Imports existing payment methods from external gateways and associates them with Customer objects in Shopify.
The operation processes payment methods asynchronously. The returned CustomerPaymentMethod initially has incomplete details while Shopify validates and processes the remote gateway information. Use the customerPaymentMethod query to retrieve the payment method status until all details are available or the payment method is revoked.
Learn more about migrating customer payment methods from remote gateways.
Sends an email invitation for a customer to create a legacy customer account. The invitation lets customers set up their password and activate their account in the online store.
You can optionally customize the email content including the subject, sender, recipients, and message body. If you don't provide email customization, the store uses its default account invitation template.
Note: The invite only works when legacy customer accounts are enabled on the shop.
Updates a customer's SMS marketing consent information. The customer must have a phone number on their account to receive SMS marketing.
You can set whether the customer subscribes or unsubscribes to SMS marketing and specify the opt-in level. Optionally include when the consent was collected and which location collected it.
Updates a Customer's attributes including personal information and tax exemptions.
Apps using protected customer data must meet Shopify's protected customer data requirements.
Creates a DelegateAccessToken with a subset of the parent token's permissions.
Delegate access tokens enable secure permission delegation to subsystems or services that need limited access to shop resources. Each token inherits only the scopes you specify, ensuring subsystems operate with minimal required permissions rather than full app access.
Learn more about delegating access tokens to subsystems.
Creates a DeliveryProfile that defines shipping rates for specific products and locations.
A delivery profile groups products with their shipping zones and rates. You can associate profiles with SellingPlanGroup objects to customize shipping for subscriptions and pre-orders. Each profile contains DeliveryProfileLocationGroup objects that specify which Location objects ship to which DeliveryZone objects with specific DeliveryMethodDefinition objects and rates.
Learn more about building delivery profiles.
Updates a DeliveryProfile's configuration, including its shipping zones, rates, and associated products.
Modify location groups to control which fulfillment Location objects serve specific geographic areas. Add or remove shipping zones with custom countries and provinces. Create or update shipping methods with rate definitions and delivery conditions. Associate or dissociate ProductVariant objects and SellingPlanGroup objects to determine which products use this profile's shipping rules.
The mutation supports partial updates through dedicated input fields for creating, updating, and deleting specific components without affecting the entire profile structure.
Learn more about building delivery profiles.
Sends an invoice email for a DraftOrder. The invoice includes a secure checkout link for reviewing and paying for the order. Use the email argument to customize the email, such as the subject and message.
Creates a webhook subscription that notifies your App when specific events occur in a shop. Webhooks push event data to your endpoint immediately when changes happen, eliminating the need for polling.
This mutation configures webhook delivery to an Amazon EventBridge partner event source. You can filter events using Shopify API search syntax to receive only relevant webhooks, control which data fields are included in webhook payloads, and specify metafield namespaces to include.
Note:
The Webhooks API version configured in your app determines the API version for webhook events. You can't specify it per subscription.
Building an app? If you only use app-specific webhooks, you won't need this. App-specific webhook subscriptions specified in your shopify.app.toml may be easier. They are automatically kept up to date by Shopify & require less maintenance. Please read About managing webhook subscriptions.
Changes the location which is assigned to fulfill a number of unfulfilled fulfillment order line items.
Moving a fulfillment order will fail in the following circumstances:
Line items which have already been fulfilled can't be re-assigned
and will always remain assigned to the original location.
You can't change the assigned location while a fulfillment order has a
request status
of SUBMITTED, ACCEPTED, CANCELLATION_REQUESTED, or CANCELLATION_REJECTED.
These request statuses mean that a fulfillment order is awaiting action by a fulfillment service
and can't be re-assigned without first having the fulfillment service accept a cancellation request.
This behavior is intended to prevent items from being fulfilled by multiple locations or fulfillment services.
First scenario: Re-assign all line items belonging to a fulfillment order to a new location.
In this case, the
assignedLocation
of the original fulfillment order will be updated to the new location.
Second scenario: Re-assign a subset of the line items belonging to a fulfillment order to a new location.
You can specify a subset of line items using the fulfillmentOrderLineItems parameter
(available as of the 2023-04 API version),
or specify that the original fulfillment order contains line items which have already been fulfilled.
If the new location is already assigned to another active fulfillment order, on the same order, then
a new fulfillment order is created. The existing fulfillment order is closed and line items are recreated
in a new fulfillment order.
Creates a new GiftCard with a specified initial value. You can assign the gift card to a Customer or create it without assignment for manual distribution.
You can customize the gift card with an optional code, expiration date, and internal note. If you don't provide a code, the system generates a random 16 character alphanumeric code. The mutation also supports scheduling gift card notifications to recipients, with a personalized message, through the recipientAttributes field on the GiftCardCreateInput input object.
Enables local pickup for a location so customers can collect their orders in person. Configures the estimated pickup time that customers see at checkout and optional instructions for finding or accessing the pickup location.
Creates a Market to deliver customized shopping experiences. Markets define various aspects of the buyer experience including pricing, product availability, custom content, inventory and fulfillment priorities, and payment methods.
Define conditions to match buyers by region, company location, retail location, or other criteria. Configure MarketCurrencySettings to control currency behavior. Set MarketPriceInclusions to determine tax and duty display. Assign Catalog objects and MarketWebPresence configurations to control product availability and SEO strategy.
Learn more about Shopify Markets.
Updates a Menu for display on the storefront. Modifies the menu's title and navigation structure, including nested MenuItem objects. You can update the handle for non-default menus.
The items argument accepts a list of menu items with their nested structure. Each item can include nested items to create multi-level navigation hierarchies. Default menus have restricted updates—you can't change their handles.
Creates a MetafieldDefinition that establishes structure and validation rules for metafields. The definition specifies the data type, validation constraints, and access permissions for metafields with a given namespace and key combination.
When you create a new definition, the system validates any existing unstructured metafields matching the same owner type, namespace, and key against it. The system updates each valid metafield's type to match the definition. Invalid metafields remain unchanged but must conform to the definition when updated.
Learn more about creating metafield definitions.
Deletes a MetafieldDefinition. You can identify the definition by providing either its owner type, namespace, and key, or its global ID.
When you set deleteAllAssociatedMetafields to true, the mutation asynchronously deletes all Metafield objects that use this definition. This option must be true when deleting definitions under the $app namespace.
Learn more about deleting metafield definitions.
Updates a MetafieldDefinition's configuration and settings. You can modify the definition's name, description, validation rules, access settings, capabilities, and constraints.
The mutation updates access settings that control visibility across different APIs, such as the GraphQL Admin API, Storefront API, and Customer Account API. It also enables capabilities like admin filtering or unique value validation, and modifies constraints that determine which resource subtypes the definition applies to.
Note: The type, namespace, key, and owner type identify the definition and so can't be changed.
Learn more about updating metafield definitions.
Deletes Metafield objects in bulk by specifying combinations of owner ID, namespace, and key.
Returns the identifiers of successfully deleted metafields. If a specified metafield doesn't exist, then the mutation still succeeds but returns null for that identifier in the response.
Creates a metaobject entry based on an existing MetaobjectDefinition. The type must match a definition that already exists in the shop.
Specify field values using key-value pairs that correspond to the field definitions. The mutation generates a unique handle automatically if you don't provide one. You can also configure capabilities like publishable status to control the metaobject's visibility across channels.
Learn more about managing metaobjects.
Creates a metaobject definition that establishes the structure for custom data objects in your store. The definition specifies the fields, data types, and access permissions that all Metaobject entries of this type share.
Use the type field to create a unique namespace for your metaobjects. Prefix the type with $app: to reserve the definition for your app's exclusive use. The definition can include capabilities like publishable status or translation eligibility, to extend how metaobjects integrate with Shopify's features.
Learn more about managing metaobjects.
Updates a MetaobjectDefinition's configuration and field structure. You can modify the definition's name, description, display name key, access controls, and capabilities, as well as those of all its fields.
The mutation supports reordering fields when resetFieldOrder is true, which arranges submitted fields first followed by alphabetized omitted fields.
Learn more about managing metaobjects.
Updates a Metaobject with new field values, handle, or capabilities. Metaobjects are custom data structures that extend Shopify's data model.
You can modify field values mapped to the metaobject's MetaobjectDefinition, update the handle for a unique identifier, and adjust capabilities like publishing status. When updating the handle, you can optionally create a redirect from the old handle to maintain existing references.
Creates or updates a Metaobject based on its handle. If a metaobject with the specified handle exists, the mutation updates it with the provided field values. If no matching metaobject exists, the mutation creates a new one.
The handle serves as a unique identifier within a metaobject type. Field values map to the MetaobjectDefinition's field keys and overwrite existing values during updates.
Records a manual payment for an Order that isn't fully paid. Use this mutation to track payments received outside the standard checkout process, such as cash, check, bank transfer, or other offline payment methods.
You can specify the payment amount, method name, and when it was processed.
Permanently deletes an Order from the store.
You can only delete specific order types. Other orders you can cancel using the orderCancel mutation instead.
Caution:
This action is irreversible. You can't recover deleted orders.
Adds a custom shipping line to an Order during an edit session. Specify the shipping title and price to create a new ShippingLine.
Returns a CalculatedOrder showing the order with edits applied but not yet saved. To save your changes, use the orderEditCommit mutation.
Learn more about editing existing orders.
Sets the quantity of a line item on an order that's being edited. Use this mutation to increase, decrease, or remove items by adjusting their quantities.
Setting the quantity to zero effectively removes the line item from the order. The item still exists as a data structure with zero quantity. When decreasing quantities, you can optionally restock the removed items to inventory by setting the restock parameter to true.
Learn more about editing workflows for existing orders.
Creates a Page for the online store.
Pages contain custom content like "About Us" or "Contact" information that merchants display outside their product catalog. The page requires a title and can include HTML content, publishing settings, and custom template suffixes. You can control visibility through the isPublished flag or schedule publication with a specific date.
The mutation returns the complete page object upon successful creation or validation errors if the input is invalid.
Permanently deletes a page from the online store.
For example, merchants might delete seasonal landing pages after campaigns end, or remove outdated policy pages when terms change.
Use the pageDelete mutation to:
The deletion is permanent and returns the deleted page's ID for confirmation.
Updates an existing page's content and settings.
For example, merchants can update their "Shipping Policy" page when rates change, or refresh their "About Us" page with new team information.
Use the pageUpdate mutation to:
The mutation supports partial updates, allowing specific changes while preserving other page properties.
Creates a product bundle that groups multiple Product objects together as components. The bundle appears as a single product in the store, with its price determined by the parent product and inventory calculated from the component products.
The mutation runs asynchronously and returns a ProductBundleOperation object to track the creation status. Poll the operation using the productOperation query to determine when the bundle is ready.
Learn more about creating product fixed bundles.
Creates new bundles, updates component quantities in existing bundles, and removes bundle components for one or multiple ProductVariant objects.
Each bundle variant can contain up to 30 component variants with specified quantities. After an app assigns components to a bundle, only that app can manage those components.
Note:
For most use cases, useproductBundleCreateinstead, which creates product fixed bundles.productVariantRelationshipBulkUpdateis for variant fixed bundles, where each variant has its own component configuration.
Deletes multiple variants in a single Product. Specify the product ID and an array of variant IDs to remove variants in bulk. You can call this mutation directly or through the bulkOperationRunMutation mutation. Returns the updated product and any UserError objects.
Creates a webhook subscription that notifies your App when specific events occur in a shop. Webhooks push event data to your endpoint immediately when changes happen, eliminating the need for polling.
This mutation configures webhook delivery to a Google Cloud Pub/Sub topic. You can filter events using Shopify API search syntax to receive only relevant webhooks, control which data fields are included in webhook payloads, and specify metafield namespaces to include.
Note:
The Webhooks API version configured in your app determines the API version for webhook events. You can't specify it per subscription.
Building an app? If you only use app-specific webhooks, you won't need this. App-specific webhook subscriptions specified in your shopify.app.toml may be easier. They are automatically kept up to date by Shopify & require less maintenance. Please read About managing webhook subscriptions.
Creates a return request that requires merchant approval before processing. The return has its status set to REQUESTED and the merchant must approve or decline it.
Use this mutation when customers initiate returns that need review. After creating a requested return, use returnApproveRequest to approve it or returnDeclineRequest to decline it.
For returns that should be immediately open for processing, use the returnCreate mutation instead.
Learn more about building return management workflows.
Adds funds to a StoreCreditAccount by creating a StoreCreditAccountCreditTransaction. The mutation accepts either a store credit account ID, a Customer ID, or a CompanyLocation ID. When you provide a customer or company location ID, it automatically creates an account if one doesn't exist for the specified currency.
Store credit accounts are currency-specific. A single owner can have multiple accounts, each holding a different currency. Use the most appropriate currency for the given store credit account owner.
Credits can optionally include an expiration date.
Creates a storefront access token that delegates unauthenticated access scopes to clients using the Storefront API. The token provides public access to storefront resources without requiring customer authentication.
Each shop can have up to 100 active StorefrontAccessToken objects. Headless storefronts, mobile apps, and other client applications typically use these tokens to access public storefront data.
Learn more about building with the Storefront API.
Creates or updates theme files in an online store theme. This mutation allows batch operations on multiple theme files, either creating new files or overwriting existing ones with the same filename.
Note: You can process a maximum of 50 files in a single request.
Each file requires a filename and body content. The body must specify a type with the corresponding value. The mutation returns a job field for tracking asynchronous operations and an upsertedThemeFiles field with details about the processed files.
Creates or updates translations for a resource's translatable content.
Each translation requires a digest value from the resource's translatable content. Use the translatableResource query to get a resource's translatable content and digest values before creating translations. You can optionally scope translations to specific markets using the marketId field in each translation input.
Learn more about managing translations.
Creates a webhook subscription that notifies your App when specific events occur in a shop. Webhooks push event data to your endpoint immediately when changes happen, eliminating the need for polling.
The subscription configuration supports multiple endpoint types including HTTPS URLs, Google Pub/Sub topics, and AWS EventBridge event sources. You can filter events using Shopify API search syntax to receive only relevant webhooks, control which data fields are included in webhook payloads, and specify metafield namespaces to include.
Note:
The Webhooks API version configured in your app determines the API version for webhook events. You can't specify it per subscription.
Building an app? If you only use app-specific webhooks, you won't need this. App-specific webhook subscriptions specified in your shopify.app.toml may be easier. They are automatically kept up to date by Shopify & require less maintenance. Please read About managing webhook subscriptions.
Deletes a WebhookSubscription and stops all future webhooks to its endpoint. Returns the deleted subscription's ID for confirmation.
Building an app? If you only use app-specific webhooks, you won't need this. App-specific webhook subscriptions specified in your shopify.app.toml may be easier. They are automatically kept up to date by Shopify & require less maintenance. Please read About managing webhook subscriptions.
Updates a webhook subscription's configuration. Modify the endpoint URL, event filters, included fields, or metafield namespaces without recreating the subscription.
The mutation accepts a WebhookSubscriptionInput that specifies the new configuration. You can switch between endpoint types (HTTP, Pub/Sub, EventBridge) by providing a different URI format. Updates apply atomically without interrupting webhook delivery.
Building an app? If you only use app-specific webhooks, you won't need this. App-specific webhook subscriptions specified in your shopify.app.toml may be easier. They are automatically kept up to date by Shopify & require less maintenance. Please read About managing webhook subscriptions.
The input fields for duplicating a collection.
Represents an in-progress collection duplication operation. Collection duplication is a synchronous operation for simple collections, and an asynchronous operation for collections containing too many products to process synchronously.
The role a collection plays in a duplication operation.
Return type for collectionDuplicate mutation.
Errors related to collection duplication.
Possible error codes that can be returned by CollectionDuplicateUserError.
Represents operations involving a collection.
Represents a user error that occurs while moving a fulfillment order.
Possible error codes that can be returned by FulfillmentOrderMoveFulfillmentOrderMoveUserError.
The input fields required to adjust the available quantity of a product variant at a location.
A standardized reason for a return.
An auto-generated type for paginating through multiple ReturnReasonDefinitions.
An auto-generated type which holds one ReturnReasonDefinition and a cursor during pagination.
The set of valid sort keys for the ReturnReasonDefinition query.
Third-party app subscription overrides for a shop.
LIMIT_REACHEDLIMIT_REACHEDSTATUSactiveOperationsCollection duplicate operations involving this collection, either as a source (copying products from this collection to another) or a target (copying products to this collection from another).
legacyModelegacyModeBlockedlegacyModeProfilesuserErrorsSERVICE_UNAVAILABLECHANGE_FROM_QUANTITY_STALESERVICE_UNAVAILABLECHANGE_FROM_QUANTITY_STALECHANGE_FROM_QUANTITY_STALESERVICE_UNAVAILABLECHANGE_FROM_QUANTITY_STALEsuggestedReturnReasonDefinitionsA list of suggested standardized return reasons for the given line item.
CANNOT_ADD_COUNTRY_CONDITION_TO_PROVINCE_MARKETstaffMemberThe staff member that created the return.
transactionsThe order transactions created from the return.
returnReasonDefinitionThe standardized reason for why the item is being returned.
returnReasonDefinitionThe standardized reason for why the item is being returned.
thirdPartyAppSubscriptionOverridebillingAddressshopAddressThe shop's address information as it will appear to buyers.
NOT_FOUNDhandleThe handle of the Shopify Function.
ACH_BANK_FAILURE_DEBIT_FEEACH_BANK_FAILURE_DEBIT_REVERSAL_FEEAGENTIC_FEE_TAX_DEBITAGENTIC_FEE_TAX_DEBIT_REVERSALAGENTIC_FEE_TAX_CREDITAGENTIC_FEE_TAX_CREDIT_REVERSALREFERRAL_FEEREFERRAL_FEE_TAXMANAGED_MARKETS_MERCHANT_OF_RECORD_ACCOUNT_FX_DRIFT_CREDITMANAGED_MARKETS_MERCHANT_OF_RECORD_ACCOUNT_FX_DRIFT_CREDIT_REVERSALMANAGED_MARKETS_MERCHANT_OF_RECORD_ACCOUNT_FX_DRIFT_DEBITMANAGED_MARKETS_MERCHANT_OF_RECORD_ACCOUNT_FX_DRIFT_DEBIT_REVERSALMANAGED_MARKETS_WEBHOOK_ADJUSTMENT_CREDITMANAGED_MARKETS_WEBHOOK_ADJUSTMENT_DEBITMANAGED_MARKETS_WEBHOOK_ADJUSTMENT_CREDIT_REVERSALMANAGED_MARKETS_WEBHOOK_ADJUSTMENT_DEBIT_REVERSALAMOUNT_TOO_LARGEMERCHANT_ACCOUNT_ERRORINVALID_BILLING_ADDRESSARTICLE_IMAGECOLLECTION_IMAGEreturnReasonDefinitionThe standardized reason for why the item is being returned.