9/5/2025, 8:31:44 PM
Developers should note that metaobjects now expose an "adminFilterable" capability, with new types MetaobjectFieldCapabilityAdminFilterable and MetaobjectFieldDefinitionCapabilities added. CustomerPaymentMethod gains a paginated "mandates" field for payment mandates and the previous resourceId/resourceType fields are removed; the MandateResourceType enum changes, dropping CARD_ON_FILE and adding CREDENTIAL_ON_FILE. Images and MediaImage now include a "translations" field that supports locale and marketId filtering. The stagedUploadsCreate mutation’s description adds a 10 MB payload limit, and the metafieldsSet mutation also notes the same limit. Queries such as channel, domain, market, orders, and sellingPlanGroup have updated descriptions for clarity, though channel remains deprecated in favor of publication. Finally, new enum values (COLLECTION_NOT_FOUND, MANUALLY_SORTED_COLLECTION, INVALID_MOVE) appear in CollectionReorderProductsUserErrorCode, and PaymentTerms receives a new "canPayEarly" boolean field. These changes affect how your queries and mutations construct request payloads and handle responses in the latest unstable schema.
Returns a Channel resource by ID.
Returns a CustomerSegmentMembersQuery resource by ID.
Returns a Domain resource by ID.
Returns a Market resource by ID.
Returns a list of orders placed in the store, including data such as order status, customer, and line item details.
Use the orders query to build reports, analyze sales performance, or automate fulfillment workflows. The orders query supports pagination,
sorting, and filtering.
Returns a SellingPlanGroup resource by ID.
Creates a one-time charge for app features or services that don't require recurring billing. This mutation is ideal for apps that sell individual features, premium content, or services on a per-use basis rather than subscription models.
For example, a design app might charge merchants once for premium templates, or a marketing app could bill for individual campaign setups without ongoing monthly fees.
Use the AppPurchaseOneTimeCreate mutation to:
The mutation returns a confirmation URL that merchants must visit to approve the charge. Test and development stores are not charged, allowing safe testing of billing flows.
Explore one-time billing options on the app purchases page.
Cancels an active app subscription, stopping future billing cycles. The cancellation behavior depends on the replacementBehavior setting - it can either disable auto-renewal (allowing the subscription to continue until the end of the current billing period) or immediately cancel with prorated refunds.
When a merchant decides to discontinue using subscription features, this mutation provides a clean cancellation workflow that respects billing periods and merchant expectations.
Use the AppSubscriptionCancel mutation to:
The cancellation timing and merchant access depends on the replacementBehavior setting and the app's specific implementation of subscription management.
For subscription lifecycle management and cancellation best practices, consult the subscription management guide.
Extends the trial period for an existing app subscription, giving merchants additional time to evaluate premium features before committing to paid billing. This mutation provides flexibility in trial management and can improve conversion rates by accommodating merchant needs.
Trial extensions are particularly valuable when merchants need more time to fully evaluate complex features, experience technical setup delays, or require additional approval processes within their organization before committing to paid subscriptions.
Use the AppSubscriptionTrialExtend mutation to:
The extension modifies the existing trial end date, allowing continued access to subscription features without immediate billing. This approach maintains subscription continuity while providing merchants the flexibility they need for thorough feature evaluation.
Trial extension strategies and conversion techniques are covered in the offer free trials guide.
Sets metafield values. Metafield values will be set regardless if they were previously created or not.
Allows a maximum of 25 metafields to be set at a time, with a maximum total request payload size of 10MB.
This operation is atomic, meaning no changes are persisted if an error is encountered.
As of 2024-07, this operation supports compare-and-set functionality to better handle concurrent requests.
If compareDigest is set for any metafield, the mutation will only set that metafield if the persisted metafield value matches the digest used on compareDigest.
If the metafield doesn't exist yet, but you want to guarantee that the operation will run in a safe manner, set compareDigest to null.
The compareDigest value can be acquired by querying the metafield object and selecting compareDigest as a field.
If the compareDigest value does not match the digest for the persisted value, the mutation will return an error.
You can opt out of write guarantees by not sending compareDigest in the request.
Creates staged upload targets for file uploads such as images, videos, and 3D models.
Use the stagedUploadsCreate mutation instead of direct file creation mutations when:
The stagedUploadsCreate mutation is the first step in Shopify's secure two-step upload process:
Step 1: Create staged upload targets (this mutation)
Step 2: Upload files and create assets
resourceUrl as the originalSource in subsequent mutations like fileCreate.This approach provides better performance for large files, handles network interruptions gracefully,
and ensures secure file transfers to Shopify's storage infrastructure.
Note:
File size is required when uploadingVIDEOorMODEL_3D
resources.
After creating staged upload targets, complete the process by:
url using the providedparametersresourceUrloriginalSource in mutations such as:fileCreate:productUpdate:Learn more about uploading media to Shopify.
Information about the admin filterable capability.
The input fields for enabling and disabling the admin filterable capability.
Capabilities available for a metaobject field definition.
The input fields for creating capabilities on a metaobject field definition.
A payment mandate with resource information, representing the permission
the owner of the payment instrument gives to the merchant to debit it
for specific resources (e.g., Order, Subscriptions).
An auto-generated type for paginating through multiple PaymentMandateResources.
An auto-generated type which holds one PaymentMandateResource and a cursor during pagination.
installUrllineItemsSubtotalPricetotalLineItemsPriceSetcollectionPublicationsV3productPublicationsV3COLLECTION_NOT_FOUNDMANUALLY_SORTED_COLLECTIONINVALID_MOVEresourceIdresourceTypemandatesThe mandates associated with the payment method.
lineItemsSubtotalPricetotalLineItemsPriceSettranslationsThe published translations associated with the resource.
quantitiesnamequantityupdatedAtCARD_ON_FILECREDENTIAL_ON_FILEtranslationsThe published translations associated with the resource.
capabilitiesCapabilities available for this metaobject field definition.
canPayEarlyWhether the payment can be made before the due date. When true, allows early payment of the invoice. When false, the payment must be made according to the payment schedule.
collectionPublicationsV3publicationStatusOnChannelpublicationStatusOnChannel