Appstle Subscriptions API changelog

​

Pagination Link URLs start with https://

​

preservePortalOrderNote

​

Pickup and delivery visibility in portal settings, and no gift cards as free products

• GET /api/external/v2/customer-portal-settings/{id} and GET /subscriptions/cp/api/customer-portal-settings/{id} return three new booleans: apdHideDelivery, apdHidePickup and apdHideShipping.
• POST /api/external/v2/subscription-groups, and PUT for new plans, return 400 when a free product in appstleCycles[] is a gift card. The title is UserGeneratedError: followed by the product’s name and is a gift card. Shopify doesn't allow free gift cards on subscription orders, so choose a different free product.

​

Upgrade selection when redeeming a campaign offer

​

repeatEvery on cycle rewards, and plan name translations

• Each entry of appstleCycles[] carries a new field, repeatEvery (integer). It applies to repeating rewards only: they come back every this many orders, counting the first order. A free gift on order 5 (afterCycle 4) with repeatEvery 5 is given on orders 5, 10, 15 and so on. When it’s absent, repeating rewards come back every N orders, where N is the highest afterCycle among them. It’s ignored on pay-as-you-go prepaid plans.
• repeatEvery is in the responses of GET /api/external/v2/subscription-groups (and its {id} variant), GET /api/external/v2/subscription-groups/all-selling-plans, GET /api/external/v2/subscription-contract-details/billing-interval, GET /subscriptions/cp/api/data/v2/products-selling-plans and GET /subscriptions/cp/api/subscription-groups/all-selling-plans. It’s accepted in POST /api/external/v2/subscription-groups, in new plans (without idNew) in PUT /api/external/v2/subscription-groups, and in lines[].pricingPolicy[] of POST /api/external/v2/subscription-contract-details/create-subscription-contract. PUT ignores appstleCycles[] on plans that already exist.
• On the subscription group calls, a repeatEvery that isn’t a whole number from 1 to 150 returns 400 with the title UserGeneratedError:Repeat every has to be a whole number of orders from 1 to 150. Repeating rewards in one plan share one repeatEvery, so different values return 400 with the title UserGeneratedError:The repeating rewards repeat together, so they need the same repeat every. Reload the page and try again. A value that would start two repeating discount or shipping rewards on the same order returns 400 with a title that starts UserGeneratedError:With repeat every.
• GET /subscriptions/cp/api/data/v2/products-selling-plans returns frequencyNameTranslations for plans whose translations are saved by plan ID. Until now it looked translations up by plan name only, so those plans came back without them. Plans whose translations are saved by name still return theirs.

​

singleOrder on cycle rewards, and stopSwapEmails on swaps

• Each entry of appstleCycles[] carries a new field, singleOrder (boolean). It applies to SHIPPING rewards only: the shipping price covers that reward’s own order, then the subscription goes back to its normal shipping price. It’s ignored on other reward types and on repeating rewards. The endpoints that return and accept repeatEvery, listed under October 26, return and accept it too.
• POST /api/external/v2/subscription-contract-details/replace-variants-v3 now honors stopSwapEmails. With true, the swap sends no email notifications. Until now the endpoint ignored the field and always sent them.

​

upsellOrderForAllProducts

​

Free Gift offers in cancellation flows

• A cancellation flow can now offer a Free Gift. GET /subscriptions/cp/api/cancellation-flows/published?contractId={contractId} returns the flow in configJSON, a JSON string. In it, a TREATMENT_SET step’s payload, or that payload’s fallback, can have action FREE_GIFT, with freeGiftVariantId and, when the merchant set one, freeGiftTitle. Before this date, a flow with a Free Gift offer was rejected when the merchant saved it, so no flow returned one.
• When the reason chosen through flowId and flowReasonId carries a Free Gift offer, POST /subscriptions/cp/api/cancellation-retention-offers/execute runs it the way it does for a reason-based offer (see October 16): retentionAction 9, the gift variant added to the next order as a free one-time item, once per subscription.

​

Cancellation note in the Subscription Cancelled trigger

​

Activity logs accept the X-API-Key header, and the countries list covers every shipping zone

• GET /api/external/v2/activity-logs now accepts the API key in the X-API-Key header, like the other Admin API endpoints. Until now, a request that sent the key only in the header returned 400, because the api_key query parameter was required. api_key still works but is deprecated.
• On a store that doesn’t use Shopify Markets shipping, GET /subscriptions/cp/api/v2/data/countries now returns the countries of every shipping zone in the store’s delivery profiles. Until now, countries in shipping zones past the first 50 were missing from the list.

