Add custom discount to subscription

Creates and applies a custom manual discount to an existing subscription contract. This powerful endpoint supports multiple discount types and configurations for flexible pricing strategies.

Full behavior, validation rules, and side effects

Discount Types:

• PERCENTAGE: Percentage off the order (e.g., 10% off)
• FIXED: Fixed amount off the order (e.g., $10 off)
• PRICE: Override price (sets total to specific amount)

Key Features:

• Custom discount titles for easy identification
• Cycle limits for time-bound promotions
• Per-item or subtotal application options
• Stacks with other discounts per Shopify rules
• Automatic shipping price recalculation
• Activity logging for audit trails

Application Methods:

• Subtotal Discount (appliesOnEachItem=false): Applied to order total after line item calculations
• Per-Item Discount (appliesOnEachItem=true): Applied to each line item individually

Cycle Limits:

• Set recurringCycleLimit to apply discount for specific number of orders
• Leave null for unlimited duration
• Useful for ‘3 months at 20% off’ promotions

Retention Campaigns: This endpoint integrates with cancellation retention workflows:

• Can trigger merchant notifications
• Tracks discount usage for retention analytics
• Helps prevent churn with targeted offers

Important Notes:

• Discounts apply to future orders only
• Cannot modify discounts once applied (must remove and re-add)
• Some discount combinations may not be allowed by Shopify
• Price overrides should be used carefully

Authentication: Requires valid X-API-Key header

PUT /api/external/v2/subscription-contracts-add-discount

Add custom discount to subscription

cURL

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

200

Success Response

{
  "id": "gid://shopify/SubscriptionContract/123456789",
  "status": "ACTIVE",
  "nextBillingDate": "2024-04-01T12: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",
          "currentPrice": {
            "amount": "29.99",
            "currencyCode": "USD"
          }
        }
      }
    ]
  },
  "discounts": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/SubscriptionManualDiscount/555555",
          "title": "Loyalty Discount",
          "targetType": "ALL_LINES",
          "type": "MANUAL",
          "recurringCycleLimit": 3,
          "value": {
            "percentage": 10
          }
        }
      }
    ]
  }
}

Headers

X-API-Key · string · required

API Key for authentication

Query Parameters

contractId · integer<int64> · required

Subscription contract ID to apply discount to. Provide the numeric ID without the gid:// prefix

Required range: x >= 1

api_key · string

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

percentage · integer

Discount percentage (1-100). Required when discountType is PERCENTAGE

Required range: 1 <= x <= 100

discountTitle · string

Custom title for the discount. If not provided, a default title will be generated

Maximum string length: 255

recurringCycleLimit · integer

Number of billing cycles the discount applies to. Leave null for unlimited duration

Required range: 1 <= x <= 9999

appliesOnEachItem · boolean · default: false

Application method: true = apply to each line item individually, false = apply to order subtotal

amount · number<double>

Fixed discount amount in store currency. Required when discountType is FIXED or PRICE

Required range: 0.01 <= x <= 999999.99

discountType · enum<string>

Type of discount to apply

Available options: PERCENTAGE, FIXED, PRICE

Response

200

application/json

Discount successfully added

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