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.

Full behavior, validation rules, and side effects

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

/

v2

/

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>'

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

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

Appstle Subscriptions webhook events and setup

Update subscription contract status

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>'

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