php

item

/item

The item REST API provides all the functionality necessary manipulate items on your UltraCart account. This is one of the largest REST APIs on the UltraCart platform due to the extensive functionality within the item object.

Software Development Kit (SDK)

To make working with our API easier, we package an SDK in the languages listed to the right. Select the language that you are interested in and sample code with additional commentary will be available. All of our APIs are available on GitHub at:

http://www.github.com/UltraCart/

By using an SDK you receive a number of important benefits.

Requirements

PHP 5.4.0 and later

Installation & Usage

Composer

To install the bindings via Composer, add the following to composer.json:

{
  "repositories": [
    {
      "type": "git",
      "url": "https://github.com/UltraCart/rest_api_v2_sdk_php.git"
    }
  ],
  "require": {
    "UltraCart/rest_api_v2_sdk_php": "*@dev"
  }
}

Then run composer install

Manual Installation

Download the GitHub files at https://github.com/UltraCart/rest_api_v2_sdk_php files and include autoload.php:

    require_once('/path/to/autoload.php');

Instantiating the API

There are four steps to instantiating the API.

  1. Include the SDK package
  2. Set the API credentials.
  3. Set the API version header.
  4. Instantiate the API Client.

Include the SDK package

require_once '/path/to/vendor/autoload.php';

Set the API credentials (for OAuth 2.0)

// Configure OAuth2 access token for authorization: ultraCartOauth
ultracart\admin\v2\Configuration::getDefaultConfiguration()->setAccessToken($access_token);

Set the API credentials (for Simple Key)

// Configure API key authorization: ultraCartSimpleApiKey
ultracart\admin\v2\Configuration::getDefaultConfiguration()->setApiKey('x-ultracart-simple-key', 'YOUR_API_KEY');

Set the API version header.

// Set the date of the API release we're using
ultracart\admin\v2\Configuration::getDefaultConfiguration()->addDefaultHeader("X-UltraCart-Api-Version", "2017-03-01");

Instantiate the API Client.

$item_api = new ultracart\admin\v2\api\ItemApi();

Expansion

The item REST API has one of the largest expansion capabilities. By default, when you read an item, a limited object is returned. If you specify the _expand parameter, additional properties of the item object are returned. We encourage you to limit the amount of information that you query for items, to the minimal amount possible to have optimal communication. The following expansion operations are available.

Retrieve items

Permissions:
  • item_read

Produces: application/json
get
/item/items

Retrieves a group of items from the account. If no parameters are specified, all items will be returned. You will need to make multiple API calls in order to retrieve the entire result set since this API performs result set pagination.

Parameters
Parameter Description Location Data Type Required
parent_category_id The parent category object id to retrieve items for. Unspecified means all items on the account. 0 = root query integer (int32) optional
parent_category_path The parent category path to retrieve items for. Unspecified means all items on the account. / = root query string optional
_limit The maximum number of records to return on this one API call. (Default 100, Max 2000)
Default: 100
query integer optional
_offset Pagination of the record set. Offset is a zero based index.
Default: 0
query integer optional
_since Fetch items that have been created/modified since this date/time. query dateTime optional
_sort The sort order of the items. See Sorting documentation for examples of using multiple values and sorting by ascending and descending.
Allowed Values
  • merchant_item_id
  • description
query string optional
_expand The object expansion to perform on the result. See documentation for examples query string optional
_placeholders Whether or not placeholder values should be returned in the result. Useful for UIs that consume this REST API. query boolean optional
Responses
Status Code Reason Response Model
200
Successful response ItemsResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500

Sample code to fetch all items from an account and print out the item id and description. Demonstrates the proper way to paginate and loop through the result set.

 // Note: To create an OAuth token or Simple API Key, login to secure.ultracart.com
 // and navigate to Home -> Configuration -> Back Office -> Authorized Applications
 // 
 // Configure OAuth2 access token for authorization: ultraCartOauth
 ultracart\admin\v2\Configuration::getDefaultConfiguration()->setAccessToken("YOUR_ACCESS_TOKEN");
 // Configure API key authorization: ultraCartSimpleApiKey
 // ultracart\admin\v2\Configuration::getDefaultConfiguration()->setApiKey('x-ultracart-simple-key', 'YOUR_API_KEY');

 $api_instance = new ultracart\admin\v2\api\ItemApi();
 $parent_category_id = null; // int | The parent category to retrieve items for.  Unspecified means all items on the account.  0 = root
 $limit = 100;
 $offset = 0;

 try {
	 for (;;) {
		 $result = $api_instance->itemItemsGet($parent_category_id, $limit, $offset);

		 foreach ($result->getItems() as $item) {
			 echo "Item: " . $item->getMerchantItemId() . " - " . $item->getDescription() . "<br/>";
		 }

		 if (count($result->getItems()) < $limit) {
			 break;
		 } else {
			 $offset += $limit;
		 }
	 }

 } catch (Exception $e) {
	 echo 'Exception when calling ItemApi->itemItemsGet: ', $e->getMessage(), PHP_EOL;
 }

Create an item

Permissions:
  • item_write

Consumes: application/json
Produces: application/json
post
/item/items

Create a new item on the UltraCart account.

Parameters
Parameter Description Location Data Type Required
item Item to create body Item required
_expand The object expansion to perform on the result. See documentation for examples query string optional
_placeholders Whether or not placeholder values should be returned in the result. Useful for UIs that consume this REST API. query boolean optional
Responses
Status Code Reason Response Model
200
Successful response ItemResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500

Delete an item

Permissions:
  • item_write

Produces: application/json
delete
/item/items/{merchant_item_oid}

Delete an item on the UltraCart account.

Parameters
Parameter Description Location Data Type Required
merchant_item_oid The item oid to delete. path integer (int32) required
Responses
Status Code Reason Response Model
204
No Content
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500

Retrieve an item

Permissions:
  • item_read

Produces: application/json
get
/item/items/{merchant_item_oid}

Retrieves a single item using the specified item oid.

