Product
Overview
Use the Product object to create, update and retrieve subscription plans/products for your account. Use 2Checkout's API and control the following product attributes:
- Product information
- Pricing
- Subscription plan settings and renewal configuration
- Subscription plan recurring billing
- Fulfillment
- Shipping classes
- Localization
Parameters
Use the parameters below to add new products into your 2Checkout catalog.
| Parameters | Type/Description | |
|---|---|---|
|
Product
|
Object / Required Product details. |
|
|
ProductCode |
String / Required |
|
|
|
The product code that you can define for each of your offerings. Needs to be unique. |
|
| ProductGroupCode | String/Required | |
|
The product code that you can define for each product group. Needs to be unique. |
||
| TaxCategory | String/Required | |
| The tax category to which the product belongs. | ||
|
ProductType |
String / Optional |
|
|
|
REGULAR or BUNDLE Defaults to REGULAR. |
|
|
ProductName |
String / Required |
|
|
|
The name of the product |
|
|
ProductVersion |
String / Optional |
|
|
|
The product version number |
|
| PurchaseMultipleUnits | Boolean / Optional | |
|
Possible values:
The default value is TRUE. |
||
|
ShippingClass |
Object / Optional |
|
|
|
Existing shipping class object with the structure detailed below. |
|
|
|
Name |
String |
|
|
|
The name of the shipping class |
|
|
Amount |
Decimal |
|
|
|
The shipping costs |
|
|
Currency |
String |
|
|
|
The currency ISO code used for shipping costs - ISO 4217. |
|
|
ApplyTo |
String |
|
|
|
Possible values: • PRODUCT • ORDER |
|
|
Type |
Possible values: • FIXED • PERCENT |
|
GiftOption |
Boolean / Optional |
|
|
|
True or false depending on whether the product can be gifted or not. |
|
|
ShortDescription |
String / Optional |
|
|
|
The product's short description |
|
|
LongDescription |
String / Optional |
|
|
|
The product's long description |
|
|
SystemRequirements |
String / Optional |
|
|
|
System requirements |
|
|
ProductCategory |
String / Optional |
|
|
|
Product category |
|
|
Platforms |
Array of Platform objects / Optional |
|
|
|
Array of objects detailing the platforms supported by the application. Details below. |
|
|
|
PlatformName |
String |
|
|
|
The label of the platform per the product configuration. |
|
|
Category |
String |
|
|
|
Platform category per product configuration. |
|
ProductImages |
Array of Image objects / Optional |
|
|
|
Image object. Details below. Read-only. |
|
|
|
Default |
Boolean |
|
|
|
True or False depending on whether you set the image stored at the address in the URL parameter as default or not. |
|
|
URL |
String |
|
|
|
The location of the image on the 2Checkout system. |
|
TrialUrl |
String (anyURI) / Optional |
|
|
|
The URL from where shoppers can download trial software. |
|
|
TrialDescription |
String / Optional |
|
|
|
Descriptive text entered for trials. |
|
|
Enabled |
Boolean / Optional |
|
|
|
True/false depending on whether the products are active or disabled. When empty, 2Checkout marks the product as disabled. |
|
|
AdditionalFields |
Array of AdditionalFieldAssigned objects / Optional |
|
|
|
Array of existing additional fields assigned to products. Details below. |
|
|
|
Label |
String |
|
|
|
The name of the additional field assigned to a product. |
|
|
Code |
String |
|
|
|
The code of the additional field assigned to a product. |
|
|
Enabled |
Boolean |
|
|
|
True or false depending on whether the assigned product field is enabled or not. |
|
|
Required |
Boolean |
|
|
|
True or false depending on whether the assigned product field is required or not. |
|
|
URLParameter |
String |
|
|
|
The value of the system generated URL parameter for the product field that can be used in Buy Links. |
|
Translations |
Array of ProductTranslation objects / Optional |
|
|
|
Details below. |
|
|
|
LongDescription |
String |
|
|
|
The translated long description in the language corresponding to the Translation object. |
|
|
TrialUrl |
String |
|
|
|
The trial URL for users speaking the language corresponding to the Translation object. |
|
|
TrialDescription |
String |
|
|
|
|
|
|
SystemRequirements |
String |
|
|
|
Localized system requirements. |
|
|
Name |
String |
|
|
|
Localized product name. |
|
|
Description |
String |
|
|
|
Localized product short description. |
|
|
Language |
String |
|
|
|
ISO 639-1 two-letter code. |
|
PricingConfigurations |
Array of PricingConfiguration objects / Optional |
|
|
|
Details below. 2Checkout creates pricing configurations during the process when you add a product. |
|
|
|
Name |
String |
|
|
|
Pricing configuration name |
|
|
Code |
String |
|
|
|
System-generated identifier. |
|
|
Default |
boolean |
|
|
|
True for the default pricing configuration |
|
|
BillingCountries |
Array of strings |
|
|
|
ISO codes of the countries assigned to the pricing configuration. Empty unless specific countries are assigned to a pricing configuration. |
|
|
PricingSchema |
String |
|
|
|
DYNAMIC – With a base price FLAT – Without a base price |
|
|
PriceType |
String |
|
|
|
Possible values: NET / GROSS |
|
|
DefaultCurrency |
String |
|
|
|
The ISO code of the default currency for the pricing configuration |
|
|
Prices |
Object |
|
|
|
Details below. |
|
|
Regular |
Array of objects |
|
|
|
Details below. |
|
|
Amount |
Int |
|
|
|
The price of the product. |
|
|
Currency |
String |
|
|
|
ISO code of the currency for the product price. |
|
|
MinQuantity |
Int |
|
|
|
The minimum quantity of volume discounts. Default is 1. |
|
|
MaxQuantity |
Int |
|
|
|
The maximum quantity of volume discounts. Default is 99999. |
|
|
OptionCodes |
Array of objects |
|
|
|
Details below. |
|
|
Code |
String |
|
|
|
Price option identifier. |
|
|
Options |
Array of strings |
|
|
|
The pricing options group option code you configured that the 2Checkout system uses to calculate product prices for pricing configurations without a base price. |
|
|
Renewal |
Array of objects |
|
|
|
Details below. |
|
|
Amount |
Int |
|
|
|
The price of the product. |
|
|
Currency |
String |
|
|
|
ISO code of the currency for the product price. |
|
|
MinQuantity |
Int |
|
|
|
The minimum quantity of volume discounts. Default is 1. |
|
|
MaxQuantity |
Int |
|
|
|
The maximum quantity of volume discounts. Default is 99999. |
|
|
OptionCodes |
Array of PriceOptionCode objects |
|
|
|
Details below. |
|
|
Code |
String |
|
|
|
Price option identifier. |
|
|
Options |
Array of strings |
|
|
|
The pricing options group option code you configured that the 2Checkout system uses to calculate product prices for pricing configurations without a base price. |
|
|
PriceOptions |
Array of AssignedPriceOptionGroup objects |
|
|
|
Details below. |
|
|
Code |
String |
|
|
|
System generated pricing options group code (you can also configure it) that the 2Checkout system uses to calculate product prices for pricing configurations without a base price. |
|
|
Required |
Boolean |
|
|
|
True or False depending on whether you want to make it mandatory for shoppers to select the price option during the puyrchase process. |
|
BundleProducts |
Array of BundleProductCode objects / Optional |
|
|
|
Details below. |
|
|
|
ProductId |
String |
|
|
|
Unique, system-generated product ID. |
|
|
ProductCode |
String |
|
|
|
Editable product code that you control. |
|
Fulfillment |
String / Required |
|
|
|
BY_AVANGATE NO_DELIVERY – The 2Checkout system finalizes orders immediately after it receives payment confirmation. BY_VENDOR – you are responsible for delivering/fulfilling orders |
|
|
Prices |
Array of Price objects / Required |
|
|
|
Use this object only when Pricing Configurations are not available for your account. Details below. |
|
|
|
Amount |
Int |
|
|
|
The price of the product. |
|
|
Currency |
String |
|
|
|
ISO code of the currency for the product price. |
|
|
MinQuantity |
Int |
|
|
|
The minimum quantity of volume discounts. Default is 1. |
|
|
MaxQuantity |
Int |
|
|
|
The maximum quantity of volume discounts. Default is 99999. |
|
|
OptionCodes |
Array of objects |
|
|
|
Details below. |
|
|
Code |
String |
|
|
|
Price option identifier. |
|
|
Options |
Array of strings |
|
|
|
The pricing options group option code you configured that the 2Checkout system uses to calculate product prices for pricing configurations without a base price. |
|
GeneratesSubscription |
Boolean / Required |
|
|
|
TRUE or FALSE depending on whether you set the product to generate subscriptions or not.
NULL for bundles for which you set the following subscription management option: “Use the subscription settings of each product in the bundle” |
|
|
SubscriptionInformation |
ProductSubscriptionInformation Object / Optional |
|
|
|
Details below. NULL for bundles which you set to use the renewal settings of child products and not of the parent bundle. |
|
|
|
DeprecatedProducts |
Array |
|
|
|
Deprecated products. |
|
|
BundleRenewalManagement String |
|
|
|
|
Possible values:
Can be NULL. |
|
|
BillingCycle |
String |
|
|
|
The number of subscription billing cycle units (months or days). Possible values:
Days
Months
|
|
|
BillingCycleUnits |
String |
|
|
|
The units of the billing cycle:
D - days |
|
|
IsOneTimeFee |
Boolean |
|
|
|
True or False depending on whether the subscription is evergreen or not. |
|
|
ContractPeriod |
Object |
|
|
|
Details below. |
|
|
Period |
Int |
|
|
|
The contract period in months or days. -1 for unlimited contracts. |
|
|
PeriodUnits |
String |
|
|
|
The contract period units days | months |
|
|
IsUnlimited |
Boolean |
|
|
|
This flag is true if the contract is for an unlimited period |
|
|
Action |
String |
|
|
|
The action performed after the subscription expires. Possible values CANCEL | RESTART |
|
|
EmailsDuringContract Boolean |
|
|
|
|
True or False depending on whether you suppress renewal notification emails throughout the duration of the contract or not. |
|
|
UsageBilling |
Int |
|
|
|
The usage billing interval must be smaller than or equal to the grace period.
Interval of time within the grace period, when the 2Checkout system attempts to automatically charge customers for recurring costs and additional metered usage fees (in arrears). 2Checkout renews subscriptions only after subscribers make all outstanding payments per the renewal settings (from the expiration or the renewal date). If automatic renewal and usage charges fail, subscriptions can be manually renewed only by the end of the grace period, after which they expire.
Can be NULL. |
|
|
GracePeriod |
Object |
|
|
Type |
String |
|
|
|
CUSTOM – you configured grace period setting at product level. GLOBAL – global grace period settings apply. |
|
|
Period |
String |
|
|
|
Number of days set for the grace period. |
|
|
PeriodUnits |
String |
|
|
|
D - Days. |
|
|
IsUnlimited |
Boolean |
|
|
|
TRUE or FALSE depending on whether you set the grace period to unlimited or not. |
|
|
RenewalEmails |
Object |
|
|
|
Details below. Can be NULL. Available only in Product API 2.5 and later. |
|
|
Type |
String |
|
|
|
GLOBAL - Send emails according to the global renewal notification settings. CUSTOM – per product renewal notification settings |
|
|
Settings |
Object (can be NULL) |
|
|
|
Details below. |
|
|
ManualRenewal |
Object (can be NULL) |
|
|
|
Details below. |
|
|
Before30Days |
Boolean |
|
|
|
True or False. |
|
|
Before15Days |
Boolean |
|
|
|
True or False. |
|
|
Before7Days |
Boolean |
|
|
|
True or False. |
|
|
Before1Day |
Boolean |
|
|
|
True or False. |
|
|
OnExpirationDate |
Boolean |
|
|
|
True or False. |
|
|
After5Days |
Boolean |
|
|
|
True or False. |
|
|
After15Days |
Boolean |
|
|
|
True or False. |
|
|
AutomaticRenewal |
Object (can be NULL) |
|
|
|
Details below. |
|
|
Before30Days |
Boolean |
|
|
|
True or False. |
|
|
Before15Days |
Boolean |
|
|
|
True or False. |
|
|
Before7Days |
Boolean |
|
|
|
True or False. |
|
|
Before1Day |
Boolean |
|
|
|
True or False. |
|
|
OnExpirationDate |
Boolean |
|
|
|
True or False. |
|
|
After5Days |
Boolean |
|
|
|
True or False. |
|
|
After15Days |
Boolean |
|
|
|
True or False. |
|
FulfillmentInformation |
Object / Optional |
|
|
|
Details below. Can be NULL. Available only in Product API 2.5 and later. |
|
|
|
IsStartAfterFulfillment |
Boolean |
|
|
|
True or False. Depending on whether you want the subscription lifetime to start afther the completion of the fulfillment process or not. |
|
|
IsElectronicCode |
Boolean |
|
|
|
True or False. Depending on whether you configure the delivery of keys/codes for the product or not. |
|
|
IsDownloadLink |
Boolean |
|
|
|
True or False. Depending on whether you configure the delivery of a product file or not. |
|
|
IsBackupMedia |
Boolean |
|
|
|
True or False. Depending on whether you configure the delivery of backup media or not. |
|
|
IsDownloadInsuranceService |
Boolean |
|
|
|
True or False. Depending on whether you enable the Download Insurance Service or not, for a product for which you configure a product file. |
|
|
IsInstantDeliveryThankYouPage |
Boolean |
|
|
|
True or False. Depending on whether you enable instant delivery in the Thank You page or not. |
|
|
IsDisplayInPartnersCPanel |
Boolean |
|
|
|
True or False. Depending on whether you share access to the product file with your channel partners or not. |
| ReturnMethod | Object | |
| Information on the customer redirect method after a successful purchase. | ||
| Type | String | |
|
Possible values:
|
||
| URL | String | |
| Website to which customers are redirected after a successful purchase. Example: "http://mySuccessURL.com" | ||
|
|
CodeList |
Object (can be NULL) |
|
|
|
Details below. |
|
|
Code |
String |
|
|
|
The unique code list identifier. |
|
|
Name |
String |
|
|
|
Name of the code list. |
|
|
Type |
String |
|
|
|
Code list type:
|
|
|
BackupMedia |
Object (can be NULL) |
|
|
|
Details below. |
|
|
Code |
String |
|
|
|
The unique backup media identifier. |
|
|
Name |
String |
|
|
|
Name of the backup CD/DVD. |
|
|
Type |
String |
|
|
|
Media type: CD |
|
|
ProductFile |
Object (can be NULL) |
|
|
|
Details below. |
|
|
Code |
String |
|
|
|
Unique product file identifier. |
|
|
Name |
String |
|
|
|
Display name. |
|
|
File |
String |
|
|
|
Name of the product file. |
|
|
Version |
String |
|
|
|
File version. |
|
|
Size |
String |
|
|
|
File size. |
|
|
Type |
String |
|
|
|
File type. |
|
|
LastUpdate |
String |
|
|
|
YYYY-MM-DD HH-MM-SS. Date time stamp when you last updated the file. |
|
|
AdditionalInformationByEmail |
String (can be NULL) |
|
|
|
The text you set up in the Additional fulfillment information - by email area. |
|
|
AdditionalInformationEmailTranslations |
Object (can be NULL) |
|
|
|
Array of localized Additional fulfillment information - by email texts. |
|
|
AdditionalThankYouPage |
String (can be NULL) |
|
|
|
The text you set up in the Additional fulfillment information - "Thank you" page area. |
|
|
AdditionalThankYouPageTranslations |
Array (can be NULL) |
|
|
|
Array of localized Additional fulfillment information - "Thank you" page texts. |
Integrate Akeeba Subscriptions
Availability
Akeeba Subscriptions integration is available only for 2Checkout accounts that handle their own tax and invoice management (2Sell and 2Subscribe accounts).
Akeeba Subscriptions Settings:
- Login to your Joomla admin.
- Under Extensions click Plugin Manager.
- Select “Akeeba Subscriptions Payment – 2Checkout Standard Purchase Routine”
- Under Status select Enabled.
- Enter your Payment Option Title.
- Enter your 2Checkout Merchant code.
- Enter in your Secret Word (set on 2Checkout Control Panel.) To obtain the Secret Word, contact 2Checkout or, if you already have a 2Checkout account, log in to your Merchant Control Panel and navigate to Dashboard → Integrations → Webhooks & API → Secret Word → INS Secret word. Your INS secret word should be the same as the buy-link secret word (can be found under Dashboard → Integrations → Webhooks & API, scroll down to the Secret Word area, under the INS Secret Word). Edit your INS secret word and buy-link secret word to match each other, then copy and paste them into your Akeeba admin.