​

Bundle display settings and freeze setting

• GET /api/external/v2/subscription-bundle-settings/{id} and GET /subscriptions/cp/api/subscription-bundle-settings/{id} return hideProductTags and showFullProductDescription (booleans).
• Customer portal settings return allowAddProductWhenContractIsFreeze (boolean). When it’s true, PUT /subscriptions/cp/api/v2/subscription-contracts-add-line-item and PUT /subscriptions/cp/api/v2/subscription-contracts-add-bundle-line-item add products even while the store locks changes until a subscription reaches its minimum number of orders.

​

Build-a-Box discount cleanup event, and a Free Gift retention offer

• The storefront script dispatches AppstleSubscription:Cart:BuildABoxDiscountRemoved on document only, not on window, when it removes a Build-a-Box discount code from a cart that has no box items. event.detail.codes lists the removed codes.
• GET /api/external/v2/cancellation-managements/{id} and GET /subscriptions/cp/api/cancellation-managements/{id} can return a cancellation reason, or a reason’s fallbackOffer, with cancellationAction 9 (Free Gift), freeGiftVariantId and, when the merchant set one, freeGiftTitle. The reasons are in cancellationReasonsJSON, a JSON string.
• POST /subscriptions/cp/api/cancellation-retention-offers/execute can run a Free Gift offer. The response then carries retentionAction 9 and retentionActionLabel Free Gift, and retentionActivity.additionalInfo (a JSON string) holds freeGiftVariantId and, when the merchant set one, freeGiftTitle. The call adds the merchant’s gift variant to the subscription’s next order as a free one-time item. A subscription gets the gift once.

• UserGeneratedError:A free gift has already been added to this subscription. The subscription already got its gift.
• UserGeneratedError:Your free gift is already being added. Please wait a moment. An earlier request is still running.
• UserGeneratedError:Another billing operation is already in progress. Please wait until all ongoing processes are completed. An order is being placed. Try again once it’s done.
• UserGeneratedError:This free gift offer has no gift product. The merchant hasn’t set a gift product.
• UserGeneratedError: followed by the merchant’s own message, when the store locks changes until a subscription reaches a minimum number of orders.

​

Keep a custom delivery price for one subscription

​

settingsVersion and expectedShopCustomizationData

​

Gift subscriptions and schedule modes for immediate orders

• Selling plans return giftSendMaxDays (integer), and POST and PUT /api/external/v2/subscription-groups accept it in subscriptionPlans[].
• New GET /subscriptions/cp/api/subscription-gifts?contractIds=… returns the gift details of the listed contracts that belong to the signed-in customer, keyed by contract ID. Without contractIds, it returns an empty object.
• eventType in GET /api/external/v2/activity-logs has a new value, SEND_GIFT_PURCHASED_MERCHANT_EMAIL.
• PUT /subscriptions/cp/api/subscription-billing-attempts/attempt-billing/{id} accepts an optional scheduleMode query parameter that sets how ordering now affects the schedule. extra_order_only places an extra order and leaves the upcoming orders as they are. extra_order_recalculate places an extra order and recalculates the upcoming order dates. Without it, the store’s Manual Order Processing setting applies.
• Send scheduleMode only when customer portal settings return allowOrderNowScheduleChoice as true. Otherwise the call returns 400 with the title UserGeneratedError:This schedule option is no longer available. Please refresh the page and try again. An unrecognized value returns 400 with the title UserGeneratedError:Invalid schedule option. Please refresh the page and try again.
• Customer portal settings return allowOrderNowScheduleChoice and hideRescheduleTimeInExtension (booleans).
• POST and PUT /api/external/v2/subscription-groups return 400 when a plan has gift true and a giftSendMaxDays outside 1 to 365, with the title UserGeneratedError:Gift invitations can be scheduled between 1 and 365 days ahead. and the errorKey invalidGiftSendMaxDays, or a minQuantity above 1, with the title UserGeneratedError:Gifts must be purchased one at a time. Leave minimum quantity empty or set it to 1. and the errorKey invalidGiftMinimumQuantity.
• PUT /api/external/v2/subscription-contracts-update-max-cycles returns 400 with the title UserGeneratedError:Gift subscriptions end after their prepaid deliveries, so their maximum can't be changed. and the errorKey giftMaxCyclesChangeBlocked when the subscription is a gift subscription. The Shopify Flow action Update Max Cycles fails on gift subscriptions for the same reason.

