Kartra Documentation Technical Documentation for Kartra

Action: Edit recurring payment subscription settings

This will allow you to change various parameters related to a particular recurring payment subscription from one particular lead.

A few limitations to keep in mind

  • PayPal subscriptions cannot be edited, since Paypal manages the subscriptions in-house and they do not allow modifications from external sources.
  • Payment subscriptions with status Cancelled or Terminated (meaning payment plans where all scheduled payments have already been paid) cannot be changed since they are not technically active anymore.

 

Type Parameters Values
POST cmd* edit_subscription
POST subscription_id* integer
POST subscription_product_id** *** integer
POST subscription_price_point** *** integer
POST subscription_next_payment_date *** ‘yyyy-mm-dd hh:mm’ format Timezone EST
POST subscription_amount *** decimal
POST subscription_recurrence ***
recurring_period_1
  • price point type ‘Recurring’ and ‘Installments’ (‘monthly’, ‘every 2 months’, ‘quarterly’,’yearly’, ‘every 2 years’, ‘weekly’, ‘every 2 weeks’)
  • price point type ‘Recurring installments’ (‘monthly’, ‘every 2 months’, ‘ ‘weekly’, ‘every 2 weeks’)
recurring_period_2
  • price point type ‘Recurring installments’ only (‘yearly’, ‘every 2 years’)
POST subscription_product_quantity *** integer
POST subscription_installments_left *** integer or ‘until cancelled’

* Required fields.

** In case of changing the product id, both subscription_product_id and subscription_price_point need to be present.

*** At least one of the parameters need to be sent to the API.

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'edit_subscription',
        'subscription_id' => 32451,
        'subscription_product_id' => 223,
        'subscription_price_point' => 2,
        'subscription_next_payment_date' => '2021-01-18 05:46:00',
        'subscription_amount' => 22.00,
        'subscription_recurrence' => [
            'recurring_period_1' => 'monthly',
            'recurring_period_2' => 'yearly'
        ],
        'subscription_product_quantity' => 2,
        'subscription_installments_left' => 3
    ]
]

Success message:

{
    "status":"Success",
    "actions":[
        {
            "edit_subscription":{
                "status":"Success",
                "message":"Subscription modified",
                "type":"115"
            }
        }
    ]
}

Error Cases:

Type Number Message Cause
248 Subscription doesn’t exist
  • The subscription you are trying to modify does not exist in our database.
284 Paypal transactions cannot be modified
  • Paypal subscriptions can only be cancelled, no other modifications are allowed.
275 Subscriptions cancelled or terminated cannot be updated
  • The subscription you are trying to modify is either cancelled or terminated. These type subscriptions cannot be modified anymore.
276 Quantity must be between 1 and 9,999
  • The quantity number must exceed the interval between 1 and 9,999.
277 Price must be between 1.00 and 9,999.99
  • The amount allowed is between 1.00 and 9,999.99 in the currency the subscription is setup with.
283 Wrong product id or price point
  • subscription_product_id or subscription_price_point do not exist or they were deleted.
281 Recurrence cannot be changed
  • Price point type ‘One time’ payment configuration cannot be applied to the subscription.
  • Type ‘Recurring installments’ can only be modified with the same type and vice-versa.
  • Subscriptions with ‘One time’ with trial payment configuration cannot have the recurrence modified.
278 Invalid number
  • The subscription_installments_left is not a valid positive number or ‘until cancelled’.
260 Invalid date format
  • subscription_next_payment_date does not have the correct ‘yyyy-mm-dd hh:mm’ format.
261 Date is in the past
  • subscription_next_payment_date is a date from the past based on EST timezone.
280 Invalid recurring period
  • recurring_period_1 or recurring_period_2 does not have the correct format stated above.
  • recurring_period_2 is sent but recurring_period_1 does not have the correct value.
282 Incorrect number of installments
  • In the case of ‘Recurring installments’ type of recurrence, the number of installments already set cannot be bigger than the total number of installments for recurring_period_1 over the recurring_period_2 interval.
268 Invalid amount
  • subscription_amount is not in the positive numeric format or numeric with two decimals.
285 No editable parameters for subscription
  • No parameters to edit were sent.

An example of an error message:

{
  "status": "Error",
  "message": "Subscription doesn't exist",
  "type": 248
}

© 2023 Kartra All Rights Reserved