| Verifone Developer Portal

Update Product

Overview

The update_product call is used to update a product.

URL: https://www.2checkout.com/api/products/update_product

HTTP Method: POST

Input Parameters

Parameter	Description
product_id	ID of product to update. Required.
name	Product Name. Required.
price	Product Price. Required.
vendor_product_id	Merchant Assigned Product ID. Optional.
description	Product Short Description. Optional.
long_description	Product Long Description. Optional.
pending_url	Product Pending URL. Optional.
approved_url	Product Approved URL. Optional.
tangible	Tangible=1, Intangible=0. Optional.
weight	Decimal value of weight. Required for tangible products.
handling	Specifies handling charge if applicable. Required for tangible products.
recurring	1 = recurring, 0 = non-recurring. Required for recurring products.
startup_fee	Specifies start up fee if applicable. Optional.
recurrence	Specifies recurrence frequency (n Week
duration	Specifies recurrence duration (n Week
commission	1 = commission, 0 = no commission. Required for affiliate products.
commission_type	Sets commission type for product. Possible values: amount, percentage. Required for affiliate products.
commission_amount	Sets commission value for product (based on commission_type). Required for affiliate products.
option_id	Accepts single or multiple option IDs to assign to product. (multiple IDs would be &option_id=xxxxxxxxx repeated for each ID to assign, where xxxxxxxxx represents each ID value to assign.) Optional.
category_id	Accepts single or multiple category IDs to assign product to. (multiple IDs would be &category_id=xxxxxxxxx repeated for each ID to assign, where xxxxxxxxx represents each ID value to assign.) Optional.

Data Returned

Parameter	Description
response_code	Tells the user whether or not the operation was successful.
response_message	Tells the user why the operation was or was not successful.

Example API Call

curl -X POST https://www.2checkout.com/api/products/update_product \
    -H 'Accept: application/json' -u 'username:password' \
    -d 'name=test product' -d 'price=1.00' -d 'product_id=4691409938'

Example Successful Response

 {
       "assigned_product_id" : "2561",
       "product_id" : "4691409938",
       "response_code" : "OK",
       "response_message" : "Product successfully updated"
    }

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

Overview

The mark_shipped call is used to attempt to mark an order as shipped and will attempt to reauthorize sale if specified in call. This call will send the SHIP_STATUS_CHANGED INS message.

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

HTTP Method: POST

Input Parameters

Parameter	Description
sale_id	The order number/sale ID to mark shipped. Optional when invoice_id is present.
invoice_id	ID of the invoice to add tracking information to. Required on sales with more than one invoice.
tracking_number	The tracking number issued by the shipper. Required.
cc_customer	Specify whether the customer should be automatically notified. Use “1” for true. Defaults to false. Optional.
reauthorize	Reauthorize payment if payment authorization has expired. Defaults to false. Optional.
comment	Any text except for “<” and “>” up to 255 chars in length. Optional.

Data Returned

Parameter	Description
response_code	Tells the user whether or not the operation was successful.
response_message	Tells the user why the operation was or was not successful.

Example API Call

curl -X POST https://www.2checkout.com/api/sales/mark_shipped \ -H 'Accept: application/json' -u 'username:password' \ -d 'tracking_number=123' -d 'cc_customer=1' -d 'sale_id=1234567890'

Example Successful Response

{ "response_code" : "OK", "response_message" : "Sale marked shipped." }

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.

Method Specific Error Codes

Code	Description
NOTHING_TO_DO	Item not shippable.
TOO_LATE	Payment is already pending or deposited and cannot be reauthorized.
TOO_SOON	Please wait until the next day before trying to reauthorize again.
FAILED	Failed to reauthorize payment.
INTERNAL_ERROR	Failed to marked shipped but reauthorization succeeded.
INTERNAL_ERROR	Failed to marked shipped.

Create Product

Overview

The create_product call is used to create a new product.

URL: https://www.2checkout.com/api/products/create_product

HTTP Method: POST

Input Parameters

Parameter	Description
name	Product Name. Required.
price	Product Price. Required.
vendor_product_id	Merchant Assigned Product ID. Optional.
description	Product Short Description. Optional.
long_description	Product Long Description. Optional.
pending_url	Product Pending URL. Optional.
approved_url	Product Approved URL. Optional.
tangible	Tangible = 1, Intangible = 0. Optional.
weight	Decimal value of weight. Required for tangible products.
handling	Specifies handling charge if applicable. Required for tangible products.
recurring	1 = recurring, 0 = non-recurring. Required for recurring products.
startup_fee	Specifies start up fee if applicable. Optional.
recurrence	Sets billing frequency. Ex. ‘1 Week’ to bill order once a week. (Can use # Week, # Month, or # Year)
duration	Sets how long to continue billing. Ex. ‘1 Year’, to continue billing based on li_#_recurrence for 1 year. (Forever or # Week, # Month, # Year)
commission	1 = commission, 0 = no commission. Required for affiliate products.
commission_type	Sets commission type for product. Possible value - amount, percentage. Required for affiliate products.
commission_amount	Sets commission value for product (based on commission_type). Required for affiliate products.
option_id	Accepts single or multiple option IDs to assign to product. (multiple IDs would be &option_id=xxxxxxxxx repeated for each ID to assign, where xxxxxxxxx represents each ID value to assign.) Optional.
category_id	Accepts single or multiple category IDs to assign product to. (multiple IDs would be &category_id=xxxxxxxxx repeated for each ID to assign, where xxxxxxxxx represents each ID value to assign.) Optional. See Valid Category IDs section below for defenetions.

Valid Category IDs

The values below can be passed in using the category_id parameter to select single or multiple category IDs to assign to product.

Art & Antiques

ID	Description
15	Prints
16	Paintings
17	Photography
18	Digital Art
19	Multimedia & Crafts
20	Antiques
1	Other

Business Solutions & Office Products

ID	Description
21	Advice & Instruction
22	Printing & Personalization
23	Office Supplies
24	Graphics & Logo Design
25	Online Advertising & Internet Services
26	Hosting
27	Domain Registration
2	Other

Apparel & Accessories

ID	Description
28	Women’s Apparel
29	Men’s Apparel
30	Kids Apparel
31	Shoes
32	Jewelry & Watches
33	Purses & Other Accessories
34	Baby Apparel
35	Maternity Apparel
3	Other

Home, Garden & Pets

ID	Description
36	Kitchen & Dining
37	Bedding & Bath
38	Garden & Patio
39	Pet Supplies
40	Baby Blankets & Gear
4	Other

Software

ID	Description
41	Graphics
42	Business & Productivity
43	Web Publishing
44	Religious
5	Other

Electronics & Computers

ID	Description
45	Audio, Video, MP3, & Cameras
46	Cell Phones & Accessories
47	Computers & Hardware
6	Other

Books

ID	Description
48	Fiction
49	Non-Fiction
50	E-Books
7	Other

Gifts, Flowers & Gourmet Food

ID	Description
51	Flowers
52	Food & Gourmet
53	Gift Baskets
54	Baby Gifts
8	Other

Sports & Outdoors

ID	Description
55	Camping & Outdoors
56	Sports & Fitness
9	Other

Toys, Games, & Video Games

ID	Description
57	Kids Toys
58	Collectibles
59	Games
60	Baby Toys
76	Online Gaming
10	Other

Movies, Videos, Music, CDs, DVDs & VHS

ID	Description
61	Movies
62	Music
63	Fitness
64	Television
65	Instructional
11	Other

Adult

ID	Description
67	Apparel
68	Toys & Novelties
75	Online Dating
12	Other

Health & Beauty

ID	Description
69	Cosmetics, Fragrance & Beauty Aids
70	Vitamins & Dietary Supplements
71	Bath & Personal Care
72	Nursing & Maternity
13	Other

Automotive

ID	Description
73	Accessories & Bumper Stickers
74	Parts
14	Other

Travel Services

ID	Description
78	Services
79	Software
77	Other

Education

ID	Description
81	Essays & Papers
80	Other

Data Returned

Parameter	Description
response_code	Tells the user whether or not the operation was successful.
response_message	Tells the user why the operation was or was not successful.
assigned_product_id	2CO Assigned Product ID
product_id	ID assigned to the product by 2Checkout.

Example API Call

curl -X POST https://www.2checkout.com/api/products/create_product \
    -H 'Accept: application/json' -u 'username:password' \
    -d 'name=test product' -d 'price=1.00' -d 'vendor_product_id=123456789'

Example Successful Response

{
       "assigned_product_id" : "2560",
       "product_id" : "4688359093",
       "response_code" : "OK",
       "response_message" : "Product successfully created"
    }

Common Error Codes

Code	Description
PARAMETER_MISSING	Required parameter missing:
PARAMETER_INVALID	Invalid value for parameter:

Stop Recurring

Stop Lineitem Recurring

The stop_lineitem_recurring call is used to attempt to stop a recurring line item for a specified sale. This call will send the RECURRING_STOPPED INS message.

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

HTTP Method: POST

Input Parameters

Parameter	Description
lineitem_id	Line Item ID to stop recurring on. Required.

Data Returned

Parameter	Description
response_code	Tells the user whether or not the operation was successful
response_message	Tells the user why the operation was or was not successful

Example API Call

curl -X POST https://www.2checkout.com/api/sales/stop_lineitem_recurring -u \
    'username:password' -d 'vendor_id=123456' -d 'lineitem_id=1234567890' \
    -H 'Accept: application/json'

Example Successful Response

 {
       "response_code" : "OK",
       "response_message" : "Recurring billing stopped for lineitem"
    }

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.

Refund Lineitem

Overview

The refund_lineitem call is used to attempt to issue a full refund on a lineitem. This call will send the REFUND_ISSUED INS message.

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

HTTP Method: POST

Input Parameters

Parameter	Description
lineitem_id	Line item to issue refund on. Required.
category	ID representing the reason the refund was issued. Required. (values: 1-17 from the following list can be used except for 7 as it is for internal use only)

ID	Description
1	Did not receive order
2	Did not like item
3	Item(s) not as described
4	Fraud
5	Other
6	Item not available
7	Do Not Use (Internal use only)
8	No response from merchant
9	Recurring last installment
10	Cancellation
11	Billed in error
12	Prohibited product
13	Service refunded at merchants request
14	Non delivery
15	Not as described
16	Out of stock
17	Duplicate

Data Returned

Parameter	Description
response_code	Tells the user whether or not the operation was successful
response_message	Tells the user why the operation was or was not successful

Example API Call

curl -X POST https://www.2checkout.com/api/sales/refund_lineitem \
    -u 'username:password' -d 'lineitem_id=1234567890' -d 'category=16' \
    -d 'comment=Item not in stock.' -H 'Accept: application/json'

Example Successful Response

 {
       "response_code" : "OK",
       "response_message" : "lineitem refunded"
    }

Common Error Codes

Code	Description
PARAMETER_MISSING	Required parameter missing:
PARAMETER_INVALID	Required parameter is invalid:
RECORD_NOT_FOUND	Unable to find record.
FORBIDDEN	Access denied to sale.

Method-Specific Error Codes

Code	Description
FORBIDDEN	Permission denied to set refund category to 7.
INVALID_PARAMETER	This lineitem cannot be refunded.
NOTHING_TO_DO	Lineitem was already refunded.
TOO_LATE	Invoice too old to refund lineitem. (Will occur if sale is over 180 days)
TOO_HIGH	Lineitem amount greater than remaining balance on invoice.
TOO_LOW	Lineitem amount must be at least 0.01.

Refund Invoice

The refund_invoice call is used to attempt to issue a full or partial refund on an invoice. This call will send the REFUND_ISSUED INS message.

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

HTTP Method: POST

Input Parameters

Parameter	Description
sale_id	Order number/sale ID to issue a refund on. Optional when invoice_id is specified, otherwise required.
invoice_id	Invoice ID to issue a refund on. Optional when sale_id is specified and sale only has 1 invoice.
amount	The amount to refund. Only needed when issuing a partial refund. If an amount is not specified, the remaining amount for the invoice is assumed.
currency	Currency type of refund amount. Can be ‘usd’, ‘vendor’ or ‘customer’. Only required if amount is used.
comment	Message explaining why the refund was issued. Required. May not contain ‘<’ or ‘>’. (5000 character max)
category	ID representing the reason the refund was issued. Required. (values: 1-17 from the following list can be used except for 7 as it is for internal use only)

ID	Description
1	Did not receive order
2	Did not like item
3	Item(s) not as described
4	Fraud
5	Other
6	Item not available
7	Do Not Use (Internal use only)
8	No response from merchant
9	Recurring last installment
10	Cancellation
11	Billed in error
12	Prohibited product
13	Service refunded at merchants request
14	Non delivery
15	Not as described
16	Out of stock
17	Duplicate

Data Returned

Parameter	Description
response_code	Tells the user whether or not the operation was successful
response_message	Tells the user why the operation was or was not successful

Example API Call

curl -X POST https://www.2checkout.com/api/sales/refund_invoice \
    -u 'username:password' -d 'sale_id=1234567890' -d 'amount=1.00' \
    -d 'currency=true' -d 'category=13' -H 'Accept: application/json' \
    -d 'comment=Buyer deserved a refund.'

Example Successful Response

 {
       "response_code" : "OK",
       "response_message" : "refund added to invoice"
    }

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.

Method-Specific Error Codes

Code	Description
FORBIDDEN	Permission denied to set refund category to 7.
FORBIDDEN	Access denied to invoice.
AMBIGUOUS	Ambiguous request. Multiple invoices on sale. invoice_id parameter required.
TOO_LOW	Amount must be at least 0.01.
NOTHING_TO_DO	Invoice was already refunded.
TOO_HIGH	Amount greater than remaining balance on invoice.
TOO_LATE	Invoice too old to refund. (Will occur if sale is over 180 days)

Overview

The reauthorize call is used to attempt to reauthorize sale having expired pre-authorized payment. Please note you can only attempt to reauthorize a sale once per day.

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

HTTP Method: POST

Input Parameters

Parameter	Description
sale_id	The order number/sale ID to reauthorize. Required.

Data Returned

Parameter	Description
response_code	Tells the user whether or not the operation was successful
response_message	Tells the user why the operation was or was not successful

Example API Call

curl -X POST https://www.2checkout.com/api/sales/reauth -u 'username:password' \
    -d 'sale_id=1234567890' -H 'Accept: application/json'

Example Successful Response

  {
       "response_code" : "OK",
       "response_message" : "Payment reauthorized."
    }

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.

Method-Specific Error Codes

Code	Description
TOO_LATE	Payment is already pending or deposited and cannot be reauthorized.
TOO_SOON	Please wait until the next day to reauthorize again.
FAILED	Failed to reauthorize payment.

Overview

The list_sales call is used to retrieve a summary of all sales or only those matching a variety of sale attributes.

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

HTTP Method: GET

Input Parameters

Parameter	Description
sale_id	Search for sale with this Sale ID. Optional.
invoice_id	Search for a Sale with this Invoice ID. Optional.
customer_name	Search for sales with this cardholder name. Must be at least 3 chars and can be substring of cardholder name. Case Insensitive. Optional.
customer_email	Search for sales with this buyer email. Can be substring of the email. Case insensitive. Optional.
customer_phone	Search for sales with this phone number. Can be an incomplete number but must match from the beginning. Optional.
vendor_product_id	Search for sales with this product id. Can be substring of the id. Optional.
ccard_first6	Search for sales with these First 6 numbers of the credit card number. Optional.
ccard_last2	Search for sales with these Last 2 numbers of the credit card number. Optional.
sale_date_begin	Search for sales from this date to current date (or sale_date_end). Optional.
sale_date_end	Search for sales from beginning of time (or sale_date_begin) to this date. Optional.
declined_recurrings	Search for declined recurring sales. Optional.
active_recurrings	Search for active recurring sales. Optional.
refunded	Search for sales that have been refunded in full or partially. Optional.
cur_page	The page number to retrieve. First page = 1. Optional.
pagesize	Total rows per page. Possible values are 1-100. If pagesize not specified, default of 20 items per page will be assigned internally. Optional.
sort_col	The name of the column to sort on. Possibile values are sale_id, date_placed, customer_name, recurring, recurring_declined and usd_total. (case insensitive) Optional.
sort_dir	The direction of the sort process. (‘ASC’ or ‘DESC’) (case insensitive) Optional.

Data Returned

Parameter	Description
sale_id	Order number/Sale Number
date_placed	Date the order was placed
customer_name	Buyer name
recurring	Is the order recurring (values: 0=No, 1=Yes)
recurring_declined	Date of most recent recurring decline
decline_code	Decline code of most recent recurring decline
usd_total	Buyer total in USD
sale_url	Direct url to sale detail page

Example API Call

curl -G https://www.2checkout.com/api/sales/list_sales \
    -H 'Accept: application/json' -u 'username:password' \
    -d 'sort_col=date_placed' -d 'sort_dir=desc'

Example Successful Response

{
       "page_info" : {
          "cur_page" : "1",
          "first_entry" : 1,
          "first_page" : 1,
          "first_page_url" : "https://www.2checkout.com/api/sales/list_sales?cur_page=1",
          "last_entry" : "4",
          "last_page" : 1,
          "last_page_url" : "https://www.2checkout.com/api/sales/list_sales?cur_page=1",
          "next_page" : null,
          "pagesize" : "20",
          "previous_page" : null,
          "total_entries" : "4"
       },
       "response_code" : "OK",
       "response_message" : "Sales summaries retrieved successfully.",
       "sale_summary" : [
          {
             "customer_name" : "Testing  Tester",
             "date_placed" : "2012-03-30",
             "decline_code" : null,
             "recurring" : "0",
             "recurring_declined" : null,
             "sale_id" : "4672226243",
             "sale_url" : "https://www.2checkout.com/api/sales/detail_sale?sale_id=4672226243",
             "usd_total" : "2.00"
          },
          {
             "customer_name" : "Testing  Tester",
             "date_placed" : "2012-03-30",
             "decline_code" : null,
             "recurring" : "0",
             "recurring_declined" : null,
             "sale_id" : "4672223284",
             "sale_url" : "https://www.2checkout.com/api/sales/detail_sale?sale_id=4672223284",
             "usd_total" : "2.00"
          },
          {
             "customer_name" : "Testing  Tester",
             "date_placed" : "2012-03-27",
             "decline_code" : null,
             "recurring" : "0",
             "recurring_declined" : null,
             "sale_id" : "4669698261",
             "sale_url" : "https://www.2checkout.com/api/sales/detail_sale?sale_id=4669698261",
             "usd_total" : "1.00"
          },
          {
             "customer_name" : "Testing  Tester",
             "date_placed" : "2012-03-26",
             "decline_code" : null,
             "recurring" : "0",
             "recurring_declined" : null,
             "sale_id" : "4669135919",
             "sale_url" : "https://www.2checkout.com/api/sales/detail_sale?sale_id=4669135919",
             "usd_total" : "1.00"
          }
       ]
    }

Common Error Codes

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

Overview

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

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.

Overview

(Formally known as Back Office API)

2Checkout’s Admin API provides a way to automate both account and order management processes. Using the Admin API along with the Instant Notification Service alleviates the necessity of logging into the standard GUI account interface on a day-to-day basis.

The Admin API system works by first having the user create an API username in their 2Checkout account which has the appropriate permissions to access the Admin API. This API username can be used to authenticate the supported methods described below to call our Admin API by HTTP POST or GET to update or return sale information. To create a username, please log in to your account, click on the Account tab and User Management sub-tab. From here, please click the Create Username link and create a new username with API Access and API Updating selected for the Access type. Our Admin API can then be accessed with this new username and password you created.

The Admin API will return XML by default unless the Accept: header is passed in the call to define the content type. The Admin API is capable of returning data in the following formats:

XML (application/xml) - default
JSON (application/json)
HTML XOXO microformat (text/html)

Simple bindings for each method are provided through our community supported libraries.

You can also call each method without using our libraries. Below is an example script that makes a detail_sale call.

var tco = new Twocheckout({
    apiUser: "APIuser1817037,
    apiPass: "APIpass1817037
});

args = {
    lineitem_id: "4774380224"
};

tco.sales.stop(args, function (error, data) {
    if (error) {
        console.log(error);
    } else {
        console.log(data.response_code);
    }
});

Errors

If a request cannot be completed successfully, the response from the Admin API will contain information that can be used to determine what went wrong. There are several ways to determine that the request was unsuccessful. Either the HTTP Status header will contain a status code of 400 or higher (typically 400, 404, or 500). Or There will be one or more errors elements in the response. Each of these elements will contain an error code, message, and (if applicable) other informative values to assist in debugging the problem such as the offending parameter name.

Example response:

{
      "code" : "PARAMETER_MISSING",
      "message" : "Required parameter missing: vendor_id",
      "parameter" : "vendor_id"
    }