​

Gift email event types and gift selling plans

• eventType in GET /api/external/v2/activity-logs has two new values: SEND_GIFT_RECEIVED_EMAIL and SEND_GIFT_THANK_YOU_EMAIL.
• Selling plans return gift (boolean), and POST and PUT /api/external/v2/subscription-groups accept it in subscriptionPlans[].
• GET /subscriptions/cp/api/data/v2/products-selling-plans accepts a contractId query parameter.
• POST /api/external/v2/subscription-groups, and PUT for new plans, return 400 with the title UserGeneratedError:Remove rewards before selling this plan as a gift. and the errorKey giftRewardsNotSupported when a plan has gift true and rewards in appstleCycles[].
• The same calls return 400 with the title UserGeneratedError:Each new gift option needs its own name. and the errorKey giftFrequencyNameNotUnique when a new plan with gift true has the same frequencyName as another plan in the request, ignoring case, and with the title UserGeneratedError:Gift plans must use Prepaid One-Time with one billing cycle. and the errorKey invalidGiftPlan when a plan with gift true has a planType other than PREPAID or a maxCycles other than 1.

​

The charge cap’s 500 USD limit is converted into the subscription’s currency

• The charge cap limits a subscription that has no original order amount on file to 500 USD. That limit is now converted into the subscription’s currency. Until now, the number 500 was compared with the subscription’s amount in whatever currency it was in.
• The same limit applies when you raise the price of a line item that costs 0, with PUT /api/external/v2/subscription-contracts-update-line-item-price or PUT /api/external/v2/subscription-contracts-update-line-item-pricing-policy. It also applies when you trigger billing with PUT /api/external/v2/subscription-billing-attempts/attempt-billing/{id} for a subscription with no original order amount on file.
• The 400 messages for this limit now show it with its currency code, for example 500.00 USD. Until now they showed only 500.
• When Appstle has no exchange rate for the subscription’s currency, these calls return 400 with the title UserGeneratedError:Unable to verify this subscription's safety limit. Please try again or contact Appstle support. and the errorKey charge_cap_currency_unavailable.

​

Cancellation rules apply during free trials, and pauses have a limit

• If the merchant doesn’t let customers cancel, the call returns 400 with the title UserGeneratedError:Permission denied, Subscription cannot be modified.
• If the merchant limits cancellation by how close the next billing date is, the call returns 400 with the errorKey timeBasedRestriction. Its title is UserGeneratedError: followed by a message that can be the merchant’s own text, so match the errorKey, not the title.

​

allowOrderNowOnListPage

​

Pickup data on live order status, and a billing-date guard

• GET /subscriptions/cp/api/orders/{orderId}/live-status accepts includePickupDeliveryData (boolean) and then returns pickupDeliveryData (string).
• PUT /subscriptions/cp/api/subscription-billing-attempts/skip-order/{id} and PUT /subscriptions/cp/api/subscription-contracts-update-billing-date accept an optional expectedBillingDate query parameter, and update-billing-date also accepts expectedBillingAttemptId. Send the upcoming order’s billingDate exactly as the API returned it. For update-billing-date, also send that order’s billing attempt id. If the upcoming order has changed since, the call changes nothing and returns 400 with the title UserGeneratedError:This upcoming order has changed. Review the latest order before trying again.

​

showSwapOnlyForOutOfStockBABProducts

​

Customers can’t go below a plan’s minimum quantity

​

Refused delivery addresses say what’s wrong

​

Skip offers, order notes and line item edits follow the store’s settings