- Under Demo mode select No.
- Select whether or not you will be placing demo sales. (INS messages are not sent on demo sales so all demo sales will have a payment status of New and will not be enabled.)
- Select the default payment method for your buyers on the checkout page.
- Under Checkout Process select Single Page.
- Save your changes.
2Checkout Settings:
- Sign in to your 2Checkout account.
- Navigate to Dashboard → Integrations → Webhooks & API
- Follow these steps to activate Redirect URL:
- In the Redirect URL section check “Enable return after sale”
- For Return method, select Link in the Thank You Page or Header redirect
- Set the Approved URL to the URL provided in your Joomla admin (Replace http://yourdomain.com with the actual URL to your domain)
- Click Update to save your settings
- In the Webhooks and API section, under the Instant Notification Service (INS) card, check the Enable Global URL box.
- Enter “http://www.yourdomain.com/index.php?...thod=2checkout” as the Global URL (replace http://www.yourdomain.com with your actual website URL)
- Enable all triggers.
- Click Update to save your changes.
Akeeba Subscriptions
Akeeba Subscriptions is a component for the popular Joomla!™ CMS which allows you to sell subscriptions on your site, the easy way. Integrate directly with Joomla!’s built-in ACL and dozens of popular extensions. It comes with built-in support for 2Checkout’s payment processing service. Limit the displayed content based on your users’ subscription level. Be in control of your business policy with its powerful features. Integrate with the popular ccInvoices component for automatic invoicing. Use it with single- or multi-lingual sites. Comply with EU VAT laws with its powerful Tax Rules feature. And as with the best things in life, Akeeba Subscriptions is available free of charge from https://www.AkeebaBackup.com.
For more information visit: AkeebaBackup.com
Upgrade price
Overview
Retrieve the upgrade price for a subscription.
Attributes
| Parameters | Type/Description |
|---|---|
|
BillingPrice |
Double |
|
|
The price Avangate charges the customer, without taxes. |
|
BillingGrossPrice |
Double |
|
|
The price Avangate charges the customer, including taxes. |
|
BillingCurrency |
String |
|
|
The currency ISO code used for the payment - ISO 4217. |
|
Quantity |
Int |
|
|
The mandatory quantity for the upgrade (you cannot make partial upgrades) |
|
DisplayPrice |
Double |
|
|
Display price. |
|
DisplayGrossPrice |
Double |
|
|
Display price before deductions. |
|
DisplayCurrency |
String |
|
|
Display currency. ISO 4217 code. |
| Discount |
Float |
| Applied discounts | |
| DiscountedProratedPrice | Float |
| Prorated net price for the upgrade with applied discounts | |
| DiscountedProratedGrossPrice | Float |
| Prorated gross price for the upgrade with applied discounts | |
| DiscountedBillingPrice | Float |
| Net billing price available for the upgrade process with applied discounts | |
| DiscountedBillingGrossPrice | Float |
| Gross billing price available for the upgrade process with applied discounts | |
| DisplayDiscount | Float |
| Discount displayed for the upgrade process | |
| DiscountedDisplayPrice | Float |
| Net display price available for the upgrade process with applied discounts | |
| DiscountedDisplayGrossPrice | Float |
| ross display price available for the upgrade process with applied discounts |
Coupons
Overview
Use this section to handle coupons that are part of your promotions.
You can add, update or remove coupons that are configured on your promotional campaigns.
API 3.0
This category is about the JSON API version 3.0 and the methods it uses.
API 4.0
This category contains the methods used by the JSON-RPC API version 4.0.
Affiliates
Overview
The Affiliates object helps you to search and extract information about your affiliates using JSON-RPC API 6.0.
The methods below will return the affiliate(s) details only if they (the affiliates) are associated with the merchant. Otherwise, they will return an error (invalid request). This will happen even if the affiliate code provided belongs to a valid affiliate from the Affiliate Network, but one that's not associated with the vendor making the calls.