Subscription Management

Update delivery price for a subscription contract

Updates the fixed delivery price for all future orders in a subscription contract. This allows manual override of calculated shipping rates with a custom delivery fee.

Key Features:

Sets a fixed delivery price regardless of shipping calculations
Overrides any dynamic shipping rates from carriers
Applies to all future orders immediately
Can set to 0 for free delivery
Automatically handles invalid discount codes
Tracks price changes in activity log

How Delivery Pricing Works:

Calculated Rates: Default behavior uses carrier rates and rules
Manual Override: This endpoint sets a fixed price
Precedence: Manual price overrides all calculations
Currency: Always in shop’s base currency

Common Use Cases:

Free Shipping Promotions: Set to 0.00
Flat Rate Shipping: Fixed price regardless of location
VIP Customer Rates: Special shipping prices
Subscription Perks: Reduced delivery fees
Price Corrections: Fix shipping calculation errors
Regional Adjustments: Custom rates for specific areas

Impact on Orders:

Next order uses new delivery price
All future recurring orders affected
Existing orders keep original pricing
Customer sees updated total immediately
No recalculation on address changes

Price Validation:

Must be a valid decimal number
Can be 0 for free shipping
No maximum limit enforced
Negative values typically rejected by Shopify
Currency precision respected (e.g., 2 decimals for USD)

Side Effects:

Invalid discount codes automatically removed
Activity log created with old/new prices
No customer email notification sent
Shipping tax recalculated if applicable
Total order value updated

Reverting to Calculated Rates: To restore dynamic shipping calculations:

Use the sync shipping price endpoint
Or update delivery method
Manual price remains until explicitly changed

Important Notes:

Price includes all delivery charges (shipping + handling)
Does not affect delivery method or speed
Consider customer communication for increases
May affect subscription profitability
Some payment methods may decline on total changes

Authentication: Requires valid X-API-Key header

PUT

api

external

subscription-contracts-update-delivery-price

Update delivery price for a subscription contract

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

import requests

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

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

	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-delivery-price")

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

{
  "customer": {
    "displayName": "John Doe",
    "email": "customer@example.com",
    "id": "gid://shopify/Customer/987654321"
  },
  "deliveryMethod": {
    "__typename": "SubscriptionDeliveryMethodShipping",
    "shippingOption": {
      "code": "STANDARD",
      "presentmentTitle": "Standard Shipping (5-7 days)",
      "title": "Standard Shipping"
    }
  },
  "deliveryPrice": {
    "amount": "9.99",
    "currencyCode": "USD"
  },
  "id": "gid://shopify/SubscriptionContract/123456789",
  "lines": {
    "edges": [
      {
        "node": {
          "currentPrice": {
            "amount": "39.99",
            "currencyCode": "USD"
          },
          "id": "gid://shopify/SubscriptionLine/111111",
          "quantity": 1,
          "title": "Monthly Subscription Box",
          "variantId": "gid://shopify/ProductVariant/42549172011164"
        }
      }
    ]
  },
  "nextBillingDate": "2024-04-01T00:00:00Z",
  "status": "ACTIVE",
  "totalPrice": {
    "amount": "49.98",
    "currencyCode": "USD"
  }
}

Headers

X-API-Key

string

required

API Key for authentication

Query Parameters

contractId

integer<int64>

required

The unique identifier of the subscription contract

deliveryPrice

number<double>

required

New delivery price to be applied to the subscription contract. This is a fixed price that overrides any calculated shipping rates. Set to 0 for free delivery. Price must be in the shop's base currency.

Required range: 0 <= x <= 99999.99

api_key

string

Deprecated API Key parameter; use the X-API-Key header instead

Response

Successfully updated delivery price and returned the updated subscription contract

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 subscription delivery method

Update maximum cycles for a subscription contract

Update delivery price for a subscription contract

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

import requests

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

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

	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-delivery-price")

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

{
  "customer": {
    "displayName": "John Doe",
    "email": "customer@example.com",
    "id": "gid://shopify/Customer/987654321"
  },
  "deliveryMethod": {
    "__typename": "SubscriptionDeliveryMethodShipping",
    "shippingOption": {
      "code": "STANDARD",
      "presentmentTitle": "Standard Shipping (5-7 days)",
      "title": "Standard Shipping"
    }
  },
  "deliveryPrice": {
    "amount": "9.99",
    "currencyCode": "USD"
  },
  "id": "gid://shopify/SubscriptionContract/123456789",
  "lines": {
    "edges": [
      {
        "node": {
          "currentPrice": {
            "amount": "39.99",
            "currencyCode": "USD"
          },
          "id": "gid://shopify/SubscriptionLine/111111",
          "quantity": 1,
          "title": "Monthly Subscription Box",
          "variantId": "gid://shopify/ProductVariant/42549172011164"
        }
      }
    ]
  },
  "nextBillingDate": "2024-04-01T00:00:00Z",
  "status": "ACTIVE",
  "totalPrice": {
    "amount": "49.98",
    "currencyCode": "USD"
  }
}