shopify_flutter 4.1.0

A Flutter package to seamlessly connect your Shopify store with your app.

4.1.0

Adds ShopifyStore.getVariantsByIds, a variant-level price lookup.

getProductsByIds matches ... on Product, so passing variant ids returns empty entries rather than an error, and the product queries cannot stand in either: getProductsQuery nests products(first: 250) -> variants(first: 250) -> sellingPlanAllocations(first: 250), which is orders of magnitude past the Storefront API's 1000-point query-cost limit and comes back as a bare "Internal error". The new query selects no nested connections, so it costs roughly one point per id.

Like the other queries it runs under @inContext(country:), so the prices are the presentment prices for the market ShopifyLocalization.countryCode selects. Ids that don't resolve to a variant are skipped.

4.0.1

Example app migrated to material_ui. Material and Cupertino were decoupled from the Flutter SDK in 3.47 into the standalone material_ui / cupertino_ui packages, so the example now imports package:material_ui/material_ui.dart instead of package:flutter/material.dart. The library itself is untouched and its constraints are unchanged; only the example's floor moves, to Dart 3.12 / Flutter 3.44 — what material_ui 1.0.0 requires.

4.0.0

Removes the Checkout API, which no longer exists on the Storefront API, plus a round of parsing and error-handling fixes.

Breaking

• Checkout API removed. Shopify deprecated it in 2024-04, removed the checkout types in 2024-07 and shut the endpoints off on April 1, 2025, so none of this worked on a supported API version — and pinning storefrontApiVersion to an old checkout-era version (≤ 2024-04) does not bring it back, because Shopify falls forward from sunset versions to a supported one whose schema has no Checkout type (verified: __type(name: "Checkout") is null on every version from 2024-01 onward). Gone: ShopifyCheckout, 26 GraphQL documents, and the checkout-only models (Checkout, TokanizedCheckout, AppliedGiftCards, AvailableShippingRates, ShippingRates, LineItem, LineItems, ProductVariantCheckout, the checkout Attribute) plus JsonHelper.lineItems.
  • Migration: use ShopifyCart and send the buyer to cart.checkoutUrl, Shopify's documented replacement. Mobile apps can also use the Checkout Sheet Kit. The example app's cart tab shows the full flow: a Checkout button opens cart.checkoutUrl in a webview (checkout_webview.dart) and reports success back to the cart.
• Failures throw ShopifyException instead of a bare String. checkForError threw errorMessages.join('\n'), which is not an Exception, so it defeated both on ShopifyException and on Exception and escaped as an unhandled error. For socket errors, timeouts and HTTP failures graphqlErrors is empty, so the thrown value was the empty string and the cause was lost entirely; the linkException detail is now included. Code using a bare catch (e) is unchanged.
• Twelve methods narrowed from Future<List<X>?> to Future<List<X>> — every return path already produced a non-null list: getAllBlogs, getXArticlesSorted, getAllOrders, getAllPages, getProductsByIds, getNProducts, getProductRecommendations, getCollectionsByIds, getXCollectionsAndNProductsSorted, getXProductsAfterCursorWithinCollection, searchProducts, getXProductsOnQueryAfterCursor. Existing calls still compile; delete any ?? [], which now warns as dead code.
• Product.isAvailableForSale no longer requires quantityAvailable > 0. That marked purchasable products unavailable both on stores without the unauthenticated_read_product_inventory scope (where the value is null) and on stores that allow overselling, which report a negative quantity while availableForSale stays true. It now follows ProductVariant.availableForSale, the non-null authoritative flag.
• MailingAddress moved from src/checkout/ to src/mailing_address/. Only a deep src/ import is affected.

Fixed

