updates RSS feed

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.

 

Subscription

Overview

The object below is returned directly or within a successful response from the following API requests:

Subscription object

Parameters Type/Description
SubscriptionReference String
  Unique, system-generated subscription identifier.
StartDate String
  Subscription start date(ISO 8601) - StartDate is mandatory when importing subscription data. If you changed the time zone for the Avangate API by editing system settings under Account settings, then the StartDate you provide must be in accordance with your custom configuration.
ActivationDate String
  Subscription activation date (ISO 8601) represents the date since the subscription became active. It might be greater or at least equal to the subscription start(creation/purchase) date. While not reached, the subscription has a pending activation status. ActivationDate is optional when updating subscription data. If you changed the time zone for the Avangate API by editing system settings under Account settings, then the ActivationDate you provide must be in accordance with your custom configuration.
ExpirationDate String
  Subscription expiration date(ISO 8601) - ExpirationDate is mandatory when importing subscription data. If you changed the time zone for the Avangate API by editing system settings under Account settings, then the ExpirationDate you provide must be in accordance with your custom configuration.
RecurringEnabled Boolean
 

Possible values:

TRUE – recurring billing/automatic subscription renewals enabled

FALSE– recurring billing/automatic subscription renewals disabled
NextBillingDate Date
  The date when the client will be billed next (ISO 8601).
SubscriptionEnabled

Boolean

Possible values:

TRUE –subscription enabled

FALSE–subscription disabled
Product Required (object)
  The product for which Avangate generated the subscription. Details below.
  ProductCode String
    Unique product identifier that you control.
  ProductId Int
    Unique, system-generated product identifier.
  ProductName String
    Product name.
  ProductQuantity Int
    Ordered number of units.
  ProductVersion String
    Product version.
  PriceOptionCodes Array
    The product options codes the customer selected when acquiring the subscription. Pricing options codes are case sensitive.
EndUser Object
  The end user of the subscription. Details below.
  Person Object
    FirstName String
      End user's first name
    LastName String
      End user's last name
    CountryCode String
      End user country code [ISO3166-1 Alpha 2].
    State String
      End user state.
    City String
      End user city.
    Address1 String
      End user first address line.
    Address2 String
      End user second address line.
    Zip String
      End user zip code.
    Email String
      End user email address.
    Phone String
      End user phone number.
    Company String
      Company name.
    Fax   String
    End user fax.
    Language   String
    Language [ISO639-2] the Avangate system uses for communications.
SKU String
  Stock keeping unit you defined.
DeliveryInfo Object
  The object contains information about the delivery/fulfillment made to the customer.
  Description String
    Delivery description.
  Codes Array of objects
    Code String
      Activation key/license code of the first order from this subscription. Use getSubscriptionHistory method if you want to retrieve the activation keys/license codes for all orders belonging to a subscription.
    Description String
      Code description for dynamic lists from your key generator. 
    ExtraInfo Object
      Info set by your key generator for dynamic lists only.
      CodeExtraInfo Object
      Type String
      Label String
      Value String
    File Array of objects
      Content String
        Content of the file (base64 encoded).
      ContentLength Int
        File size.
      Filename String
        The name of the delivered file.
      FileType String
        The type of the delivered file.
ReceiveNotifications Boolean
 

1 – Subscribe: Avangate sends subscription notifications to the end user.

0 – Unsubscribe – Avangate does not send subscription notifications to the end user.
Lifetime Boolean
 

Possible values:

  • True – the subscription is evergreen

False – the subscription has a recurring billing cycle less than or equal to three years.
PartnerCode String
 
  • Empty: for ecommerce orders
  • Partner Code
AvangateCustomerReference Int
  Unique, system-generated customer identifier.
ExternalCustomerReference String
  Customer identifier that you control.
TestSubscription Boolean
  True for test subscriptions, false otherwise.
IsTrial Boolean
  True for trial subscriptions, false otherwise.
MerchantCode String
  Unique, system-generated ID in the Avangate system.

Order object

Overview

Use this object to create new orders and collect payments from shoppers. 

The attributes below in this page include all possible properties from both the request and the response. 

To implement placing orders, please reference the API Request page (Place orders with catalog products or Place orders with dynamic product information).

