Language

2Checkout Documentation

Detail Sale

The detail_sale call is used to retrieve information about a specific sale or invoice.

URL: https://www.2checkout.com/api/sales/detail_sale

HTTP Method: GET


Input Parameters

Parameter Description
sale_id The order number of the requested sale. Optional if invoice_id is specified.
invoice_id The invoice number of the requested invoice (specify to include only the requested invoice. Omit and use sale_id to include all invoices).  Optional if sale_id is specified.

Data Returned


sale

Parameter Description
sale_id Order Number/Sale Number
ip_address Buyer IP Address
date_placed Date and time the order was placed
total Sale total amount
language Language sale was placed in (values: en,it,fr,no,es_ib,es_la,gr,nl,zh,da,jp,pt,sl,sv,el)
pay method Buyer Payment Method
cardholder_name Buyer full name
first_six_digits First 6 digits of credit card
last_two_digits Last 2 digits of credit card
method Method of sale payment (values: ach, credit card, amex, atmd, bill_me_later, fxsource, paypal_int, paypal_pl, acculynk)
avs AVS match
cvv CVV match


comment

Parameter Description
username User that entered the comment
timestamp Date and time the comment was entered
ip IP address of the user
comment_text Comment text


customer

Parameter Description
customer_id Customer ID
first_name Buyer first name
middle_initial Buyer middle initial
last_name Buyer last name
card_holder_name Buyer full name
email Buyer email address
phone Buyer phone number
phone_extension Buyer phone extension


address

Parameter Description
address_1 Billing address line 1
address_2 Billing address line 2
city Billing city
state Billing state
postal_code Billing postal code
country_code Billing country code
country Billing country


invoices

Parameter Description
invoice_id Invoice ID
sale_id Sale ID
status Sale Status (values: deposited, approved, declined, pending)
usd_total Invoice total in USD
vendor_total Invoice total in account pricing currency
customer_total Invoice total in buyer pricing currency
fees_2co 2CO transaction fees applied to invoice
recurring Recurring (values: 1=yes, 0=no)
recurring_decline Recurring (values: 1=yes, 0=no, NULL)
date_placed Date and time the invoice was placed
date_shipped Date and time invoice was shipped
date_vendor_paid Date paid
referrer Invoice referrer url
vendor_order_id Merchant Order ID


lineitems

Parameter Description
lineitem_id Line item ID
vendor_product_id Merchant assigned product ID
affiliate_vendor_id Affiliate ID
product_description Product short description
product_handling Product handling fee
product_name Product Name
product_price Line item price
product_recurrence Product Recurrence (values: A number followed by a space followed by “day”, “week”, “month” or “year”)
product_duration Recurring duration (values: “Forever” or a number followed by a space followed by “day”, “week”, “month” or “year”)
product_startup_fee Startup fee
product_tangible Tangible or Intangible (values: 1=intangible, 0=intangible)
product_is_cart Third Party Cart ID or “0” if none
installment Current installment for recurring billing items
type Line item type (values: null = products including 2Checkout Signup, signup fee, affiliate, shipping, partial, chargeback, coupon)
flat rate Flat rate commission amount of line item affiliate commission (VA Affiliate Program)
percentage Percentage of line item affiliate commission (VA Affilate Program)
lc_affiliate_vendor_id ID of affiliate credited for line item commission (VA Affiliate Program)
lc_usd_amount Amount of line item affiliate commission (VA Affiliate Program)
commission Global Affiliates commission amount
commission_affiliate_vendor_id Global Affiliates affiliate credited for line item commission
commission_flat_rate Global Affiliates flat rate commission amount
commission_percentage Global Affiliates commission percentage
commission_type Global Affiliates commission type (amount or percentage)
commission_usd_amount Global Affiliates commission USD amount


option

Parameter Description
lineitem_id Line item ID used with option
lineitem_option_id Product option ID
option_name Product option name
option_value Product option value
usd_surcharge surcharge in USD
vendor_surcharge Surcharge in account pricing currency
customer_surcharge Surcharge in buyer currency


billing

Parameter Description
billing_id Billing ID
usd_amount Billing amount in USD
vendor_amount Billing amount in account pricing currency
customer_amount Billing amount in buyer currency
customer_id 2Checkout system buyer ID
installment current installment for recurring billing items
product_recurrence Billing Recurrence (values: A number followed by a space followed by “day”, “week”, “month” or “year”)
product_duration Billing duration (values: “Forever” or a number followed by a space followed by “day”, “week”, “month” or “year”)
date_next Next lineitem recurring billing date
date_start Lineitem recurring date started.
date_end Recurring lineitem duration end date.
date_fail Last lineitem declined date
date_pending Lineitem billing date pending
date_deposited Lineitem billing date deposited
recurring_status Lineitem recurring status
status Bill Status (values: bill, refund)
bill_method Billing method (values: NULL, ach, credit_card, amex, atmd, bill_me_later, fxsource, paypal_int, paypal_pl, acculynk)


