2022-07 release notes

As of API version 2022-07, you use the GraphQL Admin API to create a new discount type in your app. To learn how to create a new discount type, refer to Build a discount experience.

New types

• AppDiscountType object was added
• AppDiscountTypes object was added
• DiscountAutomaticApp object was added
• DiscountAutomaticAppInput input object was added
• DiscountCodeApp object was added
• DiscountCodeAppInput input object was added
• HasMetafields interface was added to DiscountAutomaticNode object
• HasMetafields interface was added to DiscountCodeNode object
• HasMetafields interface was added to DiscountNode object
• HasMetafieldDefinitions interface was added to DiscountAutomaticNode object
• HasMetafieldDefinitions interface was added to DiscountCodeNode object
• HasMetafieldDefinitions interface was added to DiscountNode object
• DISCOUNT value was added to MetafieldOwnerType enum

New mutations

• DiscountCodeAppCreate mutation was added
• DiscountCodeAppUpdate mutation was added
• DiscountAutomaticAppCreate mutation was added
• DiscountAutomaticAppUpdate mutation was added

As of API version 2022-07, you can use the GraphQL Admin API to create discount combinations in your app.

New types

• AppDiscountType object was added
• AppDiscountTypes object was added
• DiscountAutomaticApp object was added
• DiscountAutomaticAppInput input object was added
• DiscountCombinesWith object was added
• DiscountCombinesWithInput input object was added
• DiscountClass enum was added
• DiscountNode object was added
• DiscountNodeConnection connection was added
• DiscountNodeEdge object was added
• DiscountSortKeys enum was added
• MerchandiseDiscountClass enum was added
• ShippingDiscountClass enum was added

New fields

combinesWith and discountClass fields were added to the following objects:

• DiscountAutomaticBasic
• DiscountAutomaticBxgy
• DiscountCodeBasic
• DiscountCodeBxgy
• DiscountCodeFreeShipping
• PriceRule

New mutations

• discountAutomaticAppCreate mutation was added
• discountAutomaticAppUpdate mutation was added

As of API version 2022-07, you can connect Braintree as a legacy subscription payment gateway and migrate each pay-as-you-go contract to Shopify. After the migration, you'll use Shopify Payments as the primary payment gateway. For more information, refer to Migrating existing subscription contracts to Shopify.

New types

• CustomerPaymentMethodRemoteInput input object was added

New error codes

• braintree_not_enabled_for_subscriptions error code was added to CustomerPaymentMethodRemoteUserErrorCode enum

As of API version 2022-07, you can set checkout charges for deferred purchase options to secure customers' commitments to orders before the orders are fulfilled. The remaining balance amount is charged at a later date.

New fields

• checkoutCharge field was added to SellingPlan object
• checkoutChargeAmount field was added to CartEstimatedCost object
• checkoutChargeAmount field was added to SellingPlanAllocation object
• remainingBalanceChargeAmount field was added to SellingPlanAllocation object

New types

• SellingPlanCheckoutCharge object was added
• SellingPlanCheckoutChargeValue union was added
• SellingPlanCheckoutChargeType enum was added

As of API version 2022-07, you can use the GraphQL Admin API to query customer statistics like predicted spend.

New types

• CustomerStatistics object was added
• CustomerPredictedSpendTier enum was added to CustomerStatistics object

New fields

• predictedSpendTier field was added to CustomerStatistics object
• statistics field was added to Customerobject

As of API version 2022-07, you can use the GraphQL Admin API to set the latest date and time by which fulfillment orders need to be fulfilled.

New types

• FulfillmentOrdersSetFulfillmentDeadlinePayload payload was added
• FulfillmentOrdersSetFulfillmentDeadlineUserErrorCode enum was added

New mutation

• fulfillmentOrdersSetFulfillmentDeadline mutation was added

New error code

• FULFILLMENT_ORDERS_NOT_FOUND error code was added to FulfillmentOrdersSetFulfillmentDeadlineUserErrorCode enum

As of API version 2022-07, you can use the GraphQL Admin API to create and manage deferred purchase options to provide merchants and customers with various ways to sell and buy products, beyond the "buy now, pay now, and ship now" experience and subscriptions. Shopify supports pre-orders and try before you buys as use cases for deferred purchase options.

There's no single API to create a specific deferred purchase option. Instead, a deferred purchase option has configurations for pricing, delivery, inventory, and billing policies. For more information, refer to Deferred purchase options.

New fields

• category field was added to SellingPlan object
• inventoryPolicy field was added to SellingPlan object
• fixed field was added to SellingPlanBillingPolicyInput object
• fixed field was added to SellingPlanDeliveryPolicyInput object

