Update shipping address for subscription contract

Changes the delivery shipping address for a subscription contract. This allows customers to update where their subscription orders are delivered.

Full behavior, validation rules, and side effects

Key Features:

• Full Address Update: Change complete shipping address in one call
• Address Validation: System validates address format and country codes
• Immediate Effect: New address applies to the next delivery
• Activity Logging: All address changes are logged for audit trail
• International Support: Supports addresses in all countries

Required Address Fields:

• firstName: Recipient’s first name
• lastName: Recipient’s last name
• address1: Street address line 1
• city: City name
• countryCode: ISO 3166-1 alpha-2 country code (e.g., US, CA, GB)
• zip: Postal/ZIP code

Optional Address Fields:

• address2: Apartment, suite, unit number
• company: Company name (for business addresses)
• phone: Contact phone number
• provinceCode: State/province code (e.g., CA, NY, ON)

Common Use Cases:

• Customer Moved: Update address after relocation
• Temporary Address: Ship to vacation home or temporary location
• Gift Recipient: Change recipient for gift subscriptions
• Correct Typos: Fix address errors from initial signup
• Business to Home: Switch between business and residential addresses
• Seasonal Address: Update for snowbird/seasonal residents

Country and Province Codes:

• countryCode: Use ISO 3166-1 alpha-2 codes
  • Examples: US (United States), CA (Canada), GB (United Kingdom), AU (Australia)
• provinceCode: Use ISO 3166-2 subdivision codes
  • US Examples: CA (California), NY (New York), TX (Texas)
  • Canada Examples: ON (Ontario), BC (British Columbia), QC (Quebec)

Address Validation:

• Format Validation: System checks required fields are present
• Country Validation: Verifies country code is valid
• Province Validation: Checks province code matches country
• Postal Code: Validates postal code format for country

Important Notes:

• Shipping Rate Recalculation: New address may have different shipping costs
• Delivery Method: System automatically selects appropriate delivery method
• Next Order Only: Only affects future orders, not orders already placed
• Address Book: Consider updating customer’s default address separately
• PO Boxes: Some delivery methods may not support PO Box addresses

Shipping Cost Impact:

• Changing address may change shipping costs for future deliveries
• International addresses typically have higher shipping costs
• Remote/rural areas may have additional delivery fees
• Consider notifying customer of cost changes

Authentication: Requires API key authentication via X-API-Key header or api_key parameter

PUT /api/external/v2/subscription-contracts-update-shipping-address

Update shipping address for subscription contract

cURL

curl --request PUT \
  --url https://membership-admin.appstle.com/api/external/v2/subscription-contracts-update-shipping-address \
  --header 'Content-Type: application/json' \
  --data '
{
  "firstName": "John",
  "lastName": "Doe",
  "address1": "123 Main Street",
  "address2": "Apt 4B",
  "city": "San Francisco",
  "provinceCode": "CA",
  "countryCode": "US",
  "zip": "94102",
  "phone": "[phone]",
  "company": "Acme Corp"
}
'

200

Example

{
  "get__typename": "<string>",
  "id": "<string>",
  "createdAt": {},
  "updatedAt": {},
  "nextBillingDate": {},
  "deliveryPrice": {
    "get__typename": "<string>",
    "amount": {}
  },
  "billingPolicy": {
    "get__typename": "<string>",
    "intervalCount": 123,
    "anchors": [
      {
        "get__typename": "<string>",
        "cutoffDay": 123,
        "day": 123,
        "month": 123
      }
    ],
    "maxCycles": 123,
    "minCycles": 123
  },
  "deliveryPolicy": {
    "get__typename": "<string>",
    "intervalCount": 123,
    "anchors": [
      {
        "get__typename": "<string>",
        "cutoffDay": 123,
        "day": 123,
        "month": 123
      }
    ]
  },
  "lines": {
    "get__typename": "<string>",
    "nodes": [
      {
        "get__typename": "<string>"
      }
    ],
    "pageInfo": {
      "get__typename": "<string>",
      "hasPreviousPage": true,
      "hasNextPage": true,
      "startCursor": "<string>",
      "endCursor": "<string>"
    }
  },
  "customerPaymentMethod": {
    "get__typename": "<string>",
    "id": "<string>",
    "instrument": {
      "get__typename": "<string>"
    },
    "revokedAt": {}
  },
  "deliveryMethod": {
    "get__typename": "<string>",
    "id": "<string>",
    "serviceCode": "<string>",
    "minDeliveryDateTime": {},
    "maxDeliveryDateTime": {},
    "additionalInformation": {
      "get__typename": "<string>",
      "instructions": "<string>"
    },
    "brandedPromise": {
      "get__typename": "<string>",
      "handle": "<string>",
      "name": "<string>"
    }
  },
  "originOrder": {
    "get__typename": "<string>",
    "id": "<string>",
    "name": "<string>",
    "fulfillmentOrders": {
      "get__typename": "<string>",
      "nodes": [
        {
          "get__typename": "<string>"
        }
      ],
      "pageInfo": {
        "get__typename": "<string>",
        "hasPreviousPage": true,
        "hasNextPage": true,
        "startCursor": "<string>",
        "endCursor": "<string>"
      }
    }
  },
  "customer": {
    "get__typename": "<string>",
    "id": "<string>",
    "email": "<string>",
    "displayName": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "phone": "<string>"
  },
  "discounts": {
    "get__typename": "<string>",
    "nodes": [
      {
        "get__typename": "<string>",
        "createdAt": {},
        "deliveredAt": {},
        "estimatedDeliveryAt": {},
        "id": "<string>",
        "inTransitAt": {},
        "name": "<string>",
        "requiresShipping": true,
        "service": {
          "get__typename": "<string>",
          "handle": "<string>",
          "serviceName": "<string>"
        },
        "trackingInfo": [
          {
            "get__typename": "<string>",
            "url": {},
            "number": "<string>",
            "company": "<string>"
          }
        ]
      }
    ],
    "pageInfo": {
      "get__typename": "<string>",
      "hasPreviousPage": true,
      "hasNextPage": true,
      "startCursor": "<string>",
      "endCursor": "<string>"
    }
  },
  "note": "<string>",
  "customAttributes": [
    {
      "get__typename": "<string>",
      "key": "<string>",
      "value": "<string>"
    }
  ],
  "billingAttempts": {
    "get__typename": "<string>",
    "nodes": [
      {
        "get__typename": "<string>",
        "completedAt": {},
        "createdAt": {},
        "id": "<string>",
        "idempotencyKey": "<string>",
        "ready": true
      }
    ]
  }
}

Headers

X-API-Key · string

Query Parameters

contractId · integer<int64> · required

Subscription contract ID

api_key · string

API Key (Deprecated - Use Header X-API-Key instead)

Body

application/json

New shipping address details

address1 · string

Primary street address

Example:

"123 Main St"

address2 · string

Secondary address line (apt, suite, etc.)

Example:

"Apt 4B"

city · string

City name

Example:

"New York"

firstName · string

Recipient first name

Example:

"John"

lastName · string

Recipient last name

Example:

"Doe"

phone · string

Contact phone number

Example:

"[phone]"

province · string

State or province name

Example:

"New York"

zip · string

Postal/ZIP code

Example:

"10001"

country · string

Country name

Example:

"United States"

countryCode · string

ISO country code

Example:

"US"

provinceCode · string

State/province code

Example:

"NY"

company · string

Company name

Example:

"Acme Inc"

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