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

subscriptions

api

subscription-contracts-update-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 '
{
  "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"
}

Query Parameters

contractId

integer<int64>

required

Body

application/json

New shipping address and delivery method details

address1

string

address2

string

city

string

company

string

country

string

countryCode

string

firstName

string

lastName

string

locationId

string

methodType

string

phone

string

province

string

provinceCode

string

zip

string

Response

Shipping address successfully updated

billingAttempts

object

Show child attributes

billingPolicy

object

Show child attributes

createdAt

object

customAttributes

object[]

Show child attributes

customer

object

Show child attributes

customerPaymentMethod

object

Show child attributes

deliveryMethod

object

Show child attributes

deliveryPolicy

object

Show child attributes

deliveryPrice

object

Show child attributes

discounts

object

Show child attributes

get__typename

string

lastPaymentStatus

enum<string>

Available options:

SUCCEEDED,

FAILED,

$UNKNOWN

lines

object

Show child attributes

nextBillingDate

object

note

string

originOrder

object

Show child attributes

status

enum<string>

Available options:

ACTIVE,

PAUSED,

CANCELLED,

EXPIRED,

FAILED,

$UNKNOWN

updatedAt

object

Split or duplicate an existing subscription contract

Update subscription contract status

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"
}
'

{
  "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"
}