Skip an upcoming billing order

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.

Full behavior, validation rules, and side effects

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

PUT /memberships/cp/api/subscription-billing-attempts/skip-order/{id}

Skip an upcoming billing order

cURL

curl --request PUT \
  --url https://www.myshop.com/apps/memberships/cp/api/subscription-billing-attempts/skip-order/{id}

200

Example

{
  "shop": "my-store.myshopify.com",
  "retryingNeeded": true,
  "id": 12345,
  "billingAttemptId": "<string>",
  "billingDate": "2023-11-07T05:31:56Z",
  "contractId": 67890,
  "attemptCount": 1,
  "attemptTime": "2023-11-07T05:31:56Z",
  "graphOrderId": "<string>",
  "orderId": 123,
  "orderAmount": 29.99,
  "orderName": "#1001",
  "applyUsageCharge": true,
  "recurringChargeId": 123,
  "transactionRate": 123,
  "billingAttemptResponseMessage": "<string>",
  "progressAttemptCount": 123,
  "orderNote": "<string>",
  "variantList": [
    {
      "variantId": 123,
      "quantity": 123,
      "title": "<string>",
      "image": "<string>",
      "productTitle": "<string>",
      "productId": "<string>",
      "sellingPlanId": "<string>"
    }
  ],
  "orderAmountUSD": 123,
  "upgradeDowngradeBilling": true
}

Path Parameters

id · integer<int64> · required

Billing attempt ID to skip

Query Parameters

subscriptionContractId · integer<int64>

Optional subscription contract ID for additional validation

isPrepaid · boolean · default: false

Set to true if this is a prepaid membership

Response

200

application/json

Billing order successfully skipped

shop · string · required

Shop domain identifier

Example:

"my-store.myshopify.com"

retryingNeeded · boolean · required

id · integer<int64>

Unique identifier of the billing attempt record

Example:

12345

billingAttemptId · string

Shopify billing attempt ID

status · enum<string>

Current status of the billing attempt

Available options: SUCCESS, FAILURE, REQUESTING, PROGRESS, QUEUED, SKIPPED, SOCIAL_CONNECTION_NULL, CONTRACT_CANCELLED, CONTRACT_ENDED, CONTRACT_PAUSED, AUTO_CHARGE_DISABLED, SKIPPED_DUNNING_MGMT, SECURITY_CHALLENGE, SHOPIFY_EXCEPTION

billingDate · string<date-time>

Scheduled billing date for this attempt

contractId · integer<int64>

Associated subscription contract ID

Example:

67890

attemptCount · integer<int32>

Number of billing retry attempts

Example:

1

attemptTime · string<date-time>

graphOrderId · string

orderId · integer<int64>

Shopify order ID if billing was successful

orderAmount · number<double>

Total order amount

Example:

29.99

orderName · string

Shopify order name/number

Example:

"#1001"

transactionFailedEmailSentStatus · enum<string>

Available options: SENT, UNSENT, FAILED, EMAIL_SETTINGS_DISABLED, CUSTOMER_PAYMENT_EMPTY, CONTRACT_CANCELLED

upcomingOrderEmailSentStatus · enum<string>

Available options: SENT, UNSENT, FAILED, EMAIL_SETTINGS_DISABLED, CUSTOMER_PAYMENT_EMPTY, CONTRACT_CANCELLED, STOP_FROM_CONTRACT, CONTRACT_PAUSED

applyUsageCharge · boolean

recurringChargeId · integer<int64>

transactionRate · number<double>

usageChargeStatus · enum<string>

Available options: SUCCESS, FAILED, TO_BE_TRIED

transactionFailedSmsSentStatus · enum<string>

Available options: SENT, UNSENT, FAILED, SMS_SETTINGS_DISABLED, CUSTOMER_PAYMENT_EMPTY, CONTRACT_CANCELLED, PHONE_NUMBER_EMPTY

upcomingOrderSmsSentStatus · enum<string>

Available options: SENT, UNSENT, FAILED, SMS_SETTINGS_DISABLED, CUSTOMER_PAYMENT_EMPTY, CONTRACT_CANCELLED, STOP_FROM_CONTRACT, CONTRACT_PAUSED, PHONE_NUMBER_EMPTY

billingAttemptResponseMessage · string

progressAttemptCount · integer<int32>

orderNote · string

Order note or special instructions

variantList · object[]

Show child attributes

orderAmountUSD · number<double>

securityChallengeSentStatus · enum<string>

Available options: SENT, UNSENT, FAILED, EMAIL_SETTINGS_DISABLED, CONTRACT_CANCELLED

upgradeDowngradeBilling · boolean