updates RSS feed

List Options

Overview

The list_options call is used to retrieve list of all options in the account.

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

HTTP Method: GET

Input Parameters

Parameter Description
option_name Filter list results by option name. Optional.
option_value_name Filter list results by option value name. 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 option_id and option_name. (case insensitive) Optional.
sort_dir The direction of the sort process. (‘ASC’ or ‘DESC’) (case insensitive) Optional.

 

Data Returned

options

Parameter Description
option_id System Option ID
option_name Option name
option_values
Parameter Description
option_id System Option ID
option_value_id System Option ID
option_value_surcharge Option value surcharge
option_value_name Option value name
option_name Option name

Example API Call

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

Example Successful Response

 {
       "options" : [
          {
             "option_id" : "4688550010",
             "option_name" : "Volume",
             "option_values" : [
                {
                   "option_value_id" : "4688550013",
                   "option_value_name" : "Low",
                   "option_value_surcharge" : "1.00"
                },
                {
                   "option_value_id" : "4688550016",
                   "option_value_name" : "Medium",
                   "option_value_surcharge" : "2.00"
                },
                {
                   "option_value_id" : "4688550019",
                   "option_value_name" : "High",
                   "option_value_surcharge" : "3.00"
                }
             ]
          }
       ],
       "page_info" : {
          "cur_page" : "1",
          "first_entry" : 1,
          "first_page" : 1,
          "first_page_url" : "https://www.2checkout.com/api/products/list_options?cur_page=1",
          "last_entry" : "1",
          "last_page" : 1,
          "last_page_url" : "https://www.2checkout.com/api/products/list_options?cur_page=1",
          "next_page" : null,
          "pagesize" : "20",
          "previous_page" : null,
          "total_entries" : "1"
       },
       "response_code" : "OK",
       "response_message" : "Option information retrieved successfully."
    }

Common Error Codes

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

Delete Product

Overview

The delete_product call is used to delete a product.

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

HTTP Method: POST

 

Input Parameters

Parameter Description
product_id 2CO system product ID to delete. 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/products/delete_product \
    -H 'Accept: application/json' -u 'username:password' \
    -d 'product_id=4136649378'

Example Successful Response

 {
       "response_code" : "OK",
       "response_message" : "Product successfully deleted."
    }

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.

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.

Mark Shipped

 

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 Sale

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)

Reauthorize

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.

List Sales

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.

Need help?

Do you have a question? If you didn’t find the answer you are looking for in our documentation, you can contact our Support teams for more information. If you have a technical issue or question, please contact us. We are happy to help.

Get in touch

Not yet a Verifone customer?

We’ll help you choose the right payment solution for your business, wherever you want to sell, in-person or online. Our team of experts will happily discuss your needs.

Contact sales Get Started
Verifone logo