> For the complete documentation index, see [llms.txt](https://docs.2checkout.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.2checkout.com/soap-api-reference/soap-api-6.0/api-requests/place-a-renewal-order.md).

# Place a renewal order

Renew a subscription and collect recurring revenue using the 2Checkout Subscription Reference. You can renew subscriptions for both catalog and dynamic products.&#x20;

## Requirements <a href="#requirements" id="requirements"></a>

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

## Payment methods <a href="#payment-methods" id="payment-methods"></a>

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.

## Request parameters <a href="#parameters" id="parameters"></a>

<table><thead><tr><th width="218">Parameter</th><th>Type / Description</th></tr></thead><tbody><tr><td><code>sessionID</code></td><td><strong>Required (string)</strong><br>Session identifier, the output of the <strong>Login</strong> method. Include <code>sessionID</code> into all your requests. 2Checkout throws an exception if the values are incorrect.  The <code>sessionID</code> expires in <strong>10 minutes</strong>.</td></tr><tr><td><a href="https://docs.2checkout.com/soap-api-reference/soap-api-6.0/api-requests/place-orders-with-catalog-products.md"><code>Order</code></a></td><td><p><strong>Required (object)</strong><br>Object designed to collect all data necessary for an order, including billing, product/subscription plan and payment details.</p><p>To place an order with PayPal rather than PayPal Express, use PAYPAL as the type of the <code>PaymentDetails</code> object and send the shopper email and a return URL as part of the <code>PaymentMethod</code> object. See code sample. </p></td></tr><tr><td><code>SubscriptionReference</code></td><td><p><strong>Required (string)</strong></p><p>2Checkout generated subscription reference number. E.q. A8C5671BFE.</p></td></tr></tbody></table>

### Request sample

```php
<?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->BillingCycleReset = true; // or false
$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->Items[1]->RenewalInformation = new stdClass();
$Order->Items[1]->RenewalInformation->SubscriptionReference = 'WIZQ9NV0HZ';

$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);
```

## Response parameters <a href="#response" id="response"></a>

<table><thead><tr><th width="190">Parameter</th><th>Type</th></tr></thead><tbody><tr><td><a href="https://docs.2checkout.com/soap-api-reference/soap-api-6.0/api-responses/order-with-catalog-products.md"><code>Order information</code></a></td><td><strong>Object</strong></td></tr></tbody></table>

## Renew a subscription with its addons

Use a single renewal order to renew a main subscription together with its addon subscriptions. 2Checkout charges the customer once for the whole order. Send one item with RenewalInformation.SubscriptionReference for the main subscription and one for each addon subscription to renew.

•       Addon subscriptions are prorated to the main subscription’s next expiration date when the main subscription is renewed in the same order, and to its current expiration date otherwise.

•       Active addon subscriptions that you leave out of the order have automatic renewal turned off after the payment succeeds.

•       You cannot renew an addon subscription whose expiration date is not before its main subscription’s expiration date. Renew the main subscription first.

## Request sample: renew a subscription with its addons

```php
<?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]->RenewalInformation = new stdClass();
    $Order->Items[0]->RenewalInformation->SubscriptionReference = 'MAIN_SUBSCRIPTION_REFERENCE';
    $Order->Items[1] = new stdClass();
    $Order->Items[1]->RenewalInformation = new stdClass();
    $Order->Items[1]->RenewalInformation->SubscriptionReference = 'ADDON_SUBSCRIPTION_REFERENCE_1';
    $Order->Items[2] = new stdClass();
    $Order->Items[2]->RenewalInformation = new stdClass();
    $Order->Items[2]->RenewalInformation->SubscriptionReference = 'ADDON_SUBSCRIPTION_REFERENCE_2';

    $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;
}

```

## Response parameters

<table><thead><tr><th width="190">Parameter</th><th>Type</th></tr></thead><tbody><tr><td><a href="https://docs.2checkout.com/soap-api-reference/soap-api-6.0/api-responses/order-with-catalog-products.md"><code>Order information</code></a></td><td><strong>Object</strong></td></tr></tbody></table>

## Error codes for renewals with addons

| Error code                                    | Description                                                                                                                                                                          |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **ADDON\_SUBSCRIPTION\_NOT\_FOUND**           | Addon subscription \[subscription reference] was not found.                                                                                                                          |
| **ADDON\_SUBSCRIPTION\_NOT\_ACTIVE**          | Addon subscription \[subscription reference] is not active.                                                                                                                          |
| **ADDON\_SUBSCRIPTION\_NOT\_LINKED**          | Addon subscription \[subscription reference] is not linked to a main subscription.                                                                                                   |
| **ADDON\_RENEWAL\_EXCEEDS\_MAIN\_EXPIRATION** | Addon subscription \[subscription reference] cannot be renewed because its expiration date is not before its main subscription's expiration date. Renew the main subscription first. |
| **INVALID\_SUBSCRIPTION\_STATE**              | Addon subscription \[subscription reference] cannot be renewed. A cancellation request has been registered for it.                                                                   |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.2checkout.com/soap-api-reference/soap-api-6.0/api-requests/place-a-renewal-order.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