New types

• SellingPlanCheckoutCharge object was added
• SellingPlanCheckoutChargePercentageValue object was added
• SellingPlanFixedBillingPolicy object was added
• SellingPlanFixedBillingPolicyInput input object was added
• SellingPlanFixedDeliveryPolicy object was added
• SellingPlanFixedDeliveryPolicyInput input object was added
• SellingPlanInventoryPolicyInput input object was added
• SellingPlanCheckoutChargeInput input object was added
• SellingPlanCheckoutChargeValueInput input object was added
• SellingPlanCheckoutChargeType enum was added
• SellingPlanCheckoutChargeValue union was added
• SellingPlanCategory enum was added
• SellingPlanRemainingBalanceChargeTriggerenum was added
• SellingPlanFulfillmentTrigger enum was added
• SellingPlanFixedDeliveryPolicyIntentenum was added
• SellingPlanFixedDeliveryPolicyPreAnchorBehaviorenum was added
• SellingPlanReserve enum was added

New error codes

• BILLING_AND_DELIVERY_POLICY_TYPES_MUST_BE_THE_SAME error code was added to SellingPlanGroupUserErrorCode enum
• CHECKOUT_CHARGE_VALUE_AND_TYPE_MUST_MATCH error code was added to SellingPlanGroupUserErrorCode enum
• FULFILLMENT_EXACT_TIME_NOT_ALLOWED error code was added to SellingPlanGroupUserErrorCode enum
• INCLUSION error code was added to SellingPlanGroupUserErrorCode enum
• NOT_FOUND error code was added to SellingPlanGroupUserErrorCode enum
• ONLY_NEED_ONE_BILLING_POLICY_TYPE error code was added to SellingPlanGroupUserErrorCode enum
• FULFILLMENT_EXACT_TIME_REQUIRED error code was added to SellingPlanGroupUserErrorCode enum
• ONLY_NEED_ONE_CHECKOUT_CHARGE_VALUE error code was added to SellingPlanGroupUserErrorCode enum
• ONLY_NEED_ONE_DELIVERY_POLICY_TYPE error code was added to SellingPlanGroupUserErrorCode enum
• ONLY_ONE_OF_FIXED_OR_RECURRING_BILLING error code was added to SellingPlanGroupUserErrorCode enum
• ONLY_ONE_OF_FIXED_OR_RECURRING_DELIVERY error code was added to SellingPlanGroupUserErrorCode enum
• REMAINING_BALANCE_CHARGE_EXACT_TIME_NOT_ALLOWED error code was added to SellingPlanGroupUserErrorCode enum
• REMAINING_BALANCE_CHARGE_EXACT_TIME_REQUIRED error code was added to SellingPlanGroupUserErrorCode enum
• REMAINING_BALANCE_CHARGE_TIME_AFTER_CHECKOUT_MUST_BE_GREATER_THAN_ZERO error code was added to SellingPlanGroupUserErrorCode enum
• REMAINING_BALANCE_CHARGE_TRIGGER_NO_REMAINING_BALANCE_ON_PARTIAL_PERCENTAGE_CHECKOUT_CHARGE error code was added to SellingPlanGroupUserErrorCode enum
• REMAINING_BALANCE_CHARGE_TRIGGER_NO_REMAINING_BALANCE_ON_PRICE_CHECKOUT_CHARGE error code was added to SellingPlanGroupUserErrorCode enum
• REMAINING_BALANCE_CHARGE_TRIGGER_ON_FULL_CHECKOUT error code was added to SellingPlanGroupUserErrorCode enum
• SELLING_PLAN_ANCHORS_NOT_ALLOWED error code was added to SellingPlanGroupUserErrorCode enum
• SELLING_PLAN_ANCHORS_REQUIRED error code was added to SellingPlanGroupUserErrorCode enum
• SELLING_PLAN_FIXED_PRICING_POLICIES_LIMIT error code was added to SellingPlanGroupUserErrorCode enum
• TOO_BIG error code was added to SellingPlanGroupUserErrorCode enum
• WRONG_LENGTH error code was added to SellingPlanGroupUserErrorCode enum

As of API version 2022-07, you can use the GraphQL Admin API to create a delegate access token. A delegate access token is an access token with a subset of the total permissions of an app.

For more information, refer to Delegate OAuth access tokens to subsystems.

New mutation

• delegateAccessTokenCreate mutation was added

%

As of API version 2022-07, you can use the GraphQL Admin API to hold fulfillments on unvalidated mailing addresses and ensure merchants check prior to requesting fulfillment.

