Skip to main content

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.

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.

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.

Verifone logo