• A failed access-token renewal no longer signs the user out. _renewAccessToken never checked for errors and fell back to an empty token, which _setShopifyUser treated as "no session" and deleted from memory and disk — an offline or rate-limited refresh silently logged the user out with no way back except re-entering credentials.
• A null quantityAvailable no longer wipes a product's variants. The field is nullable, was parsed into a non-null int, and the resulting error was swallowed by _getProductVariants, so affected stores got products with no variants and price 0.0. Null now reads as 0.
• Nullable Storefront fields no longer throw while parsing. Order.financialStatus/subtotalPrice/customerUrl/totalTax (a fully discounted order returns no tax) previously failed the entire order list; Page.onlineStoreUrl is null for unpublished pages; only id is non-null on MailingAddress, yet ShippingAddress required name, lastName, address1, city and country.
• Metafields are no longer dropped on unwrapped payloads. _getMetafieldList (on Product and Collection) read json['node']['metafields'] inside the branch reached only when there is no 'node' key, so getProductByHandle and getCollectionByHandle never returned the metafields they requested.
• getCollectionById no longer reports failures as "not found". It swallowed every error into null, making a bad token indistinguishable from a missing collection — and the not-found case worked only by letting the parse throw and discarding it. It now detects the unresolved node and returns null only for that.
• Collections.fromGraphJson no longer throws without pageInfo. hasNextPage had no default, unlike Products and Orders, so getCollectionsByIds threw type 'Null' is not a subtype of type 'bool'.
• Deprecated currency codes replaced. The symbol table listed BYR, STD and VEF but not their successors BYN, STN and VES, so those stores formatted every price as "null12.50". Unknown codes now fall back to the ISO code.
• Removed three unreachable fallbacks in getProductRecommendations, getCollectionsByIds and getCollectionByHandle. They discarded the real cause and returned values that cannot be constructed, always throwing a TypeError from outside the try.
• checkForError no longer passes a missing payload. A null data, or a null payload for the requested key, now raises instead of letting the caller dereference it into an opaque TypeError.
• getAllProductsOnQuery ignored its cursor argument — a local String? cursor shadowed the parameter, so every call restarted from page one.
• getAllOrders sent a read-only query through mutate(), bypassing the cache and ignoring ShopifyConfig.fetchPolicy. It now uses query().
• Eager pagination loops now stop on an empty page. A hasNextPage: true response with no edges left the cursor unchanged and re-issued the same request forever.
• Session writes are awaited. _setShopifyUser never awaited its SharedPreferences writes, so awaiting a sign-in or sign-out did not guarantee the token had reached, or left, disk.
• ShopifyException and AttributeInput are now exported. Both previously required reaching into src/ — updateCartAttributes could not be called without one.
• signInWithEmailAndPassword now surfaces Shopify's actual reason for a failed sign-in — a wrong password (customerUserErrors: UNIDENTIFIED_CUSTOMER), an unactivated account, rate limiting, or a missing access scope — instead of collapsing every failure to Exception('Invalid credentials'). The customerAccessTokenCreate mutation now requests customerUserErrors, and _createAccessToken runs checkForError.
• Two admin misconfiguration paths now raise a ShopifyException naming the missing config instead of an opaque error — deleteCustomer threw a bare String, and adminAccess: true without an admin token threw Null check operator used on a null value.
• Removed a duplicate parse of the same response in getAllProductsFromCollectionById and getAllProductsOnQuery, which ran the full product/variant parse twice per page.

Dependencies

• json_serializable moved from dependencies to dev_dependencies. It is a codegen tool with no runtime import, but as a regular dependency it pulled analyzer, build, build_config, dart_style, source_gen, source_helper, pub_semver and pubspec_parse into the runtime graph of every consuming app — and its analyzer pin is exactly what makes this package hard to resolve on older Flutter SDKs. The runtime closure is now just graphql_flutter, freezed_annotation, json_annotation, shared_preferences and intl.
• url_launcher removed — unused by the package and by the example.

Migration guide

• Remove any ShopifyCheckout references — code cleanup only; Shopify removed checkout server-side (endpoints shut off April 2025), so it works on no API version regardless of what storefrontApiVersion you set.
• Replace on String catch on a failed call with on ShopifyException catch (a bare catch (e) is unchanged).
• Delete any ?? [] after the twelve now-non-null list methods.
• Update deep MailingAddress imports: src/checkout/mailing_address/… → src/mailing_address/….

3.0.1

Added language code getter/setter in shopify_localization

3.0.0

Removes every deprecated Storefront API field the package still queried, migrating to the 2026-07 replacements. Because several of these change the shape of the public Dart models, this is a breaking release. This version now requires Storefront API 2026-07 or newer (it relies on Cart.lines.discountAllocations(lineLevelOnly:) and cart-level delivery, both added in 2026-07); the default storefrontApiVersion is already 2026-07.

Breaking

