updates RSS feed

Place orders with catalog products

Overview

Use this object to create new orders and collect payments from shoppers using catalog products defined in your Merchant Control Panel.

Supported payment methods

  1. Credit/Debit cards: Visa, Visa Electron, MasterCard, Maestro, Amex, Discover, Dankort, Carte Bancaire, JCB. 2Checkout supports local Brazilian cards.
  2. PayPal and PayPal Express
  3. Purchase Order
  4. Wire
  5. Check
  6. WeChat Pay
  7. iDEAL
  8. TEST orders
  9. Free orders (no payment information required)
  10. One click (1-click) purchases - In addition to the payment methods enumerated above, 2Checkout also supports 1-click purchase flows in which you use valid previous order references belonging to returning customers to pay for new orders with their previously used cards and PayPal accounts.
  11. 2Pay.js

Attributes

 
Parameters Type/Description
Currency Optional (string)
  The currency ISO code for the payment - ISO 4217. Example: “usd.”
Country Optional (string)
  Shopper country. ISO 3166 two-letter code. Example: “us.”
Language Optional (string)
  ISO 639-1 two-letter code. Language used for the purchase process. Example: “en.”
ExternalReference Optional (string)
  Set external reference identifiers for orders. Enables you to replicate the functionality of the REF parameter included in Buy Links. Maximum 100 characters. If there is a need for longer references, you can apply an md5 hash for any string value, resulting in a 32 characters string. You can verify the hash after the order notification, on the client-side.
Source Optional (string)
 

The link source for the sales. Enables you to replicate the functionality of the SRC (separate link identifier) parameter when included into Buy Links. Use the SRC parameter to track sale sources.

 

Maximum length 255 characters.
CustomerReference Optional (Int)
  System-generated 2Checkout customer reference. Aggregate subscriptions under the same Customer account by adding the AV_CUSTOMERID (case sensitive) parameter to buy links. The 2Checkout system generates default customer numerical (integer) IDs (AV_CUSTOMERID) automatically for all orders containing products that feature subscriptions.
MachineId Optional (string)
  Unique, system-generated code for each unique customer, identifying returning customers.
Items Required (array of objects)
  Details below. 
  OrderItem Object
      Details below. 
    Code Required (string)
      Unique product identifier your control. Max length 256 characters.
    Quantity Required (integer)
      Number of units
    PriceOptions Optional (array of strings)
      Array of price option codes.
    SKU Optional (string)
      SKU identifier.
    Price Object - Can be NULL. If Price Type is set to 'CUSTOM', dynamic pricing can be added to the order via the Amount parameter.
    CrossSell Object – Can be NULL
        Details below. 
      ParentCode Optional (string)
        The product code of the master product you set to trigger the campaign.
      CampaignCode Optional (string)
        Unique, system-generated identifier for cross-sell campaigns.
    Trial Optional (Object) – Can be NULL
        Details below. 
      Period Optional (integer)
        The length of the trial subscription lifetime in days.
      Price Optional (double)
        Total trial price in the payment currency before 2Checkout deducts any taxes, discounts, etc.
    AdditionalFields Optional (array of objects) – Can be NULL
      AdditionalFieldSet Optional (Object) – Can be NULL
        Code Optional (string)
          The alpha-numeric characters, underscores and dashes that are set as the field identifier.
        Value Optional (string)
          Selected field value.
    SubscriptionStartDate Optional (string)
     

Specify the date time stamp when the subscription becomes active. Format 2016-07-02 22:22:22 (YYYY-MM-DD HH:mm:ss). Available for JSON-RPC and REST.

Send empty or NULL to activate subscriptions on the same date when customers purchase them.

You can exclude HH:mm:ss when sending the date and include only YYYY-MM-DD. In this case, 2Checkout uses 00:00:01. Default time zone GMT+02:00.
BillingDetails Required (Object)
    Details below. 
  Person Object
    Details below.
    FirstName Required (string)
      Shopper name.
    LastName Required (string)
      Shopper surname.
    CountryCode Optional (string)
      Shopper country. ISO 3166 two-letter code.
    State String/Optional – Required for US, Canada, Brazil, Turkey, India and Romania
      The state in the shopper's country. Mandatory when you set the Billing Country to US, Canada, Brazil, Turkey, India and Romania. Use case insensitive utf8 strings for the full name, or just the two-letter code.
    City Optional (string)
      Shopper city.
    Address1 Optional (string)
      Shopper address.
    Address2 Optional (string)
      Shopper address.
    Zip Optional (string)
      ZIP/ Postal code.
    Email Optional (string)
      Shopper email address.
    Phone Optional (string)
      Shopper phone number. Mandatory when you set Brazil as the Billing Country. Can be NULL.
    Company Optional (string)
      Company name. Can be null for end users. When present, you also need to provide the FiscalCode.
    TaxExemptionId  Optional (string)
      Tax Exempt Certification id used to deduct taxes for US orders
Example: 1b80eecc349v
  FiscalCode Optional (string) – Required for Brazil
   

• For companies, it needs to be the VAT ID. 2Checkout will validate the value provided and throw an error if the VAT ID is invalid/incorrect when calling setPaymentDetails. When present, you also need to provide the Company name.

• Mandatory when you set Brazil as the Billing Country. For Brazilian customers it represents the Fiscal Code (CPF/CNPJ).

• Mandatory when you set India as the Billing Country, and purchase is made by a Company.

• Can be NULL for end users.
DeliveryDetails Required (Object)
                    Details below. 
  Person Object
                    Details below. 
    FirstName Required (string)
                    Shopper name from the delivery details.
    LastName Required (string)
                    Shopper surname from the delivery details.
    CountryCode Optional (string)
                    Shopper country. ISO 3166 two-letter code from the delivery details.
    State String/Optional – Required for US, Canada, Brazil, Turkey, India and Romania
                    The state in the shopper's country. Mandatory when you set the Billing Country to US, Canada, Brazil, Turkey, India and Romania. Use case insensitive utf8 strings for the full name, or just the two-letter code.
    City Optional (string)
                    Shopper city from the delivery details.
    Address1 Optional (string)
                    Shopper address from the delivery details.
    Address2 Optional (string)
                    Shopper address from the delivery details.
    Zip               Optional (string)
                    ZIP/ Postal code from the delivery details.
    Email Optional (string)
      Shopper email address from the delivery details.
    Phone Optional (string)
      Shopper phone number from the delivery details. Mandatory when you set Brazil as the Billing Country. Can be NULL.
    Company Optional (string)
      Company name from the delivery details. Can be null for end users. When present, you also need to provide the FiscalCode.
PaymentDetails Required (Object)
  Adapt this object to the desired payment method.
  Type Required (string)
   

The payment method:

  • CC (credit/debit card - including local Brazilian cards).
  • ENCRYPTED_PAYMENT_DATA (client-side encryption)
  • PAYPAL
  • PAYPAL_EXPRESS
  • DIRECT_EBANKING
  • CCNOPCI(credit/debit card for non-PCI certified merchants).
  • TEST (for test orders).
  • PREVIOUS_ORDER(place new orders using the reference of a previous order).
  • EXISTING_PAYMENT_DATA  (use a card one of your customers already used to purchase from your account).
  • WIRE – the placeOrder response includes Wire payment details.
  • CHECK – the placeOrder response includes Check payment details.
  • WE_CHAT_PAY (for WeChat payments).
  • IDEAL (for iDEAL payments).
  • PURCHASEORDER - use for orders with POs.
  • FREE – for 0 value orders for which you’re not requiring customers to provide payment details.
  • EES_TOKEN_PAYMENT (2Pay.js)

 
  Currency Required (string)
    The currency ISO code for the payment - ISO 4217. Example: “usd.”
  PaymentMethod Optional (object)
   

Object structure and parameters differ according to payment method selected and API method (placing orders (POST) vs. retrieving order data (GET)).

 

NULL for 0 value orders for which you’re not requiring customers to enter payment details.
                                                                    RecurringEnabled Optional (boolean)
 

 

true – shopper checks the auto-renewal checkbox and 2Checkout charges subscription renewals using a recurring billing process.

false – shopper doesn’t check the auto-renewal checkbox.
      CardPayment Optional (object)
          Details below. 
        CardNumber Required (string)
          The credit/debit card number.
        CardType Required (string)
          visa, visaelectron, mastercard, maestro, amex, discover, dankort, cartebleue, jcb, hipercard, elo
        ExpirationYear Required (string)
          The year in which the card expires.
        ExpirationMonth Required (string)
          The month in which the card expires.
        HolderName Required (string)
          Cardholder name.
        CCID Required (string)
          Credit Card Identification - an extra ID printed on the card, usually a 3-4 digit number, the CVC2/CVV2.
        Vendor3DSReturnURL Required (string)
          URL address to which customers are redirected after the 3DS details get validated by the bank and the order is successfully authorized.
        Vendor3DSCancelURL Required (string)
          URL address to which customers are redirected if the 3DS details were not validated or the order could not be authorized.
        HolderNameTime Optional (float)
         

The interval of time in seconds in which shoppers enter their name in the HolderName field. An abnormally short interval is usually a red flag for fraud attempts.

Can be NULL, but not a negative number.
        CardNumberTime Optional (float)
         

The interval of time in seconds in which shopper enter their card number in the CardNumber field. An abnormally short interval is usually a red flag for fraud attempts.

Can be NULL, but not a negative number.
        InstallmentsNumber  Optional (Int)
          Number of installments. Available only when customers un Brazil pay with Visa or MasterCard using Brazilian Real as the order currency. Use 1 or exclude the parameter for full payments. 
      PayPalExpress Optional (object)
          Details below. 
        Email Optional (string)
          Email address customers use for their PayPal account.
        ReturnURL Optional (string)
          The PayPal Express Checkout redirect URL returned by calling the getPayPalExpressCheckoutRedirectURL method. The return URL is the page on your website to which PayPal redirects your buyer's browser after the buyer logs in to PayPal and approves the payment. Typically, this is a secure page (https://...) on your site.
        CancelURL Optional (string)
          The cancel URL is the page on your website to which PayPal redirects your buyer's browser if the buyer does not approve the payment. Typically, this is the secure page (https://...) on your site from which you redirected the buyer to PayPal.
      PreviousOrder Optional (Object)
          Details below. 
        RefNo Optional (string)
         