• POST /subscriptions/cp/api/cancellation-retention-offers/execute skips the number of orders the merchant set on the cancellation reason when it runs a skip offer. skipCycle in the request counts only when the shop’s cancellation management setting dynamicallyPauseCycleOnCancellation is on and the request has no flowId or flowReasonId. It must then be between 1 and the configured number, or the call returns 400 with the title UserGeneratedError:Invalid skip duration for this retention offer. Otherwise the call ignores skipCycle. Until now, any skipCycle replaced the configured number.
• PUT /subscriptions/cp/api/subscription-contract-details returns 400 with the title UserGeneratedError:Permission denied, Order notes are not allowed when a customer changes the order note and the merchant has turned order notes off for the customer portal. Until now, the call saved the note.
• PUT /subscriptions/cp/api/subscription-contracts-update-line-item-attributes and PUT /subscriptions/cp/api/subscription-contracts-edit-line-item-attributes keep the attributes Appstle sets on a line, such as _appstle-bb-id and _min-cycles. The call ignores those keys in the request, except a Build-a-Box line’s product selection, and keeps the line’s existing values. Changing any other attribute needs the merchant’s permission to edit attributes, or the call returns 400 with the title UserGeneratedError:Permission denied, Editing attributes is not allowed. A request that repeats a key returns 400 with the title UserGeneratedError:Duplicate custom attribute key.
• PUT /subscriptions/cp/api/update-classic-bab-subscription/{contractId} checks each line it changes. It returns 400 with the title UserGeneratedError:This line is not a Build-A-Box product. for a line outside the box, UserGeneratedError:Permission denied, Editing or removing this product is not allowed for a product the merchant has locked, and UserGeneratedError:Permission denied, Removing products from subscription is not allowed for a quantity of 0 when customers can’t remove products. A line that must stay for a minimum number of orders returns 400 until it has, with a title that is UserGeneratedError: followed by the merchant’s message.
• When a customer swaps the product on a Build-a-Box line, the new line keeps all of the old line’s attributes, so it stays in the box. Until now it kept only Appstle’s own attributes unless the store keeps line attributes on swaps.

​

Partner approval callbacks and nonce expiry

• When a merchant approves a connection and Appstle sends the partner an apst_ access token, Appstle now saves the token before it posts it to the partner’s approval callback, /appstle/approved by default. A call made with the token as soon as it arrives no longer returns 401.
• Any 2xx reply from the callback now counts as received, whatever its body. Until now, a 2xx reply whose body wasn’t a JSON object failed the approval.
• When the callback doesn’t answer with a 2xx status within 5 seconds, the approval fails: Appstle deletes the token it created, leaves the connection pending, and returns 400 with the errorKey PARTNER_UNREACHABLE to the merchant. The partner gets no usable token from that attempt. See What if the callback fails?.
• POST /api/partner/{partnerId}/verify now returns { "verified": false } for a callback_nonce that is more than 5 minutes old, as the partner guide already said. Until now, an expired nonce could still be verified.

​

Offer tier on cancellation discounts, and no merging of cancelled subscriptions

• PUT /subscriptions/cp/api/subscription-contracts-cancellation-discount accepts an optional offerTier query parameter, PRIMARY or FALLBACK, that records which cancellation offer the customer accepted. It’s saved in the retention activity’s additionalInfo.offerTier.
• POST /subscriptions/cp/api/subscription-contract-details/merge-contract returns 400 with the title UserGeneratedError:Cancelled subscriptions cannot be merged. Please refresh the page and try again. when either subscription is cancelled. Until now the call went ahead.

​

Legacy API key revocation, and free products kept at quantity 1

• Under More → API Access in the Appstle admin, the Legacy API Key now has a Revoke button. After a merchant revokes it, every request that sends that key returns 401, with the same body as any other wrong key (see Authentication errors). Appstle doesn’t issue a replacement. Keys that start with apst_ aren’t affected.
• Each appstleCycles[] entry returns restrictFreeProductQuantity (boolean). When true, each free product stays at quantity 1 regardless of the parent line item’s quantity. It’s returned and accepted wherever repeatEvery is (see October 26).

​

Plans need their own names, and rewards sent with new plans are saved

• POST /api/external/v2/subscription-groups and PUT /api/external/v2/subscription-groups return 400 with the title UserGeneratedError:Each subscription option needs its own name. Rename one of the duplicate options. when two plans in the request have the same frequencyName. The comparison ignores spaces and letter case. On PUT, the call refuses a duplicate only when at least one of the two plans is new, meaning it has no idNew. Until now, both calls saved duplicate names.
• appstleCycles[] sent with a plan in POST /api/external/v2/subscription-groups, or with a new plan in PUT /api/external/v2/subscription-groups, is checked and saved as that plan’s rewards. Until now both calls dropped it. PUT still ignores appstleCycles[] on plans that already exist. A reward the store can’t use returns 400, for example UserGeneratedError:Your current plan doesn't include subscription rewards. Upgrade your plan to add or change rewards. or UserGeneratedError:Select the free product for every free-gift reward before saving.

​