• ShopifyImage.originalSrc → ShopifyImage.url (Image.originalSrc/src were deprecated in favour of url). Affects every image across products, collections, articles and media.
• Option.values (List<String>) → Option.optionValues (List<ProductOptionValue>, each with id + name). New exported model ProductOptionValue. Mirrors ProductOption.values → optionValues in the API.
• Order.subtotalPriceV2/totalPriceV2/totalShippingPriceV2/totalTaxV2/totalRefundedV2 → subtotalPrice/totalPrice/totalShippingPrice/totalTax/totalRefunded (the *V2 money fields were deprecated).
• CartCost lost totalTaxAmount, totalTaxAmountEstimated, totalDutyAmount, totalDutyAmountEstimated. Shopify no longer returns tax/duty amounts on the cart ("no longer available and will be removed in a future version"), so these always returned null/false.
• Cart delivery addresses moved off the buyer identity:
  • Removed CartBuyerIdentity.deliveryAddressPreferences and CartBuyerIdentityInput.deliveryAddressPreferences (the input field was deprecated).
  • Cart gains delivery (CartDelivery → List<CartSelectableAddress>, each exposing id, selected, oneTimeUse, and a CartDeliveryAddress). New exported models: CartDelivery, CartSelectableAddress, CartDeliveryAddress.
  • CartInput gains delivery (CartDeliveryInput). New exported inputs: CartDeliveryInput, CartSelectableAddressInput, CartAddressInput, CartDeliveryAddressInput. These replace the removed DeliveryAddressInput (MailingAddressInput remains for other uses). Note the new delivery inputs take countryCode/provinceCode (e.g. AU/NSW) rather than full names.
  • New ShopifyCart.addDeliveryAddresses(cartId:, addresses:) (mutation cartDeliveryAddressesAdd) to add delivery addresses to an existing cart; updateBuyerIdentityInCart no longer accepts addresses.
• Removed the Market model and its export, and the market field on Localization and Country (Localization.market/Country.market were deprecated with no Storefront replacement).

Changed

• cartDiscountCodesUpdate: optional warnings (CartWarningCode errorCode + localized message) surfaced on CartDiscountCode. When a discount code is not applicable, the payload-level warnings (errorCode/errorMessage) are attached to the corresponding CartDiscountCode via copyWith after parsing. These fields are absent from the discountCodes JSON, so fromJson leaves them null.
• Line-level discountAllocations now requests lineLevelOnly: false so order-level allocations are included, and the deprecated cart-level Cart.discountAllocations selection was dropped (use the per-line allocations).
• Internal query fields migrated with no public-API impact: Image originalSrc→url in all documents, ProductVariant.priceV2/compareAtPriceV2→price/compareAtPrice, and productByHandle/blogByHandle/pageByHandle→product/blog/page.
• Updated the default storefrontApiVersion from 2024-07 to 2026-07. 2024-07 has been sunset since July 2025; Shopify serves requests for an unsupported version from the oldest supported version instead, so callers relying on the default were silently drifting across versions as each one sunset. Callers that already pass storefrontApiVersion explicitly should ensure it is 2026-07 or newer (see the requirement above).
• Fixed three GraphQL documents that were rejected by the Storefront API on every currently supported version:
  • getXCollectionsAndNProductsSorted declared $collectonMetafields (typo) but used $collectionMetafields, so the server rejected the document with Variable "$collectionMetafields" is not defined. The Dart caller was already passing the correctly spelled variable, so this method could never have succeeded.
  • getNArticlesSorted selected the removed Article.url field. Replaced with onlineStoreUrl, which is what the Article model already parses.
  • getCollectionByIdQuery passed a list to the single-collection lookup (collection(ids: $ids)); corrected to collection(id: $id). This query has no caller in the package.
• Fixed CartAddressInput serialization. It is a Storefront "one of" input (exactly one field may be present), but toJson emitted both copyFromCustomerAddressId and deliveryAddress, so adding a cart delivery address (via ShopifyCart.addDeliveryAddresses or CartInput.delivery) failed with 'CartAddressInput' requires exactly one argument, but 2 were provided. The unused (null) field is now omitted.
• Example app: builds on the Java 25 / AGP 9 toolchain (Gradle 9.6.1, AGP 9.3.0, built-in Kotlin); removed the hard-coded price filter on the collection tab that made collections appear empty; and fixed the Blog/Pages tabs spinning forever on a failed fetch (they now clear the spinner and show the error — e.g. a missing unauthenticated_read_content scope — or an empty state).
• Example app: the cart tab added productVariants.first regardless of whether that variant was purchasable. Shopify creates a line for an unavailable variant with quantity: 0 and reports no userErrors, so on stores whose first variant is out of stock every add showed up as a 0x line and the +/- buttons appeared dead. It now adds the first variant with availableForSale == true, marks out-of-stock products and lines, and reports it when Shopify clamps a requested quantity. (Pre-existing behaviour, not specific to 2026-07.)

