Actions: Products – Kartra Documentation

Action: Retrieve recurring payment subscriptions from lead

This will allow retrieve all payment subscriptions within the refund period.

Type	Parameters	Values
POST	cmd*	retrieve_subscriptions_from_lead

* Required field
Here is an example:

'lead' => [
    'email' => 'example@email.com'
],
'actions' => [
    '0' => [
        'cmd' => 'retrieve_subscriptions_from_lead'
    ]
]

Here are the results returned by the request:

Parameters	Values
subscriptions_list	String (JSON encoded array containing the payment subscriptions for the lead, empty array if no payment subscriptions)

JSON parameters	Values
subscription_id	integer A unique numeric identifier for the subscription id.
lead_id	integer Id for the lead linked to the transaction.
lead_email	string Email of the lead linked to the subscription.
subscription_status	string The subscription status. Possible values: ‘Active’, ‘Terminated’, ‘Cancelled’, ‘Paused’

Example of the returned JSON array:

{
    "retrieve_subscriptions_from_lead":{
        "subscriptions_list":[
            {
                "subscription_id":"48110",
                "lead_id":"4174086",
                "lead_email":"example@email.com",
                "subscription_status":"Active"
            },
            {
                "subscription_id":"48112",
                "lead_id":"4174086",
                "lead_email":"example@email.com",
                "subscription_status":"Paused"
            },
        },
    }
}

Action: Retrieve payment transactions from lead

This will allow you to retrieve all payment transaction for a lead.

Type	Parameters	Values
POST	cmd*	retrieve_transactions_from_lead

* Required field
Here is an example:

'lead' => [
    'email' => 'example@email.com'
],
'actions' => [
    '0' => [
        'cmd' => 'retrieve_transactions_from_lead'
    ]
]

Here are the results returned by the request:

Parameters	Values
transaction_list	String (JSON encoded array containing the transactions for the lead, empty array if no transactions)

JSON parameters	Values
transaction_id	integer A unique numeric identifier for the transaction id.
lead_id	integer Id for the lead linked to the transaction.
lead_email	string Email of the lead at the moment of the transaction.
transaction_type	string The transaction type. Possible values: ‘sale’, ‘refund’, ‘failed’, ‘rebill’, ‘cancellation’, ‘chargeback’, ‘partial_refund’

Example of the returned JSON array:

{
    "retrieve_transactions_from_lead":{
        "transaction_list":[
            {
                "transaction_id":"48110",
                "lead_id":"4174086",
                "lead_email":"example@email.com",
                "transaction_type":"sale"
            },
            {
                "transaction_id":"48112",
                "lead_id":"4174086",
                "lead_email":"example@email.com",
                "transaction_type":"refund"
            },
        },
    }
}

Action: Get payment transaction details

This will allow you to retrieve the information related to a particular payment transaction in Kartra.

Type	Parameters	Values
POST	cmd*	get_transaction_details
POST	transaction_id*	integer

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'get_transaction_details',
        'transaction_id' => 99432
    ]
]

Here are the results returned by the request:

Parameters	Values
transaction_details	String (JSON encoded string containing the details of the payment transaction)

JSON parameters:

For sale transactions	Values
transaction_id	integer A unique numeric identifier for the transaction id.
lead_first_name	string The lead first name at the moment of purchase.
lead_last_name	string The lead last name at the moment of purchase.
lead_email	string The lead email at the moment of purchase.
lead_id	integer A unique numeric identifier for the lead id.
lead_username	string The lead username.
lead_country	string The lead country at the moment of purchase.
lead_country_code_2	string The lead two letter country code at the moment of purchase.
lead_country_code_3	string The lead three letter country code at the moment of purchase.
lead_state	string The lead state at the moment of purchase.
lead_phone_country_code	string The lead phone country code at the moment of purchase.
lead_phone_number	string The lead phone number at the moment of purchase.
lead_address	string The lead address at the moment of purchase.
lead_city	string The lead city at the moment of purchase.
lead_zip	string The lead zip at the moment of purchase.
lead_zip	string The lead zip at the moment of purchase.
product_name	string The product name at the moment of purchase.
product_id	integer The product id linked to the transaction.
product_price_point	integer The product price point linked to the transaction.
transaction_full_amount	float The final paid amount on this specific transaction.
transaction_quantity	integer The product quantity.
transaction_affiliate	string Username of the affiliate, “N/A” if none.
transaction_jv	string Username of the jv, “N/A” if none.
transaction_date	yyyy-mm-dd hh:mm:ss Transaction date EST.
transaction_type	string The transaction type. Possible values: ‘sale’
transaction_parent_id	integer The id of the parent transaction (in the case of sale it is 0)
transaction_subscription_id	string A unique identifier for the subscription id (PayPal transactions will return PayPal subscription id. If there is no recurring payments this will be “N/A”).
transaction_internal_subscription_id	integer A unique numeric identifier for the subscription id(if there is no recurring payments this will be “N/A”).
transaction_subscription_pay_number	integer The payment number of the subscription related to the transaction, if any. If not the value will be “N/A”
transaction_discount	float If any discount coupon was applied, the amount in dollars deducted from the original price. “N/A” if none.
transaction_tax	float The amount of sales tax or VAT. “N/A” if none.
transaction_base_amount	float The base price for the transaction (for trial this will be the base price of the initial transaction).
transaction_shipping	float The shipping cost.
transaction_last_4_card_digits	integer The last 4 digits of the used card (‘N/A’ if PayPal)
original_id	integer In case of a payment subscription, the order ID of the first transaction within the subscription. In this case it will be the same as the transaction_id since it is a first payment.
vendor_tracking_id_1	string Vendor’s tracking ID 1 if the sale was generated from a tracking link.
vendor_tracking_id_2	string Vendor’s tracking ID 2 if the sale was generated from a tracking link.
vendor_tracking_link	string Vendor’s tracking link name.
trial	integer 1 or 0, depending on whether trial is activated or not.
trial_period	integer The trial period in days.
trial_amount	float The trial amount.
rebill_circle	integer Days left for the next payment. Present only for recurring subscription payments.
installments	integer The number of installments for the subscription. Present only for recurring subscription payments with finite number of installments.
frequency	string The frequency of recurrence. Possible values (‘every_year’, ‘every_2_years’). Present only for recurring subscription payments with price point type recurrent.
payments_left	integer Number of upcoming payments until the end of the subscription. 9999 if “cancelled by customer”. Present only for recurring subscription payments.
shipping_first_name	string Lead’s shipping first name. “N/A” if none.
shipping_last_name	string Lead’s shipping last name. “N/A” if none.
shipping_address	string Lead’s shipping address. “N/A” if none.
shipping_city	string Lead’s shipping city. “N/A” if none.
shipping_zip	string Lead’s shipping zip. “N/A” if none.
shipping_country	string Lead’s shipping country. “N/A” if none.
shipping_state	string Lead’s shipping state. “N/A” if none.
payment_processor_type	string The payment processor type: “PayPal”, “Braintree”, “Stripe”, “Authorize.net”

JSON parameters:

