Skip to main content
knowledgecenter.2checkout.com

Order with catalog products

Overview

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

                     Place orders with catalog product                                                                   Retrieve an order

Catalog order object

Parameters Type/Description

RefNo

String

 

2Checkout generates unique reference numbers for all orders (purchases). You can use this parameter to retry authorizations for orders with failed transactions by changing the payment method.

 

NULL when you place new orders.

OrderNo

String

 

The consecutive order number 2Checkout associates with orders and displays in the Order search area of your account.

ExternalReference

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.

Status

String
 

The status of the order:

  • AUTHRECEIVED – 2Checkout blocks the amount corresponding to the transaction, but the process of collecting funds is incomplete.
  • PENDING - 2Checkout has yet to block the amount corresponding to the transaction or shoppers used an offline payment method like wire transfer.
  • COMPLETE – The shopper completed the transaction for the purchase and 2Checkout or you fulfilled the order (when required).
  • CANCELED – 2Checkout cancels orders for which shoppers fail to transfer funds in due time.
  • REVERSED – 2Checkout reverses order transactions that never reach the Complete/Finished stage. Shoppers never complete transactions for such purchases.
  • REFUND – 2Checkout refunds orders only after they reach the Complete/Finished stage and returns the funds collected to shoppers.

ApproveStatus

String
 

The status of the order resulted from the evaluation by the 2Checkout anti-fraud system or by a member of the anti-fraud department. This status varies for new purchases and for orders requiring customers to make manual payments.

Possible values:

  • WAITING: The 2Checkout anti-fraud system or a member of the anti-fraud department has yet to approve the order.
  • OK: The 2Checkout anti-fraud system or a member of the anti-fraud department approved the order.
  • INVALIDDATA: Shopper-supplied data is invalid – 2Checkout did not approve the order.
  • FRAUD: The order is fraudulent.

VendorApproveStatus

String
 

Shows if you approved or not a partner order. Possible values:

  • OK
  • WAITING
  • REJECTED

Language

String
 

ISO 639-1 two-letter code. Language used for the purchase process. Example: “en.”

OrderDate

String
 

Y-m-d H:i:s (2014-05-22 00:12:12) The datetime stamp (in the API time zone defined in cPanel) when customers place their orders.

FinishDate

String
 

Y-m-d H:i:s (2014-05-22 00:12:12) The datetime stamp (in the API time zone defined in cPanel) when the order reach the Complete status.

 

NULL for order that did not reach the Complete/Finished stage.

Source

String
 

The link source for the sale. 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. Cannot be null.

AffiliateSource

String
  The link source for affiliate referred sales. Similar to the functionality of the SRC (separate link identifier) parameter included into Buy Links, but controlled by the AFFSRC parameter. Affiliates use the AFFSRC parameter to track sale sources for their referrals. Maximum length 255 characters.

AffiliateId

Integer

 

Identifier belonging to affiliates who refer orders.

AffiliateName

String

 

Affiliate name.

AffiliateUrl

String

 

Affiliate website URL from the Affiliate Details.

RecurringEnabled

Boolean

 

true or false, depending on whether the shoppers checked the subscription auto-renewal checkbox or not, during the purchase process.

HasShipping

Boolean

 

true or false, depending on whether the order requires shipping.

DeliveryFinalized Boolean
  true or false, depending on whether product delivery has been completed.

BillingDetails

Object

   

Details below. 

   

FirstName

String

     

Shopper name.

   

LastName

String

     

Shopper surname.

   

CountryCode

String

     

Shopper country. ISO 3166 two-letter code.

   

State

String

     

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

String

     

Shopper city.

   

Address1

String

     

Shopper address.

   

Address2

String

     

Shopper address.

   

Zip

String

     

ZIP/ Postal code.

   

Email

String

     

Shopper email address.

   

Phone

String

     

Shopper phone number. Mandatory when you set Brazil as the Billing Country. Can be NULL.

   

Company

String

     

Company name. Can be null for end users. When present, you also need to provide the FiscalCode.

 

FiscalCode

String 

   

• 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 the Billing Country is set to Brazil. For Brazilian customers it represents the Fiscal Code (CPF/CNPJ).

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

• Can be null for end users.

DeliveryDetails