As of API version 2022-07, you can use the GraphQL Admin API fulfillmentOrderRejectFulfillmentRequest mutation has improved rejections with optional arguments.

For more information, refer to the changelog post.

New fields

• warningsfield was added to FulfillmentOrderLineItem object

New arguments

• reason argument was added to fulfillmentOrderRejectFulfillmentRequest mutation
• lineItems argument was added to fulfillmentOrderRejectFulfillmentRequest mutation

Use the GraphQL Admin API to specify the Multipurpose Internet Mail Extensions (MIME) type of generic files being created, updated, or deleted. Response bodies return either nil or the MIME type of the generic file, such as model/usd or application/pdf.

New field

• mimeType was added to GenericFile object

A payment mandate is the payment method and permission that a customer gives to the merchant to debit money. As of API version 2022-07, you can use the GraphQL Admin API to use a customer's payment mandate to trigger a payment for the remaining balance on an order or create a payment schedule. For more information, refer to Charging the remaining balance.

As of API version 2022-07, you can use the GraphQL Admin API to manage dispute evidence.

New fields

• dispute field was added to QueryRoot
• disputeEvidence field was added to QueryRoot

New types

• ShopifyPaymentsDisputeEvidence object was added
• ShopifyPaymentsDisputeFileUpload object was added
• ShopifyPaymentsDisputeFulfillment object was added
• ShopifyPaymentsDisputeEvidenceUpdateInput input object was added
• ShopifyPaymentsDisputeFileUploadUpdateInput input object was added
• ShopifyPaymentsDisputeEvidenceFileType enum was added

New mutations

• disputeEvidenceUpdate mutation was added

As of API version 2022-07, the following types and mutations have been removed from the GraphQL Admin API:

Removed types

• DraftFulfillment: Use FulfillmentOrder instead.

Removed mutations

• fulfillmentCreate: Use fulfillmentCreateV2 instead.
• fulfillmentTrackingInfoUpdate: Use fulfillmentTrackingInfoUpdateV2 instead.

As of API version 2022-07, you can use the GraphQL Admin API to specify a fixed cutoff day in subscription apps.

New fields

• cutoffDay field was added to SellingPlanAnchorInput input object
• cutoffDay field was added to SellingPlanAnchor object

As of API version 2022-07, you can use the GraphQL Admin API to permit a Stock Keeping Unit (SKU) to be stocked at multiple fulfillment services or merchant-managed locations.

New fields

• permitsSkuSharing field was added to FulfillmentService object

New arguments

• permitsSkuSharing argument was added to fulfillmentServiceCreate mutation
• permitsSkuSharing argument was added to fulfillmentServiceUpdate mutation

As of API version 2022-07, the phone field of the delivery address for a subscription is validated on the subscriptionContractCreate and subscriptionDraftUpdate mutations.

The validation enables you to confirm that a phone number is properly formatted and prevents errors that might occur when processing subscription payments with invalid data.

As of API version 2022-07, you can extend the trial of an app subscription with the AppSubscriptionTrialExtend mutation.

For usage-based app subscriptions, you can now subscribe to the app_subscriptions/approaching_capped_amount webhook topic to get notified when the balance used on an app subscription crosses 90% of the capped amount.

API version 2022-07 enables you to set the replacement behavior for a merchant with an existing subscription by using the replacementBehavior argument that was added to the appSubscriptionCreate mutation. For example you can set the behavior to immediately cancel the merchant's current app subscription and replace it with the newly created app subscription.

New argument

• replacementBehavior argument was added to appSubscriptionCreate mutation

New type

• AppSubscriptionReplacementBehavior enum was added

New mutation

• AppSubscriptionTrialExtend mutation was added

As of API version 2022-07, you can query the Cart object to retrieve the total number of items in a cart (totalQuantity).

You can also query the CartLineEstimatedCost object to retrieve the unit price (amount) and the unit price comparisons with other sellers (compareAtAmount) of a merchandise line in a cart. For more information, refer to Support international pricing on storefronts.

Additionally, you can query the attribute field on the Cart and CartLine objects to retrieve attributes associated with the entire cart, or with a cart line.

Breaking changes

The estimatedCost field on the Cart and CartLine objects has been deprecated. Use cost insteed to determine the estimated cost that the buyer will pay at checkout.

The 2022-07 version of the Storefront API also changes how discountAllocations on the Cart and CartLine objects are returned:

