Usage management
Overview
The usage-based/on-demand/pay-as-you-go pricing model allows merchants to charge their customers on the consumption or overage of a billable service or resource, usually on top of a recurring flat rate.
Use the Usage object to manage (add, update, delete, retrieve, and import) usage via the 2Checkout API (SOAP API 6.0).
Parameters
| Parameters | Type | Required/Optional | Description |
|---|---|---|---|
| UsageReference | Integer | Optional | The unique usage identifier. Example: 123459876. |
| SubscriptionReference | String | Required | Unique code that represents a subscription. Example: 83FE4FEF2. |
| OptionCode | String | Required | Unique 2Checkout option code. The pay-per-usage price options group for which the usage is uploaded. Example: metered pricing. |
| UsageStart | Datetime | Required | The datetime when the usage started; can be the same as UsageEnd. Example: 2018-09-03 17:28:32. |
| UsageEnd | Datetime | Required | The datetime when the usage ended and was recorded. Example: 2018-09-03 17:28:32. |
| Units | Integer | Required | Number of units recorded. Example: 10. |
| Description | String | Optional | It can be used to store a short merchant comment of the usage being uploaded. This can be anything, from the source of usage (mobile, web, etc.), to why changes occurred, etc. Example: Subscription usage for September. |
Minimize required checkout data
Overview
Use this feature to streamline the shopping cart by minimizing data entry and providing an optimized ordering experience for customers.
Availability
Available by default to 2Monetize accounts.
Requirements
This feature requires the use of the SHORT_FORM parameter in buy-links generated in the Merchant Control Panel.
The SHORT_FORM parameter is case sensitive.
Purchase flow support
This feature supports the following purchase flows:
- Checkout with cart functionalities
- One page checkout with review
- One page checkout without review
- Add to shopping cart
- Checkout page
- Product page
- Express Payments Checkout
- Trial links
Generate buy-links with the SHORT_FORM parameter
- Log in to your 2Checkout Merchant Control Panel account.
- Navigate to the Generate Links area.
- Check the checkbox for the Compact shopping cart fields option when generating your buy-link to minimize the number of mandatory cart fields shoppers need to fill in during the purchase process. This action will automatically add the SHORT_FORM=1 parameter to the generated buy-links.
Create buy-links with the SHORT_FORM parameter manually
You can also add the SHORT_FORM=1 parameter manually to buy-links for shopping carts after you generate them.
When the feature is active for your account, and SHORT_FORM=1 is used in buy-links, the name, email, ZIP code, and country pair become the only required details of the billing address.
Using the SHORT_FORM=1 parameter without the feature being enabled for your account will result in shoppers following the classic purchase flow, where all billing address data is mandatory.
Workflow
Customers accessing buy-links that include the SHORT_FORM parameter after the feature has been enabled for your account will need to:
- Fill in only the country and ZIP code (if it applies), necessary for VAT/tax calculation. The name, email, ZIP code, and the country are the only remaining address elements still mandatory. Note: Shoppers in the U.S., Puerto Rico, and Marshal Islands are required to provide a valid ZIP code for their location. The same requirement does not apply to shoppers worldwide.
- Not fill in the address information as the field is no longer mandatory. In fact, the address field doesn't need to be included in the cart design.
|
Billing address field |
Mandatory |
Comment |
|---|---|---|
|
First name |
Yes |
Becomes part of the Name field |
|
Last name |
Yes |
Becomes part of the Name field. |
|
Address |
No |
- |
|
City |
Yes |
Used for tax calculation. Shoppers from the U.S., Puerto Rico, Marshal Islands, Brazil, and Turkey are required to provide a valid city code for their location. |
|
Zip or postal code |
Yes* |
Used for tax calculation. Shoppers from the U.S., Puerto Rico, Marshal Islands, and Brazil are required to provide a valid ZIP code for their location. |
|
Country |
Yes |
Used for tax calculation. |
|
State or province |
Yes* |
Used for tax calculation. Shoppers from the US, France, Romania, Brazil, Canada, India, and Turkey are required to provide their state or province during the checkout process. |
|
|
Yes |
- |
|
Confirm email |
No |
- |
| VAT | Yes | Used for tax calculation. Shoppers from Turkey, India, and Serbia are required to provide a valid VAT id during the checkout process. |
| Company | Yes | Used for tax calculation. Shoppers from Turkey and India are required to provide a valid company id. |