shipping

Parameter Description
shipping_id Shipment ID for invoice
date_shipped Date and time the invoice was shipped
tracking_number Tracking number entered on invoice
tracking_url Tracking url listed on shipping method
shipping_method_id Shipping method ID
shipping_method Shipping method name
shipping_name Recipient name
address_1 Shipping address line 1
address_2 Shipping address line 2
city Shipping city
state Shipping state
postal_code Shipping postal code
country_code Shipping country code
country Shipping country

Example API Call

Twocheckout::username('testlibraryapi901248204');
Twocheckout::password('testlibraryapi901248204PASS');
// Twocheckout::sandbox(true);  #Uncomment to use Sandbox

$args = array(
    'sale_id' => 4834917619
);
try {
    $result = Twocheckout_Sale::retrieve($args);
} catch (Twocheckout_Error $e) {
    $e->getMessage();
}
Twocheckout::API.credentials = {
  :username => 'APIuser1817037',
  :password => 'APIpass1817037',
# :sandbox => 1   #Uncomment to use Sandbox
}

begin
  sale = Twocheckout::Sale.find(:sale_id => 4786293822)
rescue Exception => e
  puts e.message
end
var tco = new Twocheckout({
    apiUser: "APIuser1817037",
    apiPass: "APIpass1817037",
    sandbox: false 
});

args = {
    sale_id: "4647892238"
};

tco.sales.retrieve(args, function (error, data) {
    if (error) {
        console.log(error);
    } else {
        console.log(data.response_code);
    }
});
twocheckout.Api.auth_credentials({
    'username': APIuser1817037',
    'password': 'APIpass1817037',
#   'mode': 'sandbox'  #Uncomment to use Sandbox
})

params = {
    'sale_id': 4774467596
}

try:
    sale = twocheckout.Sale.find(params)
except TwocheckoutError as error:
    print error.message
TwoCheckoutConfig.ApiUsername = "APIuser1817037";
TwoCheckoutConfig.ApiPassword = "APIpass1817037";
// TwoCheckoutConfig.Sandbox = true;    #Uncomment to use Sandbox

try
{
    var ServiceObject = new SaleService();
    var ArgsObject = new SaleRetrieveServiceOptions();
    ArgsObject.sale_id = "4831145902";

    var result = ServiceObject.Retrieve(ArgsObject);
    Console.Write(result);
}
catch (TwoCheckoutException e)
{
    Console.Write(e);
}
TwoCheckoutConfig.ApiUsername = "APIuser1817037";
TwoCheckoutConfig.ApiPassword = "APIpass1817037";
// Twocheckout.mode = "sandbox";    #Uncomment to use Sandbox

try {
    Sale sale = TwocheckoutSale.retrieve("4832772521");
} catch (TwocheckoutException e) {
    String message = e.toString();
}
curl -G https://www.2checkout.com/api/sales/detail_sale \
    -H 'Accept: application/json' -d 'sale_id=4647892238' -u 'username:password'

Example Successful Response

