Skip to main content
knowledgecenter.avangate.com

Import product data using XML files

Overview

Avangate recommends that you use XML when importing product and pricing data into the system.

Availability

Importing XML files is available for all Avangate accounts.

Requirements

It's recommended that at least one product be configured in the Avangate system. This way you'll be able to download the offerings as a 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:

<?xml version="1.0" encoding="UTF-8"?>
<Import>
<Products>
<Product enabled="1">
<ProductName><![CDATA[Product for import]]></ProductName>
<ProductCode><![CDATA[productforimportCODE12345]]></ProductCode>
<PricingConfigurations>
<PricingConfiguration default="1"><DefaultCurrency>EUR</DefaultCurrency></PricingConfiguration>
</PricingConfigurations>
</Product>
</Products>
</Import>

 

Product

<Product id="1234567" enabled="1"> - product is enabled

<Product id="1234567" > - product is disabled

<Product id="1234567" enabled="0"> - product is disabled

 

Product code (mandatory )

Product ID (optional)

Result

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 Avangate 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 Avangate 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 Avangate platform:

  1. Make your way to Products under Setup.
  2. Click on Import.
  3. Click Choose file and select the XML stored on your machine.
  4. Hit Next step.
  5. The Avangate system validates the XML file.
  6. 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
  • TEXT
  • HIDDEN

ApplyTo

Sting

 

  • 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

Object

Label

String

 

Field text translated in the language of the Translations object.

Values

Object

 

Custom values you control translated in the language of the Translations object.

Language

String

 

ISO language code. (ISO 639-1 two-letter code).

Pricing

Use this object to add/create and edit/update price options for your account.

 

PriceOptionsGroup

Object

Name

String

 

Price option group name. Use this parameter when adding a new price options group. To edit the name of a price option group use the Name parameter under the Translations object.

Description

String

 

Pricing option group description.

Translations

Array of objects

 

Details below.

 

Name

String

 

 

Product pricing options group name, localized under Options.

 

Description

String

 

 

Product pricing options group description, localized under Options.

 

Language

String

 

 

ISO language code. (ISO 639-1 two-letter code).

Code

String

 

Unique code that The Avangate system generates or set for each pricing options group.

Type

String

 

The type of the pricing options group. Possible values:

· RADIO

· CHECKBOX

· INTERVAL

· COMBO

Options

Array of objects

 

Details below.

 

Name

String

 

 

Pricing option child name.

 

Description

String

 

 

Pricing option child description.

 

Translations

Array of objects

 

 

Details above.

 

 

Name

String

 

 

 

Localized product pricing options group name under PriceOptionGroup.

Localized pricing option child name under Options.

 

 

Description

String

 

 

 

Localized product pricing options group description under PriceOptionGroup.

Localized pricing option child description under Options.

 

 

Language

String

 

 

 

ISO language code. (ISO 639-1 two-letter code).

 

Code

String

 

 

The code you set or that the Avangate system generated for each pricing option child inside a pricing options group parent.

 

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.

 

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.

 

SubscriptionImpact

Object

 

 

Details below.

 

Months

String

 

 

The value in months the Avangate system adds or subtracts from the initial billing cycle of a subscription.

 

Impact

String

 

 

Possible values:

· ADD

· SUBTRACT

· LIFETIME

 

PriceImpact

Object

 

 

Details below.

 

 

ImpactOn

String

 

 

 

Possible values:

  • BASE corresponding to impact on base price
  • GLOBAL for impact on calculated sum.

 

 

Impact

String

 

 

 

Impact on price per unit:

  • ADD
  • SUBTRACT

 

 

Percent

String

 

 

 

The value of the percentage out of the price per product unit, when you use PERCENT for Method.

 

 

Method

String

 

 

 

Possible values:

· PERCENT

· FIXED

 

 

Amounts

Array of objects.

 

 

 

Details below.

 

 

 

Currency

String

 

 

 

 

Currency ISO code - ISO 4217.

 

 

 

Amount

String

 

 

 

 

The amount defined for each specific currency active for your account, when you use FIXED for Method.

 

Default

Boolean

 

 

TRUE for preselected options.

Missing for options that are not preselected.

Required

boolean

 

True if you made the pricing option group mandatory.

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

 

Product

 

Object

AvangateId

Int

 

Unique, system-generated Avangate product ID. Read-only.

ProductCode

String

 

The product code that you can define for each of your offerings. Needs to be unique.

ProductType

String

 

REGULAR or BUNDLE

ProductName

String

 

The name of the product

ProductVersion

String

 

The product version number

GroupName

String

 

The name of the Product Group to which the product belongs

ShippingClass

Object

 

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

 

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.

 

PlatformName

String

 

 

The label of the platform per the product configuration.

 

Category

String

 

 

Platform category per product configuration. 

ProductImages

Array of Image objects

 

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 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.

 

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

 

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

 

Details below. Avangate 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 Avangate 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 Avangate 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 Avangate 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

 

Details below.

 

ProductId

String

 

 

Unique, system-generated product ID.

 

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.

 

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 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.

 

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 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.

 

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 peri2od 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

 

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.

 

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.