# Membership Contracts

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

## addLineItem

 - [PUT /memberships/cp/api/v2/subscription-contracts-add-line-item](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/addlineitem.md)

## Update membership contract status

 - [PUT /memberships/cp/api/subscription-contracts-update-status](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/updatestatus.md): 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

## updateShippingAddress

 - [PUT /memberships/cp/api/subscription-contracts-update-shipping-address](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/updateshippingaddress.md)

## updatePaymentMethod

 - [PUT /memberships/cp/api/subscription-contracts-update-payment-method](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/updatepaymentmethod.md)

## updateOrderNote

 - [PUT /memberships/cp/api/subscription-contracts-update-order-note/{contractId}](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/updateordernote.md)

## updateLineItemAttributes

 - [PUT /memberships/cp/api/subscription-contracts-update-line-item-attributes](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/updatelineitemattributes.md)

## updateExistingPaymentMethod

 - [PUT /memberships/cp/api/subscription-contracts-update-existing-payment-method](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/updateexistingpaymentmethod.md)

## updateBillingInterval

 - [PUT /memberships/cp/api/subscription-contracts-update-billing-interval](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/updatebillinginterval.md)

## updateNextBillingDate

 - [PUT /memberships/cp/api/subscription-contracts-update-billing-date](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/updatenextbillingdate.md)

## removeLineItem

 - [PUT /memberships/cp/api/subscription-contracts-remove-line-item](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/removelineitem.md)

## removeDiscount

 - [PUT /memberships/cp/api/subscription-contracts-remove-discount](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/removediscount.md)

## addCancellationDiscount

 - [PUT /memberships/cp/api/subscription-contracts-cancellation-discount](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/addcancellationdiscount.md)

## applyDiscountCode

 - [PUT /memberships/cp/api/subscription-contracts-apply-discount](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/applydiscountcode.md)

## Add a product to an existing membership contract

 - [PUT /memberships/cp/api/subscription-contracts-add-line-item](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/addlineitem_1.md): Adds a new product/variant line item to an existing active membership contract. This allows customers or merchants to add additional products to their recurring membership orders.

Key Features:
- Add any product variant to an existing membership
- Specify custom quantity and price per line item
- Product will be included in all future billing cycles
- Price is per-item, total line price = price × quantity

Important Notes:
- Immediate Effect: Product is added immediately and will appear in the next billing cycle
- Price Override: The price parameter allows setting a custom price (e.g., member discount)
- Activity Logging: Addition is logged for audit trail
- Validation: System validates that the variant exists and is available

Common Use Cases:
- Customer wants to add more products to their monthly membership box
- Merchant adds a complimentary product to a membership
- Upgrading membership with additional items
- Adding seasonal or limited-time products to existing memberships

Price Considerations:
- Price is specified in shop's currency
- Can be set to member-only pricing (different from regular product price)
- Zero price is allowed for free add-ons

Variant ID Format:
- Accepts both numeric ID (e.g., '987654321') and Shopify GID format
- System will convert to proper Shopify GraphQL format internally

Authentication: Requires authenticated shop user or customer portal token

## updateVariant

 - [PUT /memberships/cp/api/subscription-contract-update-variant](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/updatevariant.md)

## updateSubscriptionContractDetails

 - [PUT /memberships/cp/api/subscription-contract-details](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/updatesubscriptioncontractdetails.md)

## getSubscriptionCustomerForCP

 - [GET /memberships/cp/api/subscription-customers](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/getsubscriptioncustomerforcp.md)

## getValidSubscriptionCustomerForCP

 - [GET /memberships/cp/api/subscription-customers/valid](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/getvalidsubscriptioncustomerforcp.md)

## getValidSubscriptionCustomerDetails

 - [GET /memberships/cp/api/subscription-customers-detail/valid/{id}](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/getvalidsubscriptioncustomerdetails.md)

## getSubscriptionContractRaw

 - [GET /memberships/cp/api/subscription-contracts/contract/{contractId}](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/getsubscriptioncontractraw.md)

## getSubscriptionContractRawExternal

 - [GET /memberships/cp/api/subscription-contracts/contract-external/{contractId}](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/getsubscriptioncontractrawexternal.md)

## emailMagicLink

 - [GET /memberships/cp/api/subscription-contracts-email-magic-link](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/emailmagiclink.md)

## getPendingDowngrade

 - [GET /memberships/cp/api/subscription-contract-details/{contractId}/pending-downgrade](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/getpendingdowngrade.md)

## cancelPendingDowngrade

 - [DELETE /memberships/cp/api/subscription-contract-details/{contractId}/pending-downgrade](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/cancelpendingdowngrade.md)

## getSubscriptionFulfillments

 - [GET /memberships/cp/api/subscription-contract-details/subscription-fulfillments/{contractId}](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/getsubscriptionfulfillments.md)

## getShopifyCustomerPaymentDetails

 - [GET /memberships/cp/api/subscription-contract-details/shopify/customer/{customerId}/payment-methods](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/getshopifycustomerpaymentdetails.md)

## getSubscriptionOrderNote

 - [GET /memberships/cp/api/subscription-contract-details/customer/{contractId}](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/getsubscriptionordernote.md)

## getCurrentCycleOfSubscriptionContract

 - [GET /memberships/cp/api/subscription-contract-details/current-cycle/{contractId}](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/getcurrentcycleofsubscriptioncontract.md)

## Cancel a membership contract

 - [DELETE /memberships/cp/api/subscription-contracts/{id}](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/deletesubscriptioncontract.md): Permanently cancels an active membership contract in Shopify. This operation stops all future billing and marks the membership as CANCELLED.

Important Notes:
- Permanent Action: Cancellation cannot be undone. A new membership must be created to re-subscribe.
- Email Notification: Cancellation email is automatically sent to the customer
- Activity Logging: Cancellation is logged with reason/feedback for analytics
- Immediate Effect: No future billing attempts will be made

Customer Portal Restrictions:
When called from customer portal, additional validations apply:
- Minimum Cycles: Cannot cancel if membership hasn't completed minimum required billing cycles
- Frozen Memberships: Cannot cancel memberships that are frozen until min cycle completion
- Attribute-Based Limits: Respects any custom attribute-based cancellation restrictions

Cancellation Feedback:
- Optional cancellationFeedback parameter to capture why customer is cancelling
- Common values: 'TOO_EXPENSIVE', 'NO_LONGER_NEEDED', 'SWITCHING_TO_COMPETITOR', 'OTHER'
- Helps merchants understand churn reasons

Use Cases:
- Customer requests to cancel their membership
- Merchant manually cancels membership (e.g., payment issues, customer request)
- Automated cancellation after max cycles reached

Authentication: Requires authenticated shop user or customer portal token