Update subscription delivery address and method
Changes a subscription’s delivery address and delivery method in one call. Appstle builds the new delivery method from the request body every time. It doesn’t start from the method the subscription has now.
Delivery method (methodType):
- SHIPPING: standard shipping to the address in the body. A request without
methodTypegets this method too, even when the subscription is on local delivery or pickup. - LOCAL: local delivery to the address in the body.
phoneis required. - PICK_UP: customer pickup.
locationId, the Shopify location ID of the pickup point, is required, as a number or agid://shopify/Location/ID. Shopify gets no address from this request. Only the ShipperHQ check and the Storefront API’s zip check read the address fields.
Any other value returns 400 with UserGeneratedError:We couldn't update this delivery address. Check the address details and try again.
To change only the address, send the subscription’s current methodType with it. Read the current method from deliveryMethod.__typename in the raw contract: SubscriptionDeliveryMethodShipping is SHIPPING, SubscriptionDeliveryMethodLocalDelivery is LOCAL and SubscriptionDeliveryMethodPickup is PICK_UP, with deliveryMethod.pickupOption.location.id as locationId. When the method type stays SHIPPING or LOCAL, the subscription keeps the title of its current delivery option. When the type changes, that title isn’t carried over. A PICK_UP request doesn’t keep the title of the current pickup option.
Address fields (SHIPPING and LOCAL):
- Send the whole address. Appstle passes it to Shopify, which validates it.
address1andcountryCodeare required.countryCodeis the two-letter ISO 3166-1 code, for exampleUS.provinceCodeis the region’s short code, for exampleORorBC. Don’t send the region’s name.provinceandcountryare ignored. SendprovinceCodeandcountryCodeinstead.- When Shopify refuses the change, the call returns 400 with
errorKeyaddressUpdateFailed.titleholds Shopify’s reason when it’s about the address, such asUserGeneratedError:Delivery method shipping address province code is invalid, andUserGeneratedError:We couldn't update this delivery address. Check the address details and try again.otherwise.
Storefront API only:
- When
changeShippingAddressFlagisfalsein the customer portal settings, the call returns 400 withUserGeneratedError:Permission denied, Changing shipping address is not allowed. - When the store limits addresses to some zip codes,
zipmust be inallowToSpecificZipCodeForLocalDeliveryforLOCAL, or inallowToSpecificZipCodefor any othermethodType. Otherwise the call returns 400 withUserGeneratedError: That zip code is not allowed. - The buyer of a gift subscription can’t change it: the call returns 400 with
errorKeygiftBuyerReadOnly. - A contract that isn’t the signed-in customer’s returns 400 with
Contract does not exist. - The Admin API skips the first three checks.
Address validation:
- When the store uses ShipperHQ, every request is checked with it,
PICK_UPincluded. An address it can’t deliver to returns 400 withAddress is not valid. No valid carriers found for given address, and an error from ShipperHQ returns 400 withError occurred while getting address validity - Some stores also refuse an address that has no delivery option for the requested method when the current address has one. The call returns 400 with
UserGeneratedError: The selected address is not eligible for delivery. Please choose a different address.PICK_UPrequests skip this check
After the update:
- Sends the customer the ‘SHIPPING_ADDRESS_UPDATED’ email, unless the store turned that email off
- Creates an activity log entry with the old and new address
- May recalculate the shipping price, sometimes after the response is sent. The recalculation can also move the subscription to another of the store’s rates, which changes the delivery option’s title. Read the contract again for the final
deliveryPriceand title - May remove a discount code that no longer applies
- On a prepaid subscription that stays on
SHIPPING, also changes the shipping address of the order that holds the remaining deliveries, when that order holds only this subscription and the country doesn’t change
Authentication: Requires a signed-in customer. Call it through Shopify’s App Proxy on the store’s domain: the proxy signs the request and attaches the customer, so you send no API key.
curl --request PUT \
--url https://www.myshop.com/apps/subscriptions/cp/api/subscription-contracts-update-shipping-address \
--header 'Content-Type: application/json' \
--data '
{
"address1": "123 Rue de la Paix",
"city": "Paris",
"countryCode": "FR",
"firstName": "Pierre",
"lastName": "Dubois",
"methodType": "SHIPPING",
"phone": "+33123456789",
"provinceCode": "75",
"zip": "75001"
}
'{
"__typename": "SubscriptionContract",
"customer": {
"__typename": "Customer",
"displayName": "Maya Brooks",
"email": "customer@example.com",
"id": "gid://shopify/Customer/987654321"
},
"deliveryMethod": {
"__typename": "SubscriptionDeliveryMethodShipping",
"address": {
"__typename": "MailingAddress",
"address1": "212 Alder Street",
"address2": null,
"city": "Portland",
"company": null,
"country": "United States",
"countryCode": "US",
"firstName": "Maya",
"lastName": "Brooks",
"phone": null,
"province": "Oregon",
"provinceCode": "OR",
"zip": "97205"
},
"shippingOption": {
"__typename": "SubscriptionDeliveryMethodShippingOption",
"code": "Standard",
"description": null,
"presentmentTitle": "Standard",
"title": "Standard"
}
},
"deliveryPrice": {
"__typename": "MoneyV2",
"amount": "5.0",
"currencyCode": "USD"
},
"id": "gid://shopify/SubscriptionContract/123456789",
"nextBillingDate": "2026-12-07T09:00:00Z",
"status": "ACTIVE"
}Body
New shipping address and delivery method details
Response
Delivery address and method updated. The body is the updated contract (trimmed in this example).
curl --request PUT \
--url https://www.myshop.com/apps/subscriptions/cp/api/subscription-contracts-update-shipping-address \
--header 'Content-Type: application/json' \
--data '
{
"address1": "123 Rue de la Paix",
"city": "Paris",
"countryCode": "FR",
"firstName": "Pierre",
"lastName": "Dubois",
"methodType": "SHIPPING",
"phone": "+33123456789",
"provinceCode": "75",
"zip": "75001"
}
'{
"__typename": "SubscriptionContract",
"customer": {
"__typename": "Customer",
"displayName": "Maya Brooks",
"email": "customer@example.com",
"id": "gid://shopify/Customer/987654321"
},
"deliveryMethod": {
"__typename": "SubscriptionDeliveryMethodShipping",
"address": {
"__typename": "MailingAddress",
"address1": "212 Alder Street",
"address2": null,
"city": "Portland",
"company": null,
"country": "United States",
"countryCode": "US",
"firstName": "Maya",
"lastName": "Brooks",
"phone": null,
"province": "Oregon",
"provinceCode": "OR",
"zip": "97205"
},
"shippingOption": {
"__typename": "SubscriptionDeliveryMethodShippingOption",
"code": "Standard",
"description": null,
"presentmentTitle": "Standard",
"title": "Standard"
}
},
"deliveryPrice": {
"__typename": "MoneyV2",
"amount": "5.0",
"currencyCode": "USD"
},
"id": "gid://shopify/SubscriptionContract/123456789",
"nextBillingDate": "2026-12-07T09:00:00Z",
"status": "ACTIVE"
}