Order reference a previous purchase that reached the Approved/Complete status. You can use the order for which customers paid with credit/debit cards or with PayPal. The status of the order should be AUTHRECEIVED or COMPLETE.

 

Check the validity of references with the isValidOrderReference method.

 

The 2Checkout system blocks you from using references for fraudulent or potentially fraudulent orders.
      PurchaseOrderPaymentDetails Optional (Object)
          Details below. 
        InternalPONumber Optional (string)
          Identifier that business customers use internally in their organization to track and manage Purchase Orders (PO). Can be NULL.
        AutoApprove Optional (boolean)
         

TRUE - requires activation of the PO AutoApprove package (If the package is inactive 2Checkout returns an error). Please contact 2Checkout. When AutoApprove is TRUE, 2Checkout no longer requires that business customers upload a PO document. As such, PO orders are automatically approved for your account, without a PO doc. 2Checkout sets the PURCHASE_PENDING status for auto-approved PO orders.

FALSE - Default. Send this if the PO AUtoApprove package is not available for your account. 2Checkout uses the same flow as cart purchases with Purchase Orders for business customers placing orders with POs via API. This means that customers receive the same emails as if they made the purchase using the cart and need to update the PO document, which is reviewed by 2Checkout and that you need to approve. 2Checkout sets the AVAITING_UPLOAD status for POs andUnfinished for their orders.

 

Can be NULL.
      WE_CHAT_PAY Optional (string)
        Details below
        ReturnURL Optional (string)
          The return URL is the page to which your customers are redirected after their successful payment.
        CancelURL Optional (string)
          The cancel URL is the page to which your customers are redirected after their failed payment attempt.
      IDEAL Optional (string)
        Details below
        ReturnURL Optional (string)
          The return URL is the page to which your customers are redirected after their successful payment.
        CancelURL Optional (string)
          The cancel URL is the page to which your customers are redirected after their failed payment attempt.
        BankCode Required (string)
          String contains the SWIFT code of the bank, the plus sign "+", and the first 3 characters from the bank name. E.q.: in the case of Rabobank, code parameter is "RABONL2U+RAB".
      EXISTING_PAYMENT_DATA Optional (Object)
        By using EXISTING_PAYMENT_DAT you no longer require shoppers to enter any payment details.
        TransientToken Optional (string)
          Returned as a part of the process of retrieving customer information by SSOToken.
  CustomerIP Optional (string)
    Shopper IP.
Promotions Optional (Array of strings)
  Array of promotion codes.
AdditionalFields  
    Details below. 
  Code Optional (string)
    The alpha-numeric characters, underscores and dashes that are set as the field identifier.
  Text Optional (string)
    Field text visible to shoppers in the cart.
  Value Optional (string)
    Selected field value.
LocalTime Optional (string)
 

Local shopper time in the following format: Y-m-d H:i:s.

This parameter can impact the fraud score of an order when it's missing, NULL or incorrectly formatted.
GiftDetails Optional (object)
  Contains contact details for the recipient of a gift purchase.
  FirstName Optional (string)
    First name of gift recipient.
  LastName Optional (string)
    Last name of gift recipient.
  Email Optional (string)
    Email of gift recipient. 2Checkout uses this email for the delivery/fulfillment process.
  GiftNote Optional (string)
    Custom text shoppers provide as a message to the gift recipient.

 

Update product group

Overview

Use the updateProductGroup method to create a new product group for your account.

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.

ProductGroup

Required (object)

 

Use this object to update product groups.

Response

bool(true)

Request

<?php

require ('PATH_TO_AUTH');

$ProductGroup = new stdClass();
$ProductGroup->Name = 'New Product Group from API';
$ProductGroup->Code = 'DBA13A4268';
$ProductGroup->TemplateName = 'Default Template'; // the name of the cart template you want to associate with the product group
$ProductGroup->Description = 'This is a generic description';
$ProductGroup->Enabled = false;

try {
    $UpdatedProductGroup = $client->updateProductGroup($sessionID, $ProductGroup);
}

catch (SoapFault $e) {
    echo "UpdatedProductGroup: " . $e->getMessage();
    exit;
}

var_dump("UpdatedProductGroup", $UpdatedProductGroup);


?>

Update promotion coupon

Overview

Use the updatePromotionCoupon method to add single or multiple coupons to a promotion.

Updating a promotion with multiple coupons causes any existing single coupon to be removed.

Parameters

Parameter Type/Description

sessionID

Required (string)

 

Output of the Login method.

promotionCode

Required (string)

 

The code corresponding to the promotion that you want to update.

promotionCoupon

Required (object)

 

type

Required (string)

 

 

Coupon type. Available values:

  • SINGLE, use in conjunction with Code
  • MULTIPLE, use in conjunction with Codes

 

Code/Codes

Required (string / array of strings)

 

 

Coupon code (for SINGLE) or array of coupon codes (for MULTIPLE).

Response

Parameter Type/Description
promotionCoupon Object

Request

<?php

function callRPC($Request, $host, $Debug = true) {
    $curl = curl_init($host);
    curl_setopt($curl, CURLOPT_POST, 1);
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($curl, CURLOPT_VERBOSE, true);
    curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
    curl_setopt($curl, CURLOPT_SSLVERSION, 0);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Accept: application/json'));
    $RequestString = json_encode($Request);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $RequestString);
    if ($Debug) {
        $RequestString;
    }
    $ResponseString = curl_exec($curl);
    if ($Debug) {
        $ResponseString;
    }
    if (!empty($ResponseString)) {
        var_dump($ResponseString);
        $Response = json_decode($ResponseString);
        if (isset($Response->result)) {
            return $Response->result;
        }
        if (!is_null($Response->error)) {
            var_dump($Request->method, $Response->error);
        }
    } else {
        return null;
    }
}

$host = 'https://api.avangate.com/rpc/3.1/';

$merchantCode = "YOUR_MERCHANT_CODE"; // your account's merchant code available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$key = "YOUR_SECRET_KEY"; // your account's secret key available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php

$string = strlen($merchantCode) . $merchantCode . strlen(gmdate('Y-m-d H:i:s')) . gmdate('Y-m-d H:i:s');
$hash = hash_hmac('md5', $string, $key);

$i = 1;

$jsonRpcRequest = new stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method = 'login';
$jsonRpcRequest->params = array($merchantCode, gmdate('Y-m-d H:i:s'), $hash);
$jsonRpcRequest->id = $i++;

$sessionID = callRPC($jsonRpcRequest, $host);

// Promotion code corresponding to the promotion you want to add coupons to
$promotionCode = '';

// Define single coupon object
$promotionCoupon = new stdClass;
$promotionCoupon->Type = 'SINGLE';
$promotionCoupon->Code = 'YOUR_CODE_HERE';

// Define multiple coupon object
$promotionCoupon = new stdClass;
$promotionCoupon->Type = 'MULTIPLE';
$promotionCoupon->Codes = ['YOUR_CODE_1', 'YOUR_CODE_2'];

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

Automatic channel renewals (Direct Renewal)

Overview

Automatic Channel Renewals (Direct Renewal) enables customers who have purchased products from your partners to renew their subscriptions directly through 2Checkout or via your website. Partners will be credited for the initial subscription renewal and subsequent renewals, receiving commissions based on the Direct Renewal margins you control.

Requirements

Direct Renewal has two prerequisites.

  1. Your partners accept enrolment into the program.
  2. Partner-sold subscriptions have end-user information attached.

Availability

Channel Manager: You need to have the Channel Manager module activated. Contact 2Checkout directly if you would like to start taking advantage of the platform in your relationship with customers.

How does Direct Renewal work?

  1. Shoppers purchase your products from a company you partnered with.
  2. You enable Direct Renewal for partners and set Direct Renewal margins, specifying the margins you'll pay for the renewals made directly by end-users on your website or via 2Checkout.
  3. Partners accept the Direct Renewal program, add end-user information to subscriptions/licenses they sold, and configure a payment option used to pay their margins.
  4. 2Checkout will send Manual Renewal notifications to shoppers ahead of the expiration deadline of their subscriptions/licenses (according to the settings you used to configure email notifications for renewals on e-commerce). When contacting end-users directly based on the info attached, 2Checkout will prompt them to renew. If the renewal is successful, the partner will be credited based on the Direct Renewal margins. The email is sent in the shopper's language if the partner has also specified the communication language when inserting end-user data.
  5. When end users click the renewal link provided via email, they are redirected to your shopping cart, prefilled with their customer data and geo-localized according to their browser language.
    • If customers leave the shopping cart ahead of placing the order, their subscriptions will not be renewed directly and partners will be able to renew them themselves.
    • If customers place the renewal order but the payment fails or the order fails to reach the complete status, the subscription is transferred to eStore, just as if the item had been sold directly by you, and 2Checkout will start attempts to recover it per the unfinished payment settings in the leads management area of the Control Panel. Partners will no longer be able to renew these items themselves.
  6. When customers place renewal orders, they also get the option of enabling auto-renewal going forward.
  7. At the same time, end-users have the option of contacting you directly via your website and renew.
  8. After the renewal orders are placed, users receive all the notifications and support as if they would have purchased the product directly from you - including access to Customer portal - myAccount area for self-service (optional). Their subscriptions also behave the same as if they were acquired directly from you.
  9. 2Checkout tracks the source of the subscription/license renewal, and if the initial orders have been referred to by your partners, will credit the sale to their account and pay the margins per the Direct Renewal margins you configured.