Object

Optional. When missing, 2Checkout uses the same details as for the BillingDetails object.

     

Details below. 

    FirstNameFirstName

 

String

       

Shopper name from the delivery details.

    LastName

 

String

       

Shopper surname from the delivery details.

    CountryCode

 

String

       

Shopper country. ISO 3166 two-letter code from the delivery details.

    State

 

String

       

The state in the shopper's country from the delivery details. Mandatory when you set the Billing Country to US, Brazil and Romania. Use case insensitive utf8 strings for the full name, or just the two letter code.

    City

 

String

       

Shopper city from the delivery details.

    Address1

 

String

       

Shopper address from the delivery details.

    Address2

 

String

       

Shopper address from the delivery details.

    Zip

 

String

       

ZIP/ Postal code from the delivery details.

    Email

 

String

       

Shopper email address from the delivery details.

    Phone

 

String

       

Shopper phone number from the delivery details. Mandatory when you set Brazil as the Billing Country. Can be NULL.

    Company

 

String

       

Company name from the delivery details. Can be null for end users. When present, you also need to provide the FiscalCode.

PaymentDetails

Optional (Object)

 

Adapt this object to the desired payment method.

 

Type

String

   

The payment method:

  • CC (credit/debit card - including local Brazilian cards).
  • 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.
  • PURCHASEORDER - use for orders with POs.
  • FREE – for 0 value orders for which you’re not requiring customers to provide payment details.
 

Currency

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)). For payments with credit cards, PalPay Express, previous order reference and purchase order use the objects below.

 

For payments with check and wire, send only the ‘CHECH’ and ‘WIRE’ strings.

 

null for 0 value orders for which you’re not requiring customers to enter payment details.

   

PaymentDetailsCard

Optional (object)

       

Details below. 

     

CardType

String

       

visa, visaelectron, mastercard, maestro, amex, discover, dankort, cartebleue, jcb, hipercard, elo

     

FirstDigits

String

       

First four digits of the credit card.

     

LastDigits

String

       

Last four digits of the credit card.

      RecurringEnabled Boolean
        true or false, depending whether the order has active recurring options
      Vendor3DSReturnURL String
        URL to which customers are redirected after a successful 3DS process.
      Vendor3DSCancelURL String
        URL to which customers are redirected after a failed 3DS process.
      InstallmentsNumber Integer
        Number of installments used for paying the order.
 

CheckPaymentDetails

Optional (Object)

     

Details below. 

   

Beneficiary

String

     

The beneficiary of the payment.

Can be NULL.

   

CheckPostalAddress

String

     

The address of the beneficiary.

Can be NULL.

   

Amount

Float

     

The total costs incurred by the customer for an order.

Can be NULL.

   

Currency

String

     

The currency ISO code of the order/payment - ISO 4217.

Can be NULL.

 

PayPalExpress

Object

       

Details below. 

     

Email

String

       

Email address customers use for their PayPal account.

     

ReturnURL

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

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.

 

WirePaymentDetails

Object

     

Details below. 

   

Amount

Float

     

The total costs customers incur.

Can be NULL.

   

Currency

String

     

The currency ISO code of the order - ISO 4217.

Can be NULL.

   

PaymentReference

String

     

Transaction identifier.

Can be NULL.

   

RoutingNumber

String

     

Identification number assigned to financial institutions.

Can be NULL.

   

BankAccounts

Optional (Array of objects)

       

Details below. 

     

Beneficiary

String

       

The beneficiary of the payment.

Can be NULL.

     

BankName

String

       

The name of the beneficiary's bank.

Can be NULL.

     

BankCountry

String

       

The country of the beneficiary's bank.

Can be NULL.

     

BankCity

String

       

The city of the beneficiary's bank.

Can be NULL.

     

BankAddress

String

       

The address of the beneficiary's bank.

Can be NULL.

     

BankAccount

String

       

The number for the account in which customers transfer the funds.

Can be NULL.

     

BankAccountIban

String

       

The IBAN of the beneficiary's bank.

Can be NULL.

     

BankAccountSwiftCode

String

       

The Swift Code of the beneficiary's bank.

Can be NULL.

     

Currency

String

       

The currency ISO code for the bank account - ISO 4217.

