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

/2.0/subscription/modifiers/create

Create a subscription modifier to 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=1234567' \
             -d 'vendor_auth_code=123456abc...' \
             -d 'subscription_id=12345' \
             -d 'modifier_recurring=false' \
             -d 'modifier_amount=10.00' \
             -d 'modifier_description=Example Description' \
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 modifier on the subscription after each payment. By default we retain them, but you can specify this field as false to automatically remove the modifier once the next payment has been charged (one-time use).

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.