Skip to main content

Update a subscription

Overview

Change specific details about a subscription. Use the updateSubscription method to change specific details about a subscription.

Parameters

Parameters Type/Description

sessionID

Required (string)

 

Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect.  The sessionID expires in 10 minutes.

Subscription

Required (Object)

 

You need to include the entire Subscription object keeping its structure unchanged (retrieve it using getSubscription) but you can update only specific parameters enumerated below.

 

EndUser

Object

 

 

End user details.

 

ExpirationDate

String

 

 

Subscription expiration date - If you changed the time zone for the 2Checkout API by editing system settings under Account settings, then 2Checkout calculates the ExpirationDate according to your custom configuration. Note: The default 2Checkout API time zone is GMT+02:00.

You cannot set an expiration date from the past.

 

SubscriptionEnabled

Boolean

 

 

Possible values: TRUE/FALSE

 

RecurringEnabled

Boolean

 

 

Possible values: TRUE/FALSE

 

ExternalCustomerReference

String

 

 

Unique customer alphanumeric (string) identifiers that you control. Use this to 

move a subscription from under a customer to another customer entity. 2Checkout moves subscription under the customer for which you provide the External customer reference during the subscription update process. View example.

 

ProductId

Int

 

 

System-generated unique product ID. Needs to be the ID of an existing product in the 2Checkout system created under your account.

The product ID governs the product to which the subscription is associated with.

Product types must match Regular - Regular or Bundle - Bundle.

IDs must identify products with the renewal system enabled (max billing cycle 36 months).

 

ProductName

String

 

 

The name of the product for identifier used under ProductID.

 

ProductQuantity

Int

 

 

Ordered quantity.

 

PriceOptionCodes

Array

 

 

Array of product options codes. Pricing options codes are case sensitive.

To impact the renewal price, the PriceOptionsCodes need to belong to price options of pricing configurations used for the product with which the subscription is associated.

 

All other parameters of the Subscription object are non-editable.

The 2Checkout system uses the updated subscription information for:

  • Manual and automatic renewals
  • Upgrades
  • Trial conversions

Response

Parameters Type/Description

Boolean

true or false depending on whether the changes were successful or not.

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReferenceTest = 'YOUR_SUBSCRIPTION_REFERENCE';

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

$updatedSubscription = callRPC((Object)$jsonRpcRequest, $host, true);
var_dump ($updatedSubscription);
$updatedSubscription->RecurringEnabled = false;
$updatedSubscription-> SubscriptionEnabled = true;
$updatedSubscription->ExpirationDate = '2020-12-12';

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

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

 

Retrieve shipping fees

Overview

Use the getShippingFees method to extract information about the shipping fees you defined for your account.

Parameters

Parameters Type/Description

Parameters

Type/Description

sessionID

Required (string)

 

Session identifier, the output of the Login method. Include sessionID into all your requests. Avangate throws an exception if the values are incorrect.  The sessionID expires in 10 minutes.

Response

Parameters Type/Description

ShippingFees

Array of objects

<?php

require ('PATH_TO_AUTH');

$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'getShippingFees',
'params' => array($sessionID)
);
var_dump (callRPC((Object)$jsonRpcRequest, $host));

?>

Enable a subscription

Overview

Use the enableSubscription method to enable a subscription.

Parameters

Parameters Type/Description

sessionID

Required (string)

 

Session identifier, the output of the Login method. Include sessionID into all your requests. Avangate throws an exception if the values are incorrect.  The sessionID expires in 10 minutes.

subscriptionReference

Required (string)

 

Unique, system-generated subscription identifier.

Response

Parameters Type/Description

Boolean

true or false depending on whether the changes were successful or not.

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';

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

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

Additional order fields

Overview

Use this object to create / update information on additional order/product fields. 

Parameters

AdditionalField Object

Label

String

 

Field text.

Code

String

 

Field identifier. Alpha-numeric chars, underscores and dashes.

Type

String

 

Field type:

  • LISTBOX
  • CHECKBOX
  • TEXT
  • HIDDEN

ApplyTo

Sting

 

  • ORDER
  • PRODUCT

Values

Array of values

 

Custom values you control.

ValidationRule

String

 

The validation rule restricting the type of information shoppers can enter in the additional field during the purchase process.

Translations

Array of objects

 

Details below.

               Label

String

 

Field text translated in the language of the Translations object.

              Values

Object

 

Custom values you control translated in the language of the Translations object.

             Language

String

 

ISO language code. (ISO 639-1 two-letter code).

 

 

Confirm payment for Proforma Invoices

Overview