Can be NULL.

 

CustomerIP

String

   

Shopper IP.

CustomerDetails

Object

2Checkout populates the parameters of the customer entity with information from the customer whose AvangateCustomerReference or ExternalCustomerReference you send during the purchase.

   

Details below. 

 

AvangateCustomerReference

Integer

   

System-generated 2Checkout customer reference. Aggregate subscriptions under the same Customer account if the products they're associated to are purchased by the same shopper 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.

 

ExternalCustomerReference

String

   

The external customer reference you control. Aggregate subscriptions under the same Customer account if the products they're associated to are purchased by the same shopper by adding the CUSTOMERID (case sensitive) parameter  to buy links.

 

FirstName

String

   

Customer's first name. 

 

LastName

String

   

Customer's last name.

 

CountryCode

String

   

Customer's country code (ISO 3166 two-letter code).

 

State

String

   

Customer's state. For example, "Alabama","Alaska","Arizona".

 

City

String

   

Customer's city.

 

Address1

String

   

Customer's address.

 

Address2

String

   

Customer's address.

 

Zip

String

   

Zip code.

 

Email

String

   

Customer's email.

 

Phone

String

   

Customer's phone number.

 

Company

String

   

Company name.

 

FiscalCode

String

   

For companies, it needs to be the VAT ID. 2Checkout validates this values and throws an error if the VAT ID is invalid/incorrect. When present, you need to also provide Company name.

 

Can be null for end users.

 

Fax

String

   

Customer's fax number.

 

Enabled

Boolean

   

true or false, depending on whether the customer account is active or inactive. An active customer account features at least one Active or Past due subscription.

 

Trial

Boolean

   

true or false, depending on whether the customer account features only trials or also paid subscriptions.

 

Language

String

   

ISO 639-1 two-letter code. Example: “en.”

 

ExistingCards

Array of objects

     

Details below. 

   

TransientToken

Object

     

Populated only when you retrieve customer information by SSOToken.

     

Token

String

       

Token for the EXISTING_PAYMENT_DATA flow. Use it to charge customers using cards they used in the past for purchases from your 2Checkout account.

   

CardType

String

     

visa, visaelectron, mastercard, maestro, amex, discover, dankort, cartebleue, jcb, hipercard, elo

   

LastDigits

String

     

Last four digits of the credit card.

   

ExpirationMonth

String

     

Card expiration month.

   

ExpirationYear

String

     

Card expiration year.

   

NameOnCard

String

     

Card holder name.

Origin

String

 

2Checkout automatically tracks the source of purchases:

 

  • Web – When customers use the desktop version of the 2Checkout shopping cart.
  • API - When customers use a custom, API-based ordering interface.
  • Mobile - When customers use the mobile version of the 2Checkout shopping cart.
  • Automatic Billing – For auto-renewals and trial conversions.

AvangateCommission

Optional (Int)

 

2Checkout's commission for the order.

OrderFlow

String

 

PURCHASE_ORDER - Sent only when shoppers used Purchase Orders.

REGULAR - Sent in all other cases.

GiftDetails

Optional (object)

 

Contains contact details for the recipient of a gift purchase.

 

FirstName

String

   

First name of gift recipient.

 

LastName

String

   

Last name of gift recipient.

 

Email

String

   

Email of gift recipient. 2Checkout uses this email for the delivery/fulfillment process.

 

GiftNote

String

   

Custom text shoppers provide as a message to the gift recipient.

PODetails

Object (optional)

   

Details below. 

 

Status

String

   

PO status. Possible values:

 

PO status API

PO status cPanel

AWAITING_UPLOAD

Awaiting form submission - Waiting for the customer to submit the PO form

TIME_EXPIRED

Expired, form not received - The customer did not submit the PO form

AWAITING_MERCHANT

Awaiting your confirmation - PO approved by 2Checkout, awaiting vendor confirmation

MERCHANT_TIME_EXPIRED

Expired, PO not confirmed - You didn't confirm/reject the PO

AWAITING_MERCHANT

Rejected - You rejected the PO

AWAITING_PAYMENT

Awaiting payment - You approved the PO, waiting for payment

AWAITING_PAYMENT