Trigger immediate billing returns an acknowledgement

• PUT /api/external/v2/subscription-billing-attempts/attempt-billing/{id} used to return 200 with an empty body. It now returns 200 with billingAttemptId, requestedBillingAttemptId, contractId, billingDate, status and message. This confirms the attempt was queued, not that the payment succeeded: the charge is sent to Shopify right after the call, and the result comes later.
• billingAttemptId is the attempt that was queued, and it can differ from the id you sent (returned as requestedBillingAttemptId). status is the attempt’s status when it was queued, for example IMMEDIATE_TRIGGERED.
• When no billing attempt could be triggered, the call returns 400 with the title UserGeneratedError:Billing attempt could not be triggered.
• GET /subscriptions/cp/api/delivery-profiles/get-locations returns fulfillsOnlineOrders (boolean) for each location.

​

Delivery type, shipping model and Markets shipping options

• GET /subscriptions/cp/api/data/contract-live-shipping-rates returns deliveryType for each rate.
• GET /subscriptions/cp/api/v2/data/countries accepts an includeShippingModel query parameter.
• deliveryMethodId is optional on PUT /api/external/v2/bulk-automations/delivery-method.
• On a store that uses Shopify Markets shipping, GET /subscriptions/cp/api/data/shop-delivery-options first returns one item per market that has active shipping options, as { name, marketOptions }, where marketOptions lists each option as { id, name }. The app’s delivery profiles follow, in the same shape as before.
• When the delivery options can’t be loaded, shop-delivery-options now fails with a server error instead of returning an empty list.
• On a store that uses Shopify Markets shipping, PUT /api/external/v2/subscription-contracts-update-delivery-method and PUT /subscriptions/cp/api/subscription-contracts-update-delivery-method return 400 with the title UserGeneratedError:The selected shipping option is no longer available. and the errorKey shippingOptionUnavailable when delivery-method-id names a shipping option that no longer exists.

​

stickyCheckoutButton

​

A clear error when an order can’t be unskipped yet, and one-time products in splits

​

Splits check the products you choose

• The title is UserGeneratedError:Select subscription products to move. Free gifts and one-time products cannot be selected. and the errorKey is invalidSplitProducts when the list is empty, names a line that isn’t in the subscription, or names a free gift or a one-time product.
• With attemptBilling true, the title is UserGeneratedError:The selected products are skipped for the next order. Unskip a product before ordering it now, or split without placing an order. and the errorKey is splitProductsSkipped when every selected product is skipped for the next order.
• With isSplitContract true, the title is UserGeneratedError:At least one subscription product must remain in the current subscription. Free gifts and one-time products do not count. when the split would leave no subscription product in the original subscription. Until now the call refused only when the list named every line, with the title UserGeneratedError:All products cannot be selected, at least one product is required in the current contract.
• With isSplitContract true, the rules for removing a product, such as the store’s minimum number of products and a product’s minimum number of orders, are checked before the new subscription is created. Until now a refusal came after it had been created. If the products then can’t be removed from the original subscription, the call returns 400 with the title UserGeneratedError:The products could not be removed from the original subscription. No immediate order was requested. Contact support before trying again. and the errorKey splitRemovalFailed. With attemptBilling true, the new subscription’s order is placed only after the products are removed.

​

Error responses use appstle.com problem types and hide internal messages

• The type of an error now starts with https://appstle.com/problem/, for example https://appstle.com/problem/problem-with-message. Before, it started with a different base URL.
• detail no longer carries internal error text. A server error (5xx) has the detail An unexpected error occurred. Please try again later. A 400 for a path or query parameter of the wrong type, such as a customer portal settings ID that isn’t a number, has the detail Unexpected runtime exception. A 400 for a request body that isn’t valid JSON has the detail Unable to convert http message.

​

Delivery address updates return specific errors

• invalidCountry: UserGeneratedError:Choose a valid country for this address. when countryCode isn’t a valid country code.
• addressRequired: UserGeneratedError:Enter a street address. when address1 is blank.
• locationRequired: UserGeneratedError:Choose a pickup location. when the delivery method is local pickup and locationId is blank.
• addressUpdateFailed: UserGeneratedError:We couldn't update this delivery address. Check the address details and try again. when Shopify refuses the change. Until now, the title was Shopify’s own message. From October 4, a refusal of the address itself names the problem again.

​

New activity log entity type and line item selling plan name