For refund/chargeback/partial refund transactions	Values
transaction_id	integer A unique numeric identifier for the transaction id.
lead_first_name	string The lead first name at the moment of purchase.
lead_last_name	string The lead last name at the moment of purchase.
lead_email	string The lead email at the moment of purchase.
lead_id	integer A unique numeric identifier for the lead id.
lead_username	string The lead username.
lead_country	string The lead country at the moment of purchase.
lead_country_code_2	string The lead two letter country code at the moment of purchase.
lead_country_code_3	string The lead three letter country code at the moment of purchase.
lead_state	string The lead state at the moment of purchase.
lead_phone_country_code	string The lead phone country code at the moment of purchase.
lead_phone_number	string The lead phone number at the moment of purchase.
lead_address	string The lead address at the moment of purchase.
lead_city	string The lead city at the moment of purchase.
lead_zip	string The lead zip at the moment of purchase.
product_name	string The product name at the moment of purchase.
product_id	integer The product id linked to the transaction.
product_price_point	integer The product price point linked to the transaction.
transaction_full_amount	float The final paid amount on this specific transaction.
transaction_quantity	integer The product quantity. Not present in cancellations.
transaction_affiliate	string Username of the affiliate, “N/A” if none.
transaction_jv	string Username of the jv, “N/A” if none.
transaction_date	yyyy-mm-dd hh:mm:ss Transaction date EST.
transaction_type	string The transaction type. Possible values: ‘refund’, ‘chargeback’, ‘partial_refund’
transaction_parent_id	integer The id of the parent transaction
transaction_subscription_id	string A unique identifier for the subscription id (PayPal transactions will return PayPal subscription id. If there is no recurring payments this will be 0).
transaction_internal_subscription_id	integer A unique numeric identifier for the subscription id(if there is no recurring payments this will be 0).
transaction_subscription_pay_number	integer The payment number of the subscription related to the transaction, if any.
transaction_discount	float If any discount coupon was applied, the amount in dollars deducted from the original price. “N/A” if none.
transaction_tax	float The amount of sales tax or VAT. “N/A” if none.
transaction_base_amount	float The base price for the transaction (for trial this will be the base price of the initial transaction).
transaction_shipping	float The shipping cost.
original_id	integer In case of a payment subscription, the order ID of the first transaction within the subscription. In this case it will be the same as the transaction_id since it is a first payment.
vendor_tracking_id_1	string Vendor’s tracking ID 1 if the sale was generated from a tracking link.
vendor_tracking_id_2	string Vendor’s tracking ID 2 if the sale was generated from a tracking link.
vendor_tracking_link	string Vendor’s tracking link name.
shipping_first_name	string Lead’s shipping first name. “N/A” if none.
shipping_last_name	string Lead’s shipping last name. “N/A” if none.
shipping_address	string Lead’s shipping address. “N/A” if none.
shipping_city	string Lead’s shipping city. “N/A” if none.
shipping_zip	string Lead’s shipping zip. “N/A” if none.
shipping_country	string Lead’s shipping country. “N/A” if none.
shipping_state	string Lead’s shipping state. “N/A” if none.
payment_processor_type	string The payment processor type: “PayPal”, “Braintree”, “Stripe”, “Authorize.net”

JSON parameters:

For rebill transactions	Values
transaction_id	integer A unique numeric identifier for the transaction id.
lead_first_name	string The lead first name at the moment of purchase.
lead_last_name	string The lead last name at the moment of purchase.
lead_email	string The lead email at the moment of purchase.
lead_id	integer A unique numeric identifier for the lead id.
lead_username	string The lead username.
lead_country	string The lead country at the moment of purchase.
lead_country_code_2	string The lead two letter country code at the moment of purchase.
lead_country_code_3	string The lead three letter country code at the moment of purchase.
lead_state	string The lead state at the moment of purchase.
lead_phone_country_code	string The lead phone country code at the moment of purchase.
lead_phone_number	string The lead phone number at the moment of purchase.
lead_address	string The lead address at the moment of purchase.
lead_city	string The lead city at the moment of purchase.
lead_zip	string The lead zip at the moment of purchase.
product_name	string The product name at the moment of purchase.
product_id	integer The product id linked to the transaction.
product_price_point	integer The product price point linked to the transaction.
transaction_full_amount	float The final paid amount on this specific transaction.
transaction_quantity	integer The product quantity. Not present in cancellations.
transaction_affiliate	string Username of the affiliate, “N/A” if none.
transaction_jv	string Username of the jv, “N/A” if none.
transaction_date	yyyy-mm-dd hh:mm:ss Transaction date EST.
transaction_type	string The transaction type. Possible values: ‘rebill’
transaction_parent_id	integer The id of the parent transaction (in the case of refunds/chargebacks)
transaction_subscription_id	string A unique identifier for the subscription id (PayPal transactions will return PayPal subscription id. If there is no recurring payments this will be 0).
transaction_internal_subscription_id	integer A unique numeric identifier for the subscription id(if there is no recurring payments this will be 0).
transaction_subscription_pay_number	integer The payment number of the subscription related to the transaction.
transaction_discount	float If any discount coupon was applied, the amount in dollars deducted from the original price. “N/A” if none.
transaction_tax	float The amount of sales tax or VAT. “N/A” if none.
transaction_base_amount	float The base price for the transaction (for trial this will be the base price of the initial transaction).
transaction_shipping	float The shipping cost.
original_id	integer In case of a payment subscription, the order ID of the first transaction within the subscription. In this case it will be the same as the transaction_id since it is a first payment.
vendor_tracking_id_1	string Vendor’s tracking ID 1 if the sale was generated from a tracking link.
vendor_tracking_id_2	string Vendor’s tracking ID 2 if the sale was generated from a tracking link.
vendor_tracking_link	string Vendor’s tracking link name.
shipping_first_name	string Lead’s shipping first name. “N/A” if none.
shipping_last_name	string Lead’s shipping last name. “N/A” if none.
shipping_address	string Lead’s shipping address. “N/A” if none.
shipping_city	string Lead’s shipping city. “N/A” if none.
shipping_zip	string Lead’s shipping zip. “N/A” if none.
shipping_country	string Lead’s shipping country. “N/A” if none.
shipping_state	string Lead’s shipping state. “N/A” if none.
rebill_circle	integer Days left for the next payment.
installments	integer The number of installments for the subscription. Present only for recurring subscription payments with finite number of installments.
frequency	string The frequency of recurrence. Possible values (‘every_year’, ‘every_2_years’). Present only for recurring subscription payments with price point type recurrent.
payments_left	integer Number of upcoming payments until the end of the subscription. 9999 if “cancelled by customer”.
payment_processor_type	string The payment processor type: “PayPal”, “Braintree”, “Stripe”, “Authorize.net”
failed_reattempt_number	integer If this is a reattempt of a failed transaction, the retry number

