updates RSS feed

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:

  • TRUE - customers can purchase multiple units of this product.
  • FALSE - customers can purchase only one unit at a time.

 

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:

  • GLOBAL
  • INDIVIDUAL

Can be NULL.

 

BillingCycle

String

 

 

The number of subscription billing cycle units (months or days).  Possible values:

  • 0 (zero represents a one-time fee)

Days

  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14

 

Months

  • 1
  • 2
  • 3
  • 6
  • 12
  • 15
  • 18
  • 24
  • 36 (max)

 

BillingCycleUnits

String

 

 

The units of the billing cycle:

  • M - months

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:

  • DIRECT_RETURN
  • HEADER_REDIRECT
  • HTML_LINK
            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:

  • STATIC

  • DYNAMIC

 

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:

  1. Login to your Joomla admin.
  2. Under Extensions click Plugin Manager.
  3. Select “Akeeba Subscriptions Payment – 2Checkout Standard Purchase Routine”
  4. Under Status select Enabled.
  5. Enter your Payment Option Title.
  6. Enter your 2Checkout Merchant code.
  7. 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. INS secret word.png
  8. Under Demo mode select No.
  9. 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.)
  10. Select the default payment method for your buyers on the checkout page.
  11. Under Checkout Process select Single Page.
  12. Save your changes.

2Checkout Settings:

  1. Sign in to your 2Checkout account.
  2. Navigate to Dashboard → Integrations → Webhooks & API
  3. 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
  4. In the Webhooks and API section, under the Instant Notification Service (INS) card, check the Enable Global URL box. 
  5. Enter “http://www.yourdomain.com/index.php?...thod=2checkout” as the Global URL (replace http://www.yourdomain.com with your actual website URL)
  6. Enable all triggers.
  7. 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.

Cross-sell

Overview

Cross-selling allows you to recommend additional products to customers and increase the average order value. The 2Checkout Public API supports classic cross-sell campaigns which means you can recommend more products from your own product catalog to your shoppers.

CrossSell Object

Use the CrossSell object to recommend additional products to customers via the 2Checkout API.

Parameters

Parameter Type/Description

MasterProducts

Array

 

Array of product codes for the items you set to trigger the cross-sell campaign.

DisplayType

String

 
  • cart – Shopping cart
  • review – Review page
  • finish – Thank you page

DisplayInEmail

Boolean

 

True or false depending on whether you set the cross-sell campaign to display in payment receipt emails or not.

Products

Array of objects

 

Details below

 

ProductCode

String

 

 

Product code for the item you set as recommended for the cross-sell campaign.

 

Discount

String

 

 

Value of the discount. This is a percentage.

 

DiscountType

String
    PERCENT – you can only set discounts as a percentage from the product price.
  Type String

 

 

Example: Own
  AutoAdded Boolean
  DiscountedPrice Array of objects
    Details below.
                            Currency String
                            Price Float
  BasePrice Array of objects
                            Currency String
                            Price Float

CampaignCode

String

 

Unique, system-generated cross-sell campaign code.

Name

String

 

Campaign name.

StartDate

String

 

YYYY-MM-DD. The start date you set for the cross-sell campaign.

EndDate

String

 

YYYY-MM-DD. The end date you set for the cross-sell campaign.
CampaignStatus String
  The status of the cross-sell campaign.
CampaignOwnerType String
  Campaign owner type: Can be either MERCH or AFF.

 

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