| Verifone Developer Portal

Update Coupon

Overview

The update_coupon call is used to update a coupon.

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

HTTP Method: POST

Input Parameters

Parameter	Description
coupon_code	The string value of the existing coupon code. Required.
new_code	String value of new coupon code. Optional.
date_expire	New expiration date of coupon. (YYYY-MM-DD) Optional.
type	Denotes if coupon applies to shipping, sale or product. Required.
percentage_off	Percentage, if supplied, to discount from purchase price. (value_off must be NULL, if percentage_off used) Optional.
value_off	Decimal value of amount to discount. (percentage_off must be NULL, if value_off used) Optional.
minimum_purchase	Decimal value indicating minimum purchase required before discount applies. Required if percentage_off or value_off are specified.
product_id	Can accept multiple product_ids in querystring. (i.e. product_id=1112223333&product_id=2223334444) Required for product coupons if select_all is not specified.
select_all	Set to 1 to enable. Set to 0 to remove all product assignments. Required for product coupons if product_id is not specified.

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_coupon \
    -H 'Accept: application/json' -u 'username:password' \
    -d 'coupon_code=APIMODIFY002' -d 'date_expire=2099-12-22' -d 'type=sale'

Example Successful Response

{
       "coupon_code" : "APIMODIFY002",
       "response_code" : "OK",
       "response_message" : "Coupon updated successfully"
    }

Common Error Codes

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

Create Coupon

The create_coupon call is used to create a new coupon.

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

HTTP Method: POST

Input Parameters

Parameter	Description
coupon_code	The string value of coupon code. Optional.
date_expire	Expiration date of new coupon. (YYYY-MM-DD) Required.
type	Denotes if coupon applies to shipping, sale or product. Required.
percentage_off	Percentage, if supplied, to discount from purchase price. Can only be used with sale or product type coupons. (value_off must be NULL, if percentage_off used)
value_off	Decimal value of amount to discount. Can only be used with sale or product type coupons. (percentage_off must be NULL, if value_off used)
minimum_purchase	Decimal value indicating minimum required purchase amount before discount applies. Optional.
product_id	2CO system product ID. Can accept multiple product_ids in querystring. (i.e. product_id=112345678&product_id=987564321) Required for product coupons if select_all is not specified.
select_all	If set to true (1), will select all products and override any product_ids supplied. Set to 0 to remove all product assignments. Required for product coupons if product_id is not specified.

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.
coupon_code	ID assigned to the product by 2Checkout.

Example API Call

 curl -X POST https://www.2checkout.com/api/products/create_coupon \
    -H 'Accept: application/json' -u 'username:password' \
    -d 'coupon_code=APITEST004' -d 'date_expire=2099-12-22' -d 'type=sale' \
    -d 'value_off=5.00' -d 'minimum_purchase=10.00'

Example Successful Response

 {
       "coupon_code" : "APITEST004",
       "response_code" : "OK",
       "response_message" : "Coupon successfully created"
    }

Common Error Codes

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

Retrieve Option

Detail Option

The detail_option call is used to retrieve the details for a single option.

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

HTTP Method: GET

Input Parameters

Parameter	Description
option_id	ID value of option to get details for. Required.

Data Returned

Parameter	Description
option_value_id	System Option ID
vendor_id	Merchant ID (2Checkout Account Number) of user.
option_value_surcharge	Option value surcharge amount.
option_value_name	Option value name.
option_id	System Option ID.

Example API Call

curl -G https://www.2checkout.com/api/products/detail_option \
    -H 'Accept: application/json' -u 'username:password' \
    -d 'option_id=4688355343'

Example Successful Response

 {
       "option" : [
          {
             "option_id" : "4688355343",
             "option_name" : "decibels",
             "option_values" : [
                {
                   "option_value_id" : "4688355346",
                   "option_value_name" : "150dB",
                   "option_value_surcharge" : "11.00"
                },
                {
                   "option_value_id" : "4688441332",
                   "option_value_name" : "200dB",
                   "option_value_surcharge" : "22.00"
                },
                {
                   "option_value_id" : "4688441335",
                   "option_value_name" : "250dB",
                   "option_value_surcharge" : "33.00"
                }
             ]
          }
       ],
       "response_code" : "OK",
       "response_message" : "Option detail 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.
FORBIDDEN	Access denied to option.

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.