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:

1. Use the sync shipping price endpoint
2. Or update delivery method
3. 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

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

200

Success Response

{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-04-01T00:00:00Z",
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "[e-mail]",
    "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

200

application/json

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