Expired, not paid - The customer did not complete the PO payment. 2Checkout accepts  payments up to 30 days after the PO payment interval expires

NOT_PAID

Canceled, not paid - The customer did not complete the PO payment

NOT_PAID

Canceled by 2Checkout - 2Checkout canceled the PO

NOT_PAID

Canceled via API - You canceled the PO (via API)

PAID

Complete - Customer paid the PO. The order is complete

 

AutoApprove

Boolean

 

TRUE or FALSE, depending on whether you set POs to auto-approve or not.

ExtraInformation

Optional (Object)

 

Details below. 

 

PaymentLink

String

 

 

Can be:

1. The PO doc upload link - If you set AutoApprove as FALSE on the original order and before shoppers upload the PO. 

2. Payment link for orders with POs. Business customers can use the PaymentLink to finalize payment for orders with POs. If you set AutoApprove as TRUE on the original order and if 2Checkout and you approve the PO. 

PaymentLink

String

 

In scenarios in which an issue blocks the transaction from finalizing, 2Checkout provides a retry link where shopper can complete their purchase by providing new payment details.

PartnerCode

String

 

Partner code you configured for your partner. NULL for eStore orders.

PartnerMargin

Float

 

Partner margin you set for the order. NULL for eStore orders.

PartnerMarginPercent

Float

 

The percentage of the partner margin from the net value of the products ordered, minus the value of any discounts. NULL for eStore orders.

ExtraMargin

Float

 

Extra margin you offer by editing partner orders. NULL for eStore orders.

ExtraMarginPercent

Float

 

The percentage of the extra partner margin from the net value of the products ordered, minus the partner margin and the value of any discounts. NULL for eStore orders.

ExtraDiscount

Float

 

Extra discount you offer by editing partner orders. NULL for eStore orders.

ExtraDiscountPercent

Float

 

The percentage of the partner margin from the net value of the products ordered, minus the value of any coupon discounts. NULL for eStore orders.

LocalTime

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.

TestOrder

Boolean

 

True for test orders. False of regular orders.

Errors

Array of strings

 

Payment gateway processing errors.

Items

Array of objects

   

Details below. 

 

ProductDetails

Object

   

Name

String

     

Product name.

    ShortDescription String
      Product short description.
    Tangible Boolean
      true or false, depending on product delivery type.
    IsDynamic Boolean
     

Possible values:

  • true - dynamic product information
  • false - catalog products
   

ExtraInfo

String

     

The text entered in the Additional information field when generating Buy links, or via the INFO[PRODUCT_ID] parameter used in Buy links.

   

RenewalStatus

Boolean

     
  • true for orders renewing subscriptions.
  • false for all other orders: new purchases, upgrades.
    DeliveryInformation

Object

Details below

          Delivery   String
     

Possible values:

  • BY_VENDOR
  • NO_DELIVERY
  • BY_AVANGATE
          DownloadFile   Object
      Information related to the download file.
          DeliveryDescription   String
      Delivery description.
          CodesDescription   String
      Description of codes delivered.
          Codes   Array of strings
              Array with the codes delivered
   

Subscriptions

Object

     

SubscriptionReference

String

       

Unique, system-generated subscription identifier.

     

PurchaseDate

String

       

The date time stamp when shoppers acquired their subscriptions corresponding to the moment when the 2Checkout system marks the purchase as finished. Format (YYYY-MM-DD HH:mm:ss). Default GMT+02:00.

 

e.g. 2015-08-11 15:18:52

     

SubscriptionStartDate

String

       

 

Example: 2015-09-29 17:57:59

     

ExpirationDate

String

       

The date time stamp of upcoming renewal/expiration for subscriptions not taking into account grace period settings.

 

Format (YYYY-MM-DD HH:mm:ss). Default GMT+02:00.

 

e.g. 2015-09-11 15:18:52

     

Lifetime

Boolean

       
  • true – For non-recurring, evergreen subscriptions.
  • false – For recurring subscriptions with a specific billing cycle from 7 days to 36 months.
     

Trial

Boolean

       
  • true – For trial subscriptions.
  • false – For non-trial, recurring subscriptions with a specific billing cycle from 7 days to 36 months.
     

Enabled

