Skip to content
/Membership Contracts

Customer Portal APIs (0.0.1)

Important Note:

The APIs in this document are for reference only and will not work directly in Swagger. To use these APIs, you need to call them from your shop.

The base URL for these APIs is your shop's domain. For example, if your shop domain is https://www.myshop.com/apps, then the full API endpoint will be based on this domain (e.g., https://www.myshop.com/apps/memberships/cp/api/**).

Please ensure the customer is logged in when calling the Customer Portal Proxy API. If the customer is not logged in, the API will return a 401 Unauthorized error.

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

Shipping & Delivery Profiles

APIs for managing Shopify delivery profiles, shipping rates, zones, and free shipping configuration for subscription memberships

Operations

Custom CSS Styling

APIs for retrieving custom CSS styles applied to subscription widgets and customer portal for theme customization

Operations

Customer Discount History

APIs for retrieving historical discount code usage and redemption information for membership contracts

Operations

Customer Portal Configuration

APIs for managing customer portal settings including UI customization, text labels, feature toggles, and branding options for the member self-service portal

Operations

Cancellation Flow Configuration

APIs for managing membership cancellation flow settings including retention offers, survey questions, and cancel confirmation screens

Operations

Membership Contracts

APIs for managing membership/subscription contracts including creation, updates, status changes, line items, discounts, and billing operations

Operations

addLineItem

Request

Query
contractIdinteger(int64)required
shopstringrequired
quantityinteger(int32)required
variantIdstringrequired
curl -i -X PUT \
  'https://www.myshop.com/apps/memberships/cp/api/v2/subscription-contracts-add-line-item?contractId=0&shop=string&quantity=0&variantId=string'

Responses

OK

Body*/*
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)

Update membership contract status

Request

Updates the status of an existing membership contract (ACTIVE, PAUSED, CANCELLED, or EXPIRED). This is one of the most critical operations for managing membership lifecycles.

Supported Status Values:

  • ACTIVE: Membership is active and will process recurring billing
  • PAUSED: Membership is temporarily paused, no billing will occur
  • CANCELLED: Membership is permanently cancelled, no future billing
  • EXPIRED: Membership has expired (typically used when max cycles reached)

Pause Duration:

  • When pausing, you can optionally specify pauseDurationCycle to auto-resume after N cycles
  • If not specified, membership remains paused until manually reactivated

Business Rules & Validations:

  • Customer Portal Restrictions: When called from customer portal, additional validations apply:
    • Cannot modify frozen memberships (freeze till min cycle condition)
    • Must respect billing cycle limits configured by merchant
  • Contract Validation: System validates that the contract belongs to the authenticated shop
  • Activity Logging: All status changes are logged with source (merchant portal vs customer portal)

Use Cases:

  • Customer wants to pause their membership temporarily
  • Merchant needs to cancel a membership due to customer request
  • Reactivating a paused membership
  • Marking membership as expired when max cycles reached

Authentication: Requires authenticated shop user or customer portal token

Query
contractIdinteger(int64)required

Membership contract ID (numeric ID, not Shopify GID)

Example: contractId=123456789
statusstringrequired

New status value

Enum"ACTIVE""PAUSED""CANCELLED""EXPIRED"
Example: status=PAUSED
pauseDurationCycleinteger(int32)

Optional pause duration in billing cycles. When specified, membership will auto-resume after N cycles

Example: pauseDurationCycle=2
curl -i -X PUT \
  'https://www.myshop.com/apps/memberships/cp/api/subscription-contracts-update-status?contractId=123456789&status=PAUSED&pauseDurationCycle=2'

Responses

Membership status updated successfully (no content returned)

Response
No content

updateShippingAddress

Request

Query
contractIdinteger(int64)required
shopstringrequired
Bodyapplication/jsonrequired
address1string
address2string
citystring
firstNamestring
lastNamestring
phonestring
provincestring
zipstring
countrystring
countryCodestring
provinceCodestring
companystring
curl -i -X PUT \
  'https://www.myshop.com/apps/memberships/cp/api/subscription-contracts-update-shipping-address?contractId=0&shop=string' \
  -H 'Content-Type: application/json' \
  -d '{
    "address1": "string",
    "address2": "string",
    "city": "string",
    "firstName": "string",
    "lastName": "string",
    "phone": "string",
    "province": "string",
    "zip": "string",
    "country": "string",
    "countryCode": "string",
    "provinceCode": "string",
    "company": "string"
  }'

Responses

OK

Body*/*
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)

Billing & Orders

APIs for managing membership billing attempts, recurring orders, payment retries, order history, and order skipping

Operations

Product & Inventory Data

APIs for retrieving product catalog, variants, pricing, and inventory information for subscription memberships

Operations

One-Time Add-Ons

APIs for managing one-time product additions to upcoming subscription orders, including adding, retrieving, and removing one-off items

Operations

Membership Plans

APIs for managing membership/subscription plan groups, including creating plans, configuring discounts, billing intervals, and assigning products to plans

Operations

Product Swap Rules

APIs for retrieving product swap/substitution options allowing members to exchange subscription items based on configured swap rules and variant groups

Operations

loyalty-integration-resource

Operations

customer-retention-activity-resource

Operations

shop-info-resource

Operations