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.

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

api

external

subscription-contracts-update-billing-interval

Update billing interval for a subscription contract

curl --request PUT \
  --url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-interval \
  --header 'X-API-Key: <x-api-key>'

import requests

url = "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-interval"

headers = {"X-API-Key": "<x-api-key>"}

response = requests.put(url, headers=headers)

print(response.text)

const options = {method: 'PUT', headers: {'X-API-Key': '<x-api-key>'}};

fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-interval', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const url = 'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-interval';
const options = {method: 'PUT', headers: {'X-API-Key': '<x-api-key>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-interval",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-interval"

	req, _ := http.NewRequest("PUT", url, nil)

	req.Header.Add("X-API-Key", "<x-api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-interval")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["X-API-Key"] = '<x-api-key>'

response = http.request(request)
puts response.read_body

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

Headers

X-API-Key

string

required

API Key for authentication

Query Parameters

contractId

integer<int64>

required

Subscription contract ID to update. Provide the numeric ID without the gid:// prefix

Required range: x >= 1

api_key

string

API Key (Deprecated - Use X-API-Key header instead)

intervalCount

integer

required

Number of intervals between billings. For example, intervalCount=2 with interval=WEEK means 'every 2 weeks'

Required range: 1 <= x <= 365

interval

enum<string>

required

Type of interval for billing frequency

Available options:

DAY,

WEEK,

MONTH,

YEAR,

$UNKNOWN

Response

Billing interval updated successfully

billingAttempts

object

Show child attributes

billingPolicy

object

Show child attributes

createdAt

object

customAttributes

object[]

Show child attributes

customer

object

Show child attributes

customerPaymentMethod

object

Show child attributes

deliveryMethod

object

Show child attributes

deliveryPolicy

object

Show child attributes

deliveryPrice

object

Show child attributes

discounts

object

Show child attributes

get__typename

string

lastPaymentStatus

enum<string>

Available options:

SUCCEEDED,

FAILED,

$UNKNOWN

lines

object

Show child attributes

nextBillingDate

object

note

string

originOrder

object

Show child attributes

status

enum<string>

Available options:

ACTIVE,

PAUSED,

CANCELLED,

EXPIRED,

FAILED,

$UNKNOWN

updatedAt

object

Update billing interval for a subscription contract

curl --request PUT \
  --url https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-interval \
  --header 'X-API-Key: <x-api-key>'

import requests

url = "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-interval"

headers = {"X-API-Key": "<x-api-key>"}

response = requests.put(url, headers=headers)

print(response.text)

const options = {method: 'PUT', headers: {'X-API-Key': '<x-api-key>'}};

fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-interval', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const url = 'https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-interval';
const options = {method: 'PUT', headers: {'X-API-Key': '<x-api-key>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-interval",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-interval"

	req, _ := http.NewRequest("PUT", url, nil)

	req.Header.Add("X-API-Key", "<x-api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://subscription-admin.appstle.com/api/external/v2/subscription-contracts-update-billing-interval")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["X-API-Key"] = '<x-api-key>'

response = http.request(request)
puts response.read_body

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

Get Started

Guides

Partner Integration

Webhooks

Admin API

Storefront API

Resources

Update billing interval for a subscription contract

Headers

Query Parameters

Response