Overview

This object is returned directly or within a successful response from the following API requests:

  Retrieve an additional field                               Retrieve assigned additional fields                              Retrieve all additional fields    

Additional fields object

Overview

One key metric when managing subscriptions is a high renewal rate to grow and maintain a valuable, loyal customer base and secure increased recurring revenues.

For this purpose, you can set renewal notifications that 2Checkout sends to your shoppers. You control the number of emails, as well as the moment in time your shoppers receive these emails.

You can use predesigned templates complete with fresh content (samples below). The new templates have replaced the previous notifications sent out for subscriptions set to be (either automatically or manually) renewed, but any customization you have in place, either in terms of styling or content, continues to be available.

Availability

All 2Checkout accounts.

Renewal notifications

According to the product settings you perform, 2Checkout can automatically send renewal notifications for:

1. Subscriptions where renewal is set to be automatically performed - your shoppers can receive email notifications both before, as well as after the subscription expiration day. Content varies depending on the moment they receive these notifications. Messages can be:

• Notification of upcoming automatic subscription renewals
• Or dunning management notifications containing instructions to update payment information/perform manual renewal as automatic renewal failed.

2. Subscriptions where renewal is manually performed - your shoppers can receive email notifications both before, as well as after the subscription expiration day. Content varies here, as well, depending on the moment they receive these notifications. Emails

• Inform shoppers about the upcoming renewal time and instruct them to perform the payment
• Or contain a subscription expiration notification urging shoppers to manually renew to avoid losing access to their product.

Notification email samples

Email notification sent for automatic renewals

Email notification sent for manual renewals

Preview and test email

Navigate to the Email template manager section to:

• Preview and test current templates for emails sent to your shoppers
• Customize the header and the footer sections by creating custom templates you can assign to your emails

Access the renewal notifications under the Renewal section. Here, you are able to access both the Auto-renewal and Manual renewal emails.

Why don't I see the new template for this email?

The redesigned templates for the renewal notifications have automatically replaced the default templates.

If your preview in the Control Panel does not show the new templates, you are most probably using customized versions that include content and/or styling your company requested at a certain point in time.

You can compare the above samples to your current templates and send us an email if you decide the new ones suit your business needs better. We will work with you on the switch.

Best practices

Find out more details here about how to curb cart abandonment and unfinished payments.

Lock-in price for auto-renewal notifications

Merchants that want to do mass price updates for a region are risking a significant increase in chargebacks and refunds for the subscribers that were already notified that they need to pay a certain renewal price.

Once the shopper is notified about an auto-renewal with a certain price, they should be charged that price, even if the merchant updates the product price settings. But, if the merchant is changing the product price right before the renewal, the subscriber is billed with the new price, which in some cases can be higher than the initial one.

To be compliant and help merchants limit the chargeback rates when price updates that impact many subscriptions take place, we introduced the lock-in price functionality. This is activated by default on all 2Checkout accounts.

The lock-in price for auto-renewal notifications ensures the continuity of the original pricing scheme for a subscription if a merchant decides to change the product pricing after a renewal notification has already been sent. Thanks to this functionality, the shopper is not impacted by any price changes during the next auto-renewal if they have already received the auto-renewal notification.

The price is locked in for the next auto-renewal when the notification is already sent to the shopper in the following scenarios:

• The product price was updated
• The merchant configured a silent upgrade
• The renewal price changed, or a new auto-renewal discount is configured

The locked-in price is ignored in the following scenarios:

• A custom price was set for the subscription via API, Control Panel, or subscription import: The shopper is notified when a custom price is applied
• The shopper manually renews the subscription
• The shopper upgrades the subscription
• The shopper accepted a discount because of a churn prevention campaign

The auto-renewal lock-in price benefits both the merchant and the shopper. Thus, the merchant has fewer disputes and customers canceling a subscription after billing a price different than what was notified, while the shopper avoids an unexpected billing amount being charged automatically.

Workflow

Merchants are notified in the Merchant Control Panel that the new price will not apply for the next renewal of subscriptions where an auto-renewal notification is already sent.

The above note is displayed in the Merchant Control Panel under:

1. Setup > Products > Edit Product Pricing > Pricing configuration > Renewal price section

2. Setup > Renewal > Renewal discounts > Edit renewal discount

Overview

Use this section to handle the renewal of your subscriptions.

You can retrieve information regarding the renewal status of a subscription, including the manual renewal link that a customer needs to access in order to renew.

Enable or disable the recurring billing for a subscription using the API methods displayed below.