Migration guide

• Replace image.originalSrc with image.url.
• Replace option.values (strings) with option.optionValues.map((v) => v.name).
• Replace order.totalPriceV2 etc. with order.totalPrice (drop the V2 suffix).
• Replace CartBuyerIdentityInput(deliveryAddressPreferences: [...]) with either CartInput(delivery: CartDeliveryInput(addresses: [...])) on create, or ShopifyCart.addDeliveryAddresses(...) on an existing cart, and read addresses back from cart.delivery.
• Remove any use of localization.market / country.market.

2.8.2

• Fix Shopify-side validation error Nullability mismatch on variable $discountCodes and argument discountCodes ([String!] / [String!]!) from ShopifyCart.updateCartDiscountCodes against newer Storefront API versions (e.g. 2026-01) that promoted the cartDiscountCodesUpdate argument from [String!] to [String!]!. The SDK's mutation document still declared the variable as the older nullable type, so the server rejected the request. Promoted the variable to [String!]!. Per the GraphQL spec ("All Variable Usages Are Allowed"), a non-null variable is also valid for the older nullable argument shape, so this change is forward- and backward-compatible across Storefront API versions; the Dart caller signature (required List<String> discountCodes) already enforces non-null.

2.8.1

• Added queryRequestTimeout to ShopifyConfig.setConfig to set the GraphQL query timeout. GraphQLClient default timeout of 5s causes issue on late HTTP requests

2.8.0

• Added storefrontCache and adminCache optional parameters to ShopifyConfig.setConfig, allowing callers to inject a custom GraphQLCache (e.g. backed by HiveStore for disk persistence) for the Storefront and Admin API clients. Defaults preserve the previous in-memory behaviour.

2.7.0

• Added category information in all product related gql.
• Updated example to show the product category

2.6.3

• Updated the "if" conditions with the null aware operator "?"

2.6.1

• Update dependencies and upgrade to next freezed version
• Upgraded example app android platform

2.6.0

• Removed published and updated date from product

2.5.6

• Added sellingPlanAllocations to the Order Item Variant

2.5.5

• GraphQL Intl plugin compatibility
• Generate toJson for nested models
• Updated example app

2.5.4

• Update type of adjustmentPercentage to num so that it works for both int and double data types

2.5.3

• Added reverse flag in cart
  • If the reverse is set to true, the line items in the cart will be in reverse order.

2.5.2

• Made phone number option on user/customer creation
• Better error handling
• Updated readme file for better experience

2.5.1

• updateCartAttributes() mutation fix

2.5.0

• Added
  • attributes to cart
  • attributes to cart line items
  • updateCartAttributes() to update the attributes associated to cart

2.4.0

• Added metafield support to products and collections

2.3.3

• Minor fixes in product selling plan allocations

2.3.1

• Upgraded SDK version to '>=3.3.0 <4.0.0'
• Upgraded Intl version

2.3.0

• Added Selling Plan Allocations in product variants

2.2.8

• Cart Line Input Model updated

2.2.7

• Cart Customer: made properties nullable
  • phone, email, firstName and lastName

2.2.6

• Cart issue resolved when passed customer access token

2.2.5

• Resolved cartline issue when adding line items
• Upgraded flutter_inappwebview to latest in example app

2.2.3

• Added cart line cost in cart line items Graph Query

2.2.1

• moved countryCode to ShopifyLocalization class. This class is responsible to handle the store localization
  • If set as 'NP', all the prices will be in the form of Nepali Rupees
• Added discountAllocations in Cart and CartLine.lines items

2.2.0

• Added a feature to set the desired country code to display the prices
  • In ShopifyConfig, set the decired county code to property countryCode.
    • If left null, the shopify default price currency will be applied
    • If set as 'NP', all the prices will be in the form of Nepali Rupees
• Updated example app to reflect the changes.

2.1.2

• made phone as required while creating user using createUserWithEmailAndPassword

2.1.1

• ability to get the cached current user or updated user from ShopifyAuth.currentUser using a boolean value of forceRefresh
• added product in cart line merchandise to access the product properties like title.

2.1.0

