API Migration Guide

Last updated: 29-Sep-2021

Rate this article:

Overview

Use this guide to prepare and migrate your 2Checkout API implementation from version 1.0 to 3.0. This document features deprecations, updates and enhancements, providing guidance on how to upgrade your implementation to the latest version of the 2Checkout API.

API 1.0 discontinuation

2Checkout plans to discontinue API 1.0 as of the end of February 2017. The end-of-support date implies ceasing all development of bug fixes and patches for API 1.0.

API 3.0 availability

Version 3.0 of the 2Checkout API is available as of June 2016, following an extensive public testing phase started in November 2015. 2Checkout recommends that you migrate to the latest version of the API (v3.0) to enjoy support for your implementation.

API 3.0 updates and benefits

Full REST support for existing platform functionalities in addition to SOAP and JSON-RPC.
Simplify interactions with single-entry point (one endpoint, one client, single-authentication).
Centralized all previous functionality under 3.0 (plus new capabilities).
Unified WSDL for Order, Subscription, and Product scenarios.

Serializations 1.0 vs. 3.0

Single API URL per serialization format

https://api.avangate.com/rpc/3.0 /
https://api.avangate.com/soap/3.0 /
https://api.avangate.com/rest/3.0 /
https://api.avangate.com/3.0 / redirects to https://api.avangate.com/rest/3.0 / by default

WSDL 1.0 vs. 3.0

When you migrate from API 1.0 to 3.0, stop using https://secure.2checkout.com/api/merchant/?wsdl in favor of https://api.2checkout.com/soap/3.0/?wsdl.

Methods 1.0 vs. 3.0

API 1.0	Status	API 3.0 equivalent
addLicense	Updated. Use:	addSubscription
addProduct	Deprecated	N/A. The placeOrder scenario now requires a single method.
clearProducts	Deprecated	N/A. The placeOrder scenario now requires a single method.
deleteProduct	Deprecated	N/A. The placeOrder scenario now requires a single method.
disableLicense	Updated. Use:	cancelSubscription
disableLicenseRecurring	Updated. Use:	disableRecurringBilling
enableLicense	Updated. Use:	enableSubscription
enableLicenseRecurring	Updated. Use:	enableRecurringBilling
extendLicense	Updated. Use:	extendSubscription
getAvailableCountries	Updated. Use:	getAvailableCountries
getAvailableCurrencies	Updated. Use:	getAvailableCurrencies
getAvailableLanguages	Updated. Use:	getAvailableLanguages
getContents	Updated. Use:	getContents
getInvoice	Updated. Use:	getInvoices
getLicense	Updated. Use:	getSubscription
getLicensePaymentDetails	Updated. Use:	getPaymentInformation
getLicenseProductUpgradeOptions	Updated. Use:	getProductUpgradeOptions
getNextRenewalPrice	Updated. Use:	getNextRenewalPrice
getOrder	Updated. Use:	getOrder
getOrderStatus	Updated. Use:	getOrder
getPrice	Updated. Use:	getPrice
getProductByCode	Updated. Use:	getProductByCode
getProductById	Updated. Use:	getProductByCode
getProductUpgradeOptionsPrice	Updated. Use:	getProductUpgradeOptionsPrice
getRenewalPrice	Updated. Use:	getRenewalDetails
getSingleSignOn	Updated. Use:	getSingleSignOn
getTimezone	Updated. Use:	getTimezone
isValidOrderReference	Updated. Use:	isValidOrderReference
login	Updated. Use:	login
placeOrder	Updated. Use:	placeOrder
renewLicense	Updated. Use:	renewSubscription
searchLicense	Updated. Use:	getSubscriptions
searchProducts	Updated. Use:	searchProducts
setBillingDetails	Deprecated.	N/A. The placeOrder scenario now requires a single method.
setClientIP	Deprecated.	N/A. The placeOrder scenario now requires a single method.
setCountry	Deprecated.	N/A. The placeOrder scenario now requires a single method.
setCurrency	Deprecated.	N/A. The placeOrder scenario now requires a single method.
setCustomer	Deprecated.	N/A. The placeOrder scenario now requires a single method.
setCustomRenewalPrice	Updated. Use:	setCustomRenewalPrice
setDeliveryDetails	Deprecated.	N/A. The placeOrder scenario now requires a single method.
setExternalRef	Deprecated.	N/A. The placeOrder scenario now requires a single method.
setLanguage	Deprecated.	N/A. The placeOrder scenario now requires a single method.
setLicenseEmailSubscription	Updated. Use:	setRenewalNotificationStatus
setLicenseUpgrade	Updated. Use:	setSubscriptionUpgrade
setPaymentDetails	Deprecated.	N/A. The placeOrder scenario now requires a single method.
setSource	Deprecated.	N/A. The placeOrder scenario now requires a single method.
setStaticPrice	Deprecated.	N/A. The placeOrder scenario now requires a single method.
updateLicense	Updated. Use:	updateSubscription
updateLicenseCustomer	Updated. Use:	updateSubscriptionEndUser

New use cases API 3.0