Overview

Avangate supports local Brazilian Visa, MasterCard and AMEX credit / debit cards limited to national purchases in the local currency BRL (Brazilian Real). 

Requirements

1. Installments are available only for:
   • Brazilian customers
   • Local Visa, MasterCard or AMEX cards
   • Non-recurring transactions
2. Minimum installment threshold is 5 BRL. Maximum number of installments is 6.
3. Mandatory information for payments also includes shopper phone number and  Fiscal Code (CPF/CNPJ).

Do local BR cards with / without installments require an addendum to my contract?

Yes. Please contact Avangate for activation.

How does it work?

1. Create the Order object.
2. Validate the number of installments available based on total order value. 
3. Place the order specifying the number of installments. 

Funds collection for installment payments

Avangate pays you in full, regardless of the number of installments (this is covered directly by the banks). 

Overview

2Checkout supports local Brazilian Visa, MasterCard and AMEX credit / debit cards limited to national purchases in the local currency BRL (Brazilian Real). 

Requirements

1. Installments are available only for:
   • Brazilian customers
   • Local Visa, MasterCard or AMEX cards
   • Non-recurring transactions
2. Minimum installment threshold is 5 BRL. Maximum number of installments is 6.
3. Mandatory information for payments also includes shopper phone number and  Fiscal Code (CPF/CNPJ).

Do local BR cards with / without installments require an addendum to my contract?

Yes. Please contact 2Checkout for activation.

How does it work?

1. Create the Order object.
2. Validate the number of installments available based on total order value. 
3. Place the order specifying the number of installments. 

Funds collection for installment payments

2Checkout pays you in full, regardless of the number of installments (this is covered directly by the banks). 

Overview

Use the getContents method to get info on all the products added to cart by the shopper in the current session. Products can be either defined in the catalog, or created with dynamic information.    

Parameters

Response

Request

<?php

require('PATH_TO_AUTH');

$Order = new stdClass();
$Order->RefNo = NULL;
$Order->Currency = 'usd';
$Order->Country = 'US';
$Order->Language = 'en';
$Order->CustomerIP = '91.220.121.21';
$Order->ExternalReference = NULL;
$Order->Source = NULL;
$Order->AffiliateId = NULL;
$Order->CustomerReference = NULL;
$Order->Items = array();
$Order->Items[0] = new stdClass();
$Order->Items[0]->Code = 'my_subscription_1'; // you can also send products with dynamic information
$Order->Items[0]->Quantity = 1;
$Order->Items[0]->PriceOptions = NULL;
$Order->Items[0]->SKU = NULL;
$Order->Items[0]->Price = NULL;
$Order->Items[0]->CrossSell = NULL;
$Order->Items[0]->Trial = false;
$Order->Items[0]->AdditionalFields = NULL;
$Order->Items[0]->Promotion = NULL;
$Order->BillingDetails = new stdClass();
$Order->BillingDetails->FirstName = 'FirstName';
$Order->BillingDetails->LastName = 'LastName';
$Order->BillingDetails->CountryCode = 'us';
$Order->BillingDetails->State = 'California';
$Order->BillingDetails->City = 'LA';
$Order->BillingDetails->Address1 = 'Address example';
$Order->BillingDetails->Address2 = NULL;
$Order->BillingDetails->Zip = '90210';
$Order->BillingDetails->Email = 'customer@email.com';
$Order->BillingDetails->Phone = NULL;
$Order->BillingDetails->Company = NULL;
$Order->DeliveryDetails = NULL;
$Order->PaymentDetails = new stdClass ();
$Order->PaymentDetails->Type = 'TEST';
$Order->PaymentDetails->Currency = 'usd';
$Order->PaymentDetails->PaymentMethod = new stdClass ();
$Order->PaymentDetails->CustomerIP = '10.10.10.10';
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = true;
$Order->PaymentDetails->PaymentMethod->CardNumber = "4111111111111111";
$Order->PaymentDetails->PaymentMethod->CardType = 'visa';
$Order->PaymentDetails->PaymentMethod->ExpirationYear = '2019';
$Order->PaymentDetails->PaymentMethod->ExpirationMonth = '12';
$Order->PaymentDetails->PaymentMethod->HolderName = 'John';
$Order->PaymentDetails->PaymentMethod->CCID = '123';
$Order->Promotions = NULL;
$Order->AdditionalFields = NULL;
$Order->LocalTime = NULL;
$Order->GiftDetails = NULL;