Subscriptions continue to be renewed automatically by 2Checkout each billing cycle, or manually by customers after the initial direct renewal. Partners can no longer renew such subscriptions themselves or edit end-user information. However, they will continue to receive margins for each purchase throughout the duration of their partnership with you.

How to enable Direct Renewal?

You can enable Direct Renewal in two ways:

  1. Per partner
  2. Per partnership program

Enable Direct Renewal for a partner

  1. Go to Partner management -> Partners.
  2. Edit or create the partner for which you'll enable the Direct Renewal program and click to edit its details.
  3. Click on the Commercial Settings tab and scroll down to the Other settings area. Make sure that the Create individual settings option is selected under Partnership details.
  4. Check the checkbox next to the Enable Direct Renewal option.
  5. Scroll further down and in the Partner margin area, specify the Direct Renewal margins (the commission for renewals performed directly by 2Checkout or tracked via your website which were initially referred by partners).
    • You can set general margins, that will apply to all partner orders.
    • You also have the option of setting margins per product and groups of products.

When Direct Renewal is enabled it impacts all subscriptions referred by your partners. Leaving the Direct Renewal margins field empty or not defining margins for specific products or groups of products will result in zero partner margins for subscription renewed by customers directly via 2Checkout or through your website.

Click Save changes to make sure that the Direct Renewal is activated for this partner.

Note: Direct Renewal is an opt-in program, which means that once activated by you, partners need to accept enrollment.

Enable Direct Renewal for a partnership program

  1. Go to Partner management -> Partnership programs. 
  2. Identify or create the partnership program for which you'll enable the Direct Renewal program and click to edit its details.
  3. Click the Commercial Settings tab and scroll down to the Other settings area.
  4. Check the checkbox next to the Enable Direct Renewal option.
  5. Scroll further down and in the Partner margin area, specify the Direct Renewal margins (the commission for renewals performed directly by 2Checkout or tracked via your website which were initially referred by partners).
    • You can set general margins, that will apply to all partner orders.
    • You also have the option of setting margins per product and groups of products.

When Direct Renewal is enabled it impacts all subscriptions referred by your partners. Leaving the Direct Renewal margins field empty or not defining margins for specific products or groups of products will result in zero partner margins for subscription renewed by customers directly via 2Checkout or through your website.

Click Save changes to make sure that the Direct Renewal is activated for this partner.

Note: Direct Renewal is an opt-in program, which means that once activated by you, partners need to accept enrolment.

Partners are automatically notified via email when Direct Renewal is enabled for their accounts

The 2Checkout system is designed to provide automatic notifications to partners when you enable Direct Renewal for their accounts. Emails are sent:

  • To specific partners when Direct Renewal is activated for their standalone accounts.
  • To partners part of a partnership program when Direct Renewal is enabled for the entire program.
  • To partners, part of a partnership program when you swap their current program with Direct Renewal disabled for a new one with Direct Renewal enabled.

Email notifications are sent in bulk at specific intervals.

Disable Direct Renewal

To disable Direct Renewal for a partner or a partnership program, follow steps 1 through 3 mentioned above in each case, and uncheck the checkbox next to the Enable Direct Renewal option. Click Save changes for the modification to be applied.

F.A.Q.

  1. What happens when the direct renewal program is disabled?
    • End users that haven't done so already, will no longer be able to renew their subscriptions directly via your website or through 2Checkout, but only through the partner which referred the initial purchase. 2Checkout will continue to control the renewal process for all subscriptions already renewed directly and partners will no longer receive margins for future transactions.
  2. Where can I see subscriptions renewed directly by end-users as a result of the Direct Renewal program?
  3. Where can I see orders for subscriptions renewed directly by end-users?
    • Go to Orders and customers -> Order search and make sure the eStore tab is selected.
  4. What are the possible Direct Renewal statuses?
    • Pending: Waiting for partner enrollment.
    • Active: Partner for which Direct Renewal was enabled.
    • Inactive: Partners for which Direct Renewal is not enabled.
    • Denied: Partners that rejected enrollment.
  5. As a partner, do I lose control over subscription/license renewals if I accept enrollment into the Direct Renewal program?
    • By taking advantage of Direct Renewal you offer end-users the option to renew their subscriptions/licenses themselves, for those items that you don't want to renew yourself. While you will be able to access information on subscriptions/licenses renewed directly, as well as receive margins for each renewal, you will no longer be able to renew the subscription/license yourself or edit end-user information.

Tiered charges

Overview

Use tiered/scale pricing to create variable cost tiers (scales/intervals) impacting product unit price and provide cost benefits and incentives to shoppers to purchase large volumes. Tiered (scale) pricing configurations enable you to change the per-unit cost gradually for multiple tiers defined based on the quantities purchased.

Example of a product with a flat charge of $100:

Quantity interval Cost per unit
1 to 3 $100
3 to 6 $90
7 to 10 $80

For this example, a shopper purchasing 6 units would pay 90*6= $540 on top of the $100 flat charge, or $640 in total.

Availability

Requirements

Set up tiered (scale) charges

To add a usage component to a subscription you need to create a new pricing options group for metered resources. 

  1. Navigate to Products under Setup, search for or add/import the product you want to set usage pricing, and click to edit it.
  2. Select the Pricing tab and click to Edit the Pricing configuration that will be used to define usage costs.
  3. On the editing screen of the pricing configuration, scroll down to the bottom and click on Create new pricing options group in the Pricing options groups area.
  4. Enter the Group name (Required) - this label is displayed to shoppers in the cart and is included on invoices. 
  5. Enter the Group description (Optional) - This text is displayed to shoppers in the cart and is included on invoices. 
  6. Select the type: Scale - Regular - for a tiered charge.
  7. Enter a unique alphanumeric/string code (Required) - this is an identifier used in the 2Checkout API, product import/export, and for Buy Links query parameters.
  8. Add the first scale.
  9. Specify the interval.
  10. Define impact on price per unit of tiered/metered resources (available only for products with dynamic pricing (with base price) configurations).
  11. Add - add a specific cost for each unit of tiered/metered resource in each available currency for your account. 
  12. Subtract - subtract a specific price for each unit of tiered/metered resource.
  13. Define impact on subscription lifecycle
  14. Adds - Add the desired number of months to the default billing cycle interval of a subscription. Adding one month to a monthly subscription purchased on April 22nd pushes the expiration/renewal deadline to June 22nd. 
  15. Subtracts - Subtract the desired number of months to the default billing cycle interval of a subscription. Subtracting 12 months from a 2-year subscription purchased on April 22nd, 2016, pushed the expiration/renewal deadline to April 22nd, 2017 instead of April 22nd, 2018. 
  16. Non-recurring - Increase the lifetime of a subscription indefinitely at the moment of purchase, making it evergreen. 
  17. When you're done defining the scale usage intervals click Save group. Localization: To localize the usage pricing options group to another market, select the desired language from the list of options available for your account, and repeat the steps described above.
  18. The newly created pricing options group is available on the pricing configuration edit page. Scroll down to the bottom of the screen to identify it by the unique name you assigned to it in the Available pricing options groups area and click the Use with this product link.
  19. Hit Save to associate the usage pricing options group with the pricing configuration you're editing.

Multiple scales

Take advantage of multiple variable pricing scales/intervals for the same product. When defining the price for your offerings, you'll be able to create multiple scale pricing options groups and associate them to the same product. Once assigned to a product, the scaled pricing options group contribute to generating the price of purchases, per the offering's configuration, in accordance with the options selected by the shopper.

  1. Products With a base price configuration can feature as many scale pricing options groups as you wish. However, only the use of a single usage pricing options group is supported at this point in time.
  2. Products Without a base price configuration can feature only a single scale pricing options group and do not support the use of usage pricing options groups.

 

 

Product With a base price

Product Without a base price

Number of scale pricing options

Unlimited

1

Number of usage scale pricing options

1

Not available

 

 

Multiple scales use cases

2Checkout's multiple scale capabilities can be used to create complex pricing schemas designed to control the costs paid by customers through the use of a multi-tiered charge model.

1. In the example below, a customer purchasing a single subscription for 15 seats and including 200 support calls will pay $150 + $800 on top of the offering's default price.

Product/Service

Pricing

Scale intervals

Impact on price per unit

Number of seats

1 to 10

Do nothing

11 to 50

Add $10 per unit

51 to 100

Add $8 per unit

Support calls

1 to 100

Add $5 per unit

101 to 500

Add $4 per unit

500 to 2000

Add $3 per unit

 

2. In the example below, a customer purchasing a subscription for 5 users, with a total of 200GB of storage, allowing the synching of 15 devices, will pay $450 + $1.600 + $3.450.

 

Product/Service

Pricing

Scale intervals

Impact on price per unit

Number of users

1 to 3

Add $100 per unit

4 to 10

Add $90 per unit

11 to 20

Add $80 per unit

GBs of storage used

1 to 25

Do nothing

26 to 50

Add $10 per unit

51 to 100

Add $9 per unit

101 to 500

Add $8 per unit

No. of synchronized devices

1 to 12

Add $250 per unit

13 to 29

Add $230 per unit

30 to 50

Add $200 per unit

Scale Pricing vs. Volume discounts



Unlike Volume discounts, focused exclusively on decreasing the cost per unit as the number of items added to cart increases, Scale Pricing involves multiple parameters unrelated to the actual volume of products your customers orders. Use Volume discounts to lower the price per unit for orders containing large quantities of your product.

Leverage scale pricing options to also reduce the price per unit, but in relation to variables beyond quantity, such as the number of seats/users/PCs for a single product subscription.

The two pricing options share the same core concept, namely the more customers buy the less they pay per unit, but control completely different factors, and can in fact be used in concert for the same order.

Scale pricing option parameters in Buy Links

Let's assume that you created a Users scale pricing options group with the unique code: users, and two options: 1 to 10 ($99 per user) and 11 to 50 ($88 per user).