Use this method to confirm the payment for proforma invoices issued to your partners on the Direct Payment module. To confirm the payment for a proforma invoice, you need to follow these steps before calling the confirmInvoicePayment API method:

  1. Authenticate to 2Checkout API based on these instructions.
  2. Set the partner for which you want to confirm the payment (method explained in the sample below).
  3. Set the proforma invoice  (method explained in the sample below).
  4. Confirm the payment using the instructions below.

Requirements

You can confirm payments only for partners set with Direct business model. Learn here how to set a business model to your partners.

Parameters

Parameters Type/Description
sessionID Required (String)
  Session identifier, output of the Login method. An exception is thrown if the values are incorrect.
partnerCode Required (String)
  The unique identifier that you need to specify when creating a partner in the Control Panel. You can find it under the General Information area when editing partner details.
proformaNo Required (String)
  The unique identifier of a partner invoice from the 2Checkout system.
rrn Optional (String)
  The code associated with the proforma invoice payment reference (receipt registration number).

Response

Parameters Type/Description

TRUE

FALSE

Boolean

True - method is successful

False - method is not successful

Error messages

Error code Error description
INVALID_PARTNER No partner is set or the proforma does not belong to the partner set.
PAYMENT_PROFORMA The proforma invoice has already been paid.
INVALID_PROFORMA The proforma invoice number is invalid.
INVALID_METHOD The partner set is not on the Direct business model.

Request

<?php

require ('PATH_TO_AUTH');  // Authentication example: https://knowledgecenter.2checkout.com/Integration/07Channel_Manager_API/SOAP/02Authentication
require ('PATH_TO_SET_PARTNER'); // setPartner example: https://knowledgecenter.2checkout.com/Integration/07Channel_Manager_API/SOAP/06Reference/00Partner/00Set_partner


$partnerCode = 'partner_code'; // direct

try {
    $setPartner = $client->setPartner($sessionID, $partnerCode);
    var_dump($setPartner);
} catch (SoapFault $e) {
    echo "<pre>";
    echo $e->xdebug_message;
    echo $e->getMessage();
}


$proformaNo = '6';

try {
    $setProforma = $client->setProforma($sessionID, $proformaNo);
    var_dump($setProforma);
} catch (SoapFault $e) {
    echo "<pre>";

    echo $e->getMessage();
}

try {
    $confirmInvoicePayment = $client->confirmInvoicePayment($sessionID);
    var_dump($confirmInvoicePayment);
} catch (SoapFault $e) {

    echo $e->getMessage();
}

How do I know what type of 2Checkout account I have?

Overview

If you are not sure or you don't remember what type of account you have on the 2Checkout platform, you can find this information in your Merchant Control Panel.

Availability

The information about the account type is available for all merchants who signed a contract with 2Checkout.

How to find your 2Checkout account type

To find out what type of account you have on the 2Checkout platform, follow these steps:

1. Log in to your Merchant Control Panel.

2. Navigate to the cogwheel in the top-right corner and click on Settings, as shown below.

account_type_1.png

3. On the Account Settings page, scroll down to the Account Information section and click on the Edit details button.

account_type_2.png

4. On the Account Information page, scroll down to the Account documents section and click on the PDF to open/download it. The PDF is the contract you signed with 2Checkout and includes the information about your account type, as well as details about margins and fees that apply to your account.

account_type_3.png

 

 

 

Assign to another customer

Overview

Use the setSubscriptionCustomer method. 2Checkout moves subscription under the customer for which you provide the 2Checkout customer reference or the External customer reference during the subscription update process.

json_diagram.png

Requirements

To move a subscription from a source customer to a target customer:

  • Use 2Checkout customer references or External customer references belonging to the target customer. 2Checkout re-assigns the subscription to the target customer. 
  • Customer references must be valid and associated to the target customer entity under which you move the subscription.
  • If you provide both the 2Checkout customer reference and External customer reference they need to belong to the same target customer entity.

Parameters

Parameters Type/Description

sessionID

Required (string)

 

Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect.  The sessionID expires in 10 minutes.

avangateCustomerReference

Required (int)

 

System-generated customer reference. Required unless you prefer to use ExternalCustomerReference.

externalCustomerReference

Optional (string)

 

External customer reference that you control. Optional when you use AvangateCustomerReference. If you include it, it needs to belong to the same customer as the AvangateCustomerReference.

Response

Parameters Type/Description

Boolean

true or false depending on whether the changes were successful or not.

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReference = 'YOUR_SUBSCRIPTION_REFERENCE';
$customerReference = CUSTOMER_REFERENCE;

$jsonRpcRequest = array (
'method' => 'setSubscriptionCustomer',
'params' => array($sessionID, $subscriptionReference, $customerReference),
'id' => $i++,
'jsonrpc' => '2.0');

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

Retrieve product information by code

Overview

Extract information about a product from the Avangate system using its unique ID and the code of the pricing list to which it is assigned to.

Requirements

Parameters