Supported payment methods

  1. Credit/Debit cards: Visa, Visa electron, MasterCard, Maestro, Amex, Discover, Dankort, Carte Bleue, JCB. 2Checkout supports local Brazilian cards.
  2. PayPal and PayPal Express
  3. Purchase Order
  4. Wire
  5. Check
  6. WeChat Pay
  7. iDEAL
  8. Previous order references - In addition to the payment methods enumerated above, 2Checkout also supports 1-click purchase flows in which you use valid previous order references belonging to returning customers to pay for new orders with their previously used cards and PayPal accounts. 

Attributes

Parameters   Type/Description
RefNo Optional (string)
 

Unique, system-generated, order reference number.

 

Do not include it when placing new orders or send it as NULL.
Currency Optional (string)
  The currency ISO code for the payment - ISO 4217. Example: “usd.”
Country Optional (string)
  Shopper country. ISO 3166 two-letter code. Example: “us.”
Language Optional (string)
  ISO 639-1 two-letter code. Language used for the purchase process. Example: “en.”
ExternalReference Optional (string)
  Set external reference identifiers for orders. Enables you to replicate the functionality of the REF parameter included into Buy Links. Maximum 100 characters. If there is a need for longer references, you can apply an md5 hash for any string value, resulting in a 32 characters string. You can verify the hash after the order notification, on the client side.
Source Optional (string)
 

The link source for the sales. Enables you to replicate the functionality of the SRC (separate link identifier) parameter when included into Buy Links. Use the SRC parameter to track sale sources.

 

Maximum length 255 characters.
Affiliate Object/Optional
  AffiliateCode String/Required
    The affiliate unique code (as returned by the affiliates API methods).
  AffiliateSource String/Optional
    The affiliate source.
CustomerReference Optional (Int)
  System-generated 2Checkout customer reference. Aggregate subscriptions under the same Customer account by adding the AV_CUSTOMERID (case sensitive) parameter to buy links. The 2Checkout system generates default customer numerical (integer) IDs (AV_CUSTOMERID) automatically for all orders containing products that feature subscriptions.
MachineId Optional (string)
  Unique, system generated code for each unique customer, identifying returning customers.
Items Required (array of objects)
  Details below. 
  OrderItem Object
    Details below. 
    Code Required (string)
      Unique product identifier your control. Max length 256 characters.
    Quantity Required (integer)
      Number of units
    PriceOptions Optional (array of strings)
      Array of price option codes.
    SKU Optional (string)
      SKU identifier.
    Price Object - Can be NULL
        OrderPrice Object - Can be NULL
        Currency Optional (string)
          The currency ISO code for the payment - ISO 4217. Example: usd.
        NetPrice Optional (double)
          Order value excluding sales tax/VAT expressed in the payment currency.
        GrossPrice Optional (double)
          Total order value, including sales tax/VAT expressed in the payment currency. GrossPrice does not reflect any discounts.
        NetDiscountedPrice Optional (double)
          The NetPrice order value excluding sales tax/VAT, from which 2Checkout deducts discounts. NetDiscountedPrice is expressed in the payment currency.
        GrossDiscountedPrice Optional (double)
          Total costs shoppers incur, expressed in the payment currency. This value includes sales tax/VAT, 2Checkout and affiliate commissions, but 2Checkout deducts the value of any discounts. For example, the GrossDiscountedPrice can be derived from the GrossPrice minus a Discount.
        Discount Optional (double)
          Value of the discounts for an order expressed in the payment currency.
        VAT Optional (double)
          Value of sales tax/VAT expressed in the payment currency.
        AffiliateCommission Optional (double)
          Value of the affiliate commission for the order calculated from the NetDiscountedPriceexpressed in the payment currency. Or NULL. 2Checkout does not take into account shipping costs when calculating affiliate commissions.
        UnitNetPrice Optional (double)
          The value per product unit, excluding sales tax/VAT expressed in the payment currency.
        UnitGrossPrice Optional (double)
          Total value per product unit, including sales tax/VAT expressed in the payment currency. UnitGrossPrice does not reflect any discounts.
        UnitVAT Optional (double)
          Sales tax/VAT per product unit expressed in the payment currency.
        UnitDiscount Optional (double)
          Value of the discount per product unit expressed in the payment currency.
        UnitNetDiscountedPrice Optional (double)
          The value per product unit, expressed in the payment currency, excluding sales tax/VAT, from which 2Checkout deducts the unit discount.
        UnitGrossDiscountedPrice Optional (double)
          Total costs shoppers incur per product unit, expressed in the payment currency. This value includes sales tax/VAT, 2Checkout and affiliate commissions, but 2Checkout deducts the value of any discounts.
        UnitAffiliateCommission Optional (double)
         

