Create and add custom discount to subscription

Creates a custom discount and applies it to a subscription contract. This endpoint allows you to create on-the-fly discounts without requiring pre-existing discount codes in Shopify.

Full behavior, validation rules, and side effects

Discount Creation & Application:

• Custom Discount: Creates discount directly on subscription contract
• Flexible Types: Supports percentage off or fixed amount off
• Cycle Limits: Optional limit on number of billing cycles discount applies
• Item-Level Control: Option to apply discount to each item vs entire order
• Immediate Effect: Discount applies to next billing cycle

Discount Parameters:

• Percentage: Percentage discount (e.g., 15 for 15% off) - use for discountType=‘PERCENTAGE’
• Amount: Fixed amount discount (e.g., 10.00 for $10 off) - use for discountType=‘FIXED_AMOUNT’
• Title: Display name for the discount (e.g., ‘Loyalty Discount’)
• Cycle Limit: Number of billing cycles discount applies (null = unlimited)
• Applies On Each Item: true = per-item discount, false = order-level discount

Discount Types:

• PERCENTAGE: Percentage-based discount (use ‘percentage’ parameter)
• FIXED_AMOUNT: Fixed dollar amount discount (use ‘amount’ parameter)

Cycle Limit Examples:

• recurringCycleLimit=1: Discount for first order only
• recurringCycleLimit=3: Discount for first 3 orders
• recurringCycleLimit=null: Discount applies forever

Use Cases:

• Customer retention offers (e.g., 20% off next 3 orders)
• Loyalty rewards and point redemptions
• Win-back campaigns with limited-time discounts
• Customer service compensation discounts
• Referral program rewards
• First-order discounts for new subscribers
• Seasonal promotions on existing subscriptions

Example Scenarios:

1. Retention Offer: 25% off for 2 billing cycles
   • percentage=25, recurringCycleLimit=2, discountType=‘PERCENTAGE’
2. Loyalty Reward: $5 off every order forever
   • amount=5.00, recurringCycleLimit=null, discountType=‘FIXED_AMOUNT’
3. First Order Deal: 50% off first order only
   • percentage=50, recurringCycleLimit=1, discountType=‘PERCENTAGE’

Returns: Updated subscription contract object with discount applied

Authentication: Requires API key authentication via X-API-Key header or api_key parameter

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

Create and add custom discount to subscription

cURL

curl --request PUT \
  --url https://membership-admin.appstle.com/api/external/v2/subscription-contracts-add-discount

200

{
  "get__typename": "<string>",
  "id": "<string>",
  "createdAt": {},
  "updatedAt": {},
  "nextBillingDate": {},
  "deliveryPrice": {
    "get__typename": "<string>",
    "amount": {}
  },
  "billingPolicy": {
    "get__typename": "<string>",
    "intervalCount": 123,
    "anchors": [
      {
        "get__typename": "<string>",
        "cutoffDay": 123,
        "day": 123,
        "month": 123
      }
    ],
    "maxCycles": 123,
    "minCycles": 123
  },
  "deliveryPolicy": {
    "get__typename": "<string>",
    "intervalCount": 123,
    "anchors": [
      {
        "get__typename": "<string>",
        "cutoffDay": 123,
        "day": 123,
        "month": 123
      }
    ]
  },
  "lines": {
    "get__typename": "<string>",
    "nodes": [
      {
        "get__typename": "<string>"
      }
    ],
    "pageInfo": {
      "get__typename": "<string>",
      "hasPreviousPage": true,
      "hasNextPage": true,
      "startCursor": "<string>",
      "endCursor": "<string>"
    }
  },
  "customerPaymentMethod": {
    "get__typename": "<string>",
    "id": "<string>",
    "instrument": {
      "get__typename": "<string>"
    },
    "revokedAt": {}
  },
  "deliveryMethod": {
    "get__typename": "<string>",
    "id": "<string>",
    "serviceCode": "<string>",
    "minDeliveryDateTime": {},
    "maxDeliveryDateTime": {},
    "additionalInformation": {
      "get__typename": "<string>",
      "instructions": "<string>"
    },
    "brandedPromise": {
      "get__typename": "<string>",
      "handle": "<string>",
      "name": "<string>"
    }
  },
  "originOrder": {
    "get__typename": "<string>",
    "id": "<string>",
    "name": "<string>",
    "fulfillmentOrders": {
      "get__typename": "<string>",
      "nodes": [
        {
          "get__typename": "<string>"
        }
      ],
      "pageInfo": {
        "get__typename": "<string>",
        "hasPreviousPage": true,
        "hasNextPage": true,
        "startCursor": "<string>",
        "endCursor": "<string>"
      }
    }
  },
  "customer": {
    "get__typename": "<string>",
    "id": "<string>",
    "email": "<string>",
    "displayName": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "phone": "<string>"
  },
  "discounts": {
    "get__typename": "<string>",
    "nodes": [
      {
        "get__typename": "<string>",
        "createdAt": {},
        "deliveredAt": {},
        "estimatedDeliveryAt": {},
        "id": "<string>",
        "inTransitAt": {},
        "name": "<string>",
        "requiresShipping": true,
        "service": {
          "get__typename": "<string>",
          "handle": "<string>",
          "serviceName": "<string>"
        },
        "trackingInfo": [
          {
            "get__typename": "<string>",
            "url": {},
            "number": "<string>",
            "company": "<string>"
          }
        ]
      }
    ],
    "pageInfo": {
      "get__typename": "<string>",
      "hasPreviousPage": true,
      "hasNextPage": true,
      "startCursor": "<string>",
      "endCursor": "<string>"
    }
  },
  "note": "<string>",
  "customAttributes": [
    {
      "get__typename": "<string>",
      "key": "<string>",
      "value": "<string>"
    }
  ],
  "billingAttempts": {
    "get__typename": "<string>",
    "nodes": [
      {
        "get__typename": "<string>",
        "completedAt": {},
        "createdAt": {},
        "id": "<string>",
        "idempotencyKey": "<string>",
        "ready": true
      }
    ]
  }
}

Headers

X-API-Key · string

Query Parameters

contractId · integer<int64> · required

Subscription contract ID to add discount to

api_key · string

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

percentage · integer<int32>

Percentage discount value (use with discountType=PERCENTAGE)

discountTitle · string

Display title for the discount

recurringCycleLimit · integer<int32>

Number of billing cycles discount applies (null for unlimited)

appliesOnEachItem · boolean

Apply discount to each item individually (true) or entire order (false)

amount · number<double>

Fixed amount discount value (use with discountType=FIXED_AMOUNT)

discountType · string

Discount type: PERCENTAGE or FIXED_AMOUNT

Response

200

application/json

Discount successfully created and applied to subscription

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