Skip to content
Customer Portal APIs
/
/
Unskip a previously skipp...

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

Billing & Payments

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

Operations

Update next billing date for a subscription contract

Request

Reschedules the next billing date for an active subscription contract. This endpoint allows you to change when the next order will be created and processed.

Key Features:

  • Updates the next billing date to the specified date
  • Optionally reschedules all future orders based on the new date
  • Syncs the updated date to Shopify
  • Sends confirmation email to customer

The rescheduleFutureOrder Parameter:

  • true (default): Updates the next billing date AND recalculates all future queued orders based on the new date. Use this to shift the entire billing schedule.
  • false: Only updates the next billing date. Other queued orders remain unchanged. Use this for one-time date adjustments.

Important Notes:

  • The new date must be in the future (with 10 minute grace period)
  • Date is validated against the shop's timezone
  • If anchor days are configured, future orders may align to those anchors

Process Flow:

  1. Validates the contract exists and belongs to the shop
  2. Validates the new date is not in the past
  3. Updates the billing attempt to the new date
  4. Syncs the updated nextBillingDate to Shopify
  5. If rescheduleFutureOrder=true, regenerates the queue from the new date
  6. Sends confirmation email to customer
  7. Records activity log entry

Date Format:

  • Must be ISO 8601 format with timezone
  • Examples: 2024-03-15T12:00:00Z, 2024-03-15T12:00:00+05:30
  • URL encode the date when passing as query parameter

Timezone Handling:

  • The provided date is used as-is for the billing attempt
  • Validation (past date check) uses the shop's configured timezone
  • All dates in the response are in UTC (Z suffix)

Date Restrictions (Customer Portal Only): When called from customer portal context:

  • Minimum days from today (skipDaysFromCurrentDate setting)
  • Maximum days from today (billingDateRestrictToDays setting)
  • External API calls bypass these restrictions

Authentication: Requires valid X-API-Key header

Query
contractIdinteger(int64)required
nextBillingDatestring(date-time)required
rescheduleFutureOrderboolean
Default true
curl -i -X PUT \
  'https://www.myshop.com/apps/subscriptions/cp/api/subscription-contracts-update-billing-date?contractId=0&nextBillingDate=2019-08-24T14%3A15%3A22Z&rescheduleFutureOrder=true'

Responses

Billing date successfully updated. The response contains the updated subscription contract from Shopify with the new nextBillingDate.

Headers
X-Application-Contextstring

Application context with alert message

Example: "appname:Subscription 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
{
  "__typename": "SubscriptionContract",
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-03-15T12:00:00Z",
  "updatedAt": "2024-02-15T10:30:00Z",
  "billingPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "customer": {
    "email": "customer@example.com",
    "displayName": "John Doe"
  }
}

Unskip a previously skipped order

Request

Reverses a skip action on a billing attempt. The order will be restored to QUEUED status and will be processed on its scheduled date.

Important Notes:

  • Only works on billing attempts with SKIPPED status
  • Must be done before the scheduled billing date
  • Cannot unskip after the billing date has passed
  • Activity logs are created for audit trail

Use Cases:

  • Customer changes their mind about skipping
  • Correct accidental skip actions
  • Restore delivery after resolving temporary issue

Authentication: Requires valid X-API-Key header

Path
idinteger(int64)required
Query
subscriptionContractIdinteger(int64)
curl -i -X PUT \
  'https://www.myshop.com/apps/subscriptions/cp/api/subscription-billing-attempts/unskip-order/{id}?subscriptionContractId=0'

Responses