Value of the affiliate commission per product unit calculated expressed in the payment currency.

 

2Checkout deducts discounts from the costs incurred by shoppers before calculating affiliate commissions.

 

2Checkout does not take into account shipping costs when calculating affiliate commissions.

 

NULL when 2Checkout does not apply an affiliate commission.
    CrossSell Object – Can be NULL
      Details below. 
      ParentCode Optional (string)
        The product code of the master product you set to trigger the campaign.
      CampaignCode Optional (string)
        Unique, system-generated identifier for cross-sell campaigns.
    Trial Optional (Object) – Can be NULL
      Details below. 
      Period Optional (integer)
        The length of the trial subscription lifetime in days.
      Price Optional (double)
        Total trial price in the payment currency before 2Checkout deducts any taxes, discounts, etc.
    AdditionalFields Optional (array of objects) – Can be NULL
      AdditionalFieldSet Optional (Object) – Can be NULL
        Code Optional (string)
          The alpha-numeric characters, underscores and dashes that are set as the field identifier.
        Value Optional (string)
            Selected field value.
    SubscriptionStartDat Optional (string)
     

Specify the date time stamp when the subscription becomes active. Format 2016-07-02 22:22:22 (YYYY-MM-DD HH:mm:ss). Available for JSON-RPC and REST.

Send empty or NULL to activate subscriptions on the same date when customers purchase them.

You can exclude HH:mm:ss when sending the date and include only YYYY-MM-DD. In this case, 2Checkout uses 00:00:01. Default time zone GMT+02:00.
    Promotion Optional (Object)
      Details below. 
      Name Optional (string)
        Promotion name.
      Description Optional (string)
        Promotion description.
      StartDate Optional (string)
        The date when you set the promotion to start. NULL for promotions that start immediately after you create them.
      EndDate Optional (string)
        The date when you set the promotion to end. NULL for promotions you want active indefinitely.
      MaximumOrdersNumber Optional (integer)
       

2Checkout only applies the promotion to a maximum number of orders you define.

 

Can be NULL if you want the promotion to apply to an unlimited number of orders.
      MaximumQuantity Optional (integer)
        Discount only applies to a maximum number of units purchased through a single order, smaller than the quantity you defined. Shoppers purchase any extra units at full price. Can be NULL if you want the promotion to apply to an unlimited number of units.
      InstantDiscount Optional (boolean)
        The instant discount option auto-applies the discount for ALL selected products, without the need for shoppers to enter a discount coupon.
      Coupon Optional (string)
        Promotion coupon/voucher.
      DiscountLabel Optional (string)
        Discounts can be set as a percentage of the product price or as a fixed amount in the chosen currency.
      Enabled Optional (string)
        true or false, depending on whether a promotion is active or disabled. 
      Type Optional (string)
       
  • REGULAR – product/cart line-level discounts.
  • ORDER – quantity discounts.
  • GLOBAL – order-level discounts.
BillingDetails Required (Object)
  Details below. 
  Person Object
      Details below. 
    FirstName Required (string)
      Shopper name.
    LastName Required (string)
      Shopper surname.
    CountryCode Required (string)
      Shopper country. ISO 3166 two-letter code.
    State

Optional (string) – Required for US, Brazil, India and Romania

The state in the shopper's country. Mandatory when you set the Billing Country to US, Brazil, India and Romania. Use case insensitive utf8 strings for the full name, or just the two letter code.
     
    City Optional (string)
      Shopper city.
    Address1 Optional (string)
      Shopper address.
    Address2 Optional (string)
      Shopper address.
    Zip Optional (string)
      ZIP/ Postal code.
    Email Optional (string)
      Shopper email address.
    Phone Optional (string)
      Shopper phone number. Mandatory when you set Brazil as the Billing Country. Can be NULL.
    Company Optional (string)
      Company name. Can be null for end users. When present, you also need to provide the FiscalCode.
    TaxExemptionId  Optional (string)
      Tax Exempt Certification id used to deduct taxes for US orders