$jsonRpcRequest = array (
'method' => 'getContents',
'params' => array($sessionID, $Order),
'id' => $i++,
'jsonrpc' => '2.0'
);

var_dump (callRPC((Object)$jsonRpcRequest, $host, true));

Overview

Retrieve information about the upgrade options for a specific subscription.

Trigger upgrade for your existing subscriptions, or set external references to a subscription by using the API methods displayed below.

Overview

Renew a subscription and collect recurring revenue using the 2Checkout Subscription Reference. You can renew subscriptions for both catalog and dynamic products. The only requirement is to provide a valid subscription reference.

Requirements

To place a renewal order, you need to provide a valid subscription reference number.

Payment methods

You can place renewal orders using the following payment methods:

• Credit cards
• PayPal
• WeChat Pay
• iDEAL
• Purchase Order
• Wire

Use the PaymentDetails object to change the payment method used in the ordering process.

Parameters

Response

 

Request

<?php

require ('PATH_TO_AUTH');

$Order = new stdClass();
$Order->Currency = 'USD';
$Order->Language = "EN";
$Order->Country = 'US';
$Order->CustomerIP = '91.220.121.21';
$Order->Source = "sourceAPI.net";
$Order->LocalTime = date('Y-m-d H:i:s');
$Order->Items = array();

/**/
$Order->Items[0]->RenewalInformation = new stdClass();
$Order->Items[0]->RenewalInformation->SubscriptionReference = 'A8C5671BFE'; //subscription used in the renewal process
$Order->Items[0]->Price = new stdClass();
$Order->Items[0]->Price->Type = 'CUSTOM';
$Order->Items[0]->Price->Amount = '10';
$Order->Items[0]->PriceOptions = array('uniqscale1=4');//

$Order->MachineId = "MachineID";

$Order->BillingDetails = new stdClass();
$Order->BillingDetails->Address1 = 'Bil1ing address';
$Order->BillingDetails->Address2 = 'Billing address 2';
$Order->BillingDetails->City = 'Billing City';
$Order->BillingDetails->State = 'Billing State';
$Order->BillingDetails->CountryCode = 'US';
$Order->BillingDetails->Phone = 1231232123;
$Order->BillingDetails->Email = 'customer_details@test.com';
$Order->BillingDetails->FirstName = 'First';
$Order->BillingDetails->LastName = 'Customer';
$Order->BillingDetails->Company = 'Billing Company';
$Order->BillingDetails->Zip = '55104';

$Order->DeliveryDetails = new stdClass();
$Order->DeliveryDetails->Address1 = 'Bil1ing address';
$Order->DeliveryDetails->Address2 = 'Billing address 2';
$Order->DeliveryDetails->City = 'Billing City';
$Order->DeliveryDetails->State = 'Billing State';
$Order->DeliveryDetails->CountryCode = 'US';
$Order->DeliveryDetails->Phone = '12345';
$Order->DeliveryDetails->Email = 'customer_details@test.com';
$Order->DeliveryDetails->FirstName = 'First';
$Order->DeliveryDetails->LastName = 'Customer';
$Order->DeliveryDetails->Zip = "55104";

$Order->PaymentDetails = new stdClass();
$Order->PaymentDetails->Type = "CC";
$Order->PaymentDetails->Currency = $currency;

$Order->PaymentDetails->PaymentMethod = new stdClass();
/**/
$Order->PaymentDetails->PaymentMethod->CardNumber = "4111111111111111";
$Order->PaymentDetails->PaymentMethod->CardType = "VISA";
$Order->PaymentDetails->PaymentMethod->ExpirationYear = "2019";
$Order->PaymentDetails->PaymentMethod->ExpirationMonth = "12";
$Order->PaymentDetails->PaymentMethod->CCID = "123";
$Order->PaymentDetails->PaymentMethod->HolderName = "John Doe";
$Order->PaymentDetails->PaymentMethod->RecurringEnabled = TRUE;
$Order->PaymentDetails->PaymentMethod->HolderNameTime = 1;
$Order->PaymentDetails->PaymentMethod->CardNumberTime = 1;
/**/


try {
    $newOrder = $client->placeOrder($sessionID, $Order);
}
catch (SoapFault $e) {
    echo "newOrder: " . $e->getMessage();
    exit;
}

var_dump("newOrder", $Order);

Use the variables in the list below to customize the Trial expiration notification shopper email according to your needs. Check the 'Mandatory' column to see the variables that are required in your customized version of the e-mail.