Subscription Contracts

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:

Starts from current or last successful billing date
Applies store timezone and order time preferences
Ensures date is in the future
Respects day-of-week preferences if configured
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 --request PUT \
  --url https://www.myshop.com/apps/subscriptions/cp/api/subscription-contracts-update-billing-interval

{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-04-01T12:00:00Z",
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "customer@example.com"
  },
  "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

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

Update Subscription contract frequency by selling plan

Update next billing date for a subscription contract

Update billing interval for a subscription contract

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

{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-04-01T12:00:00Z",
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "customer@example.com"
  },
  "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"
            }
          }
        }
      }
    ]
  }
}