Example: 1b80eecc349v
  FiscalCode Optional (string) – Required for Brazil
   

• For companies, it needs to be the VAT ID. 2Checkout will validate the value provided and throw an error if the VAT ID is invalid/incorrect when calling setPaymentDetails. When present, you also need to provide the Company name.

• Mandatory when you set Brazil as the Billing Country. For Brazilian customers, it represents the Fiscal Code (CPF/CNPJ).

• Mandatory when you set India as Billing Country, and purchase is made by a Company.

• Can be NULL for end users.
DeliveryDetails Required (Object)
    Details below. 
  Person Object
    Details below. 
    FirstName Required (string)
      Shopper name from the delivery details.
    LastName Required (string)
      Shopper surname from the delivery details.
    CountryCode Optional (string)
      Shopper country. ISO 3166 two-letter code from the delivery details.
    State Optional (string) – Required for US, Brazil and Romania
      The state in the shopper's country from the delivery details. Mandatory when you set the Billing Country to the US, Brazil, and Romania. Use case insensitive utf8 strings for the full name, or just the two-letter code.
    City Optional (string)
      Shopper city from the delivery details.
    Address1 Optional (string)
      Shopper address from the delivery details.
    Address2 Optional (string)
      Shopper address from the delivery details.
    Zip Optional (string)
      ZIP/ Postal code from the delivery details.
    Email Optional (string)
      Shopper email address from the delivery details.
    Phone Optional (string)
      Shopper phone number from the delivery details. Mandatory when you set Brazil as the Billing Country. Can be NULL.
    Company Optional (string)
      Company name from the delivery details. Can be null for end users. When present, you also need to provide the FiscalCode.
PaymentDetails Required (Object)
  Adapt this object to the desired payment method.
  Type Required (string)
   

The payment method:

  • CC (credit/debit card - including local Brazilian cards).
  • ENCRYPTED_PAYMENT_DATA (client-side encryption)
  • PAYPAL
  • PAYPAL_EXPRESS
  • CCNOPCI(credit/debit card for non-PCI certified merchants).
  • TEST (for test orders).
  • PREVIOUS_ORDER(place new orders using the reference of a previous order).
  • EXISTING_PAYMENT_DATA  (use a card one of your customers already used to purchase from your account).
  • WIRE – the placeOrder response includes Wire payment details.
  • CHECK – the placeOrder response includes Check payment details.
  • WE_CHAT_PAY (for WeChat payments).
  • IDEAL (for iDEAL payments).
  • PURCHASEORDER - use for orders with POs.
  • FREE – for 0 value orders for which you’re not requiring customers to provide payment details.

 
  Currency Optional (string)
    The currency ISO code for the payment - ISO 4217. Example: “usd.”
  PaymentMethod Optional (object)
   

Object structure and parameters differ according to payment method selected and API method (placing orders (POST) vs. retrieving order data (GET)).

 

NULL for 0 value orders for which you’re not requiring customers to enter payment details.
  AutoRenewal Optional (boolean)
   

true – shopper checks the auto renewal checkbox and 2Checkout charges subscription renewals using a recurring billing process.

false – shopper doesn’t check the auto renewal checkbox.
      CardPayment Optional (object)
        Details below. 
        CardNumber Optional (string)
          The credit/debit card number.
        CardType Optional (string)
          visa, visaelectron, mastercard, maestro, amex, discover, dankort, cartebleue, jcb, hipercard, elo
        ExpirationYear Optional (string)
          The year in which the card expires.
        ExpirationMonth Optional (string)
          The month in which the card expires.
        HolderName Optional (string)
          Card holder name.
        CCID Optional (string)
          Credit Card Identification - an extra ID printed on the card, usually a 3-4 digit number, the CVC2/CVV2.
        HolderNameTime Optional (float)
         

The interval of time in seconds in which shoppers enter their name in the HolderName field. An abnormally short interval is usually a red flag for fraud attempts.

Can be NULL, but not a negative number.
        CardNumberTime Optional (float)
         

The interval of time in seconds in which shopper enter their card number in the CardNumber field. An abnormally short interval is usually a red flag for fraud attempts.

