Import product data using XML files
Overview
2Checkout recommends that you use XML when importing product and pricing data into the system.
Availability
Importing XML files is available for all 2Checkout accounts.
Requirements
It's recommended that at least one product be configured in the 2Checkout system. This way you'll be able to download the offerings as an XML and access a schema that best fits your specific account.
Product
Use the Product object to create/add, update/edit, and retrieve subscription plans/products for your account. You can control:
Product information
Pricing
Subscription plan settings and renewal configuration
Subscription plan recurring billing
Fulfillment
Shipping classes
Localization
Import limitations
For optimal performance, we recommend importing batches of 20 to 30 products at once, and using XML files smaller than 750 MB.
At this point in time, the Import from URL functionality is not available for XML files.
Mandatory elements
Below is an example of the minimum required data for the importing process when using XML files:
Product
<Product id="1234567" enabled="1"> - product is enabled
<Product id="1234567" > - product is disabled
<Product id="1234567" enabled="0"> - product is disabled
Existent
Missing
Product is updated
Existent
Existent
Product is updated
Existent
New (is ignored)
Product is updated
New
New (is ignored)
New product is added
New
Missing
New product is added
New
Existent
New product is added
Product code
Make sure to set unique product codes to identify your products in the 2Checkout system. In scenarios involving product import and export, the product code takes precedence over the product ID, which can be excluded altogether. While the system-generated ID is unique across the platform, the product code that you control needs to be unique only for standalone accounts. This enables you to perform such tasks as product migration from one 2Checkout account to another.
Pricing configuration
To import a product with the minimum required information, the Pricing configuration element must be included, along with the default currency. All other elements can be omitted.
How do I import an XML file?
To import existing product data from the 2Checkout platform:
Make your way to Products under Setup.
Click on Import.
Click Choose file and select the XML stored on your machine.
Hit Next step.
The 2Checkout system validates the XML file.
Click Start upload.
Parameters
Additional fields
AdditionalField
Object
Label
String
Field text.
Code
String
Field identifier. Alpha-numeric chars, underscores and dashes.
Type
String
Field type:
LISTBOX
CHECKBOX
TEXTBOX
HIDDEN
ApplyTo
String
ORDER
PRODUCT
Values
Array of values
Custom values you control.
ValidationRule
String
The validation rule restricting the type of information shoppers can enter in the additional field during the purchase process.
Translations
Array of objects
Details below.
Translation.Label
String
Field text translated in the language of the Translations object.
Translation.Values
Object
Custom values you control translated in the language of the Translations object.
Translation.Language
String
ISO language code (ISO 639-1 two-letter code).
Pricing
PriceOptionsGroup
Object
Name
String
Price option group name. Use when adding a new group. To edit a group's name use the Name parameter under Translations.
Description
String
Pricing option group description.
Translations
Array of objects
Localized Name/Description and Language (ISO 639-1 code).
Translations.Name
String Product pricing options group name, localized under Options.
Translations.Description
String Product pricing options group description, localized under Options.
Translations.Language
String ISO language code. (ISO 639-1 two-letter code).
Code
String
Unique code system generates or you set for each pricing options group.
Type
String
RADIO
CHECKBOX
INTERVAL
COMBO
Options
Array of objects
Pricing option children.
Options.Name
String Pricing option child name.
Options.Description
String Pricing option child description.
Options.Translations
Array of objects Details above.
Options.Translations.Name
String Localized product pricing options group name under PriceOptionGroup.
Localized pricing option child name under Options.
Options.Translations.Description
String Localized product pricing options group description under PriceOptionGroup.
Localized pricing option child description under Options.
Options.Translations.Language
String ISO language code. (ISO 639-1 two-letter code).
Options.Code
String The code you set or that the Avangate system generated for each pricing option child inside a pricing options group parent.
Options.ScaleMin
Int The minimum value of a scale interval set for each pricing option child inside a pricing options group parent of the type INTERVAL.
Options.ScaleMax
Int The maximum value of a scale interval set for each pricing option child inside a pricing options group parent of the type INTERVAL.
Options.SubscriptionImpact
Object Details below.
Options.Months
String The value in months the Avangate system adds or subtracts from the initial billing cycle of a subscription.
Options.Impact
String Possible values:
ADD
SUBTRACT
LIFETIME
Options.PriceImpact
Object Details below.
Options.PriceImpact.ImpactOn
String
Possible values:
BASE corresponding to impact on base price
GLOBAL for impact on calculated sum.
Options.PriceImpact.Impact
String
Impact on price per unit:
ADD
SUBTRACT
Options.PriceImpact.Percent
String The value of the percentage out of the price per product unit, when you use PERCENT for Method.
Options.PriceImpact.Method
String Possible values:
PERCENT
FIXED
Options.PriceImpact.Amounts
Array of objects Details below.
Options.PriceImpact.Amounts.Currency
String Currency ISO code - ISO 4217.
Options.PriceImpact.Amounts.Amount
String The amount defined for each specific currency active for your account, when you use FIXED for Method.
Options.Default
Boolean TRUE for preselected options.
Missing for options that are not preselected.
Required
Boolean (0/1) True if you made the pricing option group mandatory.
Product
This object contains many fields. Key parameters:
Product
Object
AvangateId
Int
Unique system-generated product ID (read-only).
ProductCode
String
Product code you define; must be unique.
ProductType
String
REGULAR
BUNDLE
ProductName
String
ProductVersion
String
GroupName
String
Product Group name (cannot be edited via addProduct).
ShippingClass
Object
Existing shipping class object with the structure detailed below.
ShippingClass.Name
String The name of the shipping class
ShippingClass.Amount
Decimal The shipping costs
ShippingClass.Currency
String The currency ISO code used for shipping costs - ISO 4217.
ShippingClass.ApplyTo
String Possible values:
PRODUCT
ORDER
ShippingClass.Type
Possible values:
FIXED
PERCENT
GiftOption
Boolean True or false depending on whether the product can be gifted or not.
ShortDescription
String The product's short description
LongDescription
String The product's long description
SystemRequirements
String System requirements
ProductCategory
String Product category
Platforms
Array of Platform objects Array of objects detailing the platforms supported by the application. Details below.
Platforms.PlatformName
String The label of the platform per the product configuration.
Platforms.Category
String Platform category per product configuration.
ProductImages
Array of Image objects Image object. Details below. Read-only.
ProductImages.Default
Boolean True or False depending on whether you set the image stored at the address in the URL parameter as default or not.
ProductImages.URL
String The location of the image on the Avangate system.
TrialUrl
String (anyURI) The URL from where shoppers can download trial software.
TrialDescription
String Descriptive text entered for trials.
Enabled
Boolean True/false depending on whether the products are active or disabled. When empty, Avangate marks the product as disabled.
AdditionalFields
Array of AdditionalFieldAssigned objects Array of existing additional fields assigned to products. Details below.
AdditionalFields.Label
String The name of the additional field assigned to a product.
AdditionalFields.Code
String The code of the additional field assigned to a product.
AdditionalFields.Enabled
Boolean True or false depending on whether the assigned product field is enabled or not.
AdditionalFields.Required
Boolean True or false depending on whether the assigned product field is required or not.
AdditionalFields.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 Details below.
Translations.LongDescription
String The translated long description in the language corresponding to the Translation object.
Translations.TrialUrl
String The trial URL for users speaking the language corresponding to the Translation object.
Translations.TrialDescription
String
Translations.SystemRequirements
String Localized system requirements.
Translations.Name
String Localized product name.
Translations.Description
String Localized product short description.
Translations.Language
String ISO 639-1 two-letter code.
PricingConfigurations
Array of PricingConfiguration objects Details below. Avangate creates pricing configurations during the process when you add a product.
PricingConfigurations.Name
String Pricing configuration name
PricingConfigurations.Code
String System-generated identifier.
PricingConfigurations.Default
Boolean (0/1) True for the default pricing configuration
PricingConfigurations.BillingCountries
Array of strings ISO codes of the countries assigned to the pricing configuration.
Empty unless specific countries are assigned to a pricing configuration.
PricingConfigurations.PricingSchema
String
DYNAMIC – With a base price
FLAT – Without a base price
PricingConfigurations.PriceType
String Possible values: NET / GROSS
PricingConfigurations.DefaultCurrency
String The ISO code of the default currency for the pricing configuration
PricingConfigurations.Prices
Object Details below.
PricingConfigurations.Regular
Array of objects Details below.
PricingConfigurations.Amount
Int The price of the product.
PricingConfigurations.Currency
String ISO code of the currency for the product price.
PricingConfigurations.MinQuantity
Int The minimum quantity of volume discounts. Default is 1.
PricingConfigurations.MaxQuantity
Int The maximum quantity of volume discounts. Default is 99999.
PricingConfigurations.OptionCodes
Array of objects Details below.
PricingConfigurations.Code
String Price option identifier.
PricingConfigurations.Options
Array of strings The pricing options group option code you configured that the Avangate system uses to calculate product prices for pricing configurations without a base price.
PricingConfigurations.Renewal
Array of objects Details below.
PricingConfigurations.Amount
Int The price of the product.
PricingConfigurations.Currency
String ISO code of the currency for the product price.
PricingConfigurations.MinQuantity
Int The minimum quantity of volume discounts. Default is 1.
PricingConfigurations.MaxQuantity
Int The maximum quantity of volume discounts. Default is 99999.
PricingConfigurations.OptionCodes
Array of PriceOptionCode objects Details below.
PricingConfigurations.Code
String Price option identifier.
PricingConfigurations.Options
Array of strings The pricing options group option code you configured that the Avangate system uses to calculate product prices for pricing configurations without a base price.
PricingConfigurations.PriceOptions
Array of AssignedPriceOptionGroup objects Details below.
PricingConfigurations.Code
String System generated pricing options group code (you can also configure it) that the Avangate system uses to calculate product prices for pricing configurations without a base price.
PricingConfigurations.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 Details below.
BundleProducts.ProductId
String Unique, system-generated product ID.
BundleProducts.ProductCode
String Editable product code that you control.
Fulfillment
String BY_AVANGATE
NO_DELIVERY – The Avangate system finalizes orders immediately after it receives payment confirmation.
BY_VENDOR – you are responsible for delivering/fulfilling orders
Prices
Array of Price objects Use this object only when Pricing Configurations are not available for your account. Details below.
Prices.Amount
Int The price of the product.
Prices.Currency
String ISO code of the currency for the product price.
Prices.MinQuantity
Int The minimum quantity of volume discounts. Default is 1.
Prices.MaxQuantity
Int The maximum quantity of volume discounts. Default is 99999.
Prices.OptionCodes
Array of objects Details below.
Prices.Code
String Price option identifier.
Prices.Options
Array of strings The pricing options group option code you configured that the Avangate system uses to calculate product prices for pricing configurations without a base price.
GeneratesSubscription
Boolean 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 Details below. NULL for bundles which you set to use the renewal settings of child products and not of the parent bundle.
SubscriptionInformation.DeprecatedProducts
Array Deprecated products.
SubscriptionInformation.BundleRenewalManagement
String Possible values:
GLOBAL
INDIVIDUAL
Can be NULL.
SubscriptionInformation.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)
SubscriptionInformation.BillingCycleUnit
String The units of the billing cycle:
M - months
D - days
SubscriptionInformation.IsOneTimeFee
Boolean True or False depending on whether the subscription is evergreen or not.
SubscriptionInformation.ContractPeriod
Object Details below.
SubscriptionInformation.Period
Int The contract period in months or days. -1 for unlimited contracts.
SubscriptionInformation.PeriodUnits
String The contract period units
days | months
SubscriptionInformation.IsUnlimited
Boolean This flag is true if the contract is for an unlimited period
SubscriptionInformation.Action
String The action performed after the subscription expires.
Possible values CANCEL | RESTART
SubscriptionInformation.EmailsDuringContract
Boolean True or False depending on whether you suppress renewal notification emails throughout the duration of the contract or not.
SubscriptionInformation.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 Avangate system attempts to automatically charge customers for recurring costs and additional metered usage fees (in arrears). Avangate 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.
SubscriptionInformation.GracePeriod
Object
SubscriptionInformation.Type
String CUSTOM – you configured grace period setting at product level.
GLOBAL – global grace period settings apply.
SubscriptionInformation.Period
String Number of days set for the grace period.
SubscriptionInformation.PeriodUnits
String D - Days.
SubscriptionInformation.IsUnlimited
Boolean True or False depending on whether you set the grace peri2od to unlimited or not.
SubscriptionInformation.RenewalEmails
Object Details below. Can be NULL. Available only in Product API 2.5 and later.
SubscriptionInformation.Type
String GLOBAL - Send emails according to the global renewal notification settings.
CUSTOM – per product renewal notification settings
SubscriptionInformation.Settings
Object (can be NULL) Details below.
SubscriptionInformation.ManualRenewal
Object (can be NULL) Details below.
SubscriptionInformation.Before30Days
Boolean True or False.
SubscriptionInformation.Before15Days
Boolean True or False.
SubscriptionInformation.Before7Days
Boolean True or False.
SubscriptionInformation.Before1Days
Boolean True or False.
SubscriptionInformation.OnExpirationDate
Boolean True or False.
SubscriptionInformation.After5Days
Boolean True or False.
SubscriptionInformation.After15Days
Boolean True or False.
SubscriptionInformation.AutomaticRenewal
Object (can be NULL) Details below.
SubscriptionInformation.Before30Days
Boolean True or False.
SubscriptionInformation.Before15Days
Boolean True or False.
SubscriptionInformation.Before7Days
Boolean True or False.
SubscriptionInformation.Before1Day
Boolean True or False.
SubscriptionInformation.OnExpirationDate
Boolean True or False.
SubscriptionInformation.After5Days
Boolean True or False.
SubscriptionInformation.After15Days
Boolean True or False.
FulfillmentInformation
Object Details below. Can be NULL. Available only in Product API 2.5 and later.
FulfillmentInformation.IsStartAfterFulfillment
Boolean True or False. Depending on whether you want the subscription lifetime to start after the completion of the fulfillment process or not.
FulfillmentInformation.IsElectronicCode
Boolean True or False. Depending on whether you configure the delivery of keys/codes for the product or not.
FulfillmentInformation.IsDownloadLink
Boolean True or False. Depending on whether you configure the delivery of a product file or not.
FulfillmentInformation.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.
FulfillmentInformation.IsInstantDeliveryThankYouPage
Boolean True or False. Depending on whether you enable instant delivery in the Thank You page or not.
FulfillmentInformation.IsDisplayInPartnersCPanel
Boolean True or False. Depending on whether you share access to the product file with your channel partners or not.
FulfillmentInformation.CodeList
Object (can be NULL) Details below.
FulfillmentInformation.Code
String The unique code list identifier.
FulfillmentInformation.Name
String Name of the code list.
FulfillmentInformation.Type
String
Code list type:
STATIC
DYNAMIC
FulfillmentInformation.ProductFile
Object (can be NULL) Details below.
FulfillmentInformation.Code
String Unique product file identifier.
FulfillmentInformation.Name
String Display name.
FulfillmentInformation.File
String Name of the product file.
FulfillmentInformation.Version
String File version.
FulfillmentInformation.Size
String File size.
FulfillmentInformation.Type
String File type.
FulfillmentInformation.LastUpdate
String YYYY-MM-DD HH-MM-SS. Date time stamp when you last updated the file.
FulfillmentInformation.AdditionalInformationByEmail
String (can be NULL) The text you set up in the Additional fulfillment information - by email area.
FulfillmentInformation.AdditionalInformationEmailTranslations
Object (can be NULL) Array of localized Additional fulfillment information - by email texts.
FulfillmentInformation.AdditionalThankYouPage
String (can be NULL) The text you set up in the Additional fulfillment information - "Thank you" page area.
FulfillmentInformation.AdditionalThankYouPageTranslations
Array (can be NULL) Array of localized Additional fulfillment information - "Thank you" page texts.
Related links
Last updated
Was this helpful?