Add product with custom price to subscription

Adds a new product line item with a custom price override to an existing subscription contract. This endpoint bypasses standard pricing and selling plans to set an exact price.

Full behavior, validation rules, and side effects

Key Features:

• Direct price control - set any price regardless of product pricing
• Optional automatic discount application based on shop settings
• No selling plan assignment - pure custom pricing
• Supports both recurring and one-time products
• Email notifications sent to customers
• Activity logging for audit trails

Custom Pricing Behavior:

• Price is set exactly as provided (no calculations)
• Overrides any product-level pricing
• Not affected by currency or country
• No automatic discounts from selling plans
• Price remains fixed unless manually updated

Shop-Level Discount Application: Despite the method name, this endpoint MAY apply discounts:

• Checks shop setting: ‘applySubscriptionDiscount’
• If enabled, applies shop’s default subscription discount
• Discount type: PERCENTAGE or FIXED (per shop config)
• Creates manual discount: ‘PRODUCT_DISCOUNT_[lineId]’
• Discount is additional to the custom price

Common Use Cases:

• Negotiated Pricing: Custom rates for specific customers
• Price Matching: Match competitor pricing
• Promotional Pricing: Special one-off prices
• Bundle Pricing: Custom prices for package deals
• Legacy Pricing: Honor old pricing agreements
• Test Orders: Zero or nominal pricing for testing

Differences from Standard Add:

• No selling plan association
• No pricing policy rules
• No automatic tier discounts
• Price doesn’t adjust with frequency changes
• Manual price management required

One-Time Products: When isOneTimeProduct=true:

• Product appears only in next order
• Automatically removed after fulfillment
• Custom price applies to that single order
• Shop discount still applies if configured

Price Validation:

• Must be a positive number
• No maximum limit enforced
• Can be less than product cost (loss leader)
• Currency matches shop’s base currency
• Decimal precision per currency rules

Important Considerations:

• No automatic price updates with product changes
• Frequency changes don’t affect pricing
• May bypass minimum order values
• Consider margin implications
• Document reason for custom pricing

Post-Addition Effects:

• Customer receives product addition email
• Activity log records custom price
• Shipping may need recalculation
• Order total updates immediately
• No impact on other line items

Authentication: Requires valid X-API-Key header

PUT /api/external/v2/subscription-contract-add-line-item

Add product with custom price to subscription

cURL

curl --request PUT \
  --url https://subscription-admin.appstle.com/api/external/v2/subscription-contract-add-line-item \
  --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]"
  },
  "lines": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionLine/111111",
          "quantity": 1,
          "variantId": "gid://shopify/ProductVariant/42549172011164",
          "title": "Premium Coffee - Dark Roast",
          "currentPrice": {
            "amount": "29.99",
            "currencyCode": "USD"
          },
          "sellingPlanId": null,
          "sellingPlanName": null
        }
      },
      {
        "node": {
          "id": "gid://shopify/SubscriptionLine/222222",
          "quantity": 1,
          "variantId": "gid://shopify/ProductVariant/98765432101",
          "title": "Special Edition Box",
          "currentPrice": {
            "amount": "19.99",
            "currencyCode": "USD"
          },
          "sellingPlanId": null,
          "sellingPlanName": null,
          "discountAllocations": [
            {
              "discount": {
                "__typename": "SubscriptionManualDiscount",
                "id": "gid://shopify/SubscriptionManualDiscount/333333",
                "title": "PRODUCT_DISCOUNT_222222",
                "type": "MANUAL",
                "value": {
                  "percentage": 10
                }
              }
            }
          ]
        }
      }
    ]
  }
}

Headers

X-API-Key · string · required

API Key for authentication

Query Parameters

contractId · integer<int64> · required

Subscription contract ID to add product to

api_key · string

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

quantity · integer<int32> · required

Quantity of product to add

variantId · string · required

Shopify variant ID of the product to add

price · number<double> · required

Custom price for the product (in store currency). This exact price will be charged regardless of the product's normal price, selling plans, or frequency. If the shop has 'applySubscriptionDiscount' enabled, an additional discount may be applied on top of this price.

Required range: 0.01 <= x <= 999999.99

isOneTimeProduct · boolean · default: false

When true, product will only be included in the next order; when false, in all future orders

Response

200

application/json

Product successfully added to subscription with custom price

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