JSON parameters:

For failed transactions	Values
transaction_id	integer A unique numeric identifier for the transaction id.
lead_first_name	string The lead first name at the moment of purchase.
lead_last_name	string The lead last name at the moment of purchase.
lead_email	string The lead email at the moment of purchase.
lead_id	integer A unique numeric identifier for the lead id.
lead_username	string The lead username.
lead_country	string The lead country at the moment of purchase.
lead_country_code_2	string The lead two letter country code at the moment of purchase.
lead_country_code_3	string The lead three letter country code at the moment of purchase.
lead_state	string The lead state at the moment of purchase.
lead_phone_country_code	string The lead phone country code at the moment of purchase.
lead_phone_number	string The lead phone number at the moment of purchase.
lead_address	string The lead address at the moment of purchase.
lead_city	string The lead city at the moment of purchase.
lead_zip	string The lead zip at the moment of purchase.
product_name	string The product name at the moment of purchase.
product_id	integer The product id linked to the transaction.
product_price_point	integer The product price point linked to the transaction.
transaction_full_amount	float The final paid amount on this specific transaction.
transaction_quantity	integer The product quantity.
transaction_affiliate	string Username of the affiliate, “N/A” if none.
transaction_jv	string Username of the jv, “N/A” if none.
transaction_date	yyyy-mm-dd hh:mm:ss Transaction date EST.
transaction_type	string The transaction type. Possible values: ‘failed’
transaction_parent_id	integer The id of the parent transaction (in the case of refunds/chargebacks)
transaction_subscription_id	string A unique identifier for the subscription id (PayPal transactions will return PayPal subscription id. If there is no recurring payments this will be 0).
transaction_internal_subscription_id	integer A unique numeric identifier for the subscription id(if there is no recurring payments this will be 0).
transaction_subscription_pay_number	integer The payment number of the subscription related to the transaction.
transaction_discount	float If any discount coupon was applied, the amount in dollars deducted from the original price. “N/A” if none.
transaction_tax	float The amount of sales tax or VAT. “N/A” if none.
transaction_base_amount	float The base price for the transaction (for trial this will be the base price of the initial transaction).
transaction_shipping	float The shipping cost.
original_id	integer In case of a payment subscription, the order ID of the first transaction within the subscription. In this case it will be the same as the transaction_id since it is a first payment.
vendor_tracking_id_1	string Vendor’s tracking ID 1 if the sale was generated from a tracking link.
vendor_tracking_id_2	string Vendor’s tracking ID 2 if the sale was generated from a tracking link.
vendor_tracking_link	string Vendor’s tracking link name.
shipping_first_name	string Lead’s shipping first name. “N/A” if none.
shipping_last_name	string Lead’s shipping last name. “N/A” if none.
shipping_address	string Lead’s shipping address. “N/A” if none.
shipping_city	string Lead’s shipping city. “N/A” if none.
shipping_zip	string Lead’s shipping zip. “N/A” if none.
shipping_country	string Lead’s shipping country. “N/A” if none.
shipping_state	string Lead’s shipping state. “N/A” if none.
payment_processor_type	string The payment processor type: “PayPal”, “Braintree”, “Stripe”, “Authorize.net”
failed_reattempt_number	integer If this is a reattempt of a failed transaction, the retry number

JSON parameters:

For cancellation transactions	Values
transaction_id	integer A unique numeric identifier for the transaction id.
lead_first_name	string The lead first name at the moment of purchase.
lead_last_name	string The lead last name at the moment of purchase.
lead_email	string The lead email at the moment of purchase.
lead_id	integer A unique numeric identifier for the lead id.
lead_username	string The lead username.
lead_country	string The lead country at the moment of purchase.
lead_country_code_2	string The lead two letter country code at the moment of purchase.
lead_country_code_3	string The lead three letter country code at the moment of purchase.
lead_state	string The lead state at the moment of purchase.
lead_phone_country_code	string The lead phone country code at the moment of purchase.
lead_phone_number	string The lead phone number at the moment of purchase.
lead_address	string The lead address at the moment of purchase.
lead_city	string The lead city at the moment of purchase.
lead_zip	string The lead zip at the moment of purchase.
lead_ip	string The lead ip at the moment of purchase.
product_name	string The product name at the moment of purchase.
product_id	integer The product id linked to the transaction.
product_price_point	integer The product price point linked to the transaction.
transaction_date	yyyy-mm-dd hh:mm:ss Transaction date EST.
transaction_type	string The transaction type. Possible values: ‘cancellation’
transaction_parent_id	integer The id of the parent transaction (in the case of refunds/chargebacks)
transaction_subscription_id	string A unique identifier for the subscription id (PayPal transactions will return PayPal subscription id. If there is no recurring payments this will be 0).
transaction_internal_subscription_id	integer A unique numeric identifier for the subscription id(if there is no recurring payments this will be 0).
transaction_last_4_card_digits	integer The last 4 digits of the used card (‘N/A’ if PayPal)
original_id	integer In case of a payment subscription, the order ID of the first transaction within the subscription. In this case it will be the same as the transaction_id since it is a first payment.
vendor_tracking_id_1	string Vendor’s tracking ID 1 if the sale was generated from a tracking link.
vendor_tracking_id_2	string Vendor’s tracking ID 2 if the sale was generated from a tracking link.
vendor_tracking_link	string Vendor’s tracking link name.
payment_processor_type	string The payment processor type: “PayPal”, “Braintree”, “Stripe”, “Authorize.net”

Example of the returned JSON array:

{
    "get_transaction_details":{
        "transaction_details":{
            "transaction_id":"99432",
            "lead_first_name":"Joe",
            "lead_last_name":"Smith",
            "lead_email":"joe.smith@domain.com",
            "lead_id":"4174086",
            "lead_username":"emailtest5e9476c0",
            "product_name":"Product kartra",
            "product_id":"5425",
            "product_price_point":"2",
            "transaction_full_amount":"4.00",
            "transaction_quantity":"1",
            "transaction_affiliate":"N/A",
            "transaction_jv":"N/A",
            "transaction_date":"2020-12-23 06:22:03",
            "transaction_type":"sale",
            "transaction_parent_id":"0",
            "transaction_subscription_id":"1670",
            "transaction_internal_subscription_id":"13670",
            "transaction_subscription_pay_number":"1",
            "transaction_last_4_card_digits":"1234",
            "original_id":"48111",
            "lead_country":"United States",
            "lead_country_code_2":"US",
            "lead_country_code_3":"USA",
            "lead_state":"New York",
            "lead_phone_country_code":"1",
            "lead_phone_number":"555-43556",
            "lead_address":"1st street",
            "lead_city":"New York",
            "lead_zip":"430022",
            "lead_ip":"127.0.0.1",
            "transaction_discount":"N/A",
            "transaction_tax":"N/A",
            "vendor_tracking_id_1":"N/A",
            "vendor_tracking_id_2":"N/A",
            "trial":"0",
            "trial_period":"N/A",
            "trial_amount":"N/A"
            "rebill_circle":"66",
            "installments":21,
            "payments_left":21,
            "shipping_first_name":"N/A",
            "shipping_last_name":"N/A",
            "shipping_address":"N/A",
            "shipping_city":"N/A",
            "shipping_zip":"N/A",
            "shipping_country":"N/A",
            "shipping_state":"N/A",
            "transaction_shipping":"0.00",
            "transaction_base_amount":"4.00",
            "vendor_tracking_link":"",
            "payment_processor_type":"Stripe"
        }
    }
}

Error Cases:

Type Number	Message	Cause
247	Transaction doesn’t exist	The transaction you are trying to find does not exist in our database.

An example of an error message:

{
  "status": "Error",
  "message": "Transaction doesn't exist",
  "type": "247"
}

Action: Get recurring payment subscription details

This will allow you to retrieve the information related to a particular recurring payment subscription in Kartra.

Type	Parameters	Values
POST	cmd*	get_subscription_details
POST	subscription_id*	integer

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'get_subscription_details',
        'subscription_id' => 993037
    ]
]

Here are the results returned by the request:

Parameters	Values
subscription_details	String (JSON encoded string containing the details of the recurring payment subscription)

JSON parameters	Values
subscription_id	integer A unique numeric identifier for the subscription id.
subscription_product_id	integer Product id of the subscription.
subscription_price_point	integer Product price point number of the subscription.
subscription_lead_id	integer Id for the lead linked to the subscription.
subscription_start_date	yyyy-mm-dd hh:mm:ss Subscription start date EST.
subscription_end_date	yyyy-mm-dd hh:mm:ss Subscription end date EST (0000-00-00 00:00:00 if subscription is not cancelled or terminated).
subscription_current_installment	integer Number of the current installment.
subscription_installments_left	integer How many installments are left / string “Until cancelled”
subscription_recurring_period	string (“monthly”, “every 2 months”, “quarterly”,”yearly”, “every 2 years”, “weekly”, “every 2 weeks”) The type of recurring for the subscription.
subscription_status	string (“Active”, “Paused”, “Cancelled”, “Terminated”) Subscription status.
subscription_next_payment_date	yyyy-mm-dd hh:mm:ss Subscription next payment date EST.
subscription_next_scheduled_payment_amount	float The amount of the next scheduled payment. “N/A” if none.
subscription_affiliate	string Username of the affiliate, “N/A” if none.
subscription_jv	string Username of the jv, “N/A” if none.

Example of the returned JSON array:

{
    "get_subscription_details":{
        "subscription_details":{
            "subscription_id":"993037",
            "subscription_product_id":"213",
            "subscription_price_point":"2",
            "subscription_lead_id":"321",
            "subscription_start_date":"2021-01-07 11:14:00",
            "subscription_end_date":"0000-00-00 00:00:00",
            "subscription_current_installment":"1",
            "subscription_installments_left":"Until cancelled",
            "subscription_recurring_period":"monthly",
            "subscription_status":"Active",
            "subscription_next_payment_date":"2021-02-07 11:14:00",
            "subscription_next_scheduled_payment_amount":"22.19",
            "subscription_affiliate":"affiliate_username",
            "subscription_jv":"N/A"
        }
    }
}

Error Cases:

Type Number	Message	Cause
248	Subscription doesn’t exist	The subscription you are trying to find does not exist in our database.

An example of an error message:

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

Action: Search recurring payment subscription

This will allow you to search for a recurring payment subscription inside Kartra, and to verify whether it exists or not.

Type	Parameters	Values
POST	cmd*	search_subscription
POST	transaction_internal_subscription_id*	integer

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'search_subscription',
        'transaction_internal_subscription_id' => 94314
    ]
]

Success message:

{
  "status": "Success",
  "message": "Subscription exists"
}

Error Cases:

Type Number	Message	Cause
248	Subscription doesn’t exist	The subscription you are trying to find does not exist in our database.

An example of an error message:

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

Action: Edit recurring payment subscription status

This will allow you to change the status of a particular recurring payment subscription from one particular lead. The possible statuses are…

Active
Cancelled
Terminated: meaning payment plans where all scheduled payments have already been paid
Paused: the subscription is technically active but no further payment will be processed until you “unpause” it back to Active (see below)

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 cannot be changed since they are not technically active anymore.

Type	Parameters	Values
POST	cmd*	modify_subscription_status
POST	subscription_id*	integer
POST	subscription_status_modification*	Posible values are “cancel”, “unpause”, “pause”

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'modify_subscription_status',
        'subscription_id' => 7373847,
        'subscription_status_modification' => 'pause',
    ]
]

Success message:

{
    "status":"Success",
    "actions":[
        {
            "modify_subscription_status":{
                "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.
274	Wrong status	subscription_status_modification is not sent. subscription_status_modification value does not have one of the values “cancel”, “unpause”, “pause”.
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.
252	Subscription already cancelled	The subscription you are trying to cancel is already cancelled.
267	Cancellation has failed	The cancellation process encountered an unexpected issue.

An example of an error message:

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

Action: Cancel a recurring payment subscription

This will allow you to cancel a subscription inside Kartra. You can pass either the Kartra Transaction ID or the Kartra Subscription ID.

Type	Parameters	Values
POST	cmd*	cancel_transaction
POST	transaction_id**	integer
POST	transaction_internal_subscription_id**	integer

* Required fields
** Required either the transaction_id OR transaction_internal_subscription_id in order for a subscription to be correctly identified and canceled.

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'cancel_transaction',
        'transaction_id' => 234161
    ]
]

Success message:

{
    "cancel_transaction":{
        "status":"Success",
        "transaction_subscription_id":"I-EV375R0H61SM",
        "transaction_internal_subscription_id":"14833"
    }
}

Result parameters:

Parameters	Values
transaction_subscription_id	string A unique identifier for the subscription id (PayPal transactions will return PayPal subscription id).
transaction_internal_subscription_id	integer A unique numeric identifier for the subscription id.

Error Cases:

Type Number	Message	Cause
248	Subscription doesn’t exist	The subscription you are trying to cancel does not exist in our database.
249	Transaction not linked to any recurring subscription	The transaction is not part of a payment subscription.
252	Subscription already cancelled	The subscription you are trying to cancel is already cancelled.
253	This type of transaction cannot be refunded or cancelled	The transaction is not a sale or a rebill type, or is a test transaction.
267	Cancellation has failed	The cancellation process encountered an unexpected issue.

An example of an error message:

{
  "status": "Error",
  "message": "Subscription already cancelled",
  "type": "252"
}

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’

POST

subscription_tax_percent ***

decimal, between 0 and 100

* 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,
        'subscription_tax_percent' => 5
    ]
]

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.
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.
268	Invalid amount	subscription_amount is not in the positive numeric format or numeric with two decimals.
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.
278	Invalid number	The subscription_installments_left is not a valid positive number or ‘until cancelled’.
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.
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.
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.
283	Wrong product id or price point	subscription_product_id or subscription_price_point do not exist or they were deleted.
284	Paypal transactions cannot be modified	Paypal subscriptions can only be cancelled, no other modifications are allowed.
285	No editable parameters for subscription	No parameters to edit were sent.
290	Tax must be between 0 and 100	The tax percent must exceed the interval between 0 and 100.

An example of an error message:

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

Action: Refund a payment transaction

This will allow you to refund an individual payment transaction within the refund period.

Type	Parameters	Values
POST	cmd*	refund_transaction
POST	transaction_id*	integer
POST	refund_amount**	float

* Required field
** If refund_amount is left empty, the entire transaction amount will be refunded. No need to state the currency, as it will be executed in whatever currency the original transaction was processed in.

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'refund_transaction',
        'transaction_id' => 738474,
        'refund_amount' => 19.95
    ]
]

Success message:

{
    "refund_transaction":{
        "status":"Success",
        "transaction_refunded":"792354"
    }
}

Result parameters:

Parameters	Values
transaction_refunded	integer The unique identifier that is the transaction id.

Error Cases:

Type Number	Message	Cause
247	Transaction doesn’t exist	The transaction you are trying to refund does not exist in our database.
250	Transaction outside refund period	The transaction refund period has expired.
251	Transaction already refunded	The transaction you are trying to refund is already refunded.
253	This type of transaction cannot be refunded or cancelled	The transaction is not a sale or a rebill type, or is a test transaction.
266	Refund has failed	The refund process encountered an unexpected issue.
268	Invalid amount	If refund_amount is present, but the format is not float.

An example of an error message:

{
  "status": "Error",
  "message": "Transaction already refunded",
  "type": "251"
}

Action: Search payment transaction

This will allow you to search for a payment transaction inside Kartra, and to verify whether the transaction exists, or not.

Type	Parameters	Values
POST	cmd*	search_transaction
POST	transaction_id*	integer

* Required fields

Here is an example:

'actions' => [
    '0' => [
        'cmd' => 'search_transaction',
        'transaction_id' => 1
    ]
]

Success message:

{
  "status": "Success",
  "message": "Transaction exists"
}

Error Cases:

Type Number	Message	Cause
247	Transaction doesn’t exist	The transaction you are trying to find does not exist in our database.

An example of an error message:

{
  "status": "Error",
  "message": "Transaction doesn't exist",
  "type": "247"
}