If you want to build the Buy Link for a product using the Users scale pricing options group and charge customers for 35 users, the parameter should be formatted as such: OPTIONS=users=35, including both the unique code of the pricing options group and the specific value of the scale pricing interval.

FAQ

Can I modify scale pricing options?

All pricing scales you created are available in the Pricing options groups area under the Pricing tab for all of your products.

You can always select the Group name / label in order to access an overview of the options, and click on edit to alter the values as needed. Always make sure to save the group once you introduced modifications.

 

Can the same pricing scale be applied to different products?

Yes. But please keep in mind that the settings for a pricing scale are global, so if you edit them for one product, they will be automatically impact all others that they're associated with.

 

Can I delete a pricing scale?

No. Existing pricing group options, including scale intervals, can only be deactivated per product, and will no longer impact the price of that specific item.

Consider overhauling unused, irrelevant or obsolete pricing group options by changing all parameters including Group name, Group description, and options type, in order to obtain completely new options. Reusing older pricing options groups is as easy as editing them, and this recycling process ensures that the Pricing options groups area never gets too crowded.

 

What happens when a customer chooses a Scale interval I haven't defined?

Only the pricing intervals that you configure will be available to your customers. They won't be able to select a scale interval that has not been configured for a specific product.

 

What's the difference between Scale Pricing and Volume Discounts? 

Volume discounts are financial incentives you can offer customers that acquire large quantities of your products (multiple units). Buyers are incentivized to buy more through price discounts that increase proportionally with the volume of their order.



Scale pricing enable you to offer your customers the possibility of correlating financial incentives with product utilization, by associating the subscriptions they purchase with large numbers of users, seats, PCs, etc. The pecuniary rewards available with scale pricing extend beyond buying in bulk, to shoppers acquiring a single subscription for use by a large volume of users, or for multiple seats/PCs, etc., for example.

 

Why should I use Scale pricing and not Volume discounts?

It really depends on the customer needs you're trying to meet. With Volume discounts you can offer, let say, 20 subscriptions at a slashed price. With Scale pricing you allow them to buy a single subscriptions but for 20 users/seats. But also 20 subscriptions, each for 20 users. It's really up to you what pricing configuration to use, 2Checkout just makes sure you have more options in this regard than any other platform on the market.

LCN Parameters

Overview

You can configure and set the LCN triggers and parameters right from your Merchant Control Panel so that you choose when to be notified about license changes and updates.

Configure LCN triggers and message

Navigate to LCN settings from your Merchant Control Panel, Dashboard → Integrations → Webhooks and API. Select the events for which 2Checkout sends notifications from the list of options available in the General LCN Settings section, under Triggers.

LCN Parameters

Depending on your LCN settings, the notifications contain all or a subset of the available parameters. 2Checkout continuously adds new LCN parameters. To include additional information in the notifications, enable new parameters on the LCN settings page in the Merchant Control Panel.

Parameter Description Type/Length
FIRST_NAME Customer first name String/40
LAST_NAME Customer last name String/40
COMPANY Company name String/40
EMAIL Customer email address String/40
PHONE Phone number String/40
FAX Fax number String/40
COUNTRY Country String/50
STATE State/County String/30
CITY City String/30
ZIP Zip code String/20
ADDRESS Customer address String/100
LICENSE_CODE System-generated, unique identifier for the subscriptions String/50
EXPIRATION_DATE The date when the subscription expires. For lifetime subscriptions, the value is: 9999-12-31 23:59:59. String/20
DATE_UPDATED The date when the 2Checkout system logs an update for a subscription String/20
AVANGATE_CUSTOMER_REFERENCE Default customer numerical (integer) IDs generated automatically by the 2Checkout system. String/10
EXTERNAL_CUSTOMER_REFERENCE Unique customer alphanumeric (string) identifiers that you control String/250
TEST

Possible values:

  • 1 for test subscriptions
  • 0 for 'real' subscriptions
 String/1
CHANGED_BY

Reveals the author of subscription modifications. Possible values:

  • CUSTOMER
  • VENDOR
  • SYSTEM
 String/8
LICENSE_TYPE

Possible values:

  • REGULAR
  • TRIAL
 String/7
DISABLED

Subscription status.

  • 1 for Disabled
  • 0 for Enabled
 String/1
RECURRING

The renewal license type

  • 1 for recurring billing
  • 0 for renewal that requires manual input from the customer
 String/1
LICENSE_PRODUCT Product ID String/7
START_DATE Date when you schedule the subscription to start String/20
PURCHASE_DATE The initial date when a subscriber acquired the subscription String/20
LICENSE_LIFETIME

This parameter indicates whether the subscription is evergreen (lifetime)

  • 1 - lifetime
  • 0 - for subscriptions with a recurring billing cycle
 String/1
BILLING_CYCLES

This parameter indicates the current, total number of billing cycles for a subscription since its creation/import, reflecting the number of renewals, but counting from the first payment made, equivalent with the initial billing cycle. For imported subscriptions, the first billing cycle starts immediately after import.

The default value is 1, for the initial billing. A subscription renewed once enters the second billing cycle, and the value of the parameter changes to 2. Similarly, the value increases to 3 for the third billing cycle, 4 for the fourth, and so on. It is the correspondent of the BILLING_CYCLES option in the LCN configuration page. Available only for subscriptions for which you configure a contract.

 String/2
CONTRACT_CYCLES This parameter indicates the current subscription contract cycle. The default value is 1. For example, for a 12-month contract, the value of the CONTRACT_CYCLES is 1 for the first 12 months, 2 for the next 12 months after the contract is restarted, 3 for the following year, etc. String/2
BILLING_CYCLES_LEFT The number of billing cycles remaining until the contract restarts. 2Checkout counts down from the moment a subscription goes live. For example, the BILLING_CYCLES_LEFT value for a monthly subscription with a 12-month contract will be 11 the first month, 10 the second month, 9 the third, then 8, 7, 6, 5, 4, 3, 2, 1, and 0, before the contract restarts. String/2
CURRENT_BILLING_CYCLE This parameter indicates the current, total number of billing cycles of a subscription out of the duration of the current contract. For example, the CURRENT_BILLING_CYCLE value for a monthly subscription with a 12-month contract is 1 for the first month, 2 for the second month, and so forth until the twelfth billing cycle when the value reaches 12. Following the restart of the contract, the CURRENT_BILLING_CYCLE value is also restarted, starting with 1 for the first month of the new contract, 2 for the second, etc. String/2
NEXT_RENEWAL_PRICE Renewal price for the next billing cycle Int
NEXT_RENEWAL_CURRENCY Renewal currency for the next billing cycle String / 3
NEXT_RENEWAL_PRICE_TYPE GROSS/NET values depending on whether the price includes taxes String / 5
NEXT_RENEWAL_DATE Date of the next subscription renewal  
PARTNER_CODE

Possible values:

  • Empty - eCommerce order
  • Partner code
 String/250
PSKU Product SKU (stock keeping unit) String/250
ACTIVATION_CODE Sends out the last used activation code String/250
STATUS

The status of the subscription. Possible values:

  • PENDING_ACTIVATION (subscription with delayed start date)
  • ACTIVE (for licenses/subscriptions still in use)
  • CANCELED (for canceled licenses/subscriptions)
  • EXPIRED (for expired licenses/subscriptions)
  • PASTDUE (for licenses/subscriptions in the grace period)
  • PAUSED (for licenses/subscriptions that were paused) 
 String/18
EXPIRED
  • 1 - subscriptions/licenses expired. 
  • 0 - active subscriptions/licenses suffered modifications.
 String/1
TIMEZONE_OFFSET The time zone you selected or the default GMT+2 time zone of the 2Checkout system String/9
LICENSE_GRACE_PERIOD The grace period impacting a subscription. Can have a numeric value (INT) representing the number of days sent as the grace period. Int/2
LICENSE_BILLING_TYPE

Designed to differentiate subscriptions leveraging usage pricing options groups from those without a metered cost component.

• PREPAID - subscription cost governed only by pricing options groups of the following type: Radio, Dropdown, Checkbox, and Scale (but without a metered cost component (usage scale pricing)).

• POSTPAID - subscription cost includes a metered cost component (usage scale pricing).

 String/8
USAGE_BILLING_DATE

The date resulting from adding the Usage Billing Interval defined to the expiration deadline of the subscription.

For subscriptions with the automatic renewal system enabled and for which you uploaded usage data, the USAGE_BILLING_DATE represents the moment when 2Checkout attempts to automatically renew the subscription and charge the customer.

 String/20
USAGE_STATUS

The status of usage data upload and processing.

  • UNREPORTED
  • REPORTED
  • PAID
 String/10
LATEST_REPORTED_USAGE_DATE The most recent date when you uploaded usage data into the 2Checkout system for a subscription, preceding the renewal order before subscribers pay for the metered resources consumed. 2Checkout resets the counter after it renews the subscription. String/20
ACTION_AFTER_CYCLES

Indicates the action performed at the end of the subscription contract. Possible actions: subscription automatic renewal or expiration.

Possible values:

  • CANCEL
  • RESTART
  • NONE
 String/7
HASH

Calculated HMAC_MD5 signature based on the sent LCN fields and the secret key