• Removed depreciated proprty lastIncompleteCheckout from ShopifyUser

2.0.1

• Updated default api version to 2024-01
• Added code comments for better pub score

2.0.0

• Deprecated ShopifyCheckout from Shopify API version 2024-07
• Introduced ShopifyCart to perform cart operation
• Introduced ShopifyOrder to access customer orders

1.5.21

• Add order cancel fields

1.5.20

• Added ShopifyLocalization
• Fix blogByHandle query

1.5.19

• minor update in example and getAllOrders

1.5.18

• increase the number of varients in products
• auto renew token in ShopifyAuth.instance.currentCustomerAccessToken if it is about to expire.
• added media list in products

1.5.17

• formatted the code to inscreate the pub score

1.5.16

• code refactoring

1.5.15

• updated example

1.5.14

• added cursor to the getSearchedProducts query.

1.5.13

• null check for shipping address in orders
• made first name nullable in shipping address

1.5.12

• User nullable issue when calling currentUser() after signup
  • Issue 50

1.5.11

• formatted code using dart format . to increase pub score

1.5.10

• updated checkoutCompleteWithTokenizedPaymentV3() to return TokanizedCheckout model
• updated shop_tab.dart in example to showcase the use of checkoutCompleteWithTokenizedPaymentV3()

1.5.9

• added a support for locale.

1.5.8

• Made SKU nullable in Product Variant Checkout
  • Issue 43

1.5.7

• Made SKU nullable in Product Variant
  • Issue 43

1.5.6

• added foormatted price in product price
• added cachePolicy in ShopifyConfig for GraphQL queries
• some bugs fixes

1.5.5

• added default address in shopify user
• added method customerDefaultAddressUpdate in ShopifyCustomer class to update the default address

1.5.4

• Some bugs fixes Issue 34

1.5.3

• updates to increase pub points

1.5.2

• updated dependencies to match latest flutter 3.16.5

1.5.1

• updated getAllCollections
• optimized auto-generated files

1.5.0

• optimized checkout and product models

1.4.4

• update example with demo chekout flow in shop tab

1.4.3

• updated example with add, update and remove lineitems for checkout

1.4.2

• Minor fixes

1.4.1

• Fixed issues
  • Product fromJson/toJson

1.4.0

• Fixed issues
  • Typecast error
  • Include selectedOptions on ProductVariantCheckout in Order
  • getAllOrdersQuery is missing product fields for lineItem variants

1.3.1

• Image issue in Collection resolved
• Order Model updated

1.3.0

• added search product query and option for filters in searchProducts and getXProductsAfterCursorWithinCollection.

1.2.0

• phone and acceptsMarketing can be passed in createUserWithEmailAndPassword
• bug fixes
• updated code documentation

1.1.3

• now you can get the token with expiry date and get the boolean status of access token expiration

1.1.2

• minor update

1.1.1

• issue fixed
  • checkoutCompleteWithTokenizedPaymentV3 'Field 'payment' doesn't exist

1.1.0

• added ShopifyCustom to give the suer an ability to create custom query and mutations that are not available in the package

1.0.19

• updated readme

1.0.18

• updated signup and readme

1.0.17

• checkoutDiscountCodeApply returns Checkout object

1.0.16

• Updated Example

1.0.15

• Updated Shop model to get shippingPolicy and subscriptionPolicy

1.0.14

• Shopify Blogs issue fixes

1.0.13

• get all products error fixes

1.0.12

• made shopify admin access token optional as it is only used for deleting the customer

1.0.11

• added product relation in the Checkout lineitem

1.0.10

• added update email in checkout

1.0.9

• checkout lineitem update fixes

1.0.8

• Fixed error getting in order history when the the purchased product is archieved
• added billingAddress in getAllOrdersQuery and orders

1.0.7

• Bug fixes in registeration

1.0.6

• Bug fixes while deleting customer account

1.0.5

• Optimized orders query and product isAvailableForSale

1.0.4

• Added get collection by id

1.0.3

• Code optimization

1.0.2

• added 'email' in checkout product for eacy checkout experience if logged in

1.0.1

• add 'isAvailableForSale' in product and CustomerUpdate bug fixes

1.0.0

• updated shopify config to add admin access token.
• delete customer mutation

0.0.4

• added payment status and fulfilment status in order

0.0.3

• Bug fixes in order, product and checkout models.

0.0.2

• Added comments, Readme and example update

0.0.1

• Initial Release