Subscription Contracts

Update next billing date for a subscription contract

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:

Validates the contract exists and belongs to the shop
Validates the new date is not in the past
Updates the billing attempt to the new date
Syncs the updated nextBillingDate to Shopify
If rescheduleFutureOrder=true, regenerates the queue from the new date
Sends confirmation email to customer
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

PUT

api

external

subscription-contracts-update-billing-date

Update next billing date for a subscription contract

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

import requests

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

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-date', 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-date';
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-date",
  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-date"

	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-date")

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

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

Headers

X-API-Key

string

required

API Key for authentication

Query Parameters

contractId

integer<int64>

required

Subscription contract ID to update

Required range: x >= 1

api_key

string

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

rescheduleFutureOrder

boolean

default:true

If true (or value not provided), next billing date will be changed and also schedule for future upcoming orders will be changed based on new updated billing date. If false, then only next billing date will be changed, but the schedule for future upcoming orders will not change.

nextBillingDate

string<date-time>

required

New billing date in ISO 8601 format with timezone. The date must be in the future and may be subject to merchant-configured restrictions. Common formats:

UTC: 2024-03-15T12:00:00Z
With offset: 2024-03-15T12:00:00+05:30
With timezone: 2024-03-15T12:00:00[America/New_York]

The system will convert the date to the shop's timezone for validation.

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|[+-]\d{2}:\d{2}|\[.+\])$

Response

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

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

Remove discount from subscription

Update billing interval for a subscription contract

Update next billing date for a subscription contract

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

import requests

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

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-date', 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-date';
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-date",
  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-date"

	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-date")

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

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