ZIP validation
2Checkout performs checks designed to ensure that the ZIP code provided by customers is valid.
Tax calculation
Taxes are calculated after a valid ZIP code is provided, and if necessary, added to the value of the products in the cart.
FAQ
1. Is there any information included automatically for addresses?
A dash "-" is used for the address.
2. Does it work for trials?
Yes. SHORT_FORM is supported in scenarios in which your customers access trials for which they need to provide billing details and payment information.
3. Is it included in hash validation?
No. SHORT_FORM is not included when creating the hash for buy-links.
Upgrade test orders
Overview
You can use these instructions to upgrade test orders.
Requirements
- Configure at least 2 products for your account.
- Set up one of the products as the upgrade of another.
- Enable the test order system.
- Place a test order with the upgradeable product.
Workflow
- Navigate to Subscription management or to Order search and search either for a test subscription belonging to or a test order involving the upgradable product.
- Click on View subscription to access the details page of the item you wish to trigger the auto-renewal process for.
- Click on or copy & paste the Upgrade test link into your browser's address bar.
- You will land in the shopping cart where you can place an upgrade test order. The system adds the DOTEST=1 URL parameter to the Buy Link.
- The system updates the Subscription history area with the details on the upgrade test order.
Possible test order status transitions

|
Order status in search export |
Order status in Control Panel |
Approve status |
Notes |
|---|---|---|---|
|
COMPLETE |
Finished |
Finished |
The order was fulfilled. |
|
AUTHRECEIVED |
Pending approval |
Pending approval |
2Checkout is yet to approve the order. |
|
In progress / Processing |
In progress |
The order was approved. |
|
|
PENDING (for automatic authorization failures) |
Unfinished |
Unfinished |
2Checkout is yet to approve the order. |
|
TOTAL REFUND |
Refunded |
Refunded |
Full refund. |
|
PARTIAL REFUND |
Refunded |
Refunded |
Partial refund. |
Product group
Overview
Use the ProductGroup object to create/add and update/edit product groups.
Attributes
| Parameters | Type/Description |
|---|---|
|
ProductGroup |
Object |
|
Name |
Required (string) |
|
|
The name of the product group. |
| Code | Optional (string) |
| Unique, system-generated identifier assigned to product groups. | |
|
TemplateName |
Optional (string) |
|
|
Leave empty to assign the Default Template to the product.
Or use the name of an active shopping cart template. |
|
Description |
Optional (string) |
|
|
The description of the product group. |
Electronic delivery
Use the variables in the list below to customize the Electronic delivery shopper email according to your needs. Check the 'Mandatory' column to see the variables that are required in your customized version of the e-mail.
| Variable name | Description | Test value | Mandatory |
|---|---|---|---|
|
ADDITIONAL_PRODUCT_INFO |
Additional product-level fulfillment information set in the Avangate Control Panel |
Additional delivery information for this product. |
No |
|
ADDRESS2 |
Second section of the billing address |
0 |
No |
|
ALLOW_MYACCOUNT_PROMO |
Include or exclude myAccount information in the email body |
1 |
No |
|
ATTACHMENT |
Indicates whether or not you configured the product keys to be sent as an email attachment. Possible values: |
1 |
No |
|
AUTO_RENEWAL |
Indicates whether or not the shopper has enabled automatic renewal on the subscription |
1 |
No |
| AVANGATE_ACTED_AS_RESELLER | This is mandatory content you need to keep in your emails, given Avangate acts as Reseller / Merchant of Record for online purchases on your website. | Avangate has processed your order as the authorized reseller of #merchant commercial name. | Yes |
|
AVANGATE_COMPANY_NAME |
Avangate company name |
Avangate |
No |
|
AVANGATE_SUPPORT_EMAIL |
Avangate support email address |
No | |
|
AVANGATE_SUPPORT_PHONE |
Avangate support phone |
+31 88 0000008 |
No |
|
AVANGATE_SUPPORT_PHONE_US |
Avangate US hotline number |
+1 (650) 963-5701 / (888) 247-1614 |
No |
|
AVANGATE_WEBSITE |
Avangate website |
Yes | |
| AVANGATE_LOGO | Avangate logo URL | https://secure.avangate.com/images/e...endor_logo.png | Yes |
|
BASE_URL |
Merchant's full host |
No | |
|
BOLETO_SLIP_URL |
URL pointing to Boleto slip |
0 |
No |
|
BUSINESS_COMPANY |
Avangate company name |
Avangate |
No |
|
BUSINESS_HOTLINE |
Avangate support phone |
+31 88 0000008 |
No |
|
BUSINESS_HOTLINEUS |
* Avangate support phone for US |
+1 (650) 963-5701 / (888) 247-1614 |
No |
|
BUSINESS_SUPEMAIL |
Avangate support email address |
No | |
|
BUSINESS_WEBSITE |
Avangate website |
No | |
|
CODES |
Product keys to be delivered to the shopper. Each item of the array has two values: key and description |
0 |
No |
|
CODES[index1].description |
Product key description. |
Key description |
No |
|
CODES[index1].key |
Product key. |
123-ABC-1key-example |
No |
|
COMMERCIALNAME |
Merchant's commercial name |
[Software Company Name] |
No |
|
COMPANY |
Shopper's company name used on the billing information |
Customer company |
No |
|
CURRENCY |
Order billing currency |
0 |
No |
|
CURRENCY_ORIGINAL |
Original order currency (applicable to refunds) |
0 |
No |
|
DISPLAY_MY_ACCOUNT_INFO |
Include or exclude myAccount information in the email body |
1 |
No |
|
DOWNLOAD_INSURANCE |
Indicates whether or not the purchase includes Download Insurance Service. Possible values |
0 |
No |
|
DOWNLOAD_LINK |
Product download link |
No | |
|
DOWNLOAD_LINK_DELIVERY |
Indicates whether or not a download link is available. Possible values: |
1 |
No |
|
|
Shopper email address used on the delivery information. If no delivery information is available, the billing information is used. |
No | |
|
ENCRYPTED_MERCHANT_CODE |
Encrypted merchant code |
0 |
No |
|
FIRSTNAME |
Shopper's first name used on the delivery information |
[John |
No |
|
FIRST_NAME_DELIVERY |
Shopper's first name used on the delivery information |
John |
No |
| GATEWAY_ERROR_CODE | Gateway error code | GW_PROCESSING_ERROR See the full list of Possible Values |
No |
| GATEWAY_ERROR_MESSAGE | Reason why the transaction failed. (e.g. Invalid card, insufficient funds) | Error processing the card transaction. The card account has not been debited. Card data is invalid or incomplete. | No |
|
HAS_RENEWAL_PRODUCTS |
Flag that indicates whether at least one product has renewal settings |
0 |
No |
|
HOTLINE_NUMBERS |
Array of attributes for Avangate hotline numbers |
0 |
No |
|
IS_RENEWAL |
Flag that indicates whether at least one product has renewal settings |
0 |
No |
|
LANGUAGE |
Order language (abbreviated) selected by shopper |
en |
No |
|
LASTNAME |
Shopper's last name used on the delivery information |
Doe] |
No |
|
LAST_NAME_DELIVERY |
Shopper's last name used on the delivery information |
Doe |
No |
| LICENCECODE | The subscription reference | FGXYZ1234 | No |
|
MERCHANT_CITY |
Merchant's city |
0 |
No |
|
MERCHANT_COMMERCIAL_NAME |
Merchant's commercial name |
[Software Company Name] |
No |
|
MERCHANT_COMPANY_NAME |
Merchant's company name |
0 |
No |
|
MERCHANT_STREET |
Merchant's street name |
0 |
No |
|
MERCHANT_SUPPORT_EMAIL |
Merchant support email address |
No | |
|
MERCHANT_SUPPORT_PHONE |
Merchant support phone number |
[888-xxx-xxxx] |
No |
|
MOREINFO |
Additional product-level fulfillment information set in the Avangate Control Panel |
Additional delivery information for this product. |
No |
|
MY_ACCOUNT_LOGIN_EMAIL |
Email address used by shopper to login/signup to myAccount |
No | |
|
MY_ACCOUNT_LOGIN_TOKEN |
Token assigned to the shopper in order to access myAccount |
xxxxxxxxxxxx |
No |
|
MY_ACCOUNT_LOGIN_URL |
Avangate myAccount login/sign-up URL |
secure.sofware-company-website.com/myaccount/?lang=en |
Yes |
|
NAMES_OF_PRODUCTS |
Names of all products in the order, comma separated |
0 |
No |
|
ORDERTOTAL |
Total order price |
0 |
No |
|
ORDER_ADDITIONAL_FIELDS_TEXT |
The order additional field names configured in the Avangate Control Panel |
0 |
No |
|
ORDER_ADDITIONAL_FIELDS_VALUE |
The order additional field values filled in by the shopper |
0 |
No |
|
ADDRESS1 |
First section of the billing address |
0 |
No |
|
ORDER_AMOUNT |
Total order price |
0 |
No |
|
ORDER_AMOUNT_ORIGINAL |
Original order value (applicable to refunds) |
0 |
No |
|
ORDER_DATE |
Order placement date |
42563.96863 |
Yes |
|
ORDER_DATE_STANDARD_FORMAT |
Standard format used for the order placement date |
0 |
No |
|
ORDER_FLOW |
Purchase flow used to place the order |
0 |
No |
|
ORDER_REFERENCE_NUMBER |
Order reference number |
[9xxxxxx] |
Yes |
|
ORDER_STATUS |
Order status |
0 |
No |
|
ORDER_WEBSITE |
Website where the shopper placed the order |
Yes | |
|
PAYABLE_TO |
Payee name (applicable to wire transfer) |
0 |
No |
|
PAYMENT_TYPE_INFO |
English payment method name. Includes last four card digits (if applicable). |
0 |
No |
|
PRODUCT |
Product data |
0 |
No |
|
PRODUCT.CODE |
Product code |
0 |
No |
|
PRODUCT.CODES |
Product keys to be delivered to the shopper. Each item of the array has two values: key and description |
0 |
No |
|
PRODUCT.DOWNLOAD_LINK |
Product download link |
No | |
|
PRODUCT.HAS_CODES_ATTACHED |
Indicates whether or not you configured the product keys to be sent as an email attachment. Possible values: |
1 |
No |
|
PRODUCT.HAS_DOWNLOAD_LINK |
Indicates whether or not a download link is available. Possible values: |
1 |
No |
|
PRODUCT.ID |
Product ID number |
4682814 |
No |
|
PRODUCT.INFO |
Additional product information defined by merchant when generating buy links |
0 |
No |
|
PRODUCT.NAME |
Product name |
Product Name |
No |
|
PRODUCT.NUMBER_OF_DELIVERED_PRODUCTS |
Number of distinct products to be delivered to the shopper |
2 |
No |
|
PRODUCT.PRODUCT_OPTIONS |
Product pricing options configured in the Avangate Control Panel |
0 |
No |
|
PRODUCT.PRODUCT_OPTIONS[index1].OptionText |
Product pricing option name |
option 1 |
No |
|
PRODUCT.QUANTITY |
Purchased product quantity |
1 |
No |
|
PRODUCTCODE |
Product code |
0 |
No |
|
PRODUCTID |
Product ID number |
4682814 |
No |
|
PRODUCTNAME |
Product name |
[Product Name] |
No |
|
PRODUCTQTY |
Purchased product quantity |
1 |
No |
|
PRODUCTS[index1].LICENSE_TYPE |
Type of purchased subscription |
0 |
No |
|
PRODUCTS[index1].SHORT_DESCRIPTION |
Short product description |
0 |
No |
|
PRODUCTS_DATA[index1].IdProduct |
Product ID number |
0 |
No |
|
PRODUCTS_DATA[index1].PRODUCT_SHORT_DESCRIPTION |
Short product description |
0 |
No |
|
PRODUCTS_NO |
Number of products in cart |
0 |
No |
|
PRODUCT_INFO |
Additional product information defined by merchant when generating buy links |
0 |
No |
|
PRODUCT_OPTIONS |
Product pricing options configured in the Avangate Control Panel |
0 |
No |
|
REFNO |
Order reference number |
[9xxxxxx] |
No |
|
RETRYLINK |
Payment retry link |
0 |
No |
|
RETRY_LINK |
Payment retry link |
0 |
No |
|
SELLERCITY |
Merchant's city |
0 |
No |
|
SELLERCOMPANY |
Merchant's commercial name |
0 |
No |
|
SELLERCOUNTRY |
Merchant's country |
0 |
No |
|
SELLERSTREET |
Merchant's street name |
0 |
No |
|
SELLERWEBSITE |
Website where the shopper placed the order |
No | |
|
SELLERZIP |
Mechant's zip code |
0 |
No |
|
SHOPPER_ADDRESS_1_DELIVERY |
First section of the delivery address |
0 |
No |
|
SHOPPER_ADDRESS_2_DELIVERY |
Second section of the delivery address |
0 |
No |
|
SHOPPER_COMPANY_DELIVERY |
Shopper company name used on the delivery information. If no delivery information is available. no company name is displayed. |
Customer company |
No |
|
SHOPPER_EMAIL_ADDRESS_DELIVERY |
Shopper email address used on the delivery information. If no delivery information is available. the billing information is used. |
No | |
|
TECHEMAIL |
Merchant support email address |
No | |
|
TECHPHONE |
Merchant support phone number |
[888-xxx-xxxx] |
No |
|
TO_BE_DELIVERED |
Number of distinct products to be delivered to the shopper |
2 |
No |
|
UPLOADLINK |
File upload link |
0 |
No |
|
UPLOAD_LINK |
File upload link |
0 |
No |
|
USER_EMAIL |
Email address used by shopper to login/signup to myAccount |
No | |
|
USER_TOKEN |
Shopper token for Avangate myAccount access |
xxxxxxxxxxxx |
No |
|
WEBSITE |
Website where the shopper placed the order |
0 |
No |
Promotions
Overview
Use the Promotion object via JSON-RPC API 6.0 to retrieve information on discounts/promotions you set up for your account.
Parameters
| Parameters | Type/Description | |
|---|---|---|
|
Promotion |
Object |
|
| Detailed below. | ||
|
CouponCodes |
Array of strings |
|
|
|
Array of coupon/voucher codes when Coupon / Voucher type is Multiple. Otherwise, empty array. |
|
|
ChannelType |
String |
|
|
|
Possible values:
|
|
|
CouponType |
String |
|
|
|
Possible values:
|
|
|
DiscountType |
String |
|
|
|
Possible values:
|
|
|
Type |
String |
|
|
|
REGULAR |
|
|
Discount |
Int |
|
|
|
The value of the discount. Example, for a $30 USD discount Avangate returns the value 30 and for a 25% price cut, Avangate returns 25. |
|
|
Products |
Array |
|
|
|
Array of product codes for the products impacted by the promotion. |
|
|
Name |
String |
|
|
|
Promotion name. |
|
|
Description |
String |
|
|
|
Promotion description. |
|
|
StartDate |
String |
|
|
|
Starting date. The date when you set the promotion to start. Is NULL for promotions that start immediately after they're created. |
|
|
EndDate |
String |
|
|
|
Ending date. The date when you set the promotion to end. Is NULL for promotions that you want active indefinitely. |
|
|
MaximumOrdersNumber |
Int |
|
|
|
When the maximum number of orders is reached the promotion stops. Can be NULL if you want the promotion to apply to an unlimited number of orders. |
|
|
MaximumQuantity |
Int |
|
|
|
Discount only applies to a specific number of product, smaller than the maximum quantity you defined. Can be NULL if you want the promotion to apply to an unlimited number units. Any extra quantity added to the cart will be sold at full price. |
|
|
InstantDiscount |
Boolean |
|
|
|
Selecting the instant discount option will auto-apply the discount for ALL the selected products for all shoppers, without the need to enter the discount coupon. |
|
|
Coupon |
String |
|
|
|
The promotion/voucher for which you are extracting the information. |
|
|
DiscountLabel |
String |
|
|
|
Discounts can be set as a percentage from the product price or as a fixed amount in the chosen currency. |
|
|
Enabled |
Boolean |
|
|
|
Can be TRUE if promotion is enabled, or FALSE if otherwise. | |
|
Currency |
String |
|
|
|
Currency code available for the default currency of FIXED promotions. Missing for PERCENT promotions. |
|
|
Code |
String |
|
|
|
Unique, system-generated identifier Avangate associates with promotion campaigns. |
|
|
PriceThreshold |
Object |
|
|
|
Limits discount use only when total order value (taxes included) exceeds the threshold you configure. |
|
|
|
Amount |
Decimal |
|
|
|
The minimum threshold you defined for the default currency. |
|
|
Currency |
String |
|
|
|
Currency code available for the default currency of custom threshold settings. |
iDEAL
Overview
Standardized online banking-based payment method tailored to users in The Netherlands. iDEAL supports online payments via secure online transfers directly between bank accounts. With the participation of ABN AMRO, bunq, ASN, ING, Knab, Rabobank, RegioBank, SNS Bank, Triodos Bank, Van Lanschot Bankiers, Moneyou and Handelsbanken, nearly 97% of the Dutch consumers can be reached with iDEAL. About 75% of the consumers of these banks use internet banking. No less than 60% of all Dutch online shoppers use iDEAL, totaling 13 million transactions monthly. iDEAL supports the one-page checkout purchase flow.
Direct Debit must be enabled on your account in order to support recurring billing.
Workflow
- When placing the order, shoppers in the Netherlands can select iDeal as a payment option and choose their bank.
- Customers will have to access the online banking environment of the bank they selected, and follow the instructions presented to them in order to process the transaction.
SEPA compliance
In the process of supporting recurring payments, 2Checkout also adapted the iDEAL implementation for full SEPA compliance.
Recurrent billing support
- Dutch shoppers purchase subscriptions using iDEAL, and opt to be automatically charged for future renewals.
- 2Checkout receives the payment confirmation along with their bank account information.
- 2Checkout subsequently uses the bank account details received for the iDEAL transaction initially authorized to automatically charge customers through Direct Debit, collecting funds directly from their bank accounts when renewing their subscriptions.
Product group
Overview
Use the ProductGroup object to create/add and update/edit product groups.
Parameters
| Parameters | Type/Description |
|---|---|
|
Name |
Required (string) |
|
|
The name of the product group. |
|
TemplateName |
Optional (string) |
|
|
Leave empty to assign the Default Template to the product.
Or use the name of an active shopping cart template. |
|
Description |
Optional (string) |
|
|
The description of the product group. |
Shipping fees
Overview
Use this object to retrieve information about shipping fees.
Parameters
|
ShippingFee |
Array of objects |
|
Name |
String |
|
|
The name of the shipping fee configuration. |
| Code | String |
| Unique, system-generated shipping fee identifier. | |
|
Amount |
String |
|
|
The shipping costs |
|
Currency |
String |
|
|
The currency ISO code used for shipping costs - ISO 4217. |
|
ApplyTo |
String |
|
|
Possible values: • PRODUCT • ORDER |
|
Type |
String
|
|
Possible values: • FIXED • PERCENT |