Boolean

       
  • true – For active and past due subscriptions.
  • false – For expired and cancelled subscriptions.
     

RecurringEnabled

Boolean

         

                   

PriceOptions

Array of strings

   

Array of price option codes.

   

Code

Strings

     

Unique code that the 2Checkout system generates or that you set for each pricing options group.

   

Required

Boolean

     
  • true – you require shoppers to select the price option  through the way in which you configured pricing.
  • false – you do not require shoppers to select the price option.
   

Options

Array of strings

     

The code you set or that the 2Checkout system generates for each price option child inside a pricing options group parent.

 

Price

Object

   

This object returns the price per unit at order line level.

 

In the case of trials, the object returns the costs for the trial to full subscription conversion.

   

UnitNetPrice

Float

     

The value per product unit, excluding sales tax/VAT expressed in the payment currency.

   

UnitGrossPrice

Float

     

Total value per product unit, including sales tax/VAT expressed in the payment currency. UnitGrossPrice does not reflect any discounts.

   

UnitVAT

Float

     

Sales tax/VAT per product unit expressed in the payment currency.

   

UnitDiscount

Float

     

Value of the discount per product unit expressed in the payment currency.

   

UnitNetDiscountedPrice

Float

     

The value per product unit, expressed in the payment currency, excluding sales tax/VAT, from which 2Checkout deducts the unit discount.

   

UnitGrossDiscountedPrice

Float

     

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

Float

     

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.

   

Currency

String

     

The currency ISO code for the payment - ISO 4217. Example: usd.

   

NetPrice

Float

     

The value per order line, excluding sales tax/VAT expressed in the payment currency.

   

GrossPrice

Float

     

Total value per order line, including sales tax/VAT expressed in the payment currency. UnitGrossPrice does not reflect any discounts.

   

NetDiscountedPrice

Float

     

The NetPrice value per order line (in the payment currency), excluding sales tax/VAT, from which 2Checkout deducts discounts.

   

GrossDiscountedPrice

Float

     

Total costs shoppers incur per order line, expressed in the payment currency. This value includes sales tax/VAT, 2Checkout and affiliate commissions, but 2Checkout deducts the value of any discounts.

 

Example:

  • UnitNetPrice: 99
  • UnitGrossPrice: 120.39
  • UnitVAT: 21.39
  • UnitDiscount: 9.9
  • UnitNetDiscountedPrice: 89.1
  • UnitGrossDiscountedPrice: 110.49
  • UnitAffiliateCommission: 22.28
  • Currency: "usd"
  • NetPrice: 198
  • GrossPrice: 240.77
  • NetDiscountedPrice: 178.2
  • GrossDiscountedPrice: 220.97
  • Discount: 19.8
  • VAT: 42.77
  • AffiliateCommission: 44.56
   

Discount

Float

     

Value of the discounts per order line expressed in the payment currency.

   

VAT

Float

     

Value of sales tax/VAT per order line expressed in the payment currency.

   

AffiliateCommission

Float

     

Value of the affiliate commission per order line, calculated from the NetDiscountedPrice expressed in the payment currency. Or NULL. 2Checkout does not take into account shipping costs when calculating affiliate commissions.

    VATPercent Integer
      Percentage of the VAT/tax applied to the order.
    HandlingFeeNetPrice Integer
      Handling fee applied to the NET price configuration.
    HandlingFeeGrossPrice Integer
      Handling fee applied to the GROSS price configuration.
  LineItemReference String
    System-generated reference for the product item.
  PurchaseType String
   

Possible values:

  • PRODUCT
  • SHIPPING
  • TAX
  • COUPON
 

Code

String

   

Unique product identifier your control. Max length 256 characters.

 

Quantity

Integer

   

Number of units

 

SKU

String

   

SKU identifier.

 

CrossSell

Object

     

Details below. 

   

ParentCode

String

     

The product code of the master product you set to trigger the campaign.

   

CampaignCode

String

     

Unique, system-generated identifier for cross-sell campaigns.

 

Trial

Object

     

Details below. 

   

Period

Integer

     

The length of the trial subscription lifetime in days.

   

GrossPrice

Float

     

Total trial price in the payment currency before 2Checkout deducts any taxes, discounts, etc.

   

VAT

Float

     

