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.

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 --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": "+12135551234"
}
'

{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-03-01T00:00:00Z",
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "customer@example.com"
  },
  "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": "+12135551234"
    }
  },
  "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

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

Update subscription contract status

Update order note for subscription

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": "+12135551234"
}
'

{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-03-01T00:00:00Z",
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "customer@example.com"
  },
  "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": "+12135551234"
    }
  },
  "deliveryPrice": {
    "amount": "7.99",
    "currencyCode": "USD"
  }
}