Order successfully unskipped

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)
securityChallengeSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CONTRACT_CANCELLED"
orderAmountUSDnumber(double)
orderCancelReasonstring
Enum"CUSTOMER""DECLINED""FRAUD""INVENTORY""STAFF""OTHER""$UNKNOWN"
orderCancelledAtstring(date-time)
orderClosedboolean
orderClosedAtstring(date-time)
orderConfirmedboolean
orderDisplayFinancialStatusstring
Enum"PENDING""AUTHORIZED""PARTIALLY_PAID""PARTIALLY_REFUNDED""VOIDED""PAID""REFUNDED""EXPIRED""$UNKNOWN"
orderDisplayFulfillmentStatusstring
Enum"UNFULFILLED""PARTIALLY_FULFILLED""FULFILLED""RESTOCKED""PENDING_FULFILLMENT""OPEN""IN_PROGRESS""ON_HOLD""SCHEDULED""REQUEST_DECLINED"
orderProcessedAtstring(date-time)
lastShippingUpdatedAtstring(date-time)
inventorySkippedAttemptCountinteger(int32)
inventorySkippedRetryingNeededboolean
orderAttributesArray of objects(AttributeInfo)
partialLinesSkippedstring
Enum"INVENTORY_MANAGEMENT""MANUAL"
orderAmountContractCurrencynumber(double)
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": [
    { … }
  ],
  "securityChallengeSentStatus": "SENT",
  "orderAmountUSD": 0.1,
  "orderCancelReason": "CUSTOMER",
  "orderCancelledAt": "2019-08-24T14:15:22Z",
  "orderClosed": true,
  "orderClosedAt": "2019-08-24T14:15:22Z",
  "orderConfirmed": true,
  "orderDisplayFinancialStatus": "PENDING",
  "orderDisplayFulfillmentStatus": "UNFULFILLED",
  "orderProcessedAt": "2019-08-24T14:15:22Z",
  "lastShippingUpdatedAt": "2019-08-24T14:15:22Z",
  "inventorySkippedAttemptCount": 0,
  "inventorySkippedRetryingNeeded": true,
  "orderAttributes": [
    { … }
  ],
  "partialLinesSkipped": "INVENTORY_MANAGEMENT",
  "orderAmountContractCurrency": 0.1
}

Skip the next upcoming order for a subscription

Request

Skips the next scheduled billing attempt for a subscription contract without requiring the billing attempt ID. Automatically finds and skips the earliest QUEUED billing attempt.

Convenience Feature:

  • No need to know the specific billing attempt ID
  • Automatically finds the next order
  • Ideal for "skip next order" functionality in customer portals

Use Cases:

  • Simple "skip next delivery" button in customer portal
  • Quick skip without looking up billing attempt details
  • One-click skip functionality

Authentication: Requires valid X-API-Key header

Query
subscriptionContractIdinteger(int64)
curl -i -X PUT \
  'https://www.myshop.com/apps/subscriptions/cp/api/subscription-billing-attempts/skip-upcoming-order?subscriptionContractId=0'

Responses

Next 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)
securityChallengeSentStatusstring
Enum"SENT""UNSENT""FAILED""EMAIL_SETTINGS_DISABLED""CONTRACT_CANCELLED"
orderAmountUSDnumber(double)
orderCancelReasonstring
Enum"CUSTOMER""DECLINED""FRAUD""INVENTORY""STAFF""OTHER""$UNKNOWN"
orderCancelledAtstring(date-time)
orderClosedboolean
orderClosedAtstring(date-time)
orderConfirmedboolean
orderDisplayFinancialStatusstring
Enum"PENDING""AUTHORIZED""PARTIALLY_PAID""PARTIALLY_REFUNDED""VOIDED""PAID""REFUNDED""EXPIRED""$UNKNOWN"
orderDisplayFulfillmentStatusstring
Enum"UNFULFILLED""PARTIALLY_FULFILLED""FULFILLED""RESTOCKED""PENDING_FULFILLMENT""OPEN""IN_PROGRESS""ON_HOLD""SCHEDULED""REQUEST_DECLINED"
orderProcessedAtstring(date-time)
lastShippingUpdatedAtstring(date-time)
inventorySkippedAttemptCountinteger(int32)
inventorySkippedRetryingNeededboolean
orderAttributesArray of objects(AttributeInfo)
partialLinesSkippedstring
Enum"INVENTORY_MANAGEMENT""MANUAL"
orderAmountContractCurrencynumber(double)
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": [
    { … }
  ],
  "securityChallengeSentStatus": "SENT",
  "orderAmountUSD": 0.1,
  "orderCancelReason": "CUSTOMER",
  "orderCancelledAt": "2019-08-24T14:15:22Z",
  "orderClosed": true,
  "orderClosedAt": "2019-08-24T14:15:22Z",
  "orderConfirmed": true,
  "orderDisplayFinancialStatus": "PENDING",
  "orderDisplayFulfillmentStatus": "UNFULFILLED",
  "orderProcessedAt": "2019-08-24T14:15:22Z",
  "lastShippingUpdatedAt": "2019-08-24T14:15:22Z",
  "inventorySkippedAttemptCount": 0,
  "inventorySkippedRetryingNeeded": true,
  "orderAttributes": [
    { … }
  ],
  "partialLinesSkipped": "INVENTORY_MANAGEMENT",
  "orderAmountContractCurrency": 0.1
}

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.