Can be NULL, but not a negative number.
        InstallmentsNumber  Optional (Int)
          Number of installments. Available only when customers un Brazil pay with Visa or MasterCard using Brazilian Real as the order currency. Use 1 or exclude the parameter for full payments. 
      PayPalExpress Optional (object)
        Details below. 
        Email Optional (string)
          Email address customers use for their PayPal account.
        ReturnURL Optional (string)
          The PayPal Express Checkout redirect URL returned by calling the getPayPalExpressCheckoutRedirectURL method. The return URL is the page on your website to which PayPal redirects your buyer's browser after the buyer logs into PayPal and approves the payment. Typically, this is a secure page (https://...) on your site.
        CancelURL Optional (string)
          The cancel URL is the page on your website to which PayPal redirects your buyer's browser if the buyer does not approve the payment. Typically, this is the secure page (https://...) on your site from which you redirected the buyer to PayPal.
      PreviousOrder Optional (Object)
        Details below. 
        RefNo Optional (string)
         

Order reference a previous purchase which reached the Approved/Complete status. You can use order for which customers paid with credit/debit cards or with PayPal. The status of order should be AUTHRECEIVED or COMPLETE.

 

Check the validity of references with the isValidOrderReference method.

 

The 2Checkout system blocks you from using references for fraudulent or potentially fraudulent orders.
      PurchaseOrderPaymentDetails Optional (Object)
        Details below. 
        InternalPONumber Optional (string)
          Identifier that business customers use internally in their organization to track and manage Purchase Orders (PO). Can be NULL.
        AutoApprove Optional (boolean)
         

TRUE - requires activation of the PO AutoApprove package (If the package is inactive 2Checkout returns an error). Please contact 2Checkout. When AutoApprove is TRUE, 2Checkout no longer requires that business customers upload a PO document. As such, PO orders are automatically approved for your account, without a PO doc. 2Checkout sets the PURCHASE_PENDING status for auto-approved PO orders.

FALSE - Default. Send this if the PO AUtoApprove package is not available for your account. 2Checkout uses the same flow as cart purchases with Purchase Orders for business customers placing orders with POs via API. This means that customers receive the same emails as if they made the purchase using the cart and need to update the PO document, which is reviewed by 2Checkout and that you need to approve. 2Checkout sets the AVAITING_UPLOAD status for POs andUnfinished for their orders.

 

Can be NULL.
      WE_CHAT_PAY Optional (string)
        Details below
        ReturnUR Optional (string)
          The return URL is the page to which your customers are redirected after their successful payment.
        CancelURL Optional (string)
          The cancel URL is the page to which your customers are redirected after their failed payment attempt.
      IDEAL Optional (string)
        Details below
        ReturnURL Optional (string)
          The return URL is the page to which your customers are redirected after their successful payment.
        CancelURL Optional (string)
          The cancel URL is the page to which your customers are redirected after their failed payment attempt.
        BankCode Required (string)
          String contains the SWIFT code of the bank, the plus sign "+", and the first 3 characters from the bank name. E.q.: in the case of Rabobank, code parameter is "RABONL2U+RAB".
      EXISTING_PAYMENT_DATA Optional (Object)
        By using EXISTING_PAYMENT_DATA you no longer require shoppers to enter any payment details.
        TransientToken Optional (string)
          Returned as a part of the process of retrieving customer information by SSOToken.
  CustomerIP Required (string)
    Shopper IP.
Promotions Optional (Array of strings)
  Array of promotion codes.
AdditionalFields  
  Details below. 
  Code Optional (string)
    The alpha-numeric characters, underscores and dashes that are set as the field identifier.
  Text Optional (string)
    Field text visible to shoppers in the cart.
  Value Optional (string)
    Selected field value.
LocalTime Optional (string)
 

Local shopper time in the following format: Y-m-d H:i:s.

This parameter can impact the fraud score of an order when it's missing, NULL or incorrectly formatted.
GiftDetails Optional (object)
  Contains contact details for the recipient of a gift purchase.
  FirstName Optional (string)
    First name of gift recipient.
  LastName Optional (string)
    Last name of gift recipient.
  Email Optional (string)
    Email of gift recipient. 2Checkout uses this email for the delivery/fulfillment process.
  GiftNote Optional (string)
    Custom text shoppers provide as a message to the gift recipient.

 

 

Overview

Use the 2Checkout Channel Manager API to manage partner and reseller orders.

Availability

The partner API methods are available only in tandem with the Channel Manager module.

Requirements

Contact 2Checkout to start using the Channel manager API.

 

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