Parameters
Parameter Description Location Data Type Required
merchant_item_oid The item oid to retrieve. path integer (int32) required
_expand The object expansion to perform on the result. See documentation for examples query string optional
_placeholders Whether or not placeholder values should be returned in the result. Useful for UIs that consume this REST API. query boolean optional
Responses
Status Code Reason Response Model
200
Successful response ItemResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500

Update an item

Permissions:
  • item_write

Consumes: application/json
Produces: application/json
put
/item/items/{merchant_item_oid}

Update a new item on the UltraCart account.

Parameters
Parameter Description Location Data Type Required
item Item to update body Item required
merchant_item_oid The item oid to update. path integer (int32) required
_expand The object expansion to perform on the result. See documentation for examples query string optional
_placeholders Whether or not placeholder values should be returned in the result. Useful for UIs that consume this REST API. query boolean optional
Responses
Status Code Reason Response Model
200
Successful response ItemResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500

Upload an image to the temporary multimedia.

Permissions:
  • item_write

Consumes: multipart/form-data
Produces: application/json
post
/item/temp_multimedia

Uploads an image and returns back meta information about the image as well as the identifier needed for the item update.

Parameters
Parameter Description Location Data Type Required
file File to upload formData file required
Responses
Status Code Reason Response Model
200
Successful response TempMultimediaResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500

Webhooks

The following webhook events are generated for this resource.

Event Description Response Expansion
item_create Trigger when a new item is created Item Yes
item_delete Trigger when an item is deleted Item Yes
item_update Trigger when an item is updated Item Yes

Distance

Attributes
Name Data Type Description
uom string(2) Unit of measure
Allowed Values
  • IN
  • CM
value number The distance measured in UOM

Error

Attributes
Name Data Type Description
developer_message string A technical message meant to be read by a developer
error_code string HTTP status code
more_info string Additional information often a link to additional documentation
user_message string An end-user friendly message suitable for display to the customer

ErrorResponse

Attributes
Name Data Type Description
error Error Error object if unsuccessful
metadata ResponseMetadata Meta-data about the response such as payload or paging information
success boolean Indicates if API call was successful

Item

Attributes
Name Data Type Description
accounting ItemAccounting Accounting such as QuickBooks codes
amember ItemAmember Amember configuration
auto_order ItemAutoOrder Auto Order
ccbill ItemCCBill CCBill.com
channelPartnerMappings array of ItemChannelPartnerMapping Channel Partner Item Mapping
chargeback ItemChargeback Chargeback
checkout ItemCheckout Checkout
content ItemContent Content such as multimedia and attributes
creation_dts (read only) string (dateTime) Date/time of creation
description string(512) Description of the item up to 500 characters.
description_translated_text_instance_oid (read only) integer (int32) Description translated text instance id
digital_delivery ItemDigitalDelivery Digital Delivery
ebay ItemEbay e-Bay
email_notifications ItemEmailNotifications Email notifications
enrollment123 ItemEnrollment123 Enrollment123.com
gift_certificate ItemGiftCertificate Gift Certificate
google_product_search ItemGoogleProductSearch Google Product Search
identifiers ItemIdentifiers Identifiers such as SKU, Barcode, etc.
inactive boolean True if this item is inactive and can not be purchased
instant_payment_notifications ItemInstantPaymentNotifications Instance Payment Notifications
internal ItemInternal Internal information such as memo
kit boolean True if this item is a kit
kit_definition ItemKitDefinition Kit Definition
last_modified_dts (read only) string (dateTime) Date/time of last modification
merchant_id string(5) UltraCart merchant ID owning item
merchant_item_id string(20) Unique item id assigned to this item
merchant_item_oid (read only) integer (int32) Unique object identifier for this item
options array of ItemOption Options
parent_category_id integer (int32) Parent category of the item. Zero indicates the root folder.
payment_processing ItemPaymentProcessing Payment Processing
physical ItemPhysical Physical characters like weight and measurements
pricing ItemPricing Pricing
realtime_pricing ItemRealtimePricing Real-time Pricing
related ItemRelated Related items
reporting ItemReporting Reporting
restriction ItemRestriction Restrictions
revguard ItemRevguard Revguard.com
reviews ItemReviews Reviews
salesforce ItemSalesforce Salesforce.com configuration
shipping ItemShipping Shipping
tax ItemTax Tax settings
third_party_email_marketing array of ItemThirdPartyEmailMarketing 3rd Party Email Marketing
variant_items array of ItemVariantItem Variant Items
variations array of ItemVariation Variations
wishlist_member ItemWishlistMember WishList Member

ItemAccounting

Attributes
Name Data Type Description
accounting_code string(50) QuickBooks item name if different than the item id
qb_class string(31) QuickBooks class if you are classifying items on your invoices/receipts

ItemAmember

Attributes
Name Data Type Description
amember_payment_duration_days integer (int32) The number of days that the customer should be given access to the item
amember_product_id string(10) A-member product id give customer access to when they purchase this item

ItemAutoOrder

Attributes
Name Data Type Description
auth_future_amount number Amount to try and authorize for the future rebill
auth_test_amount number Amount to try and test authorize
auto_order_cancel_item_id string(20) Item id to attempt charging the customer for if they cancel
auto_order_cancel_item_oid integer (int32) Item object identifier to attempt charging the customer for if they cancel
auto_order_downgrade_items array of string List of downgrade items presented to customer service representatives
auto_order_paused boolean True if the rebill processing of this item is paused
auto_order_schedules array of string The user selectable schedules that are available
Allowed Values
  • Weekly
  • Every 10 Days
  • Biweekly
  • Every 24 Days
  • Every 28 Days
  • Monthly
  • Every 45 Days
  • Every 2 Months
  • Every 3 Months
  • Every 4 Months
  • Every 6 Months
  • Yearly
