Order Details
User History
Prices
Coupons
Products
Licenses
Pay Links
Transactions
Payments
Webhooks
post

/2.0/subscription/modifiers/create

Dynamically change the subscription payment amount

A modifier applied to a recurring subscription increases or decreases the next payment by a flat amount (in the currency of the subscription). The modifier itself may recur and apply to all future payments until it is removed.

Example request

curl -X POST -d 'vendor_id=123' \
             -d 'vendor_auth_code=1:54229abfcfa...' \
             -d 'subscription_id=12345' \
             -d 'modifier_recurring=false' \
             -d 'modifier_amount=10.00' \
             -d 'modifier_description=Example%20Description' \
             https://vendors.paddle.com/api/2.0/subscription/modifiers/create

Usage Notes

  • To charge the buyer an additional amount, set a positive modifier_amount (e.g. 10). To reduce the buyer’s payment amount, set a negative modifier_amount (e.g. -10).
  • Modifiers will not be applied on the immediate payment if the payment is past due, and will only be applied on payments subsequent to the past due payment.
  • For VAT-inclusive subscription: the modifier amount will be VAT-deducted first before being added/subtracted from the current subscription balance and VAT-deducted plan price. VAT is only added onto the final amount if the buyer is charged. For example, if a modifier of $10 is additionally charged on a $40 monthly plan with a buyer VAT rate of 20% and a credit balance of $5, the final charge would be: (-$5 + ($40/1.2) + ($10/1.2)) * 1.2 = $44
  • For VAT-exclusive subscription: the modifier amount will be added/subtracted from the current subscription balance and plan price. VAT is only added onto the final amount if the buyer is charged. For example, if a modifier of $10 is additionally charged on a $40 monthly plan with a buyer VAT rate of 20% and a credit balance of $5, the final charge would be: (-$5 + $40 + $10) * 1.2 = $54

Request Body

Form data (application/x-www-form-urlencoded)
vendor_id
integer

The vendor ID identifies your seller account. This can be found in Developer Tools > Authentication.

required
minimum: 1
pattern: \d+
vendor_auth_code
string

The vendor auth code is a private API key for authenticating API requests. This key should never be used in client side code or shared publicly. This can be found in Developer Tools > Authentication.

required
pattern: [0-9a-f]+
subscription_id
integer

The ID of the subscription that you want to add a modifier for

required
pattern: \d+
modifier_recurring
boolean

Whether to retain the modifiers on the subscription. By default we retain them, but you can specify this field as false to

Allowed Values: true, false
default: true
modifier_amount
number

The amount will be in the currency of the subscription.

required
pattern: ^\d+\.\d{2}$
modifier_description
string

A description text to be displayed on the buyer’s receipt email and invoice.

maxLength: 255

Responses

1 Example
Schema
object
or
object

An unsuccessful call to the Dashboard API will return a 200 response containing a field success set to false and an error object.

Send a Test Request

Send requests directly from the browser (CORS must be enabled)
$$.env
No $$.env variables are being used in this request.