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.

Full behavior, validation rules, and side effects

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 /subscriptions/cp/api/subscription-contracts-update-shipping-address

cURL

Standard Shipping Address

curl --request PUT \
  --url https://www.myshop.com/apps/subscriptions/cp/api/subscription-contracts-update-shipping-address \
  --header 'Content-Type: application/json' \
  --data '
{
  "methodType": "SHIPPING",
  "firstName": "John",
  "lastName": "Doe",
  "company": "Acme Corp",
  "address1": "456 New Street",
  "address2": "Suite 200",
  "city": "Los Angeles",
  "provinceCode": "CA",
  "countryCode": "US",
  "zip": "90001",
  "phone": "[phone]"
}
'

200

Success Response

{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-03-01T00:00:00Z",
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "[e-mail]"
  },
  "deliveryMethod": {
    "__typename": "SubscriptionDeliveryMethodShipping",
    "address": {
      "address1": "456 New Street",
      "address2": "Suite 200",
      "city": "Los Angeles",
      "provinceCode": "CA",
      "countryCode": "US",
      "zip": "90001",
      "firstName": "John",
      "lastName": "Doe",
      "company": "Acme Corp",
      "phone": "[phone]"
    }
  },
  "deliveryPrice": {
    "amount": "7.99",
    "currencyCode": "USD"
  }
}

Query Parameters

contractId · integer<int64> · required

Body

application/json

New shipping address and delivery method details

address1 · string

address2 · string

city · string

firstName · string

lastName · string

phone · string

province · string

zip · string

country · string

countryCode · string

provinceCode · string

company · string

locationId · string

methodType · string

Response

200

application/json

Shipping address successfully updated

get__typename · string

id · string

createdAt · object

updatedAt · object

nextBillingDate · object

status · enum<string>

Available options: ACTIVE, PAUSED, CANCELLED, EXPIRED, FAILED, $UNKNOWN

deliveryPrice · object

Show child attributes

lastPaymentStatus · enum<string>

Available options: SUCCEEDED, FAILED, $UNKNOWN

billingPolicy · object

Show child attributes

deliveryPolicy · object

Show child attributes

lines · object

Show child attributes

customerPaymentMethod · object

Show child attributes

deliveryMethod · object

Show child attributes

originOrder · object

Show child attributes

customer · object

Show child attributes

discounts · object

Show child attributes

note · string

customAttributes · object[]

Show child attributes

billingAttempts · object

Show child attributes