# Storefront APIs

Comprehensive API documentation for the customer-facing membership portal. These APIs enable customers to manage their memberships, 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/memberships/cp/api/**) and require customer authentication. Unauthenticated requests will return a 401 Unauthorized error.

Version: 0.0.1

## Servers

```
https://www.myshop.com/apps
```

## Download OpenAPI description

[Storefront APIs](https://developers.membership.appstle.com/_bundle/storefront-api-swagger.yaml)

## Membership Contracts

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

### Add line item to contract

 - [PUT /memberships/cp/api/v2/subscription-contracts-add-line-item](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/addlineitem.md): Adds a new product line item to a subscription contract from the customer portal.

### 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

### Update shipping address

 - [PUT /memberships/cp/api/subscription-contracts-update-shipping-address](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/updateshippingaddress.md): Updates the shipping/delivery address for a subscription contract from the customer portal.

### Update payment method

 - [PUT /memberships/cp/api/subscription-contracts-update-payment-method](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/updatepaymentmethod.md): Updates the payment method associated with a subscription contract from the customer portal.

### Update order note

 - [PUT /memberships/cp/api/subscription-contracts-update-order-note/{contractId}](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/updateordernote.md): Updates the order note for a subscription contract from the customer portal.

### Update line item attributes

 - [PUT /memberships/cp/api/subscription-contracts-update-line-item-attributes](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/updatelineitemattributes.md): Updates custom attributes on a subscription contract line item from the customer portal.

### Update existing payment method details

 - [PUT /memberships/cp/api/subscription-contracts-update-existing-payment-method](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/updateexistingpaymentmethod.md): Updates the details of an existing payment method associated with a subscription contract.

### Update billing interval

 - [PUT /memberships/cp/api/subscription-contracts-update-billing-interval](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/updatebillinginterval.md): Updates the billing frequency interval for a subscription contract from the customer portal.

### Update next billing date

 - [PUT /memberships/cp/api/subscription-contracts-update-billing-date](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/updatenextbillingdate.md): Updates the next billing date for a subscription contract from the customer portal.

### Remove line item from contract

 - [PUT /memberships/cp/api/subscription-contracts-remove-line-item](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/removelineitem.md): Removes a product line item from a subscription contract from the customer portal.

### Remove discount from contract

 - [PUT /memberships/cp/api/subscription-contracts-remove-discount](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/removediscount.md): Removes an applied discount from a subscription contract from the customer portal.

### Apply cancellation retention discount

 - [PUT /memberships/cp/api/subscription-contracts-cancellation-discount](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/addcancellationdiscount.md): Applies a retention discount to a subscription contract as part of the cancellation flow to retain the customer.

### Apply discount code

 - [PUT /memberships/cp/api/subscription-contracts-apply-discount](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/applydiscountcode.md): Applies a discount code to a subscription contract from the customer portal.

### 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

### Update line item variant

 - [PUT /memberships/cp/api/subscription-contract-update-variant](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/updatevariant.md): Updates the product variant for a line item in a subscription contract, allowing customers to swap to a different variant.

### Update subscription contract details

 - [PUT /memberships/cp/api/subscription-contract-details](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/updatesubscriptioncontractdetails.md): Updates an existing subscription contract's details from the customer portal.

### Get current customer's membership subscription profile

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

### List current customer's valid subscription contract IDs

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

### Get valid subscription contracts for a customer

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

### Get subscription contract details

 - [GET /memberships/cp/api/subscription-contracts/contract/{contractId}](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/getsubscriptioncontractraw.md): Retrieves the raw subscription contract details for a specific contract by ID.

### Get raw Shopify subscription contract data

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

### Send magic link email

 - [GET /memberships/cp/api/subscription-contracts-email-magic-link](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/emailmagiclink.md): Sends a magic link email to the customer for passwordless access to manage their subscription.

### Get pending downgrade

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

### Cancel pending downgrade

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

### List Shopify fulfillments for a subscription contract

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

### Get customer payment methods

 - [GET /memberships/cp/api/subscription-contract-details/shopify/customer/{customerId}/payment-methods](https://developers.membership.appstle.com/storefront-api-swagger/membership-contracts/getshopifycustomerpaymentdetails.md): Retrieves available Shopify payment methods for a specific customer from the customer portal.

### Get customer subscription details

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

### Get current billing cycle

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

### 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

## Billing & Orders

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

### Skip an upcoming billing order

 - [PUT /memberships/cp/api/subscription-billing-attempts/skip-order/{id}](https://developers.membership.appstle.com/storefront-api-swagger/billing-and-orders/skiporder.md): Skips the next scheduled billing/order for a membership contract. The membership remains active, but the next billing date is moved to the following cycle.

Key Features:
- Skip next billing without canceling membership
- Automatically reschedule to next billing cycle
- Works for both regular and prepaid memberships
- Activity logging for audit trail

How It Works:
1. Validates billing attempt exists and belongs to shop
2. Updates next billing date to skip current cycle
3. Moves billing to the next scheduled interval
4. Logs activity (customer portal vs merchant portal)

Customer Portal Restrictions:
- Cannot skip if membership is frozen until min cycles
- Validates contract ownership for security

Use Cases:
- Customer is traveling and wants to skip one delivery
- Customer has excess inventory and wants to pause one cycle
- Merchant wants to skip a billing due to out-of-stock items
- Skip billing for special circumstances (holidays, etc.)

Prepaid Handling:
- Set isPrepaid=true for prepaid memberships
- Different validation logic for prepaid vs pay-as-you-go

Authentication: Requires authenticated shop user or customer portal token

### Trigger billing attempt

 - [PUT /memberships/cp/api/subscription-billing-attempts/attempt-billing/{id}](https://developers.membership.appstle.com/storefront-api-swagger/billing-and-orders/attemptbilling.md): Triggers an immediate billing attempt for a specific subscription billing record from the customer portal.

### Update billing attempt

 - [PUT /memberships/cp/api/subscription-billing-attempts](https://developers.membership.appstle.com/storefront-api-swagger/billing-and-orders/updatesubscriptionbillingattempt.md): Updates a subscription billing attempt record from the customer portal.

### Get upcoming orders

 - [GET /memberships/cp/api/subscription-billing-attempts/top-orders](https://developers.membership.appstle.com/storefront-api-swagger/billing-and-orders/gettopordersforcp.md): Retrieves upcoming/scheduled orders for a subscription contract from the customer portal.

### Get past orders

 - [GET /memberships/cp/api/subscription-billing-attempts/past-orders](https://developers.membership.appstle.com/storefront-api-swagger/billing-and-orders/getpastordersforcp.md): Retrieves past order history for a subscription contract from the customer portal.

## One-Time Add-Ons

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

### Add or update one-off item

 - [PUT /memberships/cp/api/subscription-contract-one-offs-by-contractId-and-billing-attempt-id](https://developers.membership.appstle.com/storefront-api-swagger/one-time-add-ons/saveoneoffby.md): Adds or updates a one-time product for a specific subscription contract's upcoming billing attempt.

### Get one-off items for contract

 - [GET /memberships/cp/api/subscription-contract-one-offs-by-contractId](https://developers.membership.appstle.com/storefront-api-swagger/one-time-add-ons/getoneoffsforsubscriptioncontract.md): Retrieves all one-time add-on products associated with a specific subscription contract and billing attempt.

## Customer Discount History

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

### Get past discount history

 - [GET /memberships/cp/api/customer-discount-code-infos/get-past-discounts](https://developers.membership.appstle.com/storefront-api-swagger/customer-discount-history/getcustomerdiscountdetails.md): Retrieves the history of discount codes applied to a customer's subscription contracts.

## Product & Inventory Data

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

### Get contextual pricing for a variant by currency

 - [GET /memberships/cp/api/data/variant-contextual-pricing](https://developers.membership.appstle.com/storefront-api-swagger/product-and-inventory-data/getvariantcontextualpricing.md)

### List products attached to selling plans

 - [GET /memberships/cp/api/data/selling-plan-products](https://developers.membership.appstle.com/storefront-api-swagger/product-and-inventory-data/getsellingplanproductsdata.md)

### Search subscription-enabled products with pagination

 - [GET /memberships/cp/api/data/products](https://developers.membership.appstle.com/storefront-api-swagger/product-and-inventory-data/getproductsdata.md)

### Get product with selling plans and variants

 - [GET /memberships/cp/api/data/product-selling-plan-variant](https://developers.membership.appstle.com/storefront-api-swagger/product-and-inventory-data/getproductsellingplanvariantdata.md)

### Get product details by ID

 - [GET /memberships/cp/api/data/product](https://developers.membership.appstle.com/storefront-api-swagger/product-and-inventory-data/getproductdata.md)

## Product Swap Rules

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

### Get product swap options by variant

 - [POST /memberships/cp/api/product-swaps-by-variant-groups](https://developers.membership.appstle.com/storefront-api-swagger/product-swap-rules/getproductswapsbyvariantid.md): Retrieves available product swap/substitution options for specified variant IDs, allowing customers to exchange subscription items.

## Shipping & Delivery Profiles

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

### Get pickup locations

 - [GET /memberships/cp/api/delivery-profiles/get-locations](https://developers.membership.appstle.com/storefront-api-swagger/shipping-and-delivery-profiles/getlocations.md): Retrieves available pickup locations for the customer's subscription delivery.

## Membership Plans

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

### Get all selling plans

 - [GET /memberships/cp/api/subscription-groups/all-selling-plans](https://developers.membership.appstle.com/storefront-api-swagger/membership-plans/getallsellingplans.md): Retrieves all available selling plans for the customer portal, used to display plan options to customers.

## 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

### Get customer portal label translations for locale

 - [GET /memberships/cp/api/label-translations/locale](https://developers.membership.appstle.com/storefront-api-swagger/customer-portal-configuration/getcplabelsbylocaleandtype.md)

### Get customer portal settings

 - [GET /memberships/cp/api/customer-portal-settings/{id}](https://developers.membership.appstle.com/storefront-api-swagger/customer-portal-configuration/getcustomerportalsettings.md): Retrieves the customer portal configuration including UI customization, text labels, feature toggles, and branding options.

## Shop Settings

APIs for managing shop-level membership settings, configuration, email domains, webhooks, and general store information

### Get shop info for current user

 - [GET /memberships/cp/api/shop-infos-by-current-login](https://developers.membership.appstle.com/storefront-api-swagger/shop-settings/getshopinfobycurrentlogin.md): Retrieves shop information and membership settings for the currently authenticated customer's shop.

## Custom CSS Styling

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

### Get custom CSS styles

 - [GET /memberships/cp/api/subscription-custom-csses/{id}](https://developers.membership.appstle.com/storefront-api-swagger/custom-css-styling/getsubscriptioncustomcss.md): Retrieves the custom CSS styling configuration for the subscription customer portal and widgets.

## Cancellation Flow Configuration

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

### Get cancellation flow settings

 - [GET /memberships/cp/api/cancellation-managements/{id}](https://developers.membership.appstle.com/storefront-api-swagger/cancellation-flow-configuration/getcancellationmanagement.md): Retrieves the cancellation management configuration including retention offers, cancellation reasons, and survey settings.

## Loyalty Integration

APIs for integrating loyalty programs with memberships including customer points lookup, earn options, redeem options, and point redemption

### Redeem loyalty points

 - [POST /memberships/cp/api/loyalty-integration/redeem](https://developers.membership.appstle.com/storefront-api-swagger/loyalty-integration/redeempoints.md): Redeems loyalty points for a customer associated with a specific subscription contract using the specified redemption option.

### Get loyalty point redeem options

 - [GET /memberships/cp/api/loyalty-integration/redeem-options](https://developers.membership.appstle.com/storefront-api-swagger/loyalty-integration/getredeemoptions.md): Retrieves available loyalty point redemption rules and options for the shop.

### Get loyalty point earn options

 - [GET /memberships/cp/api/loyalty-integration/earn-options](https://developers.membership.appstle.com/storefront-api-swagger/loyalty-integration/getearnoptions.md): Retrieves available loyalty point earning campaigns and rules for the shop.

### Get loyalty customer details

 - [GET /memberships/cp/api/loyalty-integration/customer](https://developers.membership.appstle.com/storefront-api-swagger/loyalty-integration/fetchcustomerdetail.md): Retrieves loyalty program details for a customer associated with a specific subscription contract, including points balance.

## Customer Retention

APIs for managing customer retention activities including cancellation feedback, retention action tracking, and activity export

### Create retention activity record

 - [POST /memberships/cp/api/customer-retention-activities](https://developers.membership.appstle.com/storefront-api-swagger/customer-retention/createcustomerretentionactivity.md): Records a customer retention activity such as cancellation feedback, retention offer acceptance, or other retention-related actions.