Create Modifier

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

preparing...

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.
If a negative modifier is greater than the amount due, the difference will roll over into the buyer's subscription balance, and will reduce future payment amounts until it has been fully depleted.
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

vendor_id

integer

required

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

>= 1

vendor_auth_code

string

required

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.

Match pattern:

[0-9a-f]+

subscription_id

integer

required

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

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 it has been used on the next payment (one-time use).

Allowed values:

truefalse

Default:

true

modifier_amount

number

required

The amount will be in the currency of the subscription.

modifier_description

string

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

<= 255 characters

Body