Some content on this site may not be available right now. We are aware and actively monitoring the situation.
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Place order with addons

Use the placeOrder method to buy addons together with a main product, or to add an addon to a subscription your customer already has. This page lists the order parameters and errors that are specific to addons. The other placeOrder parameters are unchanged.

An addon can only be purchased if it is associated with the main product, and it cannot be sold on its own.

Request 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.

Items.OrderItem.MainProductCode

Optional (string)

Required for addon products purchased together with a main product. The product code of the main product in the same order that the addon is linked to. It must match the Code of a non-addon item in Items.

Items.OrderItem.MainSubscriptionReference

Optional (string)

Use it to add an addon to an existing, active subscription. The reference of the main subscription. 2Checkout prorates the first billing cycle of the addon to the remaining time until the main subscription expires. You can reference different main subscriptions in the same order. Can be NULL.

Items.OrderItem.Quantity

Optional (integer)

Number of units. The quantity of an addon cannot be higher than the quantity of its main product.

Buy an addon with a main product

Send the main product and its addon as two items in the same order, and set MainProductCode on the addon item. 2Checkout processes the order as a whole.

• An order cannot contain only addon items. It needs at least one main product.

• The main product cannot have delayed activation and cannot generate an instant subscription.

• The addon must have a price configured in the order currency.

Request sample

<?php

$vendorCode = 'YOUR_VENDOR_CODE';
$apiKey     = 'YOUR_API_KEY';
$date       = gmdate('Y-m-d H:i:s');
$hash       = hash_hmac(
    'md5',
    strlen($vendorCode) . $vendorCode . strlen($date) . $date,
    $apiKey
);

try {
    $client = new SoapClient(
        'https://api.2checkout.com/soap/6.0?wsdl',
        ['cache_wsdl' => WSDL_CACHE_NONE]
    );

    $sessionID = $client->login($vendorCode, $date, $hash);

    $Order = new stdClass();
    $Order->Currency = 'USD';
    $Order->Country = 'US';
    $Order->Language = 'en';
    $Order->CustomerIP = '91.220.121.21';
    $Order->Source = 'testAPI.com';
    $Order->Items = array();
    $Order->Items[0] = new stdClass();
    $Order->Items[0]->Code = 'MAIN_PRODUCT_CODE';
    $Order->Items[0]->Quantity = 1;
    $Order->Items[1] = new stdClass();
    $Order->Items[1]->Code = 'ADDON_PRODUCT_CODE';
    $Order->Items[1]->Quantity = 1;
    $Order->Items[1]->MainProductCode = 'MAIN_PRODUCT_CODE';

    $Order->BillingDetails = new stdClass();
    $Order->BillingDetails->Address1 = 'Test Address';
    $Order->BillingDetails->City = 'London';
    $Order->BillingDetails->CountryCode = 'US';
    $Order->BillingDetails->Email = 'customer@2Checkout.com';
    $Order->BillingDetails->FirstName = 'Customer';
    $Order->BillingDetails->LastName = '2Checkout';
    $Order->BillingDetails->Phone = '556133127400';
    $Order->BillingDetails->State = 'DF';
    $Order->BillingDetails->Zip = '70403-900';

    $Order->PaymentDetails = new stdClass();
    $Order->PaymentDetails->Type = 'CC';
    $Order->PaymentDetails->Currency = 'USD';
    $Order->PaymentDetails->CustomerIP = '91.220.121.21';
    $Order->PaymentDetails->PaymentMethod = new stdClass();
    $Order->PaymentDetails->PaymentMethod->CardNumber = '4111111111111111';
    $Order->PaymentDetails->PaymentMethod->CardType = 'VISA';
    $Order->PaymentDetails->PaymentMethod->ExpirationYear = '2030';
    $Order->PaymentDetails->PaymentMethod->ExpirationMonth = '12';
    $Order->PaymentDetails->PaymentMethod->CCID = '123';
    $Order->PaymentDetails->PaymentMethod->HolderName = 'John Doe';
    $Order->PaymentDetails->PaymentMethod->RecurringEnabled = true;
    $Order->PaymentDetails->PaymentMethod->Vendor3DSReturnURL = 'www.test.com';
    $Order->PaymentDetails->PaymentMethod->Vendor3DSCancelURL = 'www.test.com';

    $result = $client->placeOrder($sessionID, $Order);
    var_dump($result);

} catch (SoapFault $e) {
    echo 'SoapFault: ' . $e->getMessage() . PHP_EOL;
}

Error codes

Error codes
Description

ORDER_ADDON_ONLY_NOT_ALLOWED

An order cannot contain only addon items. At least one main product is required.

ORDER_ADDON_MAIN_PRODUCT_NOT_FOUND

Addon product [addon code] references main product [main product code] which is not present in the order.

ORDER_ADDON_QUANTITY_EXCEEDS_MAIN

Addon product [addon code] quantity [quantity] cannot exceed the quantity [quantity] of its main product [main product code].

ORDER_ADDON_NOT_ASSOCIATED

Addon product [addon code] is not associated to main product [main product code].

ORDER_ADDON_DELAYED_ACTIVATION_NOT_ALLOWED

Main product [main product code] has delayed activation and cannot be purchased with addons.

ORDER_ADDON_INSTANT_SUBSCRIPTION_NOT_ALLOWED

Main product [main product code] generates an instant subscription and cannot be purchased with addons.

ORDER_ADDON_PRICE_NOT_FOUND

Could not determine the catalogue price for addon product [addon code] in currency [currency]. Ensure the product has a price configured for this currency.

Add an addon to an existing subscription

To add an addon to a subscription your customer already has, send the addon as an item and set MainSubscriptionReference to the main subscription. 2Checkout prorates the first billing cycle of the addon to the remaining time until the main subscription expires.

• The main subscription must be active, have automatic renewal enabled, and not be paused.

• The order currency must match the currency of the main subscription.

• The billing email must match the customer of the main subscription.

• Accepted payment methods: CC, EXISTING_PAYMENT_DATA, EES_TOKEN_PAYMENT, PAYPAL, PAYPAL_EXPRESS and PAYPAL_CREDIT.

Request sample

Error codes

Error code
Description

ORDER_MAIN_SUBSCRIPTION_NOT_FOUND

The main subscription reference [subscription reference] was not found.

ORDER_MAIN_SUBSCRIPTION_NOT_ACTIVE

The main subscription [subscription reference] is not active.

ORDER_MAIN_SUBSCRIPTION_NOT_RECURRING

The main subscription [subscription reference] is not set to auto-renew and cannot be used for addon purchase.

ORDER_MAIN_SUBSCRIPTION_CUSTOMER_MISMATCH

The billing email does not match the customer on the main subscription [subscription reference].

ORDER_MAIN_SUBSCRIPTION_CURRENCY_MISMATCH

The order currency does not match the main subscription [subscription reference] currency [currency].

ORDER_MAIN_SUBSCRIPTION_PAYMENT_METHOD_NOT_SUPPORTED

Payment method [payment method] is not supported for prorated addon purchases. Use CC, EXISTING_PAYMENT_DATA, EES_TOKEN_PAYMENT, PAYPAL, PAYPAL_EXPRESS, or PAYPAL_CREDIT.

ORDER_MAIN_SUBSCRIPTION_PAUSED

The main subscription [subscription reference] is paused and cannot have addons added while paused.

Last updated

Was this helpful?