auto_order_upgrade_items array of string List of upgrade items presented to customer service representatives
auto_order_upsell boolean True if this item uses a fixed upsell step schedule
auto_order_upsell_no_easy_cancel boolean Do not send the easy cancel email to the customer
auto_order_upsell_one_per_customer boolean Limit the purchase of this item to one per customer
auto_orderable boolean True if this item can be automatically ordered by the customer
cancel_other_auto_orders boolean True if other auto orders for this customer should be canceled when this item is ordered
free_shipping_auto_order boolean True if the customer should be given free shipping
steps array of ItemAutoOrderStep The rebill steps if this auto order is an upsell

ItemAutoOrderStep

Attributes
Name Data Type Description
arbitrary_schedule_days integer (int32) If the schedule is arbitrary, then this is the number of days
arbitrary_unit_cost number Arbitrary unit cost used to override the regular item cost
arbitrary_unit_cost_schedules array of ItemAutoOrderStepArbitraryUnitCostSchedule Arbitrary unit costs schedules for more advanced discounting by rebill attempt
grandfather_pricing array of ItemAutoOrderStepGrandfatherPricing Grand-father pricing configuration if the rebill schedule has changed over time
managed_by string Managed by (defaults to UltraCart)
Allowed Values
  • UltraCart
  • CCBill
pause_days integer (int32) Number of days to pause
pause_until_date string (dateTime) Wait for this step to happen until the specified date
preshipment_notice_days integer (int32) If set, a pre-shipment notice is sent to the customer this many days in advance
recurring_merchant_item_id string(20) Item id to rebill
recurring_merchant_item_oid integer (int32) Item object identifier to rebill
repeat_count integer (int32) Number of times to rebill. Last step can be null for infinite
schedule string Frequency of the rebill
Allowed Values
  • Weekly
  • Every...
  • Every 10 Days
  • Biweekly
  • Every 24 Days
  • Every 28 Days
  • Monthly
  • Every 45 Days
  • Every 2 Months
  • Every 3 Months
  • Every 4 Months
  • Every 6 Months
  • Yearly
subscribe_email_list_name string Email list name to subscribe the customer to when the rebill occurs
subscribe_email_list_oid integer (int32) Email list identifier to subscribe the customer to when this rebill occurs
type string Type of step (item or pause)
Allowed Values
  • item
  • pause

ItemAutoOrderStepArbitraryUnitCostSchedule

Attributes
Name Data Type Description
arbitrary_unit_cost number Arbitrary unit cost
retry_days integer (int32) Retry days

ItemAutoOrderStepGrandfatherPricing

Attributes
Name Data Type Description
on_or_before_date string (dateTime) On or before date
unit_cost number Unit cost

ItemCCBill

Attributes
Name Data Type Description
ccbill_allowed_currencies string Allowed currencies
ccbill_allowed_types string Allowed types
ccbill_currency_code string Currency code
ccbill_form_name string Form name
ccbill_subaccount_id string Sub-account id
ccbill_subscription_type_id string Subscription type id

ItemChannelPartnerMapping

Attributes
Name Data Type Description
barcode_ua string Barcode UA (EDI only)
barcode_uc string Barcode UC (EDI only)
barcode_ui string Barcode UI (EDI only)
barcode_uk string Barcode UK (EDI only)
buyer_dpci string Buyer DPCI (EDI only)
buyer_item_number string Buyer item number (EDI only)
channel_partner_code string Channel partner code
channel_partner_oid integer (int32) Channel partner object identifier
from_item_id string(30) From Item ID
from_sku string(50) From SKU
mutually_defined_number string Mutually defined number (EDI only)
quantity_ratio_cp integer (int32) Ratio (Channel Partner)
quantity_ratio_uc integer (int32) Ratio (UltraCart)
sku string(50) SKU
unit_of_measure string Unit of measure
vendor_number string Vendor number (EDI only)
vendor_style_number string Vendor style number (EDI only)

ItemChargeback

Attributes
Name Data Type Description
addendums array of ItemChargebackAddendum Addendums
adjustment_requests array of ItemChargebackAdjustmentRequest Adjustment requests

ItemChargebackAddendum

Attributes
Name Data Type Description
chargeback_addendum_oid integer (int32) Chargeback addendum object identifier
description string Description
file_size integer (int32) Size of the file
pages integer (int32) Number of pages

ItemChargebackAdjustmentRequest

Attributes
Name Data Type Description
chargeback_adjustment_request_oid integer (int32) Chargeback adjustment request object identifier
description string Description
reason_code string Reason code

ItemCheckout

Attributes
Name Data Type Description
suppress_buysafe boolean True to suppress buySAFE
terms string(10000) Terms for purchasing this item
terms_translated_text_instance_oid (read only) integer (int32) Terms translated text instance identifier

ItemContent

Attributes
Name Data Type Description
assignments array of ItemContentAssignment StoreFront assignments
attributes array of ItemContentAttribute StoreFront attributes
exclude_from_search boolean Exclude from search
exclude_from_top_sellers boolean Exclude from the top sellers list in the StoreFront
extended_description string(2000) Extended description (max 2000 characters)
extended_description_translated_text_instance_oid (read only) integer (int32) Extneded description text translation instance identifier
multimedia array of ItemContentMultimedia Multimedia
new_item boolean True if the item is new
new_item_end string (dateTime) The date the item should no longer be considered new
new_item_start string (dateTime) The date the item should start being considered new
view_url string Legacy view URL (not used by StoreFronts)

ItemContentAssignment

Attributes
Name Data Type Description
group_oid integer (int32) Page (group) object identifier
group_path string Page (group) path
host string StoreFront host name
sort_order integer (int32) Sort order (optional)
url_part string(150) URL part if the item id is not used

ItemContentAttribute

Attributes
Name Data Type Description
name string(400) Attribute name
translated_text_instance_oid (read only) integer (int32) Attribute translated text instance identifier
type string Attribute type
Allowed Values
  • boolean
  • color
  • definitionlist
  • html
  • integer
  • mailinglist
  • multiline
  • rgba
  • simplelist
  • string
  • videolist
value string(100000) Attribute value

ItemContentMultimedia