{
   "response_code" : "OK",
   "response_message" : "Sale detail retrieved",
   "sale" : {
      "comments" : [
         {
            "changed_by_ip" : "192.168.0.1",
            "comment" : "[* Sent: Vendor *] Refund Issued On Sale: test sale",
            "timestamp" : "2012-03-31 10:56:31",
            "username" : "api_user"
         },
         {
            "changed_by_ip" : "192.168.0.1",
            "comment" : "[* Sent: Vendor *] Recurring billing stopped for test",
            "timestamp" : "2012-03-31 10:56:30",
            "username" : "api_user"
         }
      ],
      "customer" : {
         "address_1" : "123 test st",
         "address_2" : null,
         "address_id" : "4647892310",
         "cardholder_name" : "Testing  Tester",
         "city" : "test",
         "country_code" : "USA",
         "country_name" : "United States",
         "customer_id" : "4647892244",
         "email_address" : "api_user@fake-company.com",
         "first_name" : "Testing",
         "lang" : "en",
         "last_name" : "Tester",
         "middle_initial" : null,
         "pay_method" : {
            "avs" : null,
            "cvv" : null,
            "first_six_digits" : null,
            "last_two_digits" : null,
            "method" : "paypal ec"
         },
         "phone" : "123465789",
         "phone_ext" : "",
         "postal_code" : "43123",
         "prefix" : null,
         "state" : "OH"
      },
      "date_placed" : "2012-02-29 13:29:28",
      "detail_ip" : {
         "address" : "66.194.132.135",
         "area_code" : 740,
         "city" : "Galena",
         "country" : "United States",
         "country_code" : "US",
         "region" : "OH",
         "zip" : "43021"
      },
      "invoices" : [
         {
            "customer_total" : "1.00",
            "date_placed" : "2012-02-29 13:29:28",
            "date_shipped" : null,
            "date_vendor_paid" : null,
            "fees_2co" : "0.54",
            "invoice_id" : "4647892247",
            "lineitems" : [
               {
                  "affiliate_vendor_id" : null,
                  "billing" : {
                     "amount" : "1.53",
                     "bill_method" : "paypal_int",
                     "billing_id" : "4647892307",
                     "customer_amount" : "1.00",
                     "customer_id" : "4647892244",
                     "date_deposited" : "2012-02-29",
                     "date_end" : null,
                     "date_fail" : "2012-03-07",
                     "date_next" : "2012-03-29",
                     "date_pending" : "2012-02-29",
                     "date_start" : "2012-03-02",
                     "lineitem_id" : "4647892301",
                     "recurring_status" : "completed",
                     "status" : "bill",
                     "usd_amount" : "1.53",
                     "vendor_amount" : "1.00"
                  },
                  "commission" : null,
                  "commission_affiliate_vendor_id" : null,
                  "commission_flat_rate" : null,
                  "commission_percentage" : null,
                  "commission_type" : null,
                  "commission_usd_amount" : null,
                  "customer_amount" : "1.00",
                  "flat_rate" : null,
                  "installment" : "1",
                  "invoice_id" : "4647892247",
                  "lc_affiliate_vendor_id" : null,
                  "lc_usd_amount" : null,
                  "lineitem_id" : "4647892301",
                  "linked_id" : null,
                  "options" : [],
                  "percentage" : null,
                  "product_description" : "test",
                  "product_duration" : "Forever",
                  "product_handling" : "0.00",
                  "product_id" : "4647888428",
                  "product_is_cart" : "0",
                  "product_name" : "test",
                  "product_price" : "1.00",
                  "product_recurrence" : "1 Month",
                  "product_startup_fee" : null,
                  "product_tangible" : "0",
                  "sale_id" : "4647892238",
                  "status" : "bill",
                  "type" : null,
                  "usd_amount" : "1.53",
                  "usd_commission" : null,
                  "vendor_amount" : "1.00",
                  "vendor_product_id" : "1178646973"
               },
               {
                  "affiliate_vendor_id" : null,
                  "billing" : {
                     "amount" : "1.53",
                     "bill_method" : "paypal_int",
                     "billing_id" : "4672854535",
                     "customer_amount" : "1.00",
                     "customer_id" : "4647892244",
                     "date_deposited" : "2012-03-31",
                     "date_end" : null,
                     "date_fail" : "2012-04-05",
                     "date_next" : null,
                     "date_pending" : "2012-03-31",
                     "date_start" : "2012-03-31",
                     "lineitem_id" : "4672854532",
                     "recurring_status" : null,
                     "status" : "refund",
                     "usd_amount" : "1.53",
                     "vendor_amount" : "1.00"
                  },
                  "commission" : null,
                  "commission_affiliate_vendor_id" : null,
                  "commission_flat_rate" : null,
                  "commission_percentage" : null,
                  "commission_type" : null,
                  "commission_usd_amount" : null,
                  "customer_amount" : "1.00",
                  "flat_rate" : null,
                  "installment" : "1",
                  "invoice_id" : "4647892247",
                  "lc_affiliate_vendor_id" : null,
                  "lc_usd_amount" : null,
                  "lineitem_id" : "4672854532",
                  "linked_id" : "4647892301",
                  "options" : [],
                  "percentage" : null,
                  "product_description" : "test",
                  "product_duration" : "Forever",
                  "product_handling" : "0.00",
                  "product_id" : "4647888428",
                  "product_is_cart" : "0",
                  "product_name" : "test",
                  "product_price" : "1.00",
                  "product_recurrence" : "1 Month",
                  "product_startup_fee" : null,
                  "product_tangible" : "0",
                  "sale_id" : "4647892238",
                  "status" : "refund",
                  "type" : null,
                  "usd_amount" : "1.53",
                  "usd_commission" : null,
                  "vendor_amount" : "1.00",
                  "vendor_product_id" : "1178646973"
               }
            ],
            "recurring" : "1",
            "referrer" : "http://fake-company.com/buy.php",
            "sale_id" : "4647892238",
            "shipping" : null,
            "status" : "deposited",
            "usd_total" : "1.53",
            "vendor_id" : "532001",
            "vendor_order_id" : "1",
            "vendor_total" : "1.00"
         },
         {
            "customer_total" : "1.00",
            "date_placed" : "2012-03-29 02:32:58",
            "date_shipped" : null,
            "date_vendor_paid" : null,
            "fees_2co" : "0.54",
            "invoice_id" : "4671118593",
            "lineitems" : [
               {
                  "affiliate_vendor_id" : null,
                  "billing" : {
                     "amount" : "1.53",
                     "bill_method" : "paypal_int",
                     "billing_id" : "4671118602",
                     "customer_amount" : "1.00",
                     "customer_id" : "4647892244",
                     "date_deposited" : "2012-03-28",
                     "date_end" : "1999-01-01",
                     "date_fail" : "2012-04-05",
                     "date_next" : "2012-04-29",
                     "date_pending" : "2012-03-29",
                     "date_start" : "2012-03-31",
                     "lineitem_id" : "4671118599",
                     "recurring_status" : "stopped",
                     "status" : "bill",
                     "usd_amount" : "1.53",
                     "vendor_amount" : "1.00"
                  },
                  "commission" : null,
                  "commission_affiliate_vendor_id" : null,
                  "commission_flat_rate" : null,
                  "commission_percentage" : null,
                  "commission_type" : null,
                  "commission_usd_amount" : null,
                  "customer_amount" : "1.00",
                  "flat_rate" : null,
                  "installment" : "2",
                  "invoice_id" : "4671118593",
                  "lc_affiliate_vendor_id" : null,
                  "lc_usd_amount" : null,
                  "lineitem_id" : "4671118599",
                  "linked_id" : null,
                  "options" : [],
                  "percentage" : null,
                  "product_description" : "test",
                  "product_duration" : "Forever",
                  "product_handling" : "0.00",
                  "product_id" : "4647888428",
                  "product_is_cart" : "0",
                  "product_name" : "test",
                  "product_price" : "1.00",
                  "product_recurrence" : "1 Month",
                  "product_startup_fee" : null,
                  "product_tangible" : "0",
                  "sale_id" : "4647892238",
                  "status" : "bill",
                  "type" : null,
                  "usd_amount" : "1.53",
                  "usd_commission" : null,
                  "vendor_amount" : "1.00",
                  "vendor_product_id" : "1178646973"
               },
               {
                  "affiliate_vendor_id" : null,
                  "billing" : {
                     "amount" : "1.53",
                     "bill_method" : "paypal_int",
                     "billing_id" : "4672854541",
                     "customer_amount" : "1.00",
                     "customer_id" : "4647892244",
                     "date_deposited" : "2012-03-31",
                     "date_end" : null,
                     "date_fail" : "2012-04-05",
                     "date_next" : null,
                     "date_pending" : "2012-03-31",
                     "date_start" : "2012-03-31",
                     "lineitem_id" : "4672854538",
                     "recurring_status" : null,
                     "status" : "refund",
                     "usd_amount" : "1.53",
                     "vendor_amount" : "1.00"
                  },
                  "commission" : null,
                  "commission_affiliate_vendor_id" : null,
                  "commission_flat_rate" : null,
                  "commission_percentage" : null,
                  "commission_type" : null,
                  "commission_usd_amount" : null,
                  "customer_amount" : "1.00",
                  "flat_rate" : null,
                  "installment" : "2",
                  "invoice_id" : "4671118593",
                  "lc_affiliate_vendor_id" : null,
                  "lc_usd_amount" : null,
                  "lineitem_id" : "4672854538",
                  "linked_id" : "4671118599",
                  "options" : [],
                  "percentage" : null,
                  "product_description" : "test",
                  "product_duration" : "Forever",
                  "product_handling" : "0.00",
                  "product_id" : "4647888428",
                  "product_is_cart" : "0",
                  "product_name" : "test",
                  "product_price" : "1.00",
                  "product_recurrence" : "1 Month",
                  "product_startup_fee" : null,
                  "product_tangible" : "0",
                  "sale_id" : "4647892238",
                  "status" : "refund",
                  "type" : null,
                  "usd_amount" : "1.53",
                  "usd_commission" : null,
                  "vendor_amount" : "1.00",
                  "vendor_product_id" : "1178646973"
               }
            ],
            "recurring" : "1",
            "referrer" : "http://www.fake-company.com/buy.php",
            "sale_id" : "4647892238",
            "shipping" : null,
            "status" : "deposited",
            "usd_total" : "1.53",
            "vendor_id" : "532001",
            "vendor_order_id" : "1",
            "vendor_total" : "1.00"
         }
      ],
      "ip_address" : "66.194.132.135",
      "ip_country" : "United States",
      "recurring_decline" : null,
      "sale_id" : "4647892238"
   }
}

Common Error Codes

Code Description
PARAMETER_MISSING Required parameter missing:
PARAMETER_INVALID Invalid value for parameter:
RECORD_NOT_FOUND Unable to find record.
FORBIDDEN Access denied to sale.