Skip to content
/Subscription Management

Customer Portal APIs (0.0.1)

Comprehensive API documentation for the customer-facing subscription portal. These APIs enable customers to manage their subscriptions, update billing information, modify delivery schedules, and access their account details through your storefront.

Important: These APIs must be called from your shop's domain (e.g., https://www.myshop.com/apps/subscriptions/cp/api/**) and require customer authentication. Unauthenticated requests will return a 401 Unauthorized error.

Download OpenAPI description
customer-portal-swagger.json
customer-portal-swagger.yaml
Languages
Servers
https://www.myshop.com/apps

Customer Portal

Core customer portal APIs for managing customer account settings, authentication, and portal configurations.

Operations

Subscription Management

APIs for customers to view and manage their subscription contracts including status updates, frequency changes, and cancellations.

Operations

Update subscription contract status

Request

Updates the status of a subscription contract to ACTIVE, PAUSED, or CANCELLED. This endpoint manages the lifecycle of subscriptions with automatic state tracking and notifications.

Status Transitions:

  • ACTIVE: Resumes a paused subscription, enabling future billing and deliveries
  • PAUSED: Temporarily suspends all billing and deliveries until manually resumed
  • CANCELLED: Permanently terminates the subscription (irreversible)

Key Features:

  • Validates status transitions (prevents same-status updates)
  • Tracks status change timestamps for audit trails
  • Sends automated email notifications to customers
  • Creates detailed activity logs for each status change
  • Handles concurrent modifications with automatic retry
  • Adjusts next billing date when resuming subscriptions

Permission Requirements (Customer Portal): When called from customer portal context:

  • PAUSED status requires 'pauseResumeSub' permission
  • ACTIVE status (resuming) requires 'resumeSub' permission
  • CANCELLED status requires 'cancelSub' permission
  • External API calls bypass these permission checks

Status Change Side Effects:

  • Activating: Recalculates next billing date, marks activation timestamp
  • Pausing: Stops all scheduled orders, marks pause timestamp
  • Cancelling: Terminates subscription permanently, marks cancellation timestamp

Error Recovery: The system automatically handles:

  • Invalid discount codes by removing them and retrying
  • Concurrent modifications by retrying the operation
  • This ensures reliable status updates in production environments

Important Notes:

  • Status values are case-insensitive
  • Cancelled subscriptions cannot be reactivated
  • Paused subscriptions retain all settings and can be resumed
  • Email notifications are sent automatically unless internally suppressed

Authentication: Requires valid X-API-Key header

Query
contractIdinteger(int64)required
statusstringrequired
pauseDurationCycleinteger(int32)
pauseFeedbackstring
pauseReasonstring
curl -i -X PUT \
  'https://www.myshop.com/apps/subscriptions/cp/api/subscription-contracts-update-status?contractId=0&status=string&pauseDurationCycle=0&pauseFeedback=string&pauseReason=string'

Responses

Status successfully updated - No content returned

Headers
X-Alertstring

Success message

Example: "Subscription Updated"
Body*/*
string
Response
No content

Update subscription delivery address and method

Request

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

Query
contractIdinteger(int64)required
Bodyapplication/jsonrequired

New shipping address and delivery method details

address1string
address2string
citystring
firstNamestring
lastNamestring
phonestring
provincestring
zipstring
countrystring
countryCodestring
provinceCodestring
companystring
locationIdstring
methodTypestring
curl -i -X PUT \
  'https://www.myshop.com/apps/subscriptions/cp/api/subscription-contracts-update-shipping-address?contractId=0' \
  -H 'Content-Type: application/json' \
  -d '{
    "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"
  }'

Responses

Shipping address successfully updated

Bodyapplication/json
get__typenamestring
idstring
createdAtobject
updatedAtobject
nextBillingDateobject
statusstring
Enum"ACTIVE""PAUSED""CANCELLED""EXPIRED""FAILED""$UNKNOWN"
deliveryPriceobject(DeliveryPrice)
lastPaymentStatusstring
Enum"SUCCEEDED""FAILED""$UNKNOWN"
billingPolicyobject(BillingPolicy)
deliveryPolicyobject(DeliveryPolicy)
linesobject(Lines)
customerPaymentMethodobject(CustomerPaymentMethod)
deliveryMethodobject(DeliveryMethod)
originOrderobject(OriginOrder)
customerobject(Customer)
discountsobject(Discounts)
notestring
customAttributesArray of objects(CustomAttribute1)
billingAttemptsobject(BillingAttempts)
Response
application/json
{
  "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": { … }
  },
  "deliveryPrice": {
    "amount": "7.99",
    "currencyCode": "USD"
  }
}

Update custom attributes on a subscription contract

Request

Updates or replaces custom key-value attributes on a subscription contract. These attributes are stored with the subscription and can be used to track custom data, preferences, or metadata that's important for your business processes.

Custom Attributes Overview: Custom attributes are key-value pairs that allow you to store additional information on subscriptions. They are:

  • Visible in the Shopify admin and accessible via API
  • Included in order data when subscription orders are created
  • Preserved across subscription lifecycle events
  • Useful for integrations and custom workflows

Update Modes:

  • Merge Mode (overwriteExistingAttributes=false): Adds new attributes and updates existing ones with matching keys. Other attributes remain unchanged.
  • Replace Mode (overwriteExistingAttributes=true): Completely replaces all existing attributes with the provided list.

Common Use Cases:

  • Store gift messages or special instructions
  • Track referral sources or marketing campaigns
  • Add internal reference numbers or tracking codes
  • Store customer preferences or customization options
  • Integration data for third-party systems

Important Notes:

  • Attribute keys should not conflict with Shopify's reserved attributes
  • Both keys and values are stored as strings
  • Changes are logged in the activity history
  • Invalid discount codes may be automatically removed during update

Authentication: Requires valid X-API-Key header

Bodyapplication/jsonrequired
subscriptionContractIdinteger(int64)required

The ID of the subscription contract to update

Example: 123456789
customAttributesListArray of objects(OrderNoteAttribute)required

List of custom attributes to set on the subscription contract. Each attribute is a key-value pair that will be stored with the subscription.

customAttributesList[].​keystringrequired

The attribute key. Should be a unique identifier for this attribute. Use descriptive keys like 'gift_message', 'delivery_instructions', etc.

Example: "gift_message"
customAttributesList[].​valuestring

The attribute value. Can be any string value including JSON-encoded data. Set to empty string to clear an attribute.

Example: "Happy Birthday! Enjoy your subscription!"
curl -i -X POST \
  https://www.myshop.com/apps/subscriptions/cp/api/update-custom-note-attributes \
  -H 'Content-Type: application/json' \
  -d '{
    "subscriptionContractId": 123456789,
    "customAttributesList": [
      {
        "key": "gift_message",
        "value": "Happy Birthday! Enjoy your subscription!"
      }
    ]
  }'

Responses

Attributes successfully updated

Bodyapplication/json
Response
application/json
{
  "message": "Attributes updated successfully"
}

Billing & Payments

APIs for managing payment methods, billing information, and processing subscription payments.

Operations

Product Catalog

APIs for retrieving product information, selling plans, variant data, and subscription-enabled products available to customers.

Operations

Delivery & Shipping

APIs for managing delivery schedules, shipping addresses, delivery methods, and tracking order status.

Customer Retention

APIs for handling subscription cancellations, retention activities, and customer feedback management.

Loyalty Integration

APIs for integrating loyalty programs with subscriptions including points redemption and earning options.

Customization

APIs for accessing portal customization settings, translations, and theme configurations.