SOAP	JSON-RPC	REST
Product Add a subscription plan/product Retrieve product info by code Retrieve subscription plan/product info Update a subscription plan/product Enable/Disable products Pricing Add a pricing configuration Assign a PricingOption Group Create price option groups Retrieve assigned price option groups Retrieve a price option group Retrieve a pricing configuration by code Retrieve a pricing configuration by name Retrieve price option groups Retrieve pricing configurations Unassign a PricingOption Group Update price options Update pricing configuration Save prices Product group Assign a product group Create a product group Retrieve a product group Retrieve product groups Unassign a product group Update a product group Promotion Retrieve a promotion Retrieve information on promotions Order field Add order/product additional fields Assign order/product additional fields Retrieve an order field Retrieve assigned additional fields Retrieve order fields Unassign order/product additional fields Update order/product additional fields Cross-sell Retrieve cross-sell campaigns Retrieve cross-sell campaign texts Retrieve a cross-sell campaign Shipping class Retrieve a shipping class Retrieve shipping classes Order object Place an order Retrieve PayPal redirect URL 1-click purchase Validate order references as payment Orders with installments Retrieve installment information Place an order with installments Order session content object Retrieve session content Subscription import Add/Import subscriptions without payment data Add/Import subscriptions with credit/debit data Subscription Update a subscription and assign it to another customer Assign a subscription to another customer Retrieve a customer’s subscriptions Retrieve specific list of subscriptions Set grace period Next renewal price Custom subscription renewal price C onvert a trial Subscription history Retrieve the history of a subscription Renew a subscription Extend a subscription Customer Create a new customer Retrieve a customer Update a customer Retrieve a customer’s subscription C opy payment info Single Sign On (SSO) Single Sign On by customer reference Single Sign On in cart Retrieve Single Sign On customer info by SSOToken Control myAccount UI display language	Product Add a subscription plan/product Retrieve product info by code Retrieve subscription plan/product info Update a subscription plan/product Enable/Disable products Pricing Add a pricing configuration Assign a PricingOption Group Create price option groups Retrieve assigned price option groups Retrieve a price option group Retrieve a pricing configuration by code Retrieve a pricing configuration by name Retrieve price option groups Retrieve pricing configurations Unassign a PricingOption Group Update price options Update pricing configuration Save prices Product group Assign a product group Create a product group Retrieve a product group Retrieve product groups Unassign a product group Update a product group Promotion Retrieve a promotion Retrieve information on promotions Order field Add order/product additional fields Assign order/product additional fields Retrieve an order field Retrieve assigned additional fields Retrieve order fields Unassign order/product additional fields Update order/product additional fields Cross-sell Retrieve a product’s cross-sell campaigns Retrieve cross-sell campaigns Retrieve cross-sell campaign texts Shipping class Retrieve a shipping class Retrieve shipping classes Order object Place an order Retrieve PayPal redirect URL 1-click purchase Validate order references as payment Orders with installments Retrieve installment information Place an order with installments Order session content object Retrieve session content Subscription import Add/Import subscriptions without payment data Add/Import subscriptions with credit/debit data Subscription Update a subscription and assign it to another customer Assign a subscription to another customer Retrieve a customer’s subscriptions Retrieve specific list of subscriptions Set grace period Next renewal price Custom subscription renewal price C onvert a trial Subscription history Retrieve the history of a subscription Renew a subscription Extend a subscription Customer Create a new customer Retrieve a customer Update a customer Retrieve a customer’s subscriptions C opy payment info Single Sign On (SSO) Single Sign On by customer reference Single Sign On in cart Retrieve Single Sign On customer info by SSOToken Control myAccount UI display language	Product Add a subscription plan/product Retrieve product info by code Retrieve subscription plan and product info Update a subscription plan or product Enable products and subscription plans Disable products and subscription plans Product group Create a product group Retrieve a product group Retrieve product groups Assign a product to a product group Unassign a product from a product group Pricing configuration Add a pricing configuration Retrieve pricing configurations Retrieve a pricing configuration Update a pricing configuration Price options group Create price option groups Update price options Retrieve price option groups Retrieve a price options group Retrieve assigned price option groups Additional fields Create additional fields Retrieve additional fields Retrieve an additional field Retrieve additional field texts Shipping fees Retrieve shipping fees Retrieve a shipping fee configuration Cross-sell Retrieve cross-sell campaigns Retrieve cross-sell campaign texts Retrieve a product's cross-sell campaigns Promotions Retrieve all promotions set for a product Retrieve all active promotions Retrieve a product's promotion Retrieve a promotion Order Place an order Retrieve order status Retrieve PayPal Express redirect URL 1-Click purchase Use an order reference for a 1-click purchase Validate order references as payment Orders with installments Retrieve installment information Place an order with installments Order session Retrieve session content Order information Retrieve an order Invoices Retrieve invoices Retrieve invoices for refunds Subscription import Import subscriptions Subscription Retrieve subscriptions Retrieve a subscription Update a subscription Assign a subscription to another customer Enable a subscription Disable a subscription Trial conversion Convert a trial Subscription renewal Renew a subscription Retrieve renewal links and recurring billing status Enable recurring billing Disable recurring billing Enable renewal notifications Disable renewal notifications Set a custom grace period Renewal price Retrieve a subscription's next renewal price Set a custom subscription renewal price Subscription upgrade Upgrade a subscription Retrieve upgrade options for a subscription Subscription payment info Retrieve the payment info for a subscription Subscription history Retrieve the history of a subscription Retrieve a subscription's purchase, renewal or upgrade details Customer Retrieve a customer Create a customer Retrieve a subscription’s customer End user Retrieve a subscription's end user Update end user info Single Sign On SSO by subscription reference SSO in cart SSO by customer reference

SOAP

JSON-RPC

REST

Product

Enable/Disable products

Pricing