• entityType in GET /api/external/v2/activity-logs has a new value, QUICK_ACTION_LINK.
• GET /subscriptions/cp/api/orders/{orderId}/live-status returns lineItems[].sellingPlanName.

​

Requests can’t name another customer or store

• A Storefront API request that names a customerId other than the signed-in customer’s returns 403 with the detail Customer does not match the authenticated session. This covers customerId and customer_id in the query string (for example GET /subscriptions/cp/api/loyalty-integration/earn-options?customerId=...) and in the request body (for example PUT /subscriptions/cp/api/subscription-contract-details).
• A request body whose shop, shopName, shopDomain or shop_domain field names another store returns 403 with the detail Shop does not match the authenticated session. This covers Storefront API request bodies, and Admin API request bodies that have one of these fields, such as PUT /api/external/v2/product-swaps. The same check on query parameters started on September 6.

​

One error for every failed partner authentication

​

Build-a-Box pages clean the top and bottom HTML

​

removeDiscount is honored, and fixed date schedules allow 24 dates

• PUT /api/external/v2/subscription-contracts-remove-line-item now honors removeDiscount=false and keeps the subscription’s discounts where it can, as the reference describes. Until now the endpoint ignored the parameter and always removed the discounts that applied only to the removed line. Without removeDiscount, or with true, nothing changes.
• POST and PUT /api/external/v2/subscription-groups accept up to 24 entries in a plan’s fixedBillingDates, up from 12. A request with more than 24 returns 400 with the title Fixed date schedules support up to 24 billing dates a year. The title used to say up to 12.

​

New activity log event type SUPPORT_APD_DATA_REMOVED

​

New activity log event type SUPPORT_APD_DATA_UPDATED

​

Query parameters can’t name another store

​

Add products to a subscription group in the background

• New POST /api/external/v2/subscription-groups/v3/{id}/add-products takes the same body as POST /api/external/v2/subscription-groups/{id}/bulk-add-products (productIds and variantIds, at least one of them). It returns 202 right away with status processing and subscriptionGroupId, and adds the products in the background.
• One job runs per store at a time. A second POST while a job is running returns 400 with the title UserGeneratedError: A bulk add-products job for this shop is already in progress. A POST for an unknown group ID returns 400 with the title Invalid id.
• New GET /api/external/v2/subscription-groups/v3/{id}/add-products/status reports the store’s latest job: found, running, executionStatus (for example RUNNING, SUCCEEDED or FAILED), errorInfo, subscriptionGroupId and matchesRequestedGroup. Poll it until running is false. If matchesRequestedGroup is false, a newer job for another group has replaced yours, and the status isn’t about your request. A store that has never run a job gets only found: false, running: false and executionStatus: null, whatever the group ID.

​

Contract revisionId

​

Live carrier-quoted shipping rates

• New GET /subscriptions/cp/api/data/contract-live-shipping-rates lists live carrier-quoted shipping rates for a subscription contract.
• PUT /subscriptions/cp/api/subscription-contracts-update-delivery-method accepts a carrier-rate (boolean) query parameter, and GET /subscriptions/cp/api/shop-infos-by-current-login returns disableShippingPricingAutoCalculation and recalculateShippingPriceBeforeBilling.

​

Read the freeze status of a contract, and reschedule a fulfillment shared by several subscriptions

​

Latest discount usage

​

Bulk reads for several contracts, and a Retry Failed Billing action

• New GET /subscriptions/cp/api/campaigns/applicable-bulk and GET /subscriptions/cp/api/subscription-contracts/contract-external-bulk return the applicable campaigns and the raw Shopify contracts for several contracts in one call.
• The new Shopify Flow action Retry Failed Billing retries a subscription’s most recent failed billing attempt and reuses the failed order instead of creating a new one. It takes contract_id and returns contract_id, billing_attempt_id, success and success_message. success is true once billing has started, not when the payment goes through: the result fires Subscription Billing Success or Subscription Billing Failure. Like Attempt Billing, it needs an Appstle plan that includes immediate order placement.

​

New values ORPHANED_FREE_PRODUCT and CART_DRAWER

• partialLinesSkipped has a new value, ORPHANED_FREE_PRODUCT, in PUT /api/external/v2/subscription-billing-attempts and in billing attempt responses.
• bundleRedirect has a new value, CART_DRAWER, next to CART, CHECKOUT, CUSTOM and NONE, in Build-a-Box responses and in POST and PUT /api/external/v2/build-a-box bodies.

