Update billing interval for a subscription contract

Updates the billing frequency (how often the customer is charged) for a subscription contract. This comprehensive operation recalculates billing dates, adjusts pricing, updates selling plans, and may also modify delivery intervals.

Full behavior, validation rules, and side effects

Key Features:

• Changes billing frequency while maintaining subscription continuity
• Automatically adjusts delivery interval when linked to billing
• Recalculates next billing date based on store settings
• Reprices all line items for the new frequency
• Finds and applies matching selling plans
• Handles anchor day adjustments for consistent billing
• Validates prepaid subscription constraints

Billing Interval Types:

• DAY: Daily billing (use with caution)
• WEEK: Weekly billing (e.g., every 1, 2, 3 weeks)
• MONTH: Monthly billing (e.g., every 1, 2, 3 months)
• YEAR: Annual billing

Validation Rules:

• Cannot set the same interval as current (no-op prevention)
• For prepaid subscriptions: billing interval must exceed delivery interval
• Example: Can’t bill monthly if delivering weekly (would be paying for 1 delivery but receiving 4)

Next Billing Date Calculation: The system uses sophisticated logic to determine the new billing date:

1. Starts from current or last successful billing date
2. Applies store timezone and order time preferences
3. Ensures date is in the future
4. Respects day-of-week preferences if configured
5. May keep current date if ‘enableChangeFromNextBillingDate’ is false

Side Effects:

• Delivery Interval: Updated if currently equal to billing interval
• Line Item Pricing: Recalculated based on new frequency multiplier
• Selling Plans: Finds and applies best matching plans for products
• Anchor Days: Updates billing anchor for consistent scheduling
• Email Notifications: Sends ‘ORDER_FREQUENCY_UPDATED’ to customer
• Activity Logs: Records both billing and delivery changes

Prepaid vs Pay-Per-Delivery:

• Pay-per-delivery: Billing and delivery intervals typically match
• Prepaid: Customer pays upfront for multiple deliveries
• This endpoint enforces prepaid logic to prevent undercharging

Authentication: Requires valid X-API-Key header

PUT /subscriptions/cp/api/subscription-contracts-update-billing-interval

Update billing interval for a subscription contract

cURL

curl --request PUT \
  --url https://www.myshop.com/apps/subscriptions/cp/api/subscription-contracts-update-billing-interval

200

Success Response

{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-04-01T12:00:00Z",
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "[e-mail]"
  },
  "billingPolicy": {
    "interval": "MONTH",
    "intervalCount": 2,
    "anchors": [
      {
        "type": "MONTHDAY",
        "day": 1
      }
    ]
  },
  "deliveryPolicy": {
    "interval": "MONTH",
    "intervalCount": 2
  },
  "lines": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionLine/111111",
          "quantity": 1,
          "variantId": "gid://shopify/ProductVariant/42549172011164",
          "currentPrice": {
            "amount": "59.98",
            "currencyCode": "USD"
          },
          "sellingPlanId": "gid://shopify/SellingPlan/222222",
          "sellingPlanName": "Deliver every 2 months",
          "pricingPolicy": {
            "basePrice": {
              "amount": "29.99",
              "currencyCode": "USD"
            }
          }
        }
      }
    ]
  }
}

Query Parameters

contractId · integer<int64> · required

intervalCount · integer<int32> · required

interval · enum<string> · required

Available options: DAY, WEEK, MONTH, YEAR, $UNKNOWN

Response

200

application/json

Billing interval updated successfully

get__typename · string

id · string

createdAt · object

updatedAt · object

nextBillingDate · object

status · enum<string>

Available options: ACTIVE, PAUSED, CANCELLED, EXPIRED, FAILED, $UNKNOWN

deliveryPrice · object

Show child attributes

lastPaymentStatus · enum<string>

Available options: SUCCEEDED, FAILED, $UNKNOWN

billingPolicy · object

Show child attributes

deliveryPolicy · object

Show child attributes

lines · object

Show child attributes

customerPaymentMethod · object

Show child attributes

deliveryMethod · object

Show child attributes

originOrder · object

Show child attributes

customer · object

Show child attributes

discounts · object

Show child attributes

note · string

customAttributes · object[]

Show child attributes

billingAttempts · object

Show child attributes