Skip to content
Last updated

AddOrder

Adds an order to a client. For more flow control, this method ignores the "Automatically setup the product as soon as an order is placed." option. When you call this method, you must make a subsequent explicit call to AcceptOrder.

Request Parameters

ParameterTypeDescriptionRequired
actionstring"AddOrder"Required
clientidintRequired
paymentmethodstringThe payment method for the order in the system format. eg. paypal, mailinRequired
pidint[]The array of product ids to add the order forOptional
qtyint[]The array of product quantitiesOptional
domainstring[]The array of domain names associated with the products/domainsOptional
billingcyclestring[]The array of billing cycles for the productsOptional
domaintypestring[]For domain registrations, an array of register or transfer valuesOptional
regperiodint[]For domain registrations, the registration periods for the domains in the orderOptional
idnlanguagestring[]For IDN domain registrations. The language code for the domain being registeredOptional
eppcodestring[]For domain transfers. The epp codes for the domains being transferred in the orderOptional
nameserver1stringThe first nameserver to apply to all domains in the orderOptional
nameserver2stringThe second nameserver to apply to all domains in the orderOptional
nameserver3stringThe third nameserver to apply to all domains in the orderOptional
nameserver4stringThe fourth nameserver to apply to all domains in the orderOptional
nameserver5stringThe fifth nameserver to apply to all domains in the orderOptional
customfieldsstring[]an array of base64 encoded serialized array of product custom field valuesOptional
configoptionsstring[]an array of base64 encoded serialized array of product configurable options valuesOptional
priceoverridefloat[]Override the price of the product being orderedOptional
promocodestringThe promotion code to apply to the orderOptional
promooverrideboolShould the promotion apply to the order even without matching promotional productsOptional
affidintThe affiliate id to associate with the orderOptional
noinvoiceboolSet to true to suppress the invoice generating for the whole orderOptional
noinvoiceemailboolSet to true to suppress the Invoice Created email being sent for the orderOptional
noemailboolSet to true to suppress the Order Confirmation email being sentOptional
addonsstring[]A comma separated list of addons to create on order with the productsOptional
addonsqtystring[]A comma-separated list of quantities for addons that are associated with products.Optional
hostnamestring[]The hostname of the server for VPS/Dedicated Server ordersOptional
ns1prefixstring[]The first nameserver prefix for the VPS/Dedicated server. Eg. ns1 in ns1.hostname.comOptional
ns2prefixstring[]The second nameserver prefix for the VPS/Dedicated server. Eg. ns2 in ns2.hostname.comOptional
rootpwstring[]The desired root password for the VPS/Dedicated server.Optional
contactidintThe id of the contact, associated with the client, that should apply to all domains in the orderOptional
dnsmanagementbool[]Add DNS Management to the Domain OrderOptional
domainfieldsstring[]an array of base64 encoded serialized array of TLD Specific Field ValuesOptional
emailforwardingbool[]Add Email Forwarding to the Domain OrderOptional
idprotectionbool[]Add ID Protection to the Domain OrderOptional
domainpriceoverridefloat[]Override the price of the registration price on the domain being orderedOptional
domainrenewoverridefloat[]Override the price of the renewal price on the domain being orderedOptional
domainrenewalsarrayA name -> value array of $domainName -> $renewalPeriod renewals to add an order forOptional
clientipstringThe ip address to associate with the orderOptional
addonidintThe Addon ID for an Addon Only OrderOptional
addonidqtyintThe quantity of addons in an addon-only order.Optional
serviceidintThe service ID for the addon only orderOptional
addonidsint[]An Array of addon ids for an Addon Only OrderOptional
addonidsqtyint[]An array of quantities for an addon-only order.Optional
serviceidsint[]An array of service ids to associate the addons for an Addon Only orderOptional
servicerenewalsint[]An array of service IDs to be on-demand renewedOptional
addonrenewalsint[]An array of service addon IDs to be on-demand renewedOptional

Response Parameters