​

Bundle discount rules return 400 instead of a server error

​

Add a fixed pricing bundle line item

​

One-time products for a specific billing attempt are discontinued

​

Minimum quantity events

• After it raises cart lines to their selling plan’s minimum quantity, the storefront script dispatches AppstleSubscription:Cart:MinimumQuantityApplied on document and window. event.detail is an array with one { key, minQuantity, quantity } entry per corrected line.
• On a product page, when the subscription widget raises the quantity input to the selected plan’s minimum quantity, it dispatches AppstleSubscription:SubscriptionWidget:MinimumQuantityApplied on document and window. event.detail is { widgetId, minQuantity }.

​

New activity log event type, and a 400 when a customer adds a product during an order

• eventType in GET /api/external/v2/activity-logs has a new value, BILLING_ATTEMPT_BACKFILLED.
• PUT /subscriptions/cp/api/v2/subscription-contracts-add-line-item now returns 400 with the title UserGeneratedError:Another billing operation is already in progress. Please wait until all ongoing processes are completed. while a billing attempt for the subscription is in progress. Until now the call went through while the order was being placed.

​

One error for products a customer isn’t allowed to add or swap to

• PUT /subscriptions/cp/api/v2/subscription-contracts-add-line-item
• POST /subscriptions/cp/api/subscription-contract-details/replace-variants-v3

​

minQuantity on selling plans

​

New activity log event type DELIVERY_PRICE_SYNC_SKIPPED

​

Pickup contractId, nextPaidBillingDate in the contract list, and a delivery price check

• GET /subscriptions/cp/api/pickup/eligible-dates/first, POST /subscriptions/cp/api/pickup/eligible-dates, and GET and POST /subscriptions/cp/api/pickup/eligible-times accept an optional contractId. With it, eligibility is checked against that subscription’s products, starting from its next order date. locationId is now optional on eligible-dates/first and eligible-dates.
• GET /api/external/v2/subscription-contract-details now fills nextPaidBillingDate for each contract: the next date the customer is actually charged, which skips upcoming orders that a reward makes fully free. Until now it was null in this list.
• PUT /api/external/v2/subscription-contracts-update-delivery-price now checks that Shopify applied the new price. When Shopify didn’t, usually because the subscription has no delivery method, the call returns 400 with the title UserGeneratedError:Shopify did not apply the new delivery price. This subscription has no delivery method set, so a custom shipping price can't be saved yet. Please set a delivery method first and try again. Until now it returned 200 and the price stayed the same.

​

Multiple free products, delivery method type on new contracts

• Each appstleCycles[] entry returns freeProducts[] (freeVariantId, freeProductHandle, freeProductTitle, freeProductImage) for rewards of discount type FREE_PRODUCT. It holds up to 5 free products. Entry 0 is always copied to the older single freeVariantId, freeProductHandle, freeProductTitle and freeProductImage fields, so clients that read only those keys keep working. When freeProducts is absent, those single fields describe the one free product.
• POST /api/external/v2/subscription-contract-details/create-subscription-contract accepts methodType (SHIPPING, LOCAL or PICK_UP). LOCAL requires deliveryPhone, and PICK_UP requires locationId, a Shopify location ID.

​

Customer retention activities

​

A clear error for a discount code on a $0 subscription

​

reasonId on cancellation offers, inventory tracking mode

• POST /subscriptions/cp/api/cancellation-retention-offers/execute and PUT /subscriptions/cp/api/subscription-contracts-cancellation-discount accept reasonId.
• Build-a-Box bundles return and accept inventoryTrackingMode (ADD_CHILD_PRODUCT_ON_ORDER or ADD_CHILD_PRODUCT_ON_CHECKOUT).

​

Translated cancellation reasons, custom attributes on live order status

• GET /api/external/v2/cancellation-managements/{id} and its Storefront API twin accept languageCode and return reasonMessageTranslationsJSON.
• GET /subscriptions/cp/api/orders/{orderId}/live-status returns lineItems[].customAttributes.

​

Pickup and delivery selections update the delivery price

• pickupRatesUnavailable: for a shipping selection, the store’s Pickup & Delivery rates couldn’t be loaded.
• shippingRateUnavailable: for a shipping selection, no eligible Shopify shipping rate is available.
• pickupRateUnavailable: for a pickup or delivery selection, the selected rate couldn’t be verified.

​

Pickup times