Subscription Management
Update subscription delivery address and method
Updates the shipping address or delivery method for a subscription contract. Supports standard shipping, local delivery, and pickup options with comprehensive address validation.
Delivery Method Types:
- SHIPPING: Standard shipping to customer address (default)
- LOCAL: Local delivery within specified zip codes
- PICK_UP: Customer pickup at designated location
Key Features:
- Zip code restrictions for customer portal access
- Optional ShipperHQ address validation
- Automatic phone number handling for local delivery
- Email notifications to customers
- Shipping price recalculation
- Activity log tracking with old/new addresses
Zip Code Validation (Customer Portal Only): When called from customer portal:
- Standard shipping: Validates against ‘allowToSpecificZipCode’ setting
- Local delivery: Validates against ‘allowToSpecificZipCodeForLocalDelivery’ setting
- External API calls bypass zip code restrictions
Address Validation:
- If ShipperHQ is configured, addresses are validated for deliverability
- Invalid addresses will return appropriate error messages
- Helps prevent failed deliveries and shipping issues
Special Handling:
- Local delivery addresses missing phone numbers are auto-populated
- Uses customer’s phone if available, otherwise defaults to placeholder
- Handles missing address components gracefully
Post-Update Actions:
- Sends ‘SHIPPING_ADDRESS_UPDATED’ email to customer
- Creates activity log with address change details
- Triggers asynchronous shipping price recalculation
- May remove invalid discount codes automatically
Important Notes:
- Province codes should use ISO 3166-2 format (e.g., ‘NY’ for New York)
- Country codes should use ISO 3166-1 alpha-2 format (e.g., ‘US’)
- Phone numbers should include country code for international addresses
- Pickup locations must be pre-configured in Shopify
Authentication: Requires valid X-API-Key header
PUT
/
api
/
external
/
v2
/
subscription-contracts-update-shipping-address
curl --request PUT \
--url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-shipping-address \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <x-api-key>' \
--data '
{
"address1": "123 Rue de la Paix",
"city": "Paris",
"countryCode": "FR",
"firstName": "Pierre",
"lastName": "Dubois",
"methodType": "SHIPPING",
"phone": "+33123456789",
"provinceCode": "75",
"zip": "75001"
}
'{
"customer": {
"email": "customer@example.com",
"id": "gid://shopify/Customer/987654321"
},
"deliveryMethod": {
"__typename": "SubscriptionDeliveryMethodShipping",
"address": {
"address1": "456 New Street",
"address2": "Suite 200",
"city": "Los Angeles",
"company": "Acme Corp",
"countryCode": "US",
"firstName": "John",
"lastName": "Doe",
"phone": "+12135551234",
"provinceCode": "CA",
"zip": "90001"
}
},
"deliveryPrice": {
"amount": "7.99",
"currencyCode": "USD"
},
"id": "gid://shopify/SubscriptionContract/123456789",
"nextBillingDate": "2024-03-01T00:00:00Z",
"status": "ACTIVE"
}Headers
API Key for authentication
Query Parameters
Subscription contract ID to update. Provide the numeric ID without the gid:// prefix
Required range:
x >= 1API Key (Deprecated - Use X-API-Key header instead)
Body
application/json
New shipping address and delivery method details
Response
Shipping address successfully updated
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Available options:
SUCCEEDED, FAILED, $UNKNOWN Show child attributes
Show child attributes
Show child attributes
Show child attributes
Available options:
ACTIVE, PAUSED, CANCELLED, EXPIRED, FAILED, $UNKNOWN ⌘I
curl --request PUT \
--url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-shipping-address \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <x-api-key>' \
--data '
{
"address1": "123 Rue de la Paix",
"city": "Paris",
"countryCode": "FR",
"firstName": "Pierre",
"lastName": "Dubois",
"methodType": "SHIPPING",
"phone": "+33123456789",
"provinceCode": "75",
"zip": "75001"
}
'{
"customer": {
"email": "customer@example.com",
"id": "gid://shopify/Customer/987654321"
},
"deliveryMethod": {
"__typename": "SubscriptionDeliveryMethodShipping",
"address": {
"address1": "456 New Street",
"address2": "Suite 200",
"city": "Los Angeles",
"company": "Acme Corp",
"countryCode": "US",
"firstName": "John",
"lastName": "Doe",
"phone": "+12135551234",
"provinceCode": "CA",
"zip": "90001"
}
},
"deliveryPrice": {
"amount": "7.99",
"currencyCode": "USD"
},
"id": "gid://shopify/SubscriptionContract/123456789",
"nextBillingDate": "2024-03-01T00:00:00Z",
"status": "ACTIVE"
}