ParameterTypeDescription
resultstringThe result of the operation: success or error
orderidintThe Order ID for the created order
serviceidsstringThe Service ID(s) created by the order
addonidsstringThe Addon ID(s) created by the order
domainidsstringThe Domain ID(s) created by the order
invoiceidintThe Invoice ID created for the order

Example Request (CURL)

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.example.com/includes/api.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'action' => 'AddOrder',
            // See https://developers.whmcs.com/api/authentication
            'username' => 'IDENTIFIER_OR_ADMIN_USERNAME',
            'password' => 'SECRET_OR_HASHED_PASSWORD',
            'clientid' => '1',
            'pid' => array(1,1),
            'qty' => array(2, 3),
            'domain' => array('domain1.com', 'dómáin2.com'),
            'idnlanguage' => array('', 'fre'),
            'billingcycle' => array('monthly','semiannually'),
            'addons' => array('1,3,9', ''),
            '$addonsqty' => array('2,4,9', ''),
            'customfields' => array(base64_encode(serialize(array("1" => "Google"))), base64_encode(serialize(array("1" => "Google")))),
            'configoptions' => array(base64_encode(serialize(array("1" => 999))), base64_encode(serialize(array("1" => 999)))),
            'domaintype' => array('register', 'register'),
            'regperiod' => array(1, 2),
            'dnsmanagement' => array(0 => false, 1 => true),
            'nameserver1' => 'ns1.demo.com',
            'nameserver2' => 'ns2.demo.com',
            'paymentmethod' => 'mailin',
            'servicerenewals' => array(3, 10),
            'addonrenewals' => array(3, 10),
            'responsetype' => 'json',
        )
    )
);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($ch);
curl_close($ch);

Example Request (Local API)

$command = 'AddOrder';
$postData = array(
    'clientid' => '1',
    'pid' => array(1,1),
    'qty' => array(2, 3),
    'domain' => array('domain1.com', 'dómáin2.com'),
    'idnlanguage' => array('', 'fre'),
    'billingcycle' => array('monthly','semiannually'),
    'addons' => array('1,3,9', ''),
    '$addonsqty' => array('2,4,9', ''),
    'customfields' => array(base64_encode(serialize(array("1" => "Google"))), base64_encode(serialize(array("1" => "Google")))),
    'configoptions' => array(base64_encode(serialize(array("1" => 999))), base64_encode(serialize(array("1" => 999)))),
    'domaintype' => array('register', 'register'),
    'regperiod' => array(1, 2),
    'dnsmanagement' => array(0 => false, 1 => true),
    'nameserver1' => 'ns1.demo.com',
    'nameserver2' => 'ns2.demo.com',
    'paymentmethod' => 'mailin',
    'servicerenewals' => array(3, 10),
    'addonrenewals' => array(3, 10),
);
$adminUsername = 'ADMIN_USERNAME'; // Optional for WHMCS 7.2 and later

$results = localAPI($command, $postData, $adminUsername);
print_r($results);

Example Response JSON

{
    "result": "success",
    "orderid": "1",
    "serviceids": "1,2",
    "addonids": "1,2,3",
    "domainids": "1,2",
    "invoiceid": "1"
}

Error Responses

Possible error condition responses include:

  • Client ID Not Found
  • Unable to add order when client status is Closed
  • Invalid Payment Method. Valid options include
  • Addon ID invalid
  • Service ID not owned by Client ID provided
  • Domain status is set to 'Pending|Cancelled|Pending Transfer|Transferred|Fraud' and cannot be renewed
  • Domain not owned by Client ID provided
  • No items added to cart so order cannot proceed
  • Expecting parameter <request-parameter> to be an array
  • Service ID xxx can not be renewed at this time.

Version History

VersionChangelog
1.0Initial Version
7.8Renamed productids response to serviceids. productids may be removed in a future version.
8.0Added IDN Language parameter
8.6Increase strictness of array/set data type parameters when requesting multiple 'domaintype' operations.
8.8Added servicerenewals parameter
8.9Added addonrenewals parameter
8.12Added qty parameter
8.12Added $addonsqty parameter
8.12Added $addonidqty parameter
8.12Added $addonidsqty parameter