Parameter Type/Description
sessionID Required (string)
  Session identifier, which is the output of the Login method. An exception will be thrown if the values are incorrect.
productCode Required (string)
  The unique product identifier from your system.
pricingListCode Required (string)
  The unique identifier of the pricing list.

Response

Parameter Type/Description
ProductInfo Complet object
  Complex object containing arrays of SimpleProduct and PriceOptions objects.

Request

<?php

require ('PATH_TO_AUTH');  // Authentication example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/JSON-RPC/02Authentication
require ('PATH_TO_SET_PARTNER'); // setPartner example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/JSON-RPC/06Reference/Partner/00Set_partner

$productCode = 'YOUR_PRODUCT_CODE';
$pricingListCode = 'YOUR_PRICING_LIST_CODE';

$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'getProductByCode',
'params' => array($sessionID, $productCode, $pricingListCode)
);
var_dump (callRPC((Object)$jsonRpcRequest, $host));

Errors

Error Description

INVALID_PARTNER

No partner is set.

INVALID_PRODUCT

Provide a valid product ID.

INVALID_PRICING_LIST_CODE

Provide a valid pricing list code.

PARTNER_PRICING_LISTS_NOT_FOUND

There are no pricing lists with the provided code.

PRODUCT_NOT_FOUND

There is no product with this ID in the given pricing list.

 

Retrieve all configurations

Overview

Use the getPricingConfigurations method to extract information on the pricing configurations you set for a product.

Parameters

Parameters Type/Description

sessionID

Required (string)

 

Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect.  The sessionID expires in 10 minutes.

ProductCode

Required (string)

 

The editable code that you control at product-level, not the unique, system-generated product ID.

Response

Parameters Type/Description

PricingConfiguration

Array of objects

Request

<?php

require ('PATH_TO_AUTH');

$productCode = 'YOUR_PRODUCT_CODE';

$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'getPricingConfigurations',
'params' => array($sessionID, $productCode)
);
var_dump (callRPC((Object)$jsonRpcRequest, $host));

?>

Retrieve order subscription references

Overview

List the references associated with the subscription generated for an order.

Requirements

Parameters

Parameter Type/Description
sessionID Required (String)
  Session identifier, output of the Login method. An exception is thrown if the values are incorrect.
refNo Required (String)
  The unique identifier of an order from the Avangate system.
pageNo Optional (Int)
 

Break down the subscription information using pagination into groups of 50 items (PartnerSubscription objects) per page.

Example values:

  • 1 - the first 50
  • 2 - the next 50
  • 3 - the next 50

Can be NULL.

Response

Parameter Type/Description

PartnerSubscription

Array of objects

 

Details below

 

SubscriptionReference

String

 

 

The unique reference associated with a subscription generated for a product included in a partner order.

 

HasEndUserInformation

Boolean

 

 

True or false, depending on whether end user information is attached to the subscription.

 

RegistrationStatus

String

 

 

Possible values:

  • Not registered
  • Registered

 

RegistrationEmails

String

 

 

The email used by the end user in the registration process. Can be NULL.

 

FullfilmentStatus

String

 

 

Fulfillment status possible values:

  1. DELIVERED - Order was fulfilled/delivered.
  2. NOT_DELIVERED - Fulfillment is blocked due to various reasons including lack of payment/credit, missing reseller/end user details.
  3. NO_DELIVERY_REQUIRED - No fulfillment confirmation is required.
  4. VENDOR_CONFIRMED_DELIVERY - Fulfillment has been confirmed.
  5. VENDOR_DELIVERY_CONFIRMATION_REQUIRED - You need to confirm fulfillment.

Request

<?php

require('PATH_TO_AUTH'); // Authentication example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/SOAP/02Authentication
require('PATH_TO_setPartner'); // setPartner example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/SOAP/06Reference/Partner/00Set_partner

$refNo = 'YOUR_ORDER_REFERENCE';

try {
    $SubscriptionsGenerated= $client->getOrderSubscriptions ($sessionID, $refNo, $pageNo);
} catch (SoapFault $e) {
    Echo "Subscriptions: " . $e->getMessage();
    exit;
}
var_dump ("Subscriptions ", $SubscriptionsGenerated);

Errors

Error Description

NOT_FOUND_PARTNER

A partner must be set first.

EMPTY_ORDER_REFERENCE

Order reference not provided.

INVALID_REFERENCE

Invalid order reference.

 

Need help?

Do you have a question? If you didn’t find the answer you are looking for in our documentation, you can contact our Support teams for more information. If you have a technical issue or question, please contact us. We are happy to help.

Not yet a Verifone customer?

We’ll help you choose the right payment solution for your business, wherever you want to sell, in-person or online. Our team of experts will happily discuss your needs.

Verifone logo