The total value of taxes for the trial in the payment currency, before 2Checkout deducts any discounts.

   

NetPrice

Float

     

Total trial price in the payment currency, not including taxes, before 2Checkout deducts any discounts.

 

AdditionalFields

Array of objects

     

Details below. 

   

Code

String

     

The alpha-numeric characters, underscores and dashes that are set as the field identifier.

   

Text

String

     

Field text visible to shoppers in the cart.

   

Value

String

     

Selected field value.

 

Promotion

Object

     

Details below. 

   

Name

String

     

Promotion name.

   

Description

String

     

Promotion description.

   

StartDate

String

     

The date when you set the promotion to start. NULL for promotions that start immediately after you create them.

   

EndDate

String

     

The date when you set the promotion to end. NULL for promotions you want active indefinitely.

   

MaximumOrdersNumber

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

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

   

InstantDiscount

Boolean

     

The instant discount option auto-applies the discount for ALL selected products, without the need for shoppers to enter a discount coupon.

   

Coupon

String

     

Promotion coupon/voucher.

   

DiscountLabel

String

     

Discounts can be set as a percentage from the product price or as a fixed amount in the chosen currency.

   

Enabled

String

     

true or false, depending on whether a promotion is active or disabled. 

   

Type

String

     
  • REGULAR – product/cart line level discounts.
  • ORDER – quantity discounts.
  • GLOBAL – order-level discounts.
  • AFFILIATE – for discounts created by affiliates.

Promotions

Array of objects

   

Details below. 

 

Name

String

   

Promotion name.

 

Description

String

   

Promotion description.

 

StartDate

String

   

The date when you set the promotion to start. NULL for promotions that start immediately after you create them.

 

EndDate

String

   

The date when you set the promotion to end. NULL for promotions you want active indefinitely.

 

MaximumOrdersNumber

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

Integer

   

Discount only applies to a specific number of units purchased at once, smaller than the maximum 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 units.

 

InstantDiscount

Boolean

   

The instant discount option auto-applies the discount for ALL selected products, without the need for shoppers to enter a discount coupon.

 

Coupon

String

   

Promotion coupon/voucher.

 

DiscountLabel

String

   

Discounts can be set as a percentage from the product price or as a fixed amount in the payment currency.

 

Enabled

String

   

true or false, depending on whether a promotion is active or disabled. 

 

Type

String

   
  • REGULAR – product/cart line level discounts.
  • ORDER – quantity discounts.
  • GLOBAL – order-level discounts.
  • AFFILIATE – for discounts created by affiliates.

AdditionalFields

Array of objects

   

Details below. 

 

Code

String

   

The alpha-numeric characters, underscores and dashes that are set as the field identifier.

 

Text

String

   

Field text visible to shoppers in the cart.

 

Value

String

   

Selected field value.

Currency

String

 

The currency ISO code for the payment - ISO 4217. Example: usd.

NetPrice

Float

 

Order value excluding sales tax/VAT expressed in the payment currency.

GrossPrice

Float

 

Total order value, including sales tax/VAT expressed in the payment currency. GrossPrice does not reflect any discounts.

NetDiscountedPrice

Float

 

The NetPrice order value excluding sales tax/VAT, from which 2Checkout deducts discounts. NetDiscountedPrice is expressed in the payment currency.

GrossDiscountedPrice

Float

 

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:

  • Currency: "usd"
  • NetPrice: 396
  • GrossPrice: 486.29
  • NetDiscountedPrice: 376.2
  • GrossDiscountedPrice: 466.49
  • Discount: 19.8
  • VAT: 90.29
  • AffiliateCommission: 94.05

Discount

Float

 

Value of the discounts for an order expressed in the payment currency.

VAT

Float

 

Value of sales tax/VAT expressed in the payment currency.

AffiliateCommission

Float

 

Value of the affiliate commission for the order calculated from the NetDiscountedPrice expressed in the payment currency. Or NULL. 2Checkout does not take into account shipping costs when calculating affiliate commissions.

FxRate Integer
  Exchange rate used by 2Checkout for converting the order to your payout currency.
FxMarkup Integer
  Exchange rate markup for the order.
PayoutCurrency String
  The ISO code of your account's payout currency - ISO 4217.