(Note: This parameter won't be used anymore for LCN validation as of 15th of August, 2024.)

 String/32
SIGNATURE_SHA2_256 Calculated HMAC_SHA2_256 signature based on the sent LCN fields and the secret key String/64
SIGNATURE_SHA3_256 Calculated HMAC_SHA3_256 signature based on the sent LCN fields and the secret key String/64
COUNTRY_CODE Customer country code from the billing details String/2
END_USER_LANGUAGE The language used by the customer for placing the order String/2
DISPATCH_REASON

The reason why LCN was dispatched. Value depends on the change made on the license.

Possible values:

  • LICENCE_CHANGE - Licence change
  • LICENCE_EXPIRATION - Licence expiration
  •  LICENCE_PASTDUE - Licence past due 
  • LICENCE_CC_CHANGE - Licence payment method changes
  • LICENCE_IMPORTED - Licences changed via import
  • LICENCE_CPC_ACCEPTED-  Licences when a Churn Prevention Campaign was accepted
  • SCHEDULED_FOR_CANCELATION_ON_DEMAND - Scheduled cancellation event has been registered 
  •  REVERT_CANCELATION_ON_DEMAND - Scheduled cancellation event has been reverted
  • CANCELATION_ON_DEMAND - Scheduled cancellation actually has taken place
  • LICENCE_PENDING_ACTIVATION - Licence pending activation
  • LICENCE_GP_CHANGE - Licence grace period change
 String/27
NEXT_RENEWAL_PAYMETHOD The payment method used in the upcoming renewal String/20
NEXT_RENEWAL_PAYMETHOD_CODE Code of the payment method String/15
NEXT_RENEWAL_CARD_LAST_DIGITS Last four digits of the debit/credit card used by the shopper String/4
NEXT_RENEWAL_CARD_TYPE Card type used by the customer String/12
NEXT_RENEWAL_CARD_EXPIRATION_DATE The expiration date of the card used by the customer String/6
ORIGINAL_ORDER_REFERENCE Reference of the order that generated the subscription String/8
LAST_ORDER_REFERENCE Reference of the last order generated on the subscription, such as a renewal or an upgrade String/8
LICENSE_PRODUCT_CODE The product identifier you create or a system-generated code that you control String
LCN_LICENSE_ADDITIONAL_INFO_CUSTOM_TEXT Name of the subscription additional information field String
LCN_LICENSE_ADDITIONAL_INFO_CUSTOM_VALUE Value of the subscription additional information field String/100
EXPIRATION_DATE_TIME   The date and time when a license/subscription expires. For lifetime licenses/subscriptions, the value will always be 9999-12-31 23:59:59. Date
START_DATE_TIME   The license/subscription start date and time Date
PURCHASE_DATE_TIME   The initial date and time when the license/subscription was purchased Date
RENEWALS_NUMBER   The number of renewals Int
UPGRADES_NUMBER   The number of upgrades Int
IS_TRIAL  

Possible values: 

  • 1 - for trial subscriptions
  • 0 - for regular subscriptions
 Int/1
PAUSE_START_DATE Date when the subscription pause is scheduled to start or has started Date
PAUSE_END_DATE Date when the subscription pause will end and the next billing cycle starts Date
PAUSE_REASON The reason why the pause was set up, as specified by the merchant or shopper Date
PRODUCT_QUANTITY The number of units on the subscription Number
VENDOR_CODE Unique merchant identifier generated by the 2Checkout system String
MESSAGE_ID The sequence ID number of the sent message Integer
LCN_LICENSE_OPTIONS_TEXT

Array with the names of all the price options used on the product generating the license

For usage scale pricing option groups, 2Checkout returns the name of the pricing options as well as the number of units of metered resources consumed by the customer. Format: 'PricingOptionsGroupName: NumberOfUnitsConsumed', for example 'GBs: 100'.

 Array of strings/250
LCN_LICENSE_OPTIONS_VALUE

Array with unique codes set up for the active pricing option groups of the product generating the license.

In the case of usage scale pricing options groups, 2Checkout returns both the unique code of the group as well as the number of units of metered resources consumed by the customer. Format: 'UniqueCode: NumberOfUnitsConsumed', for example 'metered GBs: 100'.

 Array of strings/250
LCN_LICENSE_OPTIONS_PRICE Array with all prices corresponding to each active option (prices are in the order currency of the product generating the license). In the case of usage scale pricing options groups, it will return the price of the metered resources consumed by the customer in the order currency. Array of float numbers
LCN_LICENSE_OPTIONS_OPERATOR

Array with all price operators corresponding to each active price option, of the product generating the license.

Possible values:

• ADD

• SUBTRACT

 Array of strings/9
LCN_LICENSE_OPTIONS_USAGE

Designed to differentiate usage pricing options groups from non-usage pricing options groups.

Possible values:

• PREPAID - for orders involving products with pricing options groups of the following type: Radio, Dropdown, Checkbox, and Scale (but without a metered cost component (usage scale pricing)). 
• POSTPAID - for orders involving products with a metered cost component (usage scale pricing).

 String/8
LCN_LICENSE_OPTIONS_OPTIONAL_VALUE Array with optional codes (unique for pricing option group). In the case of usage scale pricing options groups, 2Checkout returns both the unique code of the group as well as the number of units of metered resources consumed by the customer. Format: 'UniqueCode: NumberOfUnitsConsumed', for example 'metered GBs: 100'. Array of strings/250
LCN_LICENSE_OPTIONS_IMPACT_SUBSCRIPTION

Array with operators showing the impact of the active pricing option on the subscription.

Possible values:

  • ADD
  • SUBTRACT
  • NONE
  • RECURRING
 Array of strings/9
LCN_LICENSE_OPTIONS_IMPACT_SUBSCRIPTION_VALUE

Array with the values (number of months) which are the impact of the active pricing options.

When LCN_LICENSE_OPTIONS_IMPACT_SUBSCRIPTION returns “NONE” or “RECURRING”, LCN_LICENSE_OPTIONS_IMPACT_SUBSCRIPTION_VALUE will return 0.

 Array of integer numbers
LCN_PRODUCT_GROUP_ID Group ID of the product generating the license String
LCN_PRODUCT_GROUP_NAME Group Name of the product generating the license String
PRODUCT_EXTERNAL_REFERENCE The external reference used to match the product with identifiers in your own system String
PRODUCT_VERSION_MODEL The version or model of the product String
CLIENT_DEAL_AUTO_RENEWAL Client option to automatically renew a deal contract at its expiration date String
MERCHANT_DEAL_AUTO_RENEWAL Merchant option to automatically renew a deal contract at its expiration date String
LAST_CHURN_REASONS The reason(s) provided by the shopper for disabling a subscription or cancelling the auto-renewal  String/20
LAST_CHURN_SOURCE The flow through which the subscription was disabled or the auto-renewal was cancelled String/10
LAST_CHURN_DATE The date when the subscription was disabled or the auto-renewal was cancelled String/255
CANCEL_ON_DEMAND_DATE   Latest churn cancel on demand date. String
CHURN_PREVENTION_CAMPAIGN_TYPE The type of the churn prevention campaign whose discount has been accepted by the shopper. String
CHURN_PREVENTION_CAMPAIGN_NAME The type of the churn prevention campaign whose discount has been accepted by the shopper. String
CHURN_PREVENTION_CAMPAIGN_DISCOUNT The value of the discount accepted via the churn prevention campaign/auto-renewal enrolment based on which the next renewal price is calculated. String

Volume discounts

Overview

Use Volume discounts to incentivize shoppers to purchase your products in large quantities/number of units. Set a different price per unit based on the total purchased quantity.

Volume discounts impact the unit price applied by the platform for Channel Manager and resellers if you (vendor) use the products in both channels.

 

Example:

Quantity interval Cost per unit
1 to 100 $59
101 to 500 $49
501  and more $39

For this example, a shopper purchasing 55 units would pay 55*59= $3,245. Another, purchasing a quantity of 600 would pay 600*39= $23,400.

Availability

All 2Checkout accounts.

Requirements

Create at least a product/subscription plan before defining pricing. 

Type 

  • Net: without taxes - 2Checkout applies extra taxes to the default price, such as Tax/VAT for US/EU orders during the ordering process. 
  • Gross: with taxes included - 2Checkout takes the taxes out of the costs paid by shoppers, without modifying the price during the ordering process. 

Currency 

When defining product prices you can:

  1. Configure the price only for the default currency - 2Checkout converts amounts in the cart based on the currency selected by/for shoppers. Currency rates are available here: https://secure.2checkout.com/content/...p?CURRENCY=USD. 

    This is an XML schema with the corresponding values for the other currencies compared to the one supplied in the CURRENCY query parameter.

  2. Specify prices in all currencies available for your account - 2Checkout serves shoppers the prices for all the currencies you set up without converting the amounts. 

Setup

Set volume discounts under the Pricing tab when editing or first configuring products. 

  • Products with dynamic pricing (with base price):
    1. Define your first quantity interval and click save. The initial discounted price per unit is the same as the default price; changes as needed for at least the default currency or for all currencies available for your account.
    2. Click the Add new volume discount link, define the interval, the discounted price per unit, and click Add interval.
    3. Repeat as needed. 
  • Static pricing (without base price)
    1. ​Create as many unit intervals for purchase volume discounts as you need and save the configuration. 
    2. Define prices for each possible option available to your shoppers in the Prices area. 

Limitations

Volumes not defined are not available for purchase to your shoppers. For example, if you define two intervals, 1 to 100 and 102 to 1,000, your shoppers will not be able to purchase 101 units or 1,200 units. 

 

Create product group

Overview

Use the addProductGroup method to create product groups for your account:

  • Send null for product group Code. 2Checkout ignores any values you send for Code and generates identifiers itself. 
  • Use unique product group names. 
  • 2Checkout throws an exception if you send a blank product group.
  • If you send only the name of the product group 2Checkout creates the new product group 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.

ProductGroup

Required (object)

 

Use this object to create product groups. Send null for the Code. 2Checkout generates unique product group code identifiers. 

Response

bool(true)

Request

<?php

require ('PATH_TO_AUTH');

$ProductGroup = new stdClass();
$ProductGroup->Name = 'New Product Group from API';
$ProductGroup->Code = null;//Send null for the Code. 2Checkout generates unique product group code identifiers.
$ProductGroup->TemplateName = 'Default Template';//'001 - Two Column Billing'; //the name of the cart template you want to associate with the product group
$ProductGroup->Description = 'This is a generic description';
$ProductGroup->Enabled = true;

try {
    $NewProductGroup = $client->addProductGroup($sessionID, $ProductGroup);
}

catch (SoapFault $e) {
    echo "NewProductGroup: " . $e->getMessage();
    exit;
}

var_dump("NewProductGroup", $NewProductGroup);


?>

Order with catalog products

Overview

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

Place orders with catalog product

Retrieve an order

Catalog order object

Parameters Type/Description
RefNo String
 

2Checkout generates unique reference numbers for all orders (purchases). You can use this parameter to retry authorizations for orders with failed transactions by changing the payment method.

 

NULL when you place new orders.
ChargebackResolution String
 

Chargeback status information. Possible values:

· OPEN (chargeback is in progress)

· WON (chargeback won by you)

· LOST (chargeback won by the customer)

· ACCEPTED (you agreed to repay the value of the order to the customer)

· NONE (no chargeback initiated for the order)

To manage chargeback notifications navigate to Control Panel Dashboard →Integrations → Webhooks and API, and click on the IPN settings tab.

In the General IPN Settings section, under Triggers, make sure to check the boxes next to the following options:

· chargeback open (2Checkout sends an IPN when shoppers open a chargeback dispute).

· chargeback closed - (2Checkout sends an IPN when the parties involved resolve a chargeback dispute).

Also, check the checkbox next to the CHARGEBACK_RESOLUTION parameter featured in the Response tags area.
ChargebackReasonCode String
 

Identifier for the chargeback dispute reason from the 2Checkout system. Empty for orders with no chargeback dispute initiated.

Possible values:

  • MERCHANDISE_NOT_RECEIVED - Order not fulfilled/not delivered
  • NOT_AS_DESCRIBED - Product(s) not as described/unfunctional
  • DUPLICATE_TRANSACTION - Duplicate order
  • FRAUD / NOT_RECOGNIZED - Fraud/Order not recognized
  • CREDIT_NOT_PROCESSED - Agreed refund not processed
  • NOT_RECOGNIZED - New/renewal order not recognized
  • AUTHORIZATION_PROBLEM - Authorization problem
  • INFO_REQUEST - Information request
  • UNKNOWN - Unknown
OrderNo String
  The consecutive order number 2Checkout associates with orders and displays in the Order search area of your account.
ExternalReference String
  Set external reference identifiers for orders. Enables you to replicate the functionality of the REF parameter included into Buy Links. Maximum 100 characters. If there is a need for longer references, you can apply an md5 hash for any string value, resulting in a 32 characters string. You can verify the hash after the order notification, on the client side.
Status String
 

The status of the order:

  • AUTHRECEIVED – 2Checkout blocks the amount corresponding to the transaction, but the process of collecting funds is incomplete.
  • PENDING - 2Checkout has yet to block the amount corresponding to the transaction or shoppers used an offline payment method like wire transfer.
  • COMPLETE – The shopper completed the transaction for the purchase and 2Checkout or you fulfilled the order (when required).
  • CANCELED – 2Checkout cancels orders for which shoppers fail to transfer funds in due time.
  • REVERSED – 2Checkout reverses order transactions that never reach the Complete/Finished stage. Shoppers never complete transactions for such purchases.
  • REFUND – 2Checkout refunds orders only after they reach the Complete/Finished stage and returns the funds collected to shoppers.
ApproveStatus String
 

The status of the order resulted from the evaluation by the 2Checkout anti-fraud system or by a member of the anti-fraud department. This status varies for new purchases and for orders requiring customers to make manual payments.

Possible values:

  • WAITING: The 2Checkout anti-fraud system or a member of the anti-fraud department has yet to approve the order.
  • OK: The 2Checkout anti-fraud system or a member of the anti-fraud department approved the order.
  • INVALIDDATA: Shopper-supplied data is invalid – 2Checkout did not approve the order.
  • FRAUD: The order is fraudulent.
VendorApproveStatus String
 

Shows if you approved or not a partner order. Possible values:

  • OK
  • WAITING
  • REJECTED
Language String
  ISO 639-1 two-letter code. Language used for the purchase process. Example: “en.”
OrderDate String
  Y-m-d H:i:s (2014-05-22 00:12:12) The datetime stamp (in the API time zone defined in cPanel) when customers place their orders.
FinishDate String
 

Y-m-d H:i:s (2014-05-22 00:12:12) The datetime stamp (in the API time zone defined in cPanel) when the order reach the Complete status.

 

NULL for order that did not reach the Complete/Finished stage.
Source String
 

The link source for the sale. Enables you to replicate the functionality of the SRC (separate link identifier) parameter when included into Buy Links. Use the SRC parameter to track sale sources.

Maximum length 255 characters. Cannot be null.
Affiliate Object
  Details below.
                   AffiliateCode String
  The unique code of the affiliate who refer orders.
                   AffiliateSource String
  The link source for affiliate referred sales. Similar to the functionality of the SRC (separate link identifier) parameter included into Buy Links, but controlled by the AFFSRC parameter. Affiliates use the AFFSRC parameter to track sale sources for their referrals. Maximum length 255 characters.
                   AffiliateName String
  Affiliate name.
                   AffiliateUrl String
  Affiliate website URL from the Affiliate Details.
HasShipping Boolean
  true or false, depending on whether the order requires shipping.
DeliveryFinalized Boolean
  true or false, depending on whether product delivery has been completed.
BillingDetails Object
    Details below. 
    FirstName String
      Shopper name.
    LastName String
      Shopper surname.
    CountryCode String
      Shopper country. ISO 3166 two-letter code.
    State String
      The state in the shopper's country. Mandatory when you set the Billing Country to US, Turkey, India and Romania. Use case insensitive utf8 strings for the full name, or just the two letter code.
    City String
      Shopper city.
    Address1 String
      Shopper address.
    Address2 String
      Shopper address.
    Zip String
      ZIP/ Postal code.
    Email String
      Shopper email address.
    Phone String
      Shopper phone number. Mandatory when you set Brazil as the Billing Country. Can be NULL.
    Company String
      Company name. Can be null for end users. When present, you also need to provide the FiscalCode.
  FiscalCode String 
   

• For companies, it needs to be the VAT ID. 2Checkout will validate the value provided and throw an error if the VAT ID is invalid/incorrect when calling setPaymentDetails. When present, you also need to provide the Company name.

• Mandatory when the Billing Country is set to Brazil. For Brazilian customers it represents the Fiscal Code (CPF/CNPJ).

• Mandatory when the Billing Country is set to India, and purchase is made by a Company.

• Can be null for end users.
DeliveryDetails

Object

Optional. When missing, 2Checkout uses the same details as for the BillingDetails object.
      Details below. 
    FirstNameFirstName   String
        Shopper name from the delivery details.
    LastName   String
        Shopper surname from the delivery details.
    CountryCode   String
        Shopper country. ISO 3166 two-letter code from the delivery details.
    State   String
        The state in the shopper's country from the delivery details. Mandatory when you set the Billing Country to US, Turkey and Romania. Use case insensitive utf8 strings for the full name, or just the two letter code.
    City   String
        Shopper city from the delivery details.
    Address1   String
        Shopper address from the delivery details.
    Address2   String
        Shopper address from the delivery details.
    Zip   String
        ZIP/ Postal code from the delivery details.
    Email   String
        Shopper email address from the delivery details.
    Phone   String
        Shopper phone number from the delivery details. Mandatory when you set Brazil as the Billing Country. Can be NULL.
    Company   String
        Company name from the delivery details. Can be null for end users. When present, you also need to provide the FiscalCode.
PaymentDetails Optional (Object)
  Adapt this object to the desired payment method.
  Type String
   

The payment method:

  • CC (credit/debit card - including local Brazilian cards).
  • PAYPAL
  • PAYPAL_EXPRESS
  • CCNOPCI (credit/debit card for non-PCI certified merchants).
  • TEST (for test orders).
  • PREVIOUS_ORDER (place new orders using the reference of a previous order).
  • EXISTING_PAYMENT_DATA  (use a card one of your customers already used to purchase from your account).
  • WIRE – the placeOrder response includes Wire payment details.
  • CHECK – the placeOrder response includes Check payment details.
  • PURCHASEORDER - use for orders with POs.
  • FREE – for 0 value orders for which you’re not requiring customers to provide payment details.
  • GOOGLE PAY
  • eCheck/ACH
  • Stored Credit
  Currency String
    The currency ISO code for the payment - ISO 4217. Example: “usd.”
  PaymentMethod Optional (object)
   

Object structure and parameters differ according to payment method selected and API method (placing orders (POST) vs. retrieving order data (GET)). For payments with credit cards, PalPay Express, previous order reference and purchase order use the objects below.

 

For payments with check and wire, send only the ‘CHECH’ and ‘WIRE’ strings.

 

null for 0 value orders for which you’re not requiring customers to enter payment details.
                 RecurringEnabled Boolean
    true or false, depending on whether the shoppers checked the subscription auto-renewal checkbox or not, during the purchase process.
    PaymentDetailsCard Optional (object)
        Details below. 
      CardType String
        visa, visaelectron, mastercard, maestro, amex, discover, dankort, cartebleue, jcb, hipercard, elo
      FirstDigits String
        First four digits of the credit card.
      LastDigits String
        Last four digits of the credit card.
      RecurringEnabled Boolean
        true or false, depending whether the order has active recurring options
      Vendor3DSReturnURL String
        URL to which customers are redirected after a successful 3DS process.
      Vendor3DSCancelURL String
        URL to which customers are redirected after a failed 3DS process.
      InstallmentsNumber Integer
        Number of installments used for paying the order.
  CheckPaymentDetails Optional (Object)
      Details below. 
    Beneficiary String
     

The beneficiary of the payment.

Can be NULL.
    CheckPostalAddress String
     

The address of the beneficiary.

Can be NULL.
    Amount Float
     

The total costs incurred by the customer for an order.

Can be NULL.
    Currency String
     

The currency ISO code of the order/payment - ISO 4217.

Can be NULL.
  PayPalExpress Object
        Details below. 
      Email String
        Email address customers use for their PayPal account.
      ReturnURL String
        The PayPal Express Checkout redirect URL returned by calling the getPayPalExpressCheckoutRedirectURL method. The return URL is the page on your website to which PayPal redirects your buyer's browser after the buyer logs into PayPal and approves the payment. Typically, this is a secure page (https://...) on your site.
      CancelURL String
        The cancel URL is the page on your website to which PayPal redirects your buyer's browser if the buyer does not approve the payment. Typically, this is the secure page (https://...) on your site from which you redirected the buyer to PayPal.
  WirePaymentDetails Object
      Details below. 
    Amount Float
     

The total costs customers incur.

Can be NULL.
    Currency String
     

The currency ISO code of the order - ISO 4217.

Can be NULL.
    PaymentReference String
     

Transaction identifier.

Can be NULL.
    RoutingNumber String
     

Identification number assigned to financial institutions.

Can be NULL.
    BankAccounts Optional (Array of objects)
        Details below. 
      Beneficiary String
       

The beneficiary of the payment.

Can be NULL.
      BankName String
       

The name of the beneficiary's bank.

Can be NULL.
      BankCountry String
       

The country of the beneficiary's bank.

Can be NULL.
      BankCity String
       

The city of the beneficiary's bank.

Can be NULL.
      BankAddress String
       

The address of the beneficiary's bank.

Can be NULL.
      BankAccount String
       

The number for the account in which customers transfer the funds.

Can be NULL.
      BankAccountIban String
       

The IBAN of the beneficiary's bank.

Can be NULL.
      BankAccountSwiftCode String
       

The Swift Code of the beneficiary's bank.

Can be NULL.
      Currency String
       

The currency ISO code for the bank account - ISO 4217.

Can be NULL.
  DIRECT_DEBIT_ACH Object
    Details below.
    AccountHolderName String
      Full name of the account holder.
    BankRoutingNumber String
      Bank Routing number consisting of up to 17 digits.
    AccountNumber String
      Account number with fixed 9 digit length.
    AccountType String
      Possible values are "S" for SAVINGS accounts or "C" for CHECKING accounts.
  CustomerIP String
    Shopper IP.
CustomerDetails

Object

2Checkout populates the parameters of the customer entity with information from the customer whose AvangateCustomerReference or ExternalCustomerReference you send during the purchase.
    Details below. 
  AvangateCustomerReference Integer
    System-generated 2Checkout customer reference. Aggregate subscriptions under the same Customer account if the products they're associated to are purchased by the same shopper by adding the AV_CUSTOMERID (case sensitive) parameter to buy links. The 2Checkout system generates default customer numerical (integer) IDs (AV_CUSTOMERID) automatically for all orders containing products that feature subscriptions.
  ExternalCustomerReference String
    The external customer reference you control. Aggregate subscriptions under the same Customer account if the products they're associated to are purchased by the same shopper by adding the CUSTOMERID (case sensitive) parameter  to buy links.
  FirstName String
    Customer's first name. 
  LastName String
    Customer's last name.
  CountryCode String
    Customer's country code (ISO 3166 two-letter code).
  State String
    Customer's state. For example, "Alabama","Alaska","Arizona".
  City String
    Customer's city.
  Address1 String
    Customer's address.
  Address2 String
    Customer's address.
  Zip String
    Zip code.
  Email String
    Customer's email.
  Phone String
    Customer's phone number.
  Company String
    Company name.
  FiscalCode String
   

For companies, it needs to be the VAT ID. 2Checkout validates this values and throws an error if the VAT ID is invalid/incorrect. When present, you need to also provide Company name.

 

Can be null for end users.
  Fax String
    Customer's fax number.
  Enabled Boolean
    true or false, depending on whether the customer account is active or inactive. An active customer account features at least one Active or Past due subscription.
  Trial Boolean
    true or false, depending on whether the customer account features only trials or also paid subscriptions.
  Language String
    ISO 639-1 two-letter code. Example: “en.”
  ExistingCards Array of objects
      Details below. 
    TransientToken Object
      Populated only when you retrieve customer information by SSOToken.
      Token String
        Token for the EXISTING_PAYMENT_DATA flow. Use it to charge customers using cards they used in the past for purchases from your 2Checkout account.
    CardType String
      visa, visaelectron, mastercard, maestro, amex, discover, dankort, cartebleue, jcb, hipercard, elo
    LastDigits String
      Last four digits of the credit card.
    ExpirationMonth String
      Card expiration month.
    ExpirationYear String
      Card expiration year.
    NameOnCard String
      Card holder name.
Origin String
 

2Checkout automatically tracks the source of purchases:

 

  • Web – When customers use the desktop version of the 2Checkout shopping cart.
  • API - When customers use a custom, API-based ordering interface.
  • Mobile - When customers use the mobile version of the 2Checkout shopping cart.
  • Automatic Billing – For auto-renewals and trial conversions.
AvangateCommission Optional (Int)
  2Checkout's commission for the order.
OrderFlow String
 

PURCHASE_ORDER - Sent only when shoppers used Purchase Orders.

REGULAR - Sent in all other cases.
GiftDetails Optional (object)
  Contains contact details for the recipient of a gift purchase.
  FirstName String
    First name of gift recipient.
  LastName String
    Last name of gift recipient.
  Email String
    Email of gift recipient. 2Checkout uses this email for the delivery/fulfillment process.
  GiftNote String
    Custom text shoppers provide as a message to the gift recipient.
PODetails Object (optional)
    Details below. 
  Status String
   

PO status. Possible values:

 

PO status API PO status cPanel
AWAITING_UPLOAD Awaiting form submission - Waiting for the customer to submit the PO form
TIME_EXPIRED Expired, form not received - The customer did not submit the PO form
AWAITING_MERCHANT Awaiting your confirmation - PO approved by 2Checkout, awaiting vendor confirmation
MERCHANT_TIME_EXPIRED Expired, PO not confirmed - You didn't confirm/reject the PO
AWAITING_MERCHANT Rejected - You rejected the PO
AWAITING_PAYMENT Awaiting payment - You approved the PO, waiting for payment
AWAITING_PAYMENT Expired, not paid - The customer did not complete the PO payment. 2Checkout accepts  payments up to 30 days after the PO payment interval expires
NOT_PAID Canceled, not paid - The customer did not complete the PO payment
NOT_PAID Canceled by 2Checkout - 2Checkout canceled the PO
NOT_PAID Canceled via API - You canceled the PO (via API)
PAID Complete - Customer paid the PO. The order is complete
  AutoApprove Boolean
  TRUE or FALSE, depending on whether you set POs to auto-approve or not.
  RequireDocumentUpload Boolean
  TRUE or FALSE, depending on whether require document upload or not.
  NetPaymentTerms Integer
  The term of net payment in days.
  CopyPreviousDocuments Boolean
  TRUE or FALSE, depending on whether copy documents from previous order or not.
  PdfFormUrl String
  URL of Purchase Order form which needs to be printed, signed and uploaded.
  InternalPONumber String
  Identifier that business customers use internally in their organization to track and manage Purchase Orders (PO). Can be NULL.
ExtraInformation Optional (Object)
  Details below. 
  PaymentLink String
   

Can be:

1. The PO doc upload link - If you set AutoApprove as FALSE on the original order and before shoppers upload the PO. 

2. Payment link for orders with POs. Business customers can use the PaymentLink to finalize payment for orders with POs. If you set AutoApprove as TRUE on the original order and if 2Checkout and you approve the PO. 
PaymentLink String
  In scenarios in which an issue blocks the transaction from finalizing, 2Checkout provides a retry link where shopper can complete their purchase by providing new payment details.
PartnerCode String
  Partner code you configured for your partner. NULL for eStore orders.
PartnerMargin Float
  Partner margin you set for the order. NULL for eStore orders.
PartnerMarginPercent Float
  The percentage of the partner margin from the net value of the products ordered, minus the value of any discounts. NULL for eStore orders.
ExtraMargin Float
  Extra margin you offer by editing partner orders. NULL for eStore orders.
ExtraMarginPercent Float
  The percentage of the extra partner margin from the net value of the products ordered, minus the partner margin and the value of any discounts. NULL for eStore orders.
ExtraDiscount Float
  Extra discount you offer by editing partner orders. NULL for eStore orders.
ExtraDiscountPercent Float
  The percentage of the partner margin from the net value of the products ordered, minus the value of any coupon discounts. NULL for eStore orders.
LocalTime String
 

Local shopper time in the following format: Y-m-d H:i:s.

This parameter can impact the fraud score of an order when it's missing, NULL or incorrectly formatted.
TestOrder Boolean
  True for test orders. False of regular orders.
Errors Array of strings
  Payment gateway processing errors.
Items Array of objects
    Details below. 
  ProductDetails Object
    Name String
      Product name.
    ShortDescription String
      Product short description.
    Tangible Boolean
      true or false, depending on product delivery type.
    IsDynamic Boolean
     

Possible values:

  • true - dynamic product information
  • false - catalog products
    ExtraInfo String
      The text entered in the Additional information field when generating Buy links, or via the INFO[PRODUCT_ID] parameter used in Buy links.
    RenewalStatus Boolean
     
  • true for orders renewing subscriptions.
  • false for all other orders: new purchases, upgrades.
    DeliveryInformation

Object

Details below
          Delivery   String
     

Possible values:

  • BY_VENDOR
  • NO_DELIVERY
  • BY_AVANGATE
          DownloadFile   Object
      Information related to the download file.
          DeliveryDescription   String
      Delivery description.
          CodesDescription   String
      Description of codes delivered.
          Codes   Array of strings
              Array with the codes delivered
    Subscriptions Object
      SubscriptionReference String
        Unique, system-generated subscription identifier.
      PurchaseDate String
       

The date time stamp when shoppers acquired their subscriptions corresponding to the moment when the 2Checkout system marks the purchase as finished. Format (YYYY-MM-DD HH:mm:ss). Default GMT+02:00.

 

e.g. 2015-08-11 15:18:52
      SubscriptionStartDate String
       

 

Example: 2015-09-29 17:57:59
      ExpirationDate String
       

The date time stamp of upcoming renewal/expiration for subscriptions not taking into account grace period settings.

 

Format (YYYY-MM-DD HH:mm:ss). Default GMT+02:00.

 

e.g. 2015-09-11 15:18:52
      Lifetime Boolean
       
  • true – For non-recurring, evergreen subscriptions.
  • false – For recurring subscriptions with a specific billing cycle from 7 days to 36 months.
      Trial Boolean
       
  • true – For trial subscriptions.
  • false – For non-trial, recurring subscriptions with a specific billing cycle from 7 days to 36 months.
      Enabled Boolean
       
  • true – For active and past due subscriptions.
  • false – For expired and cancelled subscriptions.
      RecurringEnabled Boolean
         
  PriceOptions Array of strings
    Array of price option codes.
    Code Strings
      Unique code that the 2Checkout system generates or that you set for each pricing options group.
    Required Boolean
     
  • true – you require shoppers to select the price option  through the way in which you configured pricing.
  • false – you do not require shoppers to select the price option.
    Options Array of strings
      The code you set or that the 2Checkout system generates for each price option child inside a pricing options group parent.
  Price Object
   

This object returns the price per unit at order line level.

 

In the case of trials, the object returns the costs for the trial to full subscription conversion.
    UnitNetPrice Float
      The value per product unit, excluding sales tax/VAT expressed in the payment currency.
    UnitGrossPrice Float
      Total value per product unit, including sales tax/VAT expressed in the payment currency. UnitGrossPrice does not reflect any discounts.
    UnitVAT Float
      Sales tax/VAT per product unit expressed in the payment currency.
    UnitDiscount Float
      Value of the discount per product unit expressed in the payment currency.
    UnitNetDiscountedPrice Float
      The value per product unit, expressed in the payment currency, excluding sales tax/VAT, from which 2Checkout deducts the unit discount.
    UnitGrossDiscountedPrice Float
      Total costs shoppers incur per product unit, expressed in the payment currency. This value includes sales tax/VAT, 2Checkout and affiliate commissions, but 2Checkout deducts the value of any discounts.
    UnitAffiliateCommission Float
     

Value of the affiliate commission per product unit calculated expressed in the payment currency.

 

2Checkout deducts discounts from the costs incurred by shoppers before calculating affiliate commissions.

 

2Checkout does not take into account shipping costs when calculating affiliate commissions.

 

NULL when 2Checkout does not apply an affiliate commission.
    Currency String
      The currency ISO code for the payment - ISO 4217. Example: usd.
    NetPrice Float
      The value per order line, excluding sales tax/VAT expressed in the payment currency.
    GrossPrice Float
      Total value per order line, including sales tax/VAT expressed in the payment currency. UnitGrossPrice does not reflect any discounts.
    NetDiscountedPrice Float
      The NetPrice value per order line (in the payment currency), excluding sales tax/VAT, from which 2Checkout deducts discounts.
    GrossDiscountedPrice Float
     

Total costs shoppers incur per order line, expressed in the payment currency. This value includes sales tax/VAT, 2Checkout and affiliate commissions, but 2Checkout deducts the value of any discounts.

 

Example:

  • UnitNetPrice: 99
  • UnitGrossPrice: 120.39
  • UnitVAT: 21.39
  • UnitDiscount: 9.9
  • UnitNetDiscountedPrice: 89.1
  • UnitGrossDiscountedPrice: 110.49
  • UnitAffiliateCommission: 22.28
  • Currency: "usd"
  • NetPrice: 198
  • GrossPrice: 240.77
  • NetDiscountedPrice: 178.2
  • GrossDiscountedPrice: 220.97
  • Discount: 19.8
  • VAT: 42.77
  • AffiliateCommission: 44.56
    Discount Float
      Value of the discounts per order line expressed in the payment currency.
    VAT Float
      Value of sales tax/VAT per order line expressed in the payment currency.
    AffiliateCommission Float
      Value of the affiliate commission per order line, calculated from the NetDiscountedPrice expressed in the payment currency. Or NULL. 2Checkout does not take into account shipping costs when calculating affiliate commissions.
    VATPercent Integer
      Percentage of the VAT/tax applied to the order.
    HandlingFeeNetPrice Integer
      Handling fee applied to the NET price configuration.
    HandlingFeeGrossPrice Integer
      Handling fee applied to the GROSS price configuration.
  LineItemReference String
    System-generated reference for the product item.
  PurchaseType String
   

Possible values:

  • PRODUCT
  • SHIPPING
  • TAX
  • COUPON
  Code String
    Unique product identifier your control. Max length 256 characters.
  Quantity Integer
    Number of units
  SKU String
    SKU identifier.
  CrossSell Object
      Details below. 
    ParentCode String
      The product code of the master product you set to trigger the campaign.
    CampaignCode String
      Unique, system-generated identifier for cross-sell campaigns.
  Trial Object
      Details below. 
    Period Integer
      The length of the trial subscription lifetime in days.
    GrossPrice Float
      Total trial price in the payment currency before 2Checkout deducts any taxes, discounts, etc.
    VAT Float
      The total value of taxes for the trial in the payment currency, before 2Checkout deducts any discounts.
    NetPrice Float
      Total trial price in the payment currency, not including taxes, before 2Checkout deducts any discounts.
  AdditionalFields Array of objects
      Details below. 
    Code String
      The alpha-numeric characters, underscores and dashes that are set as the field identifier.
    Text String
      Field text visible to shoppers in the cart.
    Value String
      Selected field value.
  Promotion Object
      Details below. 
    Name String
      Promotion name.
    Description String
      Promotion description.
    StartDate String
      The date when you set the promotion to start. NULL for promotions that start immediately after you create them.
    EndDate String
      The date when you set the promotion to end. NULL for promotions you want active indefinitely.
    MaximumOrdersNumber Integer
     

2Checkout only applies the promotion to a maximum number of orders you define.

 

Can be NULL if you want the promotion to apply to an unlimited number of orders.
    MaximumQuantity Integer
      Discount only applies to a maximum number of units purchased through a single order, smaller than the quantity you defined. Shoppers purchase any extra units at full price. Can be NULL if you want the promotion to apply to an unlimited number units.
    InstantDiscount Boolean
      The instant discount option auto-applies the discount for ALL selected products, without the need for shoppers to enter a discount coupon.
    Coupon String
      Promotion coupon/voucher.
    DiscountLabel String
      Discounts can be set as a percentage from the product price or as a fixed amount in the chosen currency.
    Enabled String
      true or false, depending on whether a promotion is active or disabled. 
    Type String
     
  • REGULAR – product/cart line level discounts.
  • ORDER – quantity discounts.
  • GLOBAL – order-level discounts.
  • AFFILIATE – for discounts created by affiliates.
Promotions Array of objects
    Details below. 
  Name String
    Promotion name.
  Description String
    Promotion description.
  StartDate String
    The date when you set the promotion to start. NULL for promotions that start immediately after you create them.
  EndDate String
    The date when you set the promotion to end. NULL for promotions you want active indefinitely.
  MaximumOrdersNumber Integer
   

2Checkout only applies the promotion to a maximum number of orders you define.

 

Can be NULL if you want the promotion to apply to an unlimited number of orders.
  MaximumQuantity Integer
    Discount only applies to a specific number of units purchased at once, smaller than the maximum quantity you defined. Shoppers purchase any extra units at full price. Can be NULL if you want the promotion to apply to an unlimited number units.
  InstantDiscount Boolean
    The instant discount option auto-applies the discount for ALL selected products, without the need for shoppers to enter a discount coupon.
  Coupon String
    Promotion coupon/voucher.
  DiscountLabel String
    Discounts can be set as a percentage from the product price or as a fixed amount in the payment currency.
  Enabled String
    true or false, depending on whether a promotion is active or disabled. 
  Type String
   
  • REGULAR – product/cart line level discounts.
  • ORDER – quantity discounts.
  • GLOBAL – order-level discounts.
  • AFFILIATE – for discounts created by affiliates.
AdditionalFields Array of objects
    Details below. 
  Code String
    The alpha-numeric characters, underscores and dashes that are set as the field identifier.
  Text String
    Field text visible to shoppers in the cart.
  Value String
    Selected field value.
Currency String
  The currency ISO code for the payment - ISO 4217. Example: usd.
NetPrice Float
  Order value excluding sales tax/VAT expressed in the payment currency.
GrossPrice Float
  Total order value, including sales tax/VAT expressed in the payment currency. GrossPrice does not reflect any discounts.
NetDiscountedPrice Float
  The NetPrice order value excluding sales tax/VAT, from which 2Checkout deducts discounts. NetDiscountedPrice is expressed in the payment currency.
GrossDiscountedPrice Float
 

Total costs shoppers incur, expressed in the payment currency. This value includes sales tax/VAT, 2Checkout and affiliate commissions, but 2Checkout deducts the value of any discounts.

 

For example:

  • Currency: "usd"
  • NetPrice: 396
  • GrossPrice: 486.29
  • NetDiscountedPrice: 376.2
  • GrossDiscountedPrice: 466.49
  • Discount: 19.8
  • VAT: 90.29
  • AffiliateCommission: 94.05
Discount Float
  Value of the discounts for an order expressed in the payment currency.
VAT Float
  Value of sales tax/VAT expressed in the payment currency.
AffiliateCommission Float
  Value of the affiliate commission for the order calculated from the NetDiscountedPrice expressed in the payment currency. Or NULL. 2Checkout does not take into account shipping costs when calculating affiliate commissions.
FxRate Integer
  Exchange rate used by 2Checkout for converting the order to your payout currency.
FxMarkup Integer
  Exchange rate markup for the order.
PayoutCurrency String
  The ISO code of your account's payout currency - ISO 4217.

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.

Get in touch

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.

Contact sales Get Started
Verifone logo