• Cart.discountAllocations now returns discount allocations that are applied to the entire Cart.
• CartLine.discountAllocations now only returns discount allocations that are applied to the specific CartLine.
• CartLine.total now reflects the line total with only line-level discounts applied. It doesn't include discounts applied to the entire Cart.

New fields

• attribute field was added to Cart object
• attribute field was added to CartLine object
• discountAllocations field was added to Cart object
• cost field was added to Cart object
• cost field was added to CartLine object
• totalQuantity field was added to Cart object
• amount field was added to CartLineEstimatedCost object
• compareAtAmount field was added to CartLineEstimatedCost object

Deprecated fields

• estimatedCost field has been deprecated on the Cart object
• estimatedCost field has been deprecated on the CartLine object

As of API version 2022-07, the HasMetafields.metafields paginated connection is deprecated. Previously, this connection enabled you to paginate over all visible metafields in a given resource.

HasMetafields.metafields now accepts a list of metafield namespaces and keys, and returns a list of associated metafields that match the given namespaces and keys.

For more information, refer to the HasMetafields interface.

As of API version 2022-07, the following mutations have been removed from the Storefront API:

• checkoutGiftCardApply: Use checkoutGiftCardAppend instead.
• checkoutGiftCardRemove: Use checkoutGiftCardRemoveV2 instead.
• checkoutEmailUpdate: Use checkoutEmailUpdateV2 instead.
• checkoutDiscountCodeApply: Use checkoutDiscountCodeApplyV2 instead.
• checkoutCustomerAssociate: Use checkoutCustomerAssociateV2 instead.
• checkoutCustomerDisassociate: Use checkoutCustomerDisassociateV2 instead.
• checkoutCompleteWithTokenizedPayment: Use checkoutCompleteWithTokenizedPaymentV3 instead.
• checkoutCompleteWithTokenizedPaymentV2: Use checkoutCompleteWithTokenizedPaymentV3 instead.
• checkoutShippingAddressUpdate: Use checkoutShippingAddressUpdateV2 instead.
• checkoutCompleteWithCreditCard: Use checkoutCompleteWithCreditCardV2 instead.
• checkoutAttributesUpdate: Use checkoutAttributesUpdateV2 instead.

As of API version 2022-07, you can query the urlRedirect object to retrieve information about a URL redirect on an online store. For example, you can query both the URL that users are redirected from and the URL where users will be redirected to.

New type

• UrlRedirect object was added

New connection

• urlRedirects connection was added to QueryRoot

As of API version 2022-07, the following Function APIs for discounts are available:

• Order Discount API: Create a new type of discount that's applied to all merchandise in the cart.
• Product Discount API: Create a new type of discount that's applied to a particular product or product variant in the cart.
• Shipping Discount API: Create a new type of discount that's applied to one or more shipping rates at checkout.

To learn how to use a Function API to create a new discount type for merchants, refer to Build a discount experience.

As of API version 2022-07, the /set_fulfillment_orders_deadline endpoint has been added to the FulfillmentOrder resource. You can use this endpoint to set the latest date and time by which fulfillment orders need to be fulfilled.

As of API version 2022-07, the following customer object properties on the REST Admin API's Order resource have been deprecated:

• last_order_id
• last_order_name
• orders_count
• total_spent

Use the Customer resource instead to access these properties.

As of API version 2022-07, you can use the Rest Admin API to manage dispute evidence.

New resources

• dispute_evidences resource was added
• dispute_file_uploads resource was added

New endpoints

• show endpoint was added to dispute_evidences resource
• update endpoint was added to dispute_evidences resource
• create endpoint was added to dispute_file_uploads resource
• destroy endpoint was added to dispute_file_uploads resource

As of API version 2022-07, the following endpoints have been removed from the Fulfillment resource in the REST Admin API:

• POST /orders/{order_id}/fulfillments.json
• PUT/PATCH /orders/{order_id}/fulfillments/{fulfillment_id}.json
• POST /orders/{order_id}/fulfillments/{fulfillment_id}/complete.json
• POST /orders/{order_id}/fulfillments/{fulfillment_id}/open.json
• POST /orders/{order_id}/fulfillments/{fulfillment_id}/cancel.json

Use the FulfillmentOrder resource instead.

As of API version 2022-07, you can use the REST Admin API to permit a Stock Keeping Unit (SKU) to be stocked at multiple fulfillment services or merchant-managed locations.

New properties

• permits_sku_sharing property was added to FulfillmentService resource

The REST Admin API no longer supports XML-format responses and payloads. Requests that expect an XML response will result in a 404 error. Requests that send an XML payload will result in a 415 error.

If you're using XML for REST Admin API requests and payloads, then you need to switch to using JSON format.