Attributes
Name Data Type Description
cloud_url (read only) string URL where the image can be downloaded from the cloud
cloud_url_expiration (read only) string (dateTime) Expiration date of the cloud URL
code string(20) Code assigned to the file
description string(50000) Description
exclude_from_gallery boolean True to exclude from multimedia gallery
file_name string(75) File name
height integer (int32) Height of the image
merchant_item_multimedia_oid integer (int32) Item multimedia object identifier
orphan boolean True if the multimedia is an orphan of the active StoreFront themes
placeholder boolean True if the object is a place holder that can be populated
temp_multimedia_oid integer (int32) Temporary multimedia object identifier assigned if uploading new multimedia
thumbnails array of ItemContentMultimediaThumbnail Thumbnails of this image
type string Type of file
Allowed Values
  • Image
  • PDF
  • Text
  • Unknown
  • Video
url (read only) string URL to download file
width integer (int32) Width of the image

ItemContentMultimediaThumbnail

Attributes
Name Data Type Description
height integer (int32) Height of the thumbnail
http_url string HTTP URL to view the thumbnail
https_url string HTTPS URL to view the thumbnail
png_format boolean True if PNG, false if JPEG
square boolean True if the thumbnail is square
width integer (int32) Width of the thumbnail

ItemDigitalDelivery

Attributes
Name Data Type Description
activation_code_description string(50) Description of the activation code
activation_code_low_warning integer (int32) The number of activation codes whcih should generate a warning email
activation_code_realtime_url string(350) The URL to retrieve activation codes from in real-time
activation_code_shared_secret string(20) Shared secret used when communicating with the real-time URL
activation_code_type string Type of activation code
Allowed Values
  • off
  • list
  • realtime
digital_items array of ItemDigitalItem Digital items that customer can download when this item is purchased

ItemDigitalItem

Attributes
Name Data Type Description
creation_dts (read only) string (dateTime) File creation date
description (read only) string(200) Description of the digital item
file_size (read only) integer (int64) File size
mime_type (read only) string(100) Mime type associated with the file
original_filename string(250) Original filename

ItemEbay

Attributes
Name Data Type Description
active boolean True if the item is active for listing
category_id integer (int32) e-Bay category ID
category_specifics array of ItemEbayCategorySpecific Answers to category specific questions
condition_description string Description of the condition (e-Bay constant)
Allowed Values
  • New
  • New other (see details)
  • New with defects
  • Manufacturer Refurbished
  • Seller Refurbished
  • Like New
  • Used
  • Very Good
  • Good
  • Acceptable
  • For parts or not working
condition_id integer (int32) Numerical ID of the condition (e-Bay constant)
consecutive_failures integer (int32) Number of consecutive failures trying to list this item
custom_category1 integer (int64) e-Bay Store category 1
custom_category2 integer (int64) e-Bay Store category 2
dispatch_time_max integer (int32) Maximum number of days it will take to ship the item
domestic_1_additional_cost number Domestic 1 method additional item cost
domestic_1_first_cost number Domestic 1 method first item cost
domestic_2_additional_cost number Domestic 2 method additional item cost
domestic_2_first_cost number Domestic 2 method first item cost
domestic_3_additional_cost number Domestic 3 method additional item cost
domestic_3_first_cost number Domestic 3 method first item cost
domestic_4_additional_cost number Domestic 4 method additional item cost
domestic_4_first_cost number Domestic 4 method first item cost
ebay_auction_id string If listed, this is the e-Bay auction id
ebay_specific_inventory integer (int32) e-Bay specific inventory
ebay_template_name string The template name to use hwen rendering the e-Bay listing
ebay_template_oid integer (int32) The template object identifier to use when rendering the e-Bay listing
end_time (read only) string (dateTime) Date/time of the auction end
free_shipping boolean True if item receives free shipping
free_shipping_method string The method that is free for free shipping
international_1_additional_cost number International 1 method additional item cost
international_1_first_cost number International 1 method first item cost
international_2_additional_cost number International 2 method additional item cost
international_2_first_cost number International 2 method first item cost
international_3_additional_cost number International 3 method additional item cost
international_3_first_cost number International 3 method first item cost
international_4_additional_cost number International 4 method additional item cost
international_4_first_cost number International 4 method first item cost
last_status_dts (read only) string (dateTime) Date/time of the last status check
listed_dispatch_time_max integer (int32) Current listing dispatch time maximum
listed_ebay_template_oid integer (int32) The template object identifier used for the listing
listing_dts (read only) string (dateTime) Date/time of the listing
listing_duration string The duration of the listing
Allowed Values
  • GTC
  • Days 1
  • Days 3
  • Days 5
  • Days 7
  • Days 10
  • Days 14
  • Days 21
  • Days 30
  • Days 60
  • Days 90
  • Days 120
  • End
listing_price number Price to list the item at
listing_price_override number The price to list the item at if different than the regular UltraCart item price
listing_type string The type of e-Bay listing
Allowed Values
  • Auction
  • Fixed
  • Store
marketplace_analysis (read only) ItemEbayMarketPlaceAnalysis Details of the marketplace analysis
marketplace_analysis_perform boolean True if marketplace analysis should be performed
marketplace_final_value_fee_percentage number Marketplace FVF percentage
marketplace_last_check_dts (read only) string (dateTime) Date/time of the marketplace analysis last check
marketplace_lowest (read only) boolean True if we are the lowest offer in the marketplace
marketplace_map_violation (read only) boolean True if another seller is violating MAP
marketplace_multiplier number Marketplace multiplier
marketplace_other_price (read only) number Marketplace other price
marketplace_other_seller (read only) string Marketplace other seller
marketplace_other_shipping (read only) number Marketplace other shipping
marketplace_other_total (read only) number Marketplace other total
marketplace_our_additional_profit_potential number Marketplace our additional profit potential
marketplace_our_price (read only) number Marketplace our price
marketplace_our_profit (read only) number Marketplace our profit
marketplace_our_shipping (read only) number Marketplace our shipping
marketplace_our_total (read only) number Marketplace our total
marketplace_overhead number Marketplace overhead
marketplace_profitable (read only) boolean True if our listing is profitable to sell
next_attempt_dts (read only) string (dateTime) Date/time for the next attempt to list
next_listing_duration string The next listing duration to use when the current listing ends.
Allowed Values
  • GTC
  • Days 1
  • Days 3
  • Days 5
  • Days 7
  • Days 10
  • Days 14
  • Days 21
  • Days 30
  • Days 60
  • Days 90
  • Days 120
  • End
no_promotional_shipping boolean True if the item should not qualify for promotional shipping
packaging_handling_costs number Packaging and handling costs
previous_ebay_auction_id (read only) string Previous e-Bay auction id
quantity integer (int32) Quantity available of the item
reserve_price number Reserve price
send_dimensions_and_weight string How to send the item dimensions and weights to e-Bay
Allowed Values
  • packedItem
  • itemOnly
start_time (read only) string Date/time of the auction start
status string Status of the item's listing
Allowed Values
  • Listed
  • To Be Listed
  • Success
  • Error
  • Expired
  • Inactive
  • Revise
  • To Be Delisted
  • To Be Deleted
  • Configuration Issue
  • Listed Other UC Account
target_dispatch_time_max integer (int32) Typical number of days it will take to ship the item

ItemEbayCategorySpecific

Attributes
Name Data Type Description
name string Name of the category specification field
value string Value

ItemEbayMarketListing

Attributes
Name Data Type Description
auction_id string Auction ID
price number Price
seller string Seller
shipping number Shipping
total number Total

ItemEbayMarketPlaceAnalysis

Attributes
Name Data Type Description
adjusted_price number Adjusted price
adjusted_shipping number Adjusted shipping
adjusted_total number Adjusted total
cogs number Cost of goods sold
final_value_fee number Final value fee
minimum_advertised_price number Minimum advertised price
other_listings array of ItemEbayMarketListing Other listings
our_listing ItemEbayMarketListing Our listing
overhead number Overhead
profit_potential number Profit potential

ItemEmailNotifications

Attributes
Name Data Type Description
skip_receipt boolean Skip receipt email to customer
skip_shipment_notification boolean Skip shipment notification to customer

ItemEnrollment123

Attributes
Name Data Type Description
enrollment123_product_code string Enrolment 123 product code

ItemGiftCertificate

Attributes
Name Data Type Description
gift_certificate boolean True if the purchase of this item generates a gift certificate
gift_certificate_expiration_days integer (int32) The number of days that the gift certificate is good for (optional)

ItemGoogleProductSearch

Attributes
Name Data Type Description
adwords_grouping string(50) Adwords grouping
adwords_label1 string(50) Adwords label 1
adwords_label2 string(50) Adwords label 2
adwords_label3 string(50) Adwords label 3
adwords_label4 string(50) Adwords label 4
adwords_label5 string(50) Adwords label 5
age_group string(5) Age group
available_at_physical_store boolean Available at physical store
book_author string(50) Book - author
book_format string(50) Book - format
book_isbn string(20) Bood - ISBN
book_publisher string(50) Book - publisher
category_description string(1000) Category description
color string(20) Color
condition string(15) Condition
custom_label0 string(50) Custom label 0
custom_label1 string(50) Custom label 1
custom_label2 string(50) Custom label 2
custom_label3 string(50) Custom label 3
custom_label4 string(50) Custom label 4
gender string(6) Gender
google_product_category string(250) Google product category
music_artist string(50) Music - artist
music_format string(5) Music - format
music_release_date string (dateTime) Music - release date
omit_from_feed boolean Omit from feed
product_type string(10) Product type
promotion_id1 string(30) Promotion ID 1
promotion_id10 string(30) Promotion ID 10
promotion_id2 string(30) Promotion ID 2
promotion_id3 string(30) Promotion ID 3
promotion_id4 string(30) Promotion ID 4
promotion_id5 string(30) Promotion ID 5
promotion_id6 string(30) Promotion ID 6
promotion_id7 string(30) Promotion ID 7
promotion_id8 string(30) Promotion ID 8
promotion_id9 string(30) Promotion ID 9
search_dts string (dateTime) Search date/time
search_lowest_price number Search lowest price
search_lowest_url string(250) Search lowest URL
search_position integer (int32) Search position
size string(20) Size
video_director string(50) Video - director
video_format string(5) Video - format
video_rating string(5) Video - rating
video_release_date string (dateTime) Video - release date
video_starring string(150) Video - starring

ItemIdentifiers

Attributes
Name Data Type Description
barcode string(30) Barcode
manufacturer_name string(50) Manufacturer Name
manufacturer_sku string(25) Manufacturer SKU
unspsc string(20) UNSPSC

ItemInstantPaymentNotification

Attributes
Name Data Type Description
post_operation boolean True for HTTP POST instead of GET
successful_response_text string(1024) Successful response text
url string(1024) URL

ItemInstantPaymentNotifications

Attributes
Name Data Type Description
notifications array of ItemInstantPaymentNotification Notifications

ItemInternal

Attributes
Name Data Type Description
memo string(250) Memo

ItemKitComponent

Attributes
Name Data Type Description
component_cost number Component item cost
component_description (read only) string Component item description
component_merchant_item_id string Component item ID
component_merchant_item_oid integer (int32) Component item object identifier
quantity integer (int32) Quantity

ItemKitDefinition

Attributes
Name Data Type Description
components array of ItemKitComponent Components

ItemOption

Attributes
Name Data Type Description
cost_if_specified number Cost if specified
cost_per_letter number Cost per letter
cost_per_line number Cost per line
ignore_if_default boolean Ignore this option on the order if the default value is selected
label string(50) Label
label_translated_text_instance_oid (read only) integer (int32) Label translated text instance ID
name string(50) Name
name_translated_text_instance_oid (read only) integer (int32) Name translated text instance ID
one_time_fee boolean One time fee
option_oid integer (int32) Option object identifier
required boolean True if the customer is required to specify an answer
system_option boolean True if this is a system option
type string Type of option
Allowed Values
  • dropdown
  • file attachment
  • fixed
  • hidden
  • multiline
  • radio
  • single
values array of ItemOptionValue Values

ItemOptionValue

Attributes
Name Data Type Description
additional_dimension_application string Additional dimensions application
Allowed Values
  • none
  • set item to
  • add item
additional_items array of ItemOptionValueAdditionalItem Additional items to add to the order if this value is selected
cost_change number Cost change
default_value boolean True if default value
digital_items array of ItemOptionValueDigitalItem Digital items to allow the customer to download if this option value is selected
height Distance If additional_dimension_application != none
Additional dimensions (height)
length Distance If additional_dimension_application != none
Additional dimensions (length)
merchant_item_multimedia_oid integer (int32) Multimedia object identifier associated with this option value
option_value_oid integer (int32) Option value object identifier
percent_cost_change number Percentage cost change
translated_text_instance_oid (read only) integer (int32) Translated text instance id
value string(1024) Value
weight_change Weight Weight change
weight_change_percent number Percentage weight change
width Distance If additional_dimension_application != none
Additional dimensions (width)

ItemOptionValueAdditionalItem

Attributes
Name Data Type Description
additional_merchant_item_id string Additional item id
additional_merchant_item_oid integer (int32) Additional item object identifier

ItemOptionValueDigitalItem

Attributes
Name Data Type Description
digital_item_oid integer (int32) Digital item object identifier
original_filename string Original filename

ItemPaymentProcessing

Attributes
Name Data Type Description
block_prepaid boolean True if prepaid cards should be blocked from buying this item
credit_card_transaction_type string Credit card transaction type
Allowed Values
  • auth and capture
  • auth then capture
  • auth only
no_realtime_charge boolean True if no real-time charge should be performed on this item.
payment_method_validity array of string Payment method validity
Allowed Values
  • +Affirm
  • -Affirm
  • +Amazon
  • -Amazon
  • +AMEX
  • -AMEX
  • +CASH
  • -CASH
  • +Check
  • -Check
  • +COD
  • -COD
  • +Diners Club
  • -Diners Club
  • +Discover
  • -Discover
  • +eCheck
  • -eCheck
  • +JCB
  • -JCB
  • +MasterCard
  • -MasterCard
  • +Money Order
  • -Money Order
  • +PayPal
  • -PayPal
  • +Purchase Order
  • -Purchase Order
  • +Quote Request
  • -Quote Request
  • +VISA
  • -VISA
  • -Wire Transfer
  • +Wire Transfer
rotating_transaction_gateway_codes array of string Rotating transaction gateway codes

ItemPhysical

Attributes
Name Data Type Description
height Distance Height
length Distance Length
weight Weight Weight
width Distance Width

ItemPricing

Attributes
Name Data Type Description
allow_arbitrary_cost boolean Allow arbitrary cost
arbitrary_cost_velocity_code string(10000) Arbitrary cost velocity code
automatic_pricing_tier_name string Automatic pricing tier name
automatic_pricing_tier_oid integer (int32) Automatic pricing tier object identifier
cogs number Cost of goods sold
cost number Cost
currency_code string(3) Currency code
Allowed Values
  • AUD
  • BRL
  • CAD
  • CHF
  • EUR
  • GBP
  • JPY
  • MXN
  • NOK
  • NZD
  • RUB
  • SEK
  • SGD
  • TRY
  • USD
manufacturer_suggested_retail_price number Manufacturer suggested retail price
maximum_arbitrary_cost number Maximum arbitrary cost
minimum_advertised_price number Minimum advertised price
minimum_arbitrary_cost number Minimum arbitrary cost
mix_and_match_group string Mix and match group
mix_and_match_group_oid integer (int32) Mix and match group object identifier
sale_cost number Sale cost
sale_end string (dateTime) If sale_cost specified
Sale end
sale_start string (dateTime) If sale_cost specified
Sale start
tiers array of ItemPricingTier Tiers

ItemPricingTier

Attributes
Name Data Type Description
default_tier (read only) boolean True if this is the default tier
discounts array of ItemPricingTierDiscount Discounts
limit ItemPricingTierLimit Limits
name (read only) string Pricing tier name
pricing_tier_oid (read only) integer (int32) Pricing tier object identifier

ItemPricingTierDiscount

Attributes
Name Data Type Description
cost number Cost
quantity integer (int32) Quantity

ItemPricingTierLimit

Attributes
Name Data Type Description
cumulative_order_limit integer (int32) Cumulative order limit
individual_order_limit integer (int32) Individual order limit
multiple_quantity integer (int32) Multiple quantity

ItemRealtimePricing

Attributes
Name Data Type Description
realtime_pricing_parameter string Real-time pricing provider parameters
realtime_pricing_provider string Real-time pricing provider name
realtime_pricing_provider_oid integer (int32) Real-time pricing provide object identifier

ItemRelated

Attributes
Name Data Type Description
no_system_calculated_related_items boolean True to suppress system calculated relationships
not_relatable boolean Not relatable
related_items array of ItemRelatedItem Related items

ItemRelatedItem

Attributes
Name Data Type Description
related_merchant_item_id string Related item id
related_merchant_item_oid integer (int32) Related item object identifier
type string Relationship type
Allowed Values
  • System
  • UserDefined

ItemReporting

Attributes
Name Data Type Description
report_as_upsell boolean Report as an upsell
report_pickable_quantities array of integer (int32) Report pickable quantities

ItemResponse

Attributes
Name Data Type Description
error Error Error object if unsuccessful
item Item Item
metadata ResponseMetadata Meta-data about the response such as payload or paging information
success boolean Indicates if API call was successful

ItemRestriction

Attributes
Name Data Type Description
exclude_coupon boolean Exclude coupons
exclude_from_free_promotion boolean Exclude from free promotion
items array of ItemRestrictionItem Items
maximum_quantity integer (int32) Maximum quantity
minimum_quantity integer (int32) Minimum quantity (defaults to 1)
multiple_quantity integer (int32) Multiple of quantity
one_per_customer boolean One per customer
purchase_separately boolean Purchase separately

ItemRestrictionItem

Attributes
Name Data Type Description
restrict_merchant_item_id string Restrict item id
restrict_merchant_item_oid integer (int32) Restrict item object identifier
type string Restriction type
Allowed Values
  • can not be purchased with
  • can only be purchased with
  • must be purchased with

ItemRevguard

Attributes
Name Data Type Description
revguard_canceled_csr_prompt_group integer (int64) Canceled CSR prompt group
revguard_canceled_ivr_prompt_group integer (int64) IVR prompt group
revguard_canceled_web_prompt_group integer (int64) Canceled web prompt group
revguard_client_brand integer (int64) Client brand
revguard_csr_prompt_group integer (int64) CSR prompt group
revguard_ivr_prompt_group integer (int64) IVR prompt group
revguard_web_prompt_group integer (int64) Web prompt group

ItemReviews

Attributes
Name Data Type Description
has_approved_review (read only) boolean True if the item has an approved review
has_review (read only) boolean True if the item has a review
review_count (read only) integer (int32) Number of approved reviews
review_overall (read only) number Overall score of reviews
review_template_name string Review template name
review_template_oid integer (int32) Review template object identifier
reviewable boolean True if the item is reviewable

ItemSalesforce

Attributes
Name Data Type Description
sfdc_pricebook_id string Salesforce.com pricebook id
sfdc_product_id string Salesforce.com product id

ItemShipping

Attributes
Name Data Type Description
allow_back_order boolean Allow back order
amazon_fba boolean Fulfillment by Amazon.com
case_inner_packs integer (int32) Case inner packs
case_units integer (int32) Case units
cases array of ItemShippingCase Cases
country_code_of_origin string(2) Country code of origin for customs forms. (ISO-3166 two letter code)
customs_description string Customs description
customs_value number Customs value
delivery_on_friday boolean Delivery on Friday
delivery_on_monday boolean Delivery on Monday
delivery_on_saturday boolean Delivery on Saturday
delivery_on_sunday boolean Delivery on Sunday
delivery_on_thursday boolean Delivery on Thursday
delivery_on_tuesday boolean Delivery on Tuesday
delivery_on_wednesday boolean Delivery on Wednesday
destination_markups array of ItemShippingDestinationMarkup Destination markups
destination_restrictions array of ItemShippingDestinationRestriction Destination restrictions
distribution_centers array of ItemShippingDistributionCenter Distribution centers
eta string (dateTime) Estimated time of arrival
free_shipping boolean Qualifies for free shipping
freight_class string Freight class
hazmat boolean Hazardous material
made_to_order boolean True if this item is made to order
made_to_order_lead_time integer (int32) Number of days lead time it takes to make the item before ite can ship
max_days_time_in_transit integer (int32) Maximum days allowed in transit
methods array of ItemShippingMethod Methods
no_shipping_discount boolean No shipping discounts
package_requirements array of ItemShippingPackageRequirement Package requirements
perishable_class_name string Perishable class name
perishable_class_oid integer (int32) Perishable class object identifier
preorder boolean This item is on pre-order
require_delivery_date boolean True to require customer to select a delivery date
restrict_shipment_on_friday boolean Restrict shipment on Friday
restrict_shipment_on_monday boolean Restrict shipment on Monday
restrict_shipment_on_saturday boolean Restrict shipment on Saturday
restrict_shipment_on_sunday boolean Restrict shipment on Sunday
restrict_shipment_on_thursday boolean Restrict shipment on Thursday
restrict_shipment_on_tuesday boolean Restrict shipment on Tuesday
restrict_shipment_on_wednesday boolean Restrict shipment on Wednesday
ship_separately boolean Ship this item in a separate box
ship_separately_additional_weight Weight Ship separately box weight
ship_separately_height Distance Ship separately box height
ship_separately_length Distance Ship separately box length
ship_separately_package_special_type string Ship separately package special type
Allowed Values
  • Crate
  • FedEx: Box
  • FedEx: Envelope
  • FedEx: Pak
  • FedEx: Tube
  • Pallet Other
  • Pallet 48 x 40
  • Pallet 48 x 48
  • Pallet 60 x 48
  • Pallet 120 x 80
  • Pallet 120 x 100
  • Pallet 120 x 120
  • UPS: Express Box
  • UPS: Letter
  • UPS: Pak
  • UPS: Tube
  • USPS: Express Mail Flat Rate Envelope
  • USPS: Express Mail Padded Flat Rate Envelope
  • USPS: Priority Mail Medium Flat Rate Box
  • USPS: Priority Mail Large Flat Rate Box
  • USPS: Priority Mail Small Flat Rate Box
  • USPS: Priority Mail Regional Rate A Box
  • USPS: Priority Mail Regional Rate B Box
  • USPS: Priority Mail Regional Rate C Box
  • USPS: Priority Mail Flat Rate Envelope
  • USPS: Priority Mail Padded Flat Rate Envelope
  • USPS: Priority Mail Legal Flat Rate Envelope
ship_separately_width Distance Ship separately box width
special_product_type string Special product type (USPS Media Mail)
Allowed Values
  • Book or Software
  • Music
  • Editorial
track_inventory boolean Track inventory

If all of the delivery_on_<day of week> flags are false, then delivery is allowed on all days of the week.

If all of the restrict_shipment_on<day of week> are false, then shipment is not restricted on any days of the week.

If all of the delivery_on_<day of week> flags are false, then delivery is allowed on all days of the week.

If all of the restrict_shipment_on<day of week> are false, then shipment is not restricted on any days of the week.

ItemShippingCase

Attributes
Name Data Type Description
case_label string(20) Case label
case_merchant_item_id string Case item id
case_merchant_item_oid integer (int32) Case item object identifier
quantity integer (int32) Case quantity

ItemShippingDestinationMarkup

Attributes
Name Data Type Description
country_code string(2) Country code (ISO-3166 two letter)
flat_fee number Flat fee
per_item number Per item
postal_code string(20) Postal code
shipping_method string Shipping method
state string(32) State

ItemShippingDestinationRestriction

Attributes
Name Data Type Description
country_code string(2) Country code (ISO-3166 two letter)
state string(32) State
validity string Validity
Allowed Values
  • valid only for
  • invalid for

ItemShippingDistributionCenter

Attributes
Name Data Type Description
allocated_to_placed_orders (read only) number Allocated to placed orders
allocated_to_shopping_carts (read only) number Allocated to shopping carts
available_to_allocate (read only) number Available to allocate
desired_inventory_level number Desired inventory level
distribution_center_code string Distribution center code
distribution_center_oid integer (int32) Distribution center object identifier
eta string (dateTime) Estimated time of arrival
handles boolean True if this distribution center handles this item
inventory_level number Inventory level
maximum_backorder integer (int32) Maximum back-order
reorder_inventory_level number Reorder inventory level (triggers notification)
sku string(50) SKU
stock_picking_location string(20) Stock picking location

ItemShippingMethod

Attributes
Name Data Type Description
cost number Cost
each_additional_item_markup number Each additional item markup
filter_to_if_available boolean Filter to this method if available
first_item_markup number First item markup
fixed_shipping_cost number Fixed shipping cost
flat_fee_markup number Flat fee markup
free_shipping boolean Free shipping
per_item_fee_markup number Per item fee markup
percentage_markup number Percentage markup
percentage_of_item_markup number Percentage of item markup
relax_restrictions_on_upsell boolean Relax restrictions on upsell
shipping_method string Shipping method name
shipping_method_oid integer (int32) Shipping method object identifier
shipping_method_validity string Shipping method validity
Allowed Values
  • invalid for
  • valid for
  • valid only for
signature_required boolean Signature required

ItemShippingPackageRequirement

Attributes
Name Data Type Description
package_name string Package name
package_oid integer (int32) Package object identifier

ItemsResponse

Attributes
Name Data Type Description
error Error Error object if unsuccessful
items array of Item items
metadata ResponseMetadata Meta-data about the response such as payload or paging information
success boolean Indicates if API call was successful

ItemTax

Attributes
Name Data Type Description
exemptions array of ItemTaxExemption Exemptions
tax_free boolean True if tax free
taxable_cost number Taxable cost if different than regular cost

ItemTaxExemption

Attributes
Name Data Type Description
city string(32) City
country_code string(2) Country code (ISO-3166 two letter)
county string(32) County
postal_code string(20) Postal code
state_code string(32) State code

ItemThirdPartyEmailMarketing

Attributes
Name Data Type Description
add_tags array of string Add tags
provider_name string Provider name
Allowed Values
  • ActiveCampaign
  • AWeber
  • Campaign Monitor
  • ConstantContact
  • Emma
  • GetResponse
  • iContact
  • Klaviyo
  • Lyris
  • LyrisHQ
  • MailChimp
  • SilverPop
remove_tags array of string Remove tags
subscribe_lists array of string Subscribe to lists
unsubscribe_lists array of string Unsubscribe from lists

ItemVariantItem

Attributes
Name Data Type Description
description (read only) string(512) Description
merchant_item_multimedia_oid integer (int32) Multimedia object identifier
variant_merchant_item_id string Variant item id
variant_merchant_item_oid integer (int32) Variant item object identifier
variation_options array of string Variation options
variations array of string Variations

ItemVariation

Attributes
Name Data Type Description
default_text string(50) Default text
default_text_translated_text_instance_oid (read only) integer (int32) Default text translated text instance id
name string(50) Name
name_translated_text_instance_oid (read only) integer (int32) Name translated text instance id
options array of ItemVariationOption Options

ItemVariationOption

Attributes
Name Data Type Description
default_option boolean True if default option
merchant_item_multimedia_oid integer (int32) Multimedia object identifier
translated_text_instance_oid (read only) integer (int32) Translated text instance id
value string(50) Value

ItemWishlistMember

Attributes
Name Data Type Description
wishlist_member_instance_description string WishList Member instance description
wishlist_member_instance_oid integer (int32) WishList Member instance object identifier
wishlist_member_sku string(25) WishList Member SKU

ResponseMetadata

Attributes
Name Data Type Description
payload_name string Payload name
result_set ResultSet Result set

ResultSet

Attributes
Name Data Type Description
count integer (int32) Number of results in this set
limit integer (int32) Maximum number of results that can be returned in a set
more boolean True if there are more results to query
next_offset integer (int32) The next offset that you should query to retrieve more results
offset integer (int32) Offset of this result set (zero based)
total_records integer (int32) The total number of records in the result set. May be null if the number is not known and the client should continue iterating as long as more is true.

TempMultimedia

Attributes
Name Data Type Description
filename string(75) Filename
height (read only) integer (int32) Height
multimedia_type string Multimedia type
Allowed Values
  • Image
  • PDF
  • Text
  • Video
size (read only) integer (int64) Size
temp_multimedia_oid integer (int32) Temporary multimedia object identifier
url (read only) string URL
width (read only) integer (int32) Width

TempMultimediaResponse

Attributes
Name Data Type Description
error Error Error object if unsuccessful
metadata ResponseMetadata Meta-data about the response such as payload or paging information
success boolean Indicates if API call was successful
temp_multimedia TempMultimedia Temporary multimedia

Weight

Attributes
Name Data Type Description
uom string Unit of measure
Allowed Values
  • KG
  • LB
  • OZ
value number Weight

400
Status Code 400: bad request input such as invalid json

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse

401
Status Code 401: invalid credentials supplied

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse

410
Status Code 410: Your authorized application has been disabled by UltraCart

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse

429
Status Code 429: you have exceeded the allowed API call rate limit for your application.

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse

500
Status Code 500: any server side error. the body will contain a generic server error message

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse