Skip to content
/Billing & Orders

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

Billing & Orders

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

Operations

Skip an upcoming billing order

Request

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

Path
idinteger(int64)required

Billing attempt ID to skip

Example: 123456
Query
subscriptionContractIdinteger(int64)

Optional subscription contract ID for additional validation

Example: subscriptionContractId=789012
isPrepaidboolean

Set to true if this is a prepaid membership

Default false
curl -i -X PUT \
  'https://www.myshop.com/apps/memberships/cp/api/subscription-billing-attempts/skip-order/123456?subscriptionContractId=789012&isPrepaid=false'

Responses

Billing order successfully skipped

Bodyapplication/json
idinteger(int64)
shopstringrequired
billingAttemptIdstring
statusstring
Enum"SUCCESS""FAILURE""REQUESTING""PROGRESS""QUEUED""SKIPPED""SOCIAL_CONNECTION_NULL""CONTRACT_CANCELLED""CONTRACT_ENDED""CONTRACT_PAUSED"
billingDatestring(date-time)
contractIdinteger(int64)
attemptCountinteger(int32)
attemptTimestring(date-time)
graphOrderIdstring
orderIdinteger(int64)
orderAmountnumber(double)
orderNamestring
retryingNeededbooleanrequired
transactionFailedEmailSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED"
upcomingOrderEmailSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED""STOP_FROM_CONTRACT""CONTRACT_PAUSED"
applyUsageChargeboolean
recurringChargeIdinteger(int64)
transactionRatenumber(double)
usageChargeStatusstring
Enum"SUCCESS""FAILED""TO_BE_TRIED"
transactionFailedSmsSentStatusstring
Enum"SENT""UNSENT""FAILED""SMS_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED""PHONE_NUMBER_EMPTY"
upcomingOrderSmsSentStatusstring
Enum"SENT""UNSENT""FAILED""SMS_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED""STOP_FROM_CONTRACT""CONTRACT_PAUSED""PHONE_NUMBER_EMPTY"
billingAttemptResponseMessagestring
progressAttemptCountinteger(int32)
orderNotestring
variantListArray of objects(VariantQuantity)
orderAmountUSDnumber(double)
securityChallengeSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CONTRACT_CANCELLED"
upgradeDowngradeBillingboolean
Response
application/json
{
  "id": 0,
  "shop": "string",
  "billingAttemptId": "string",
  "status": "SUCCESS",
  "billingDate": "2019-08-24T14:15:22Z",
  "contractId": 0,
  "attemptCount": 0,
  "attemptTime": "2019-08-24T14:15:22Z",
  "graphOrderId": "string",
  "orderId": 0,
  "orderAmount": 0.1,
  "orderName": "string",
  "retryingNeeded": true,
  "transactionFailedEmailSentStatus": "SENT",
  "upcomingOrderEmailSentStatus": "SENT",
  "applyUsageCharge": true,
  "recurringChargeId": 0,
  "transactionRate": 0.1,
  "usageChargeStatus": "SUCCESS",
  "transactionFailedSmsSentStatus": "SENT",
  "upcomingOrderSmsSentStatus": "SENT",
  "billingAttemptResponseMessage": "string",
  "progressAttemptCount": 0,
  "orderNote": "string",
  "variantList": [
    { … }
  ],
  "orderAmountUSD": 0.1,
  "securityChallengeSentStatus": "SENT",
  "upgradeDowngradeBilling": true
}

attemptBilling

Request

Path
idinteger(int64)required
Query
shopstringrequired
curl -i -X PUT \
  'https://www.myshop.com/apps/memberships/cp/api/subscription-billing-attempts/attempt-billing/{id}?shop=string'

Responses

OK

updateSubscriptionBillingAttempt

Request

Bodyapplication/jsonrequired
idinteger(int64)
shopstringrequired
billingAttemptIdstring
statusstring
Enum"SUCCESS""FAILURE""REQUESTING""PROGRESS""QUEUED""SKIPPED""SOCIAL_CONNECTION_NULL""CONTRACT_CANCELLED""CONTRACT_ENDED""CONTRACT_PAUSED"
billingDatestring(date-time)
contractIdinteger(int64)
attemptCountinteger(int32)
attemptTimestring(date-time)
graphOrderIdstring
orderIdinteger(int64)
orderAmountnumber(double)
orderNamestring
retryingNeededbooleanrequired
transactionFailedEmailSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED"
upcomingOrderEmailSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED""STOP_FROM_CONTRACT""CONTRACT_PAUSED"
applyUsageChargeboolean
recurringChargeIdinteger(int64)
transactionRatenumber(double)
usageChargeStatusstring
Enum"SUCCESS""FAILED""TO_BE_TRIED"
transactionFailedSmsSentStatusstring
Enum"SENT""UNSENT""FAILED""SMS_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED""PHONE_NUMBER_EMPTY"
upcomingOrderSmsSentStatusstring
Enum"SENT""UNSENT""FAILED""SMS_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED""STOP_FROM_CONTRACT""CONTRACT_PAUSED""PHONE_NUMBER_EMPTY"
billingAttemptResponseMessagestring
progressAttemptCountinteger(int32)
orderNotestring
variantListArray of objects(VariantQuantity)
orderAmountUSDnumber(double)
securityChallengeSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CONTRACT_CANCELLED"
upgradeDowngradeBillingboolean
curl -i -X PUT \
  https://www.myshop.com/apps/memberships/cp/api/subscription-billing-attempts \
  -H 'Content-Type: application/json' \
  -d '{
    "id": 0,
    "shop": "string",
    "billingAttemptId": "string",
    "status": "SUCCESS",
    "billingDate": "2019-08-24T14:15:22Z",
    "contractId": 0,
    "attemptCount": 0,
    "attemptTime": "2019-08-24T14:15:22Z",
    "graphOrderId": "string",
    "orderId": 0,
    "orderAmount": 0.1,
    "orderName": "string",
    "retryingNeeded": true,
    "transactionFailedEmailSentStatus": "SENT",
    "upcomingOrderEmailSentStatus": "SENT",
    "applyUsageCharge": true,
    "recurringChargeId": 0,
    "transactionRate": 0.1,
    "usageChargeStatus": "SUCCESS",
    "transactionFailedSmsSentStatus": "SENT",
    "upcomingOrderSmsSentStatus": "SENT",
    "billingAttemptResponseMessage": "string",
    "progressAttemptCount": 0,
    "orderNote": "string",
    "variantList": [
      {
        "variantId": 0,
        "quantity": 0,
        "title": "string",
        "image": "string",
        "productTitle": "string",
        "productId": "string",
        "sellingPlanId": "string"
      }
    ],
    "orderAmountUSD": 0.1,
    "securityChallengeSentStatus": "SENT",
    "upgradeDowngradeBilling": true
  }'

Responses

OK

Body*/*
idinteger(int64)
shopstringrequired
billingAttemptIdstring
statusstring
Enum"SUCCESS""FAILURE""REQUESTING""PROGRESS""QUEUED""SKIPPED""SOCIAL_CONNECTION_NULL""CONTRACT_CANCELLED""CONTRACT_ENDED""CONTRACT_PAUSED"
billingDatestring(date-time)
contractIdinteger(int64)
attemptCountinteger(int32)
attemptTimestring(date-time)
graphOrderIdstring
orderIdinteger(int64)
orderAmountnumber(double)
orderNamestring
retryingNeededbooleanrequired
transactionFailedEmailSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED"
upcomingOrderEmailSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED""STOP_FROM_CONTRACT""CONTRACT_PAUSED"
applyUsageChargeboolean
recurringChargeIdinteger(int64)
transactionRatenumber(double)
usageChargeStatusstring
Enum"SUCCESS""FAILED""TO_BE_TRIED"
transactionFailedSmsSentStatusstring
Enum"SENT""UNSENT""FAILED""SMS_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED""PHONE_NUMBER_EMPTY"
upcomingOrderSmsSentStatusstring
Enum"SENT""UNSENT""FAILED""SMS_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED""STOP_FROM_CONTRACT""CONTRACT_PAUSED""PHONE_NUMBER_EMPTY"
billingAttemptResponseMessagestring
progressAttemptCountinteger(int32)
orderNotestring
variantListArray of objects(VariantQuantity)
orderAmountUSDnumber(double)
securityChallengeSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CONTRACT_CANCELLED"
upgradeDowngradeBillingboolean

getTopOrdersForCP

Request

Query
contractIdinteger(int64)
curl -i -X GET \
  'https://www.myshop.com/apps/memberships/cp/api/subscription-billing-attempts/top-orders?contractId=0'

Responses

OK

Body*/*Array [
idinteger(int64)
shopstringrequired
billingAttemptIdstring
statusstring
Enum"SUCCESS""FAILURE""REQUESTING""PROGRESS""QUEUED""SKIPPED""SOCIAL_CONNECTION_NULL""CONTRACT_CANCELLED""CONTRACT_ENDED""CONTRACT_PAUSED"
billingDatestring(date-time)
contractIdinteger(int64)
attemptCountinteger(int32)
attemptTimestring(date-time)
graphOrderIdstring
orderIdinteger(int64)
orderAmountnumber(double)
orderNamestring
retryingNeededbooleanrequired
transactionFailedEmailSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED"
upcomingOrderEmailSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED""STOP_FROM_CONTRACT""CONTRACT_PAUSED"
applyUsageChargeboolean
recurringChargeIdinteger(int64)
transactionRatenumber(double)
usageChargeStatusstring
Enum"SUCCESS""FAILED""TO_BE_TRIED"
transactionFailedSmsSentStatusstring
Enum"SENT""UNSENT""FAILED""SMS_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED""PHONE_NUMBER_EMPTY"
upcomingOrderSmsSentStatusstring
Enum"SENT""UNSENT""FAILED""SMS_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED""STOP_FROM_CONTRACT""CONTRACT_PAUSED""PHONE_NUMBER_EMPTY"
billingAttemptResponseMessagestring
progressAttemptCountinteger(int32)
orderNotestring
variantListArray of objects(VariantQuantity)
orderAmountUSDnumber(double)
securityChallengeSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CONTRACT_CANCELLED"
upgradeDowngradeBillingboolean
]

getPastOrdersForCP

Request

Query
contractIdinteger(int64)
curl -i -X GET \
  'https://www.myshop.com/apps/memberships/cp/api/subscription-billing-attempts/past-orders?contractId=0'

Responses

OK

Body*/*Array [
idinteger(int64)
shopstringrequired
billingAttemptIdstring
statusstring
Enum"SUCCESS""FAILURE""REQUESTING""PROGRESS""QUEUED""SKIPPED""SOCIAL_CONNECTION_NULL""CONTRACT_CANCELLED""CONTRACT_ENDED""CONTRACT_PAUSED"
billingDatestring(date-time)
contractIdinteger(int64)
attemptCountinteger(int32)
attemptTimestring(date-time)
graphOrderIdstring
orderIdinteger(int64)
orderAmountnumber(double)
orderNamestring
retryingNeededbooleanrequired
transactionFailedEmailSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED"
upcomingOrderEmailSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED""STOP_FROM_CONTRACT""CONTRACT_PAUSED"
applyUsageChargeboolean
recurringChargeIdinteger(int64)
transactionRatenumber(double)
usageChargeStatusstring
Enum"SUCCESS""FAILED""TO_BE_TRIED"
transactionFailedSmsSentStatusstring
Enum"SENT""UNSENT""FAILED""SMS_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED""PHONE_NUMBER_EMPTY"
upcomingOrderSmsSentStatusstring
Enum"SENT""UNSENT""FAILED""SMS_SETTINGS_DISABLED""CUSTOMER_PAYMENT_EMPTY""CONTRACT_CANCELLED""STOP_FROM_CONTRACT""CONTRACT_PAUSED""PHONE_NUMBER_EMPTY"
billingAttemptResponseMessagestring
progressAttemptCountinteger(int32)
orderNotestring
variantListArray of objects(VariantQuantity)
orderAmountUSDnumber(double)
securityChallengeSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CONTRACT_CANCELLED"
upgradeDowngradeBillingboolean
]

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