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.
/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.
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.
There are four steps to instantiating the API.
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.
Retrieves a group of digital items (file information) from the account. If no parameters are specified, all digital items will be returned. Be aware that these are not normal items that can be added to a shopping cart. Rather, they are digital files that may be associated with normal items. You will need to make multiple API calls in order to retrieve the entire result set since this API performs result set pagination.
SDK Function Name: getDigitalItems
Parameter | Description | Location | Data Type | Required |
---|---|---|---|---|
_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
|
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 |
using System;
using System.Collections.Generic;
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;
using SdkSample.item;
namespace SdkSample.item
{
public class GetDigitalItems
{
public static void Execute()
{
try
{
/*
* Please Note!
* Digital Items are not normal items you sell on your site. They are digital files that you may add to
* a library and then attach to a normal item as an accessory or the main item itself.
* See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
*/
int digitalItemOid = ItemFunctions.InsertSampleDigitalItem(); // create an item so I can get an item
ItemApi itemApi = Samples.GetItemApi();
int limit = 100;
int offset = 0;
string since = null; // digital items do not use since. leave as null.
string sort = null; // if null, use default of original_filename
string expand = null; // digital items have no expansion. leave as null. this value is ignored
bool? placeholders = null; // digital items have no placeholders. leave as null.
ItemDigitalItemsResponse apiResponse = itemApi.GetDigitalItems(limit, offset, since, sort, expand, placeholders);
List<ItemDigitalItem> digitalItems = apiResponse.DigitalItems; // assuming this succeeded
Console.WriteLine("The following items were retrieved via GetDigitalItems():");
foreach (ItemDigitalItem digitalItem in digitalItems)
{
Console.WriteLine(digitalItem);
}
}
catch (Exception e)
{
Console.WriteLine("An Exception occurred. Please review the following error:");
Console.WriteLine(e); // <-- change_me: handle gracefully
Environment.Exit(1);
}
}
}
}
package item;
import com.ultracart.admin.v2.ItemApi;
import com.ultracart.admin.v2.models.*;
import common.Constants;
import java.util.List;
public class GetDigitalItems {
public static void execute() {
try {
/*
* Please Note!
* Digital Items are not normal items you sell on your site. They are digital files that you may add to
* a library and then attach to a normal item as an accessory or the main item itself.
* See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
*/
int digitalItemOid = ItemFunctions.insertSampleDigitalItem(null);
ItemApi itemApi = new ItemApi(Constants.API_KEY);
int limit = 100;
int offset = 0;
String since = null; // digital items do not use since. leave as null.
String sort = null; // if null, use default of original_filename
String expand = null; // digital items have no expansion. leave as null. this value is ignored
Boolean placeholders = null; // digital items have no placeholders. leave as null.
ItemDigitalItemsResponse apiResponse = itemApi.getDigitalItems(limit, offset, since, sort, expand, placeholders);
List<ItemDigitalItem> digitalItems = apiResponse.getDigitalItems();
System.out.println("The following items were retrieved via GetDigitalItems():");
for (ItemDigitalItem digitalItem : digitalItems) {
System.out.println(digitalItem);
}
} catch (Exception e) {
System.out.println("An Exception occurred. Please review the following error:");
e.printStackTrace();
System.exit(1);
}
}
}
import {itemApi} from '../api.js';
import {ItemFunctions} from './itemFunctions.js'; // Assuming ItemFunctions is in a separate file
export class GetDigitalItems {
static async execute() {
try {
/*
* Please Note!
* Digital Items are not normal items you sell on your site. They are digital files that you may add to
* a library and then attach to a normal item as an accessory or the main item itself.
* See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
*/
const digitalItemOid = await ItemFunctions.insertSampleDigitalItem(); // create an item so I can get an item
const limit = 100;
const offset = 0;
const since = undefined; // digital items do not use since. leave as undefined.
const sort = undefined; // if undefined, use default of original_filename
const expand = undefined; // digital items have no expansion. leave as undefined. this value is ignored
const placeholders = undefined; // digital items have no placeholders. leave as undefined.
const request = {
_limit: limit,
_offset: offset,
_since: since,
_sort: sort,
_expand: expand,
_placeholders: placeholders
};
const apiResponse = await new Promise((resolve, reject) => {
itemApi.getDigitalItems(request, function (error, data, response) {
if (error) {
reject(error);
} else {
resolve(data, response);
}
});
});
const digitalItems = apiResponse.digital_items; // assuming this succeeded
if (digitalItems === undefined) {
console.error("Could not find digital items from the list");
} else {
console.log("The following items were retrieved via GetDigitalItems():");
for (const digitalItem of digitalItems) {
console.log(digitalItem);
}
}
} catch (e) {
console.log("An Exception occurred. Please review the following error:");
console.log(e); // <-- change_me: handle gracefully
throw e; // Equivalent to Environment.Exit(1), but better for async context
}
}
}
<?php
/** @noinspection SpellCheckingInspection */
/** @noinspection GrazieInspection */
use ultracart\v2\ApiException;
require_once '../vendor/autoload.php';
require_once '../samples.php';
require_once './item_functions.php'; // <-- see this file for details
try {
/*
* Please Note!
* Digital Items are not normal items you sell on your site. They are digital files that you may add to
* a library and then attach to a normal item as an accessory or the main item itself.
* See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
*/
$digital_item_oid = insertSampleDigitalItem(); // create an item so I can get an item
$item_api = Samples::getItemApi();
$_limit = 100;
$_offset = 0;
$_since = null; // digital items do not use since. leave as null.
$_sort = null; // if null, use default of original_filename
$_expand = null; // digital items have no expansion. leave as null. this value is ignored
$_placeholders = null; // digital items have no placeholders. leave as null.
$api_response = $item_api->getDigitalItems($_limit, $_offset, $_since, $_sort, $_expand, $_placeholders);
$digital_items = $api_response->getDigitalItems(); // assuming this succeeded
echo 'The following items were retrieved via getDigitalItems():';
foreach ($digital_items as $digital_item) {
var_dump($digital_item);
}
} catch (ApiException $e) {
echo 'An ApiException occurred. Please review the following error:';
var_dump($e); // <-- change_me: handle gracefully
die(1);
}
from ultracart.apis import ItemApi
from samples import api_client
from item_functions import insert_sample_digital_item
try:
"""
Please Note!
Digital Items are not normal items you sell on your site. They are digital files that you may add to
a library and then attach to a normal item as an accessory or the main item itself.
See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
"""
# Create a digital item to get an item
digital_item_oid = insert_sample_digital_item()
# Create Item API client
item_api = ItemApi(api_client())
# Set parameters for getDigitalItems
limit = 100
offset = 0
since = None # digital items do not use since. leave as None.
sort = None # if None, use default of original_filename
expand = None # digital items have no expansion. leave as None. this value is ignored
placeholders = None # digital items have no placeholders. leave as None.
# Retrieve digital items
api_response = item_api.get_digital_items(limit=limit, offset=offset, since=since,
sort=sort, expand=expand,
placeholders=placeholders)
digital_items = api_response.get_digital_items() # assuming this succeeded
print('The following items were retrieved via get_digital_items():')
for digital_item in digital_items:
print(digital_item)
except Exception as e:
print('An exception occurred. Please review the following error:')
print(e)
raise
require 'ultracart_api'
require_relative '../constants'
require_relative './item_functions'
begin
# Please Note!
# Digital Items are not normal items you sell on your site. They are digital files that you may add to
# a library and then attach to a normal item as an accessory or the main item itself.
# See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
# Create a sample digital item to retrieve
digital_item_oid = insert_sample_digital_item
# Initialize the item API
item_api = UltracartClient::ItemApi.new_using_api_key(Constants::API_KEY)
# Prepare API call parameters
opts = {
'_limit' => 100,
'_offset' => 0,
'_since' => nil, # digital items do not use since. leave as nil.
'_sort' => nil, # if nil, use default of original_filename
'_expand' => nil, # digital items have no expansion. leave as nil. this value is ignored
'_placeholders' => nil # digital items have no placeholders. leave as nil.
}
# Retrieve digital items
api_response = item_api.get_digital_items(opts)
digital_items = api_response.digital_items # assuming this succeeded
# Output retrieved digital items
puts 'The following items were retrieved via getDigitalItems():'
digital_items.each do |digital_item|
p digital_item
end
rescue UltracartClient::ApiException => e
puts 'An ApiException occurred. Please review the following error:'
p e # change_me: handle gracefully
exit 1
end
import {itemApi} from '../api';
import {ItemDigitalItem, ItemDigitalItemsResponse} from 'ultracart_rest_api_v2_typescript';
import {ItemFunctions} from './ItemFunctions'; // Assuming ItemFunctions is in a separate file
export class GetDigitalItems {
public static async execute(): Promise<void> {
try {
/*
* Please Note!
* Digital Items are not normal items you sell on your site. They are digital files that you may add to
* a library and then attach to a normal item as an accessory or the main item itself.
* See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
*/
const digitalItemOid: number = await ItemFunctions.insertSampleDigitalItem(); // create an item so I can get an item
const limit = 100;
const offset = 0;
const since: string | undefined = undefined; // digital items do not use since. leave as undefined.
const sort: string | undefined = undefined; // if undefined, use default of original_filename
const expand: string | undefined = undefined; // digital items have no expansion. leave as undefined. this value is ignored
const placeholders: boolean | undefined = undefined; // digital items have no placeholders. leave as undefined.
const apiResponse: ItemDigitalItemsResponse = await itemApi.getDigitalItems({
limit,
offset,
since,
sort,
expand: expand,
placeholders
});
const digitalItems: ItemDigitalItem[] | undefined = apiResponse.digital_items; // assuming this succeeded
if (digitalItems === undefined) {
console.error("Could not find digital items from the list");
} else {
console.log("The following items were retrieved via GetDigitalItems():");
for (const digitalItem of digitalItems) {
console.log(digitalItem);
}
}
} catch (e) {
console.log("An Exception occurred. Please review the following error:");
console.log(e); // <-- change_me: handle gracefully
throw e; // Equivalent to Environment.Exit(1), but better for async context
}
}
}
Create a file within the digital library. This does not create an item, but makes this digital file available and selectable as part (or all) of an item.
SDK Function Name: insertDigitalItem
Parameter | Description | Location | Data Type | Required |
---|---|---|---|---|
digital_item | Digital item to create | body | ItemDigitalItem | required |
using System;
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;
namespace SdkSample.item
{
public class InsertDigitalItem
{
/// <summary>
/// Execute method containing all business logic
/// </summary>
public static void Execute()
{
try
{
int digitalItemOid = ItemFunctions.InsertSampleDigitalItem();
ItemFunctions.DeleteSampleDigitalItem(digitalItemOid);
}
catch (Exception e)
{
Console.WriteLine("An Exception occurred. Please review the following error:");
Console.WriteLine(e.ToString()); // <-- change_me: handle gracefully
Environment.Exit(1);
}
}
}
}
package item;
public class InsertDigitalItem {
/// <summary>
/// Execute method containing all business logic
/// </summary>
public static void execute() {
try {
int digitalItemOid = ItemFunctions.insertSampleDigitalItem(null);
ItemFunctions.deleteSampleDigitalItem(digitalItemOid);
}
catch (Exception e) {
System.out.println("An Exception occurred. Please review the following error:");
System.out.println(e.toString()); // <-- change_me: handle gracefully
System.exit(1);
}
}
}
import { ItemFunctions } from './itemFunctions.js';
/**
* Execute method containing all business logic
*/
export async function execute() {
try {
const digitalItemOid = await ItemFunctions.insertSampleDigitalItem();
await ItemFunctions.deleteSampleDigitalItem(digitalItemOid);
} catch (error) {
console.error("An Exception occurred. Please review the following error:");
console.error(error); // <-- change_me: handle gracefully
process.exit(1);
}
}
<?php
use ultracart\v2\ApiException;
require_once '../vendor/autoload.php';
require_once '../samples.php';
require_once './item_functions.php'; // <-- see this file for details
try {
$digital_item_oid = insertSampleDigitalItem();
deleteSampleDigitalItem($digital_item_oid);
} catch (ApiException $e) {
echo 'An ApiException occurred. Please review the following error:';
var_dump($e); // <-- change_me: handle gracefully
die(1);
}
from ultracart.apis import ItemApi
from samples import api_client
from item_functions import insert_sample_digital_item, delete_sample_digital_item
from ultracart.exceptions import ApiException
try:
# Create and then delete a sample digital item
digital_item_oid = insert_sample_digital_item()
delete_sample_digital_item(digital_item_oid)
except ApiException as e:
print('An ApiException occurred. Please review the following error:')
print(e)
exit(1)
require 'ultracart_api'
require_relative '../constants'
require_relative './item_functions'
begin
# Create and then delete a sample digital item
digital_item_oid = insert_sample_digital_item
delete_sample_digital_item(digital_item_oid)
rescue UltracartClient::ApiError => e
warn 'An ApiException occurred. Please review the following error:'
p e
exit(1)
end
import { ItemFunctions } from './ItemFunctions';
/**
* Execute method containing all business logic
*/
export async function execute(): Promise<void> {
try {
const digitalItemOid: number = await ItemFunctions.insertSampleDigitalItem();
await ItemFunctions.deleteSampleDigitalItem(digitalItemOid);
} catch (error) {
console.error("An Exception occurred. Please review the following error:");
console.error(error); // <-- change_me: handle gracefully
process.exit(1);
}
}
Retrieves digital items from the digital library (which are digital files that may be attached to normal items) that having a matching external id. Be aware that these are not normal items that can be added to a shopping cart. Rather, they are digital files that may be associated with normal items.
SDK Function Name: getDigitalItemsByExternalId
Parameter | Description | Location | Data Type | Required |
---|---|---|---|---|
external_id | The external id to match against. | path | string | required |
using System;
using System.Collections.Generic;
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;
using SdkSample.item;
namespace SdkSample.item
{
public class GetDigitalItemsByExternalId
{
public static void Execute()
{
try
{
/*
* Please Note!
* Digital Items are not normal items you sell on your site. They are digital files that you may add to
* a library and then attach to a normal item as an accessory or the main item itself.
* See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
*/
string externalId = Guid.NewGuid().ToString("N");
Console.WriteLine("My external id is " + externalId);
int digitalItemOid = ItemFunctions.InsertSampleDigitalItem(externalId); // create digital item with a specific external id I can later use.
ItemApi itemApi = Samples.GetItemApi();
ItemDigitalItemsResponse apiResponse = itemApi.GetDigitalItemsByExternalId(externalId);
List<ItemDigitalItem> digitalItems = apiResponse.DigitalItems; // assuming this succeeded
Console.WriteLine("The following item was retrieved via GetDigitalItem():");
Console.WriteLine(digitalItems);
ItemFunctions.DeleteSampleDigitalItem(digitalItemOid);
}
catch (Exception e)
{
Console.WriteLine("An Exception occurred. Please review the following error:");
Console.WriteLine(e); // <-- change_me: handle gracefully
Environment.Exit(1);
}
}
}
}
package item;
import com.ultracart.admin.v2.ItemApi;
import com.ultracart.admin.v2.models.*;
import common.Constants;
import java.util.List;
import java.util.UUID;
public class GetDigitalItemsByExternalId {
public static void execute() {
try {
/*
* Please Note!
* Digital Items are not normal items you sell on your site. They are digital files that you may add to
* a library and then attach to a normal item as an accessory or the main item itself.
* See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
*/
String externalId = UUID.randomUUID().toString().replace("-", "");
System.out.println("My external id is " + externalId);
int digitalItemOid = ItemFunctions.insertSampleDigitalItem(externalId);
ItemApi itemApi = new ItemApi(Constants.API_KEY);
ItemDigitalItemsResponse apiResponse = itemApi.getDigitalItemsByExternalId(externalId);
List<ItemDigitalItem> digitalItems = apiResponse.getDigitalItems();
System.out.println("The following item was retrieved via GetDigitalItem():");
System.out.println(digitalItems);
ItemFunctions.deleteSampleDigitalItem(digitalItemOid);
} catch (Exception e) {
System.out.println("An Exception occurred. Please review the following error:");
e.printStackTrace();
System.exit(1);
}
}
}
import {itemApi} from '../api.js';
import {ItemFunctions} from './itemFunctions.js';
export class GetDigitalItemsByExternalId {
/**
* Please Note!
* Digital Items are not normal items you sell on your site. They are digital files that you may add to
* a library and then attach to a normal item as an accessory or the main item itself.
* See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
*/
static async execute() {
try {
// Generate a random external ID (replacing Guid.NewGuid())
const externalId = crypto.randomUUID();
console.log(`My external id is ${externalId}`);
// Insert sample digital item
const digitalItemOid = await ItemFunctions.insertSampleDigitalItem(externalId);
// Retrieve digital items by external ID
const apiResponse = await new Promise((resolve, reject) => {
itemApi.getDigitalItemsByExternalId(externalId, function (error, data, response) {
if (error) {
reject(error);
} else {
resolve(data, response);
}
});
});
const digitalItems = apiResponse.digital_items || []; // Use OR operator instead of nullish coalescing
console.log("The following item was retrieved via GetDigitalItem():");
console.log(digitalItems);
// Delete the sample digital item
await ItemFunctions.deleteSampleDigitalItem(digitalItemOid);
} catch (error) {
console.error("An Exception occurred. Please review the following error:");
console.error(error);
process.exit(1);
}
}
}
// Optional: If you want to execute the method
// GetDigitalItemsByExternalId.execute().catch(console.error);
<?php
/** @noinspection SpellCheckingInspection */
/** @noinspection GrazieInspection */
use ultracart\v2\ApiException;
require_once '../vendor/autoload.php';
require_once '../samples.php';
require_once './item_functions.php'; // <-- see this file for details
try {
/*
* Please Note!
* Digital Items are not normal items you sell on your site. They are digital files that you may add to
* a library and then attach to a normal item as an accessory or the main item itself.
* See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
*/
$external_id = uniqid();
echo 'My external id is ' . $external_id;
$digital_item_oid = insertSampleDigitalItem($external_id); // create digital item with a specific external id I can later use.
$item_api = Samples::getItemApi();
$api_response = $item_api->getDigitalItemsByExternalId($external_id);
$digital_items = $api_response->getDigitalItems(); // assuming this succeeded
echo 'The following item was retrieved via getDigitalItem():';
var_dump($digital_items);
deleteSampleDigitalItem($digital_item_oid);
} catch (ApiException $e) {
echo 'An ApiException occurred. Please review the following error:';
var_dump($e); // <-- change_me: handle gracefully
die(1);
}
import uuid
from ultracart.apis import ItemApi
from samples import api_client
from item_functions import insert_sample_digital_item, delete_sample_digital_item
try:
"""
Please Note!
Digital Items are not normal items you sell on your site. They are digital files that you may add to
a library and then attach to a normal item as an accessory or the main item itself.
See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
"""
# Generate a unique external ID
external_id = str(uuid.uuid4())
print(f'My external id is {external_id}')
# Create digital item with a specific external id I can later use
digital_item_oid = insert_sample_digital_item(external_id)
# Create Item API client
item_api = ItemApi(api_client())
# Retrieve digital items by external ID
api_response = item_api.get_digital_items_by_external_id(external_id)
digital_items = api_response.get_digital_items() # assuming this succeeded
print('The following item was retrieved via get_digital_items_by_external_id():')
print(digital_items)
# Delete the sample digital item
delete_sample_digital_item(digital_item_oid)
except Exception as e:
print('An exception occurred. Please review the following error:')
print(e)
raise
require 'ultracart_api'
require_relative '../constants'
require_relative './item_functions'
begin
# Please Note!
# Digital Items are not normal items you sell on your site. They are digital files that you may add to
# a library and then attach to a normal item as an accessory or the main item itself.
# See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
# Generate a unique external ID
external_id = SecureRandom.uuid
puts "My external id is #{external_id}"
# Create digital item with a specific external id for later use
digital_item_oid = insert_sample_digital_item(external_id)
# Initialize the item API
item_api = UltracartClient::ItemApi.new_using_api_key(Constants::API_KEY)
# Retrieve digital items by external ID
api_response = item_api.get_digital_items_by_external_id(external_id)
digital_items = api_response.digital_items # assuming this succeeded
# Output retrieved items
puts 'The following item was retrieved via getDigitalItem():'
p digital_items
# Delete the sample digital item
delete_sample_digital_item(digital_item_oid)
rescue UltracartClient::ApiException => e
puts 'An ApiException occurred. Please review the following error:'
p e # change_me: handle gracefully
exit 1
end
import { itemApi } from '../api';
import {
ItemDigitalItemsResponse,
ItemDigitalItem
} from 'ultracart_rest_api_v2_typescript';
import { ItemFunctions } from './ItemFunctions';
export class GetDigitalItemsByExternalId {
/**
* Please Note!
* Digital Items are not normal items you sell on your site. They are digital files that you may add to
* a library and then attach to a normal item as an accessory or the main item itself.
* See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
*/
public static async execute(): Promise<void> {
try {
// Generate a random external ID (replacing Guid.NewGuid())
const externalId = crypto.randomUUID();
console.log(`My external id is ${externalId}`);
// Insert sample digital item
const digitalItemOid = await ItemFunctions.insertSampleDigitalItem(externalId);
// Retrieve digital items by external ID
const apiResponse: ItemDigitalItemsResponse = await itemApi.getDigitalItemsByExternalId({externalId});
const digitalItems: ItemDigitalItem[] = apiResponse.digital_items ?? []; // Use nullish coalescing
console.log("The following item was retrieved via GetDigitalItem():");
console.log(digitalItems);
// Delete the sample digital item
await ItemFunctions.deleteSampleDigitalItem(digitalItemOid);
} catch (error) {
console.error("An Exception occurred. Please review the following error:");
console.error(error);
process.exit(1);
}
}
}
// Optional: If you want to execute the method
// GetDigitalItemsByExternalId.execute().catch(console.error);
Retrieves a group of digital items (file information) from the account that are not yet associated with any actual items. If no parameters are specified, all digital items will be returned. Be aware that these are not normal items that can be added to a shopping cart. Rather, they are digital files that may be associated with normal items. You will need to make multiple API calls in order to retrieve the entire result set since this API performs result set pagination.
SDK Function Name: getUnassociatedDigitalItems
Parameter | Description | Location | Data Type | Required |
---|---|---|---|---|
_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
|
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 |
using System;
using System.Collections.Generic;
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;
namespace SdkSample.item
{
public class GetUnassociatedDigitalItems
{
/// <summary>
/// Execute method containing all business logic
/// </summary>
public static void Execute()
{
try
{
/*
* Please Note!
* Digital Items are not normal items you sell on your site. They are digital files that you may add to
* a library and then attach to a normal item as an accessory or the main item itself.
* See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
*
* Retrieves a group of digital items (file information) from the account that are not yet associated with any
* actual items. If no parameters are specified, all digital items will be returned. Be aware that these are
* not normal items that can be added to a shopping cart. Rather, they are digital files that may be associated
* with normal items. You will need to make multiple API calls in order to retrieve the entire result set since
* this API performs result set pagination.
*
* Default sort order: original_filename
* Possible sort orders: original_filename, description, file_size
*/
int digitalItemOid = ItemFunctions.InsertSampleDigitalItem(); // create an item that will be unassociated.
ItemApi itemApi = new ItemApi(Constants.ApiKey);
int limit = 100;
int offset = 0;
string since = null; // digital items do not use since. leave as null.
string sort = null; // if null, use default of original_filename
string expand = null; // digital items have no expansion. leave as null. this value is ignored
bool? placeholders = null; // digital items have no placeholders. leave as null.
ItemDigitalItemsResponse apiResponse = itemApi.GetUnassociatedDigitalItems(limit, offset, since, sort, expand, placeholders);
List<ItemDigitalItem> digitalItems = apiResponse.DigitalItems; // assuming this succeeded
Console.WriteLine("The following items were retrieved via GetUnassociatedDigitalItems():");
foreach (ItemDigitalItem digitalItem in digitalItems)
{
Console.WriteLine(digitalItem.ToString());
}
}
catch (Exception e)
{
Console.WriteLine("An Exception occurred. Please review the following error:");
Console.WriteLine(e.ToString()); // <-- change_me: handle gracefully
Environment.Exit(1);
}
}
}
}
package item;
import com.ultracart.admin.v2.ItemApi;
import com.ultracart.admin.v2.models.*;
import common.Constants;
import java.util.List;
public class GetUnassociatedDigitalItems {
/// <summary>
/// Execute method containing all business logic
/// </summary>
public static void execute() {
try {
/*
* Please Note!
* Digital Items are not normal items you sell on your site. They are digital files that you may add to
* a library and then attach to a normal item as an accessory or the main item itself.
* See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
*
* Retrieves a group of digital items (file information) from the account that are not yet associated with any
* actual items. If no parameters are specified, all digital items will be returned. Be aware that these are
* not normal items that can be added to a shopping cart. Rather, they are digital files that may be associated
* with normal items. You will need to make multiple API calls in order to retrieve the entire result set since
* this API performs result set pagination.
*
* Default sort order: original_filename
* Possible sort orders: original_filename, description, file_size
*/
int digitalItemOid = ItemFunctions.insertSampleDigitalItem(null); // create an item that will be unassociated.
ItemApi itemApi = new ItemApi(Constants.API_KEY);
int limit = 100;
int offset = 0;
String since = null; // digital items do not use since. leave as null.
String sort = null; // if null, use default of original_filename
String expand = null; // digital items have no expansion. leave as null. this value is ignored
Boolean placeholders = null; // digital items have no placeholders. leave as null.
ItemDigitalItemsResponse apiResponse = itemApi.getUnassociatedDigitalItems(limit, offset, since, sort, expand, placeholders);
List<ItemDigitalItem> digitalItems = apiResponse.getDigitalItems(); // assuming this succeeded
System.out.println("The following items were retrieved via GetUnassociatedDigitalItems():");
for (ItemDigitalItem digitalItem : digitalItems) {
System.out.println(digitalItem.toString());
}
}
catch (Exception e) {
System.out.println("An Exception occurred. Please review the following error:");
System.out.println(e.toString()); // <-- change_me: handle gracefully
System.exit(1);
}
}
}
import { itemApi } from '../api.js';
import { ItemFunctions } from './itemFunctions.js';
/**
* Execute method containing all business logic
*/
export async function execute() {
try {
/*
* Please Note!
* Digital Items are not normal items you sell on your site. They are digital files that you may add to
* a library and then attach to a normal item as an accessory or the main item itself.
* See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
*
* Retrieves a group of digital items (file information) from the account that are not yet associated with any
* actual items. If no parameters are specified, all digital items will be returned. Be aware that these are
* not normal items that can be added to a shopping cart. Rather, they are digital files that may be associated
* with normal items. You will need to make multiple API calls in order to retrieve the entire result set since
* this API performs result set pagination.
*
* Default sort order: original_filename
* Possible sort orders: original_filename, description, file_size
*/
const digitalItemOid = await ItemFunctions.insertSampleDigitalItem(); // create an item that will be unassociated.
const limit = 100;
const offset = 0;
const since = undefined; // digital items do not use since. leave as undefined.
const sort = undefined; // if undefined, use default of original_filename
const expand = undefined; // digital items have no expansion. leave as undefined. this value is ignored
const placeholders = undefined; // digital items have no placeholders. leave as undefined.
const request = {
_limit: limit,
_offset: offset,
_since: since,
_sort: sort,
_expand: expand,
_placeholders: placeholders
};
const apiResponse = await new Promise((resolve, reject) => {
itemApi.getUnassociatedDigitalItems(request, function (error, data, response) {
if (error) reject(error);
else resolve(data, response);
});
});
const digitalItems = apiResponse.digital_items || [];
console.log("The following items were retrieved via getUnassociatedDigitalItems():");
digitalItems.forEach((digitalItem) => {
console.log(digitalItem ? digitalItem.toString() : undefined); // Handle toString() in JS
});
} catch (error) {
console.error("An Exception occurred. Please review the following error:");
console.error(error); // <-- change_me: handle gracefully
process.exit(1);
}
}
<?php
/** @noinspection SpellCheckingInspection */
/** @noinspection GrazieInspection */
use ultracart\v2\ApiException;
require_once '../vendor/autoload.php';
require_once '../samples.php';
require_once './item_functions.php'; // <-- see this file for details
try {
/*
Please Note!
Digital Items are not normal items you sell on your site. They are digital files that you may add to
a library and then attach to a normal item as an accessory or the main item itself.
See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
Retrieves a group of digital items (file information) from the account that are not yet associated with any
actual items. If no parameters are specified, all digital items will be returned. Be aware that these are
not normal items that can be added to a shopping cart. Rather, they are digital files that may be associated
with normal items. You will need to make multiple API calls in order to retrieve the entire result set since
this API performs result set pagination.
Default sort order: original_filename
Possible sort orders: original_filename, description, file_size
*/
$digital_item_oid = insertSampleDigitalItem(); // create an item that will be unassociated.
$item_api = Samples::getItemApi();
$_limit = 100;
$_offset = 0;
$_since = null; // digital items do not use since. leave as null.
$_sort = null; // if null, use default of original_filename
$_expand = null; // digital items have no expansion. leave as null. this value is ignored
$_placeholders = null; // digital items have no placeholders. leave as null.
$api_response = $item_api->getUnassociatedDigitalItems($_limit, $_offset, $_since, $_sort, $_expand, $_placeholders);
$digital_items = $api_response->getDigitalItems(); // assuming this succeeded
echo 'The following items were retrieved via getUnassociatedDigitalItems():';
foreach ($digital_items as $digital_item) {
var_dump($digital_item);
}
} catch (ApiException $e) {
echo 'An ApiException occurred. Please review the following error:';
var_dump($e); // <-- change_me: handle gracefully
die(1);
}
from ultracart.apis import ItemApi
from samples import api_client
from item_functions import insert_sample_digital_item
from ultracart.exceptions import ApiException
"""
Please Note!
Digital Items are not normal items you sell on your site. They are digital files that you may add to
a library and then attach to a normal item as an accessory or the main item itself.
See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
Retrieves a group of digital items (file information) from the account that are not yet associated with any
actual items. If no parameters are specified, all digital items will be returned. Be aware that these are
not normal items that can be added to a shopping cart. Rather, they are digital files that may be associated
with normal items. You will need to make multiple API calls in order to retrieve the entire result set since
this API performs result set pagination.
Default sort order: original_filename
Possible sort orders: original_filename, description, file_size
"""
try:
# Create an unassociated digital item
digital_item_oid = insert_sample_digital_item()
# Initialize Item API
item_api = ItemApi(api_client())
# Set up parameters for retrieving unassociated digital items
limit = 100
offset = 0
since = None # digital items do not use since. leave as None
sort = None # if None, use default of original_filename
expand = None # digital items have no expansion. leave as None
placeholders = None # digital items have no placeholders. leave as None
# Retrieve unassociated digital items
api_response = item_api.get_unassociated_digital_items(
limit=limit,
offset=offset,
since=since,
sort=sort,
expand=expand,
placeholders=placeholders
)
# Extract digital items from the response
digital_items = api_response.digital_items
# Print retrieved digital items
print('The following items were retrieved via get_unassociated_digital_items():')
for digital_item in digital_items:
print(digital_item)
except ApiException as e:
print('An ApiException occurred. Please review the following error:')
print(e)
exit(1)
require 'ultracart_api'
require_relative '../constants'
require_relative './item_functions'
=begin
Digital Items are not normal items you sell on your site. They are digital files that you may add to
a library and then attach to a normal item as an accessory or the main item itself.
See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
Retrieves a group of digital items (file information) from the account that are not yet associated with any
actual items. If no parameters are specified, all digital items will be returned. These are
digital files that may be associated with normal items.
Default sort order: original_filename
Possible sort orders: original_filename, description, file_size
=end
begin
# Create an unassociated digital item
digital_item_oid = insert_sample_digital_item
# Initialize the item API
item_api = UltracartClient::ItemApi.new_using_api_key(Constants::API_KEY)
# Prepare options for API call
opts = {
'_limit' => 100,
'_offset' => 0,
'_since' => nil, # digital items do not use since
'_sort' => nil, # defaults to original_filename
'_expand' => nil, # digital items have no expansion
'_placeholders' => nil
}
# Get unassociated digital items
api_response = item_api.get_unassociated_digital_items(opts)
# Print retrieved digital items
puts 'The following items were retrieved via get_unassociated_digital_items():'
api_response.digital_items.each do |digital_item|
p digital_item
end
rescue UltracartClient::ApiError => e
warn 'An ApiException occurred. Please review the following error:'
p e
exit(1)
end
import { itemApi } from '../api';
import {
ItemDigitalItemsResponse,
ItemDigitalItem
} from 'ultracart_rest_api_v2_typescript';
import { ItemFunctions } from './ItemFunctions';
/**
* Execute method containing all business logic
*/
export async function execute(): Promise<void> {
try {
/*
* Please Note!
* Digital Items are not normal items you sell on your site. They are digital files that you may add to
* a library and then attach to a normal item as an accessory or the main item itself.
* See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
*
* Retrieves a group of digital items (file information) from the account that are not yet associated with any
* actual items. If no parameters are specified, all digital items will be returned. Be aware that these are
* not normal items that can be added to a shopping cart. Rather, they are digital files that may be associated
* with normal items. You will need to make multiple API calls in order to retrieve the entire result set since
* this API performs result set pagination.
*
* Default sort order: original_filename
* Possible sort orders: original_filename, description, file_size
*/
const digitalItemOid: number = await ItemFunctions.insertSampleDigitalItem(); // create an item that will be unassociated.
const limit: number = 100;
const offset: number = 0;
const since: string | undefined = undefined; // digital items do not use since. leave as undefined.
const sort: string | undefined = undefined; // if undefined, use default of original_filename
const expand: string | undefined = undefined; // digital items have no expansion. leave as undefined. this value is ignored
const placeholders: boolean | undefined = undefined; // digital items have no placeholders. leave as undefined.
const apiResponse: ItemDigitalItemsResponse = await itemApi.getUnassociatedDigitalItems({
limit,
offset,
since,
sort,
expand,
placeholders
});
const digitalItems: ItemDigitalItem[] = apiResponse.digital_items || [];
console.log("The following items were retrieved via getUnassociatedDigitalItems():");
digitalItems.forEach((digitalItem: ItemDigitalItem) => {
console.log(digitalItem.toString());
});
} catch (error) {
console.error("An Exception occurred. Please review the following error:");
console.error(error); // <-- change_me: handle gracefully
process.exit(1);
}
}
Delete a digital item on the UltraCart account.
SDK Function Name: deleteDigitalItem
Parameter | Description | Location | Data Type | Required |
---|---|---|---|---|
digital_item_oid | The digital item oid to delete. | path | integer (int32) | required |
using System;
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;
using SdkSample.item;
namespace SdkSample.item
{
public class DeleteDigitalItem
{
public static void Execute()
{
try
{
int digitalItemOid = ItemFunctions.InsertSampleDigitalItem();
ItemFunctions.DeleteSampleDigitalItem(digitalItemOid);
}
catch (Exception e)
{
Console.WriteLine("An Exception occurred. Please review the following error:");
Console.WriteLine(e); // <-- change_me: handle gracefully
Environment.Exit(1);
}
}
}
}
package item;
public class DeleteDigitalItem {
public static void execute() {
try {
int digitalItemOid = ItemFunctions.insertSampleDigitalItem(null);
ItemFunctions.deleteSampleDigitalItem(digitalItemOid);
} catch (Exception e) {
System.err.println("An Exception occurred. Please review the following error:");
e.printStackTrace();
System.exit(1);
}
}
}
import {ItemFunctions} from './itemFunctions.js';
export class DeleteDigitalItem {
static async execute() {
try {
const digitalItemOid = await ItemFunctions.insertSampleDigitalItem();
await ItemFunctions.deleteSampleDigitalItem(digitalItemOid);
} catch (e) {
console.log("An Exception occurred. Please review the following error:");
console.log(e); // <-- change_me: handle gracefully
throw e; // Equivalent to Environment.Exit(1), but better for async context
}
}
}
<?php
use ultracart\v2\ApiException;
require_once '../vendor/autoload.php';
require_once '../samples.php';
require_once './item_functions.php'; // <-- see this file for details
try {
$digital_item_oid = insertSampleDigitalItem();
deleteSampleDigitalItem($digital_item_oid);
} catch (ApiException $e) {
echo 'An ApiException occurred. Please review the following error:';
var_dump($e); // <-- change_me: handle gracefully
die(1);
}
# Digital item operations sample script
from ultracart.api_client import ApiException
from item_functions import insert_sample_digital_item, delete_sample_digital_item
try:
digital_item_oid = insert_sample_digital_item()
delete_sample_digital_item(digital_item_oid)
except ApiException as e:
print('An ApiException occurred. Please review the following error:')
print(e) # Handle gracefully as noted in original comment
exit(1)
require 'ultracart_api'
require_relative '../constants'
require_relative './item_functions'
begin
digital_item_oid = insert_sample_digital_item
delete_sample_digital_item(digital_item_oid)
rescue UltracartClient::ApiException => e
puts 'An ApiException occurred. Please review the following error:'
p e
exit(1)
end
import {ItemFunctions} from './ItemFunctions';
export class DeleteDigitalItem {
public static async execute(): Promise<void> {
try {
const digitalItemOid: number = await ItemFunctions.insertSampleDigitalItem();
await ItemFunctions.deleteSampleDigitalItem(digitalItemOid);
} catch (e) {
console.log("An Exception occurred. Please review the following error:");
console.log(e); // <-- change_me: handle gracefully
throw e; // Equivalent to Environment.Exit(1), but better for async context
}
}
}
Retrieves a digital item (file information) from the account. Be aware that these are not normal items that can be added to a shopping cart. Rather, they are digital files that may be associated with normal items.
SDK Function Name: getDigitalItem
Parameter | Description | Location | Data Type | Required |
---|---|---|---|---|
digital_item_oid | The digital item oid to retrieve. | path | integer (int32) | required |
using System;
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;
using SdkSample.item;
namespace SdkSample.item
{
public class GetDigitalItem
{
public static void Execute()
{
try
{
/*
* Please Note!
* Digital Items are not normal items you sell on your site. They are digital files that you may add to
* a library and then attach to a normal item as an accessory or the main item itself.
* See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
*/
int digitalItemOid = ItemFunctions.InsertSampleDigitalItem(); // create an item so I can get an item
ItemApi itemApi = Samples.GetItemApi();
ItemDigitalItemResponse apiResponse = itemApi.GetDigitalItem(digitalItemOid);
ItemDigitalItem digitalItem = apiResponse.DigitalItem; // assuming this succeeded
Console.WriteLine("The following item was retrieved via GetDigitalItem():");
Console.WriteLine(digitalItem);
ItemFunctions.DeleteSampleDigitalItem(digitalItemOid);
}
catch (Exception e)
{
Console.WriteLine("An Exception occurred. Please review the following error:");
Console.WriteLine(e); // <-- change_me: handle gracefully
Environment.Exit(1);
}
}
}
}
package item;
import com.ultracart.admin.v2.ItemApi;
import com.ultracart.admin.v2.models.*;
import common.Constants;
public class GetDigitalItem {
/**
* Digital Items are not normal items sold on site. They are digital files added to
* a library and attached to normal items as accessories or main items.
* See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
*/
public static void execute() {
try {
int digitalItemOid = ItemFunctions.insertSampleDigitalItem(null);
ItemApi itemApi = new ItemApi(Constants.API_KEY);
ItemDigitalItemResponse apiResponse = itemApi.getDigitalItem(digitalItemOid);
ItemDigitalItem digitalItem = apiResponse.getDigitalItem();
System.out.println("The following item was retrieved via GetDigitalItem():");
System.out.println(digitalItem);
ItemFunctions.deleteSampleDigitalItem(digitalItemOid);
} catch (Exception e) {
System.err.println("An Exception occurred. Please review the following error:");
e.printStackTrace();
System.exit(1);
}
}
}
import { itemApi } from '../api.js';
import { ItemFunctions } from './itemFunctions.js'; // Assuming ItemFunctions is in a separate file
export class GetDigitalItem {
static async execute() {
try {
/*
* Please Note!
* Digital Items are not normal items you sell on your site. They are digital files that you may add to
* a library and then attach to a normal item as an accessory or the main item itself.
* See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
*/
const digitalItemOid = await ItemFunctions.insertSampleDigitalItem(); // create an item so I can get an item
const apiResponse = await new Promise((resolve, reject) => {
itemApi.getDigitalItem(digitalItemOid, function (error, data, response) {
if (error) {
reject(error);
} else {
resolve(data, response);
}
});
});
const digitalItem = apiResponse.digital_item; // assuming this succeeded
console.log("The following item was retrieved via GetDigitalItem():");
console.log(digitalItem);
await ItemFunctions.deleteSampleDigitalItem(digitalItemOid);
} catch (e) {
console.log("An Exception occurred. Please review the following error:");
console.log(e); // <-- change_me: handle gracefully
throw e; // Equivalent to Environment.Exit(1), but better for async context
}
}
}
<?php
/** @noinspection SpellCheckingInspection */
/** @noinspection GrazieInspection */
use ultracart\v2\ApiException;
require_once '../vendor/autoload.php';
require_once '../samples.php';
require_once './item_functions.php'; // <-- see this file for details
try {
/*
* Please Note!
* Digital Items are not normal items you sell on your site. They are digital files that you may add to
* a library and then attach to a normal item as an accessory or the main item itself.
* See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
*/
$digital_item_oid = insertSampleDigitalItem(); // create an item so I can get an item
$item_api = Samples::getItemApi();
$api_response = $item_api->getDigitalItem($digital_item_oid);
$digital_item = $api_response->getDigitalItem(); // assuming this succeeded
echo 'The following item was retrieved via getDigitalItem():';
var_dump($digital_item);
deleteSampleDigitalItem($digital_item_oid);
} catch (ApiException $e) {
echo 'An ApiException occurred. Please review the following error:';
var_dump($e); // <-- change_me: handle gracefully
die(1);
}
# Digital Item Retrieval Example
#
# Please Note!
# Digital Items are not normal items you sell on your site. They are digital files that you may add to
# a library and then attach to a normal item as an accessory or the main item itself.
# See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
from ultracart.api_client import ApiException
from ultracart.apis import ItemApi
from samples import api_client
from item_functions import insert_sample_digital_item, delete_sample_digital_item
try:
# Create a digital item to retrieve
digital_item_oid = insert_sample_digital_item()
# Get the item API and retrieve the digital item
item_api = ItemApi(api_client())
api_response = item_api.get_digital_item(digital_item_oid)
digital_item = api_response.digital_item
# Print the retrieved item
print('The following item was retrieved via get_digital_item():')
print(digital_item)
# Clean up the sample digital item
delete_sample_digital_item(digital_item_oid)
except ApiException as e:
print('An ApiException occurred. Please review the following error:')
print(e) # Handle gracefully as noted in original comment
exit(1)
require 'ultracart_api'
require_relative '../constants'
require_relative './item_functions'
begin
# Digital Items are not normal items you sell on your site. They are digital files that you may add to
# a library and then attach to a normal item as an accessory or the main item itself.
# See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
digital_item_oid = insert_sample_digital_item # create an item so I can get an item
item_api = UltracartClient::ItemApi.new_using_api_key(Constants::API_KEY)
opts = { '_expand' => nil }
api_response = item_api.get_digital_item(digital_item_oid, opts)
digital_item = api_response.digital_item # assuming this succeeded
puts 'The following item was retrieved via get_digital_item():'
p digital_item
delete_sample_digital_item(digital_item_oid)
rescue UltracartClient::ApiException => e
puts 'An ApiException occurred. Please review the following error:'
p e
exit(1)
end
import { itemApi } from '../api';
import { ItemDigitalItem, ItemDigitalItemResponse } from 'ultracart_rest_api_v2_typescript';
import { ItemFunctions } from './ItemFunctions'; // Assuming ItemFunctions is in a separate file
export class GetDigitalItem {
public static async execute(): Promise<void> {
try {
/*
* Please Note!
* Digital Items are not normal items you sell on your site. They are digital files that you may add to
* a library and then attach to a normal item as an accessory or the main item itself.
* See: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/1376485/Digital+Items
*/
const digitalItemOid: number = await ItemFunctions.insertSampleDigitalItem(); // create an item so I can get an item
const apiResponse: ItemDigitalItemResponse = await itemApi.getDigitalItem({ digitalItemOid });
const digitalItem: ItemDigitalItem|undefined = apiResponse.digital_item; // assuming this succeeded
console.log("The following item was retrieved via GetDigitalItem():");
console.log(digitalItem);
await ItemFunctions.deleteSampleDigitalItem(digitalItemOid);
} catch (e) {
console.log("An Exception occurred. Please review the following error:");
console.log(e); // <-- change_me: handle gracefully
throw e; // Equivalent to Environment.Exit(1), but better for async context
}
}
}
Updates a file within the digital library. This does not update an item, but updates a digital file available and selectable as part (or all) of an item.
SDK Function Name: updateDigitalItem
Parameter | Description | Location | Data Type | Required |
---|---|---|---|---|
digital_item_oid | The digital item oid to update. | path | integer (int32) | required |
digital_item | Digital item to update | body | ItemDigitalItem | required |
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;
using System;
using com.ultracart.admin.v2.Client;
namespace SdkSample.item
{
public class UpdateDigitalItem
{
public static void Execute()
{
try
{
int digitalItemOid = ItemFunctions.InsertSampleDigitalItem();
ItemApi itemApi = new ItemApi(Constants.ApiKey);
ItemDigitalItemResponse apiResponse = itemApi.GetDigitalItem(digitalItemOid);
ItemDigitalItem digitalItem = apiResponse.DigitalItem;
digitalItem.Description = "I have updated the description to this sentence.";
digitalItem.ClickWrapAgreement = "You hereby agree that the earth is round. No debate.";
itemApi.UpdateDigitalItem(digitalItemOid, digitalItem);
ItemFunctions.DeleteSampleDigitalItem(digitalItemOid);
}
catch (ApiException e)
{
Console.WriteLine("An ApiException occurred. Please review the following error:");
Console.WriteLine(e); // <-- change_me: handle gracefully
Environment.Exit(1);
}
}
}
}
package item;
import com.ultracart.admin.v2.ItemApi;
import com.ultracart.admin.v2.models.ItemDigitalItem;
import com.ultracart.admin.v2.models.ItemDigitalItemResponse;
import com.ultracart.admin.v2.util.ApiException;
import common.Constants;
public class UpdateDigitalItem {
public static void execute() {
try {
int digitalItemOid = ItemFunctions.insertSampleDigitalItem(null);
ItemApi itemApi = new ItemApi(Constants.API_KEY);
ItemDigitalItemResponse apiResponse = itemApi.getDigitalItem(digitalItemOid);
ItemDigitalItem digitalItem = apiResponse.getDigitalItem();
digitalItem.setDescription("I have updated the description to this sentence.");
digitalItem.setClickWrapAgreement("You hereby agree that the earth is round. No debate.");
itemApi.updateDigitalItem(digitalItemOid, digitalItem);
ItemFunctions.deleteSampleDigitalItem(digitalItemOid);
}
catch (ApiException e) {
System.out.println("An ApiException occurred. Please review the following error:");
System.out.println(e); // <-- change_me: handle gracefully
System.exit(1);
}
}
}
import {itemApi} from '../api.js';
import {ItemFunctions} from './itemFunctions.js';
export class UpdateDigitalItem {
/**
* Updates a digital item by:
* 1. Inserting a sample digital item
* 2. Retrieving the item
* 3. Modifying its description and click-wrap agreement
* 4. Updating the item
* 5. Deleting the sample digital item
*/
static async execute() {
try {
// Insert a sample digital item and get its OID
const digitalItemOid = await ItemFunctions.insertSampleDigitalItem();
// Retrieve the digital item
const apiResponse = await new Promise((resolve, reject) => {
itemApi.getDigitalItem(digitalItemOid, function (error, data, response) {
if (error) {
reject(error);
} else {
resolve(data);
}
});
});
const digitalItem = apiResponse.digital_item;
// Ensure the digital item exists before updating
if (!digitalItem) {
throw new Error('Digital item not found');
}
// Update the digital item details
digitalItem.description = "I have updated the description to this sentence.";
digitalItem.click_wrap_agreement = "You hereby agree that the earth is round. No debate.";
// Update the digital item
await new Promise((resolve, reject) => {
itemApi.updateDigitalItem(digitalItemOid, digitalItem, function (error, data, response) {
if (error) {
reject(error);
} else {
resolve(data);
}
});
});
// Delete the sample digital item
await ItemFunctions.deleteSampleDigitalItem(digitalItemOid);
} catch (error) {
console.error("An error occurred while updating the digital item:", error);
process.exit(1);
}
}
}
<?php
/** @noinspection SpellCheckingInspection */
/** @noinspection GrazieInspection */
use ultracart\v2\ApiException;
require_once '../vendor/autoload.php';
require_once '../samples.php';
require_once './item_functions.php'; // <-- see this file for details
try {
$digital_item_oid = insertSampleDigitalItem();
$item_api = Samples::getItemApi();
$api_response = $item_api->getDigitalItem($digital_item_oid);
$digital_item = $api_response->getDigitalItem();
$digital_item->setDescription("I have updated the description to this sentence.");
$digital_item->setClickWrapAgreement("You hereby agree that the earth is round. No debate.");
$item_api->updateDigitalItem($digital_item_oid, $digital_item);
deleteSampleDigitalItem($digital_item_oid);
} catch (ApiException $e) {
echo 'An ApiException occurred. Please review the following error:';
var_dump($e); // <-- change_me: handle gracefully
die(1);
}
from ultracart.apis import ItemApi
from samples import api_client
from item_functions import insert_sample_digital_item, delete_sample_digital_item
from ultracart.exceptions import ApiException
try:
digital_item_oid = insert_sample_digital_item()
item_api = ItemApi(api_client())
api_response = item_api.get_digital_item(digital_item_oid)
digital_item = api_response.digital_item
digital_item.description = "I have updated the description to this sentence."
digital_item.click_wrap_agreement = "You hereby agree that the earth is round. No debate."
item_api.update_digital_item(digital_item_oid, digital_item)
delete_sample_digital_item(digital_item_oid)
except ApiException as e:
print('An ApiException occurred. Please review the following error:')
print(e)
exit(1)
#!/usr/bin/env ruby
# frozen_string_literal: true
require 'ultracart_api'
require_relative '../constants'
require_relative './item_functions'
begin
# Insert a sample digital item
digital_item_oid = insert_sample_digital_item()
# Initialize the Item API
item_api = UltracartClient::ItemApi.new_using_api_key(Constants::API_KEY)
# Retrieve the digital item
api_response = item_api.get_digital_item(digital_item_oid)
digital_item = api_response.digital_item
# Update the digital item details
digital_item.description = "I have updated the description to this sentence."
digital_item.click_wrap_agreement = "You hereby agree that the earth is round. No debate."
# Update the digital item
item_api.update_digital_item(digital_item_oid, digital_item)
# Delete the sample digital item
delete_sample_digital_item(digital_item_oid)
rescue UltracartClient::ApiError => e
puts 'An ApiException occurred. Please review the following error:'
p e
exit(1)
end
import {itemApi} from '../api';
import {ItemFunctions} from './ItemFunctions';
import {
ItemDigitalItem,
ItemDigitalItemResponse
} from 'ultracart_rest_api_v2_typescript';
export class UpdateDigitalItem {
/**
* Updates a digital item by:
* 1. Inserting a sample digital item
* 2. Retrieving the item
* 3. Modifying its description and click-wrap agreement
* 4. Updating the item
* 5. Deleting the sample digital item
*/
public static async execute(): Promise<void> {
try {
// Insert a sample digital item and get its OID
const digitalItemOid: number = await ItemFunctions.insertSampleDigitalItem();
// Retrieve the digital item
const apiResponse: ItemDigitalItemResponse = await itemApi.getDigitalItem({digitalItemOid});
const digitalItem: ItemDigitalItem | undefined = apiResponse.digital_item;
// Ensure the digital item exists before updating
if (!digitalItem) {
throw new Error('Digital item not found');
}
// Update the digital item details
digitalItem.description = "I have updated the description to this sentence.";
digitalItem.click_wrap_agreement = "You hereby agree that the earth is round. No debate.";
// Update the digital item
await itemApi.updateDigitalItem({digitalItemOid, digitalItem});
// Delete the sample digital item
await ItemFunctions.deleteSampleDigitalItem(digitalItemOid);
} catch (error) {
console.error("An error occurred while updating the digital item:", error);
process.exit(1);
}
}
}
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.
SDK Function Name: getItems
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
|
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 |
using System;
using System.Collections.Generic;
using System.Linq;
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;
namespace SdkSample.item
{
public class GetItems
{
/// <summary>
/// Execute the item retrieval example
/// </summary>
public static void Execute()
{
/*
* This example illustrates how to retrieve items. When dealing with items, please note that categories are
* essentially folders to organize and store items. They are only used for that purpose and play no role in
* the checkout process or in the storefront display of items. So you may organize your items as best serves
* you. We're often asked why was use the word 'category' instead of 'folder'. We started down the road of
* item management 27 years ago with the word 'category', and it's too much trouble to change. So items are
* managed by categories, not folders. But they are folders. :)
* The call takes two possible parameters:
* 1) parentCategoryId: This is a number which uniquely identifies a category in our system. Not easy to determine.
* 2) parentCategoryPath: This is the folder path you wish to retrieve, starting with a forward slash "/"
* If you provide neither of these values, all items are returned.
*/
// Increase timeout for long-running operation
// Note: In C# we don't need to explicitly set execution time limits like in PHP
ItemApi itemApi = new ItemApi(Constants.ApiKey);
List<Item> items = new List<Item>();
int iteration = 1;
int offset = 0;
int limit = 200;
bool moreRecordsToFetch = true;
try
{
while (moreRecordsToFetch)
{
Console.WriteLine($"executing iteration {iteration}");
List<Item> chunkOfItems = GetItemChunk(itemApi, offset, limit);
items = items.Concat(chunkOfItems).ToList();
offset += limit;
moreRecordsToFetch = chunkOfItems.Count == limit;
iteration++;
}
}
catch (com.ultracart.admin.v2.Client.ApiException e)
{
Console.WriteLine($"ApiException occurred on iteration {iteration}");
Console.WriteLine(e.ToString());
Environment.Exit(1);
}
// this will be verbose...
foreach (Item item in items)
{
Console.WriteLine(item.ToString());
}
}
/// <summary>
/// Get a chunk of items from the API
/// </summary>
/// <param name="itemApi">ItemApi instance</param>
/// <param name="offset">Starting offset for retrieval</param>
/// <param name="limit">Maximum number of records to retrieve</param>
/// <returns>List of retrieved items</returns>
private static List<Item> GetItemChunk(ItemApi itemApi, int offset, int limit)
{
// The real devil in the getItem calls is the expansion, making sure you return everything you need without
// returning everything since these objects are extremely large.
// These are the possible expansion values.
/*
accounting amember auto_order auto_order.steps
ccbill channel_partner_mappings chargeback checkout
content content.assignments content.attributes content.multimedia
content.multimedia.thumbnails digital_delivery ebay email_notifications
enrollment123 gift_certificate google_product_search kit_definition
identifiers instant_payment_notifications internal options
payment_processing physical pricing pricing.tiers
realtime_pricing related reporting restriction
reviews salesforce shipping shipping.cases
tax third_party_email_marketing variations wishlist_member
shipping.destination_markups
shipping.destination_restrictions
shipping.distribution_centers
shipping.methods
shipping.package_requirements
*/
string expand = "kit_definition,options,shipping,tax,variations"; // just some random ones. contact us if you're unsure
int? parentCategoryId = null;
string parentCategoryPath = null;
string since = null;
string sort = null;
ItemsResponse apiResponse = itemApi.GetItems(parentCategoryId, parentCategoryPath, limit, offset, since,
sort, expand, false);
if (apiResponse.Items != null)
{
return apiResponse.Items;
}
return new List<Item>();
}
}
}
package item;
import com.ultracart.admin.v2.ItemApi;
import com.ultracart.admin.v2.models.Item;
import com.ultracart.admin.v2.models.ItemsResponse;
import com.ultracart.admin.v2.util.ApiException;
import common.Constants;
import java.util.ArrayList;
import java.util.List;
public class GetItems {
public static void execute() {
/*
* This example illustrates how to retrieve items. When dealing with items, please note that categories are
* essentially folders to organize and store items. They are only used for that purpose and play no role in
* the checkout process or in the storefront display of items. So you may organize your items as best serves
* you. We're often asked why was use the word 'category' instead of 'folder'. We started down the road of
* item management 27 years ago with the word 'category', and it's too much trouble to change. So items are
* managed by categories, not folders. But they are folders. :)
* The call takes two possible parameters:
* 1) parentCategoryId: This is a number which uniquely identifies a category in our system. Not easy to determine.
* 2) parentCategoryPath: This is the folder path you wish to retrieve, starting with a forward slash "/"
* If you provide neither of these values, all items are returned.
*/
ItemApi itemApi = new ItemApi(Constants.API_KEY);
List<Item> items = new ArrayList<>();
int iteration = 1;
int offset = 0;
int limit = 200;
boolean moreRecordsToFetch = true;
try {
while (moreRecordsToFetch) {
System.out.println("executing iteration " + iteration);
List<Item> chunkOfItems = getItemChunk(itemApi, offset, limit);
items.addAll(chunkOfItems);
offset += limit;
moreRecordsToFetch = chunkOfItems.size() == limit;
iteration++;
}
} catch (ApiException e) {
System.out.println("ApiException occurred on iteration " + iteration);
e.printStackTrace();
System.exit(1);
}
for (Item item : items) {
System.out.println(item.toString());
}
}
private static List<Item> getItemChunk(ItemApi itemApi, int offset, int limit) throws ApiException {
// The real devil in the getItem calls is the expansion, making sure you return everything you need without
// returning everything since these objects are extremely large.
// These are the possible expansion values.
/*
accounting amember auto_order auto_order.steps
ccbill channel_partner_mappings chargeback checkout
content content.assignments content.attributes content.multimedia
content.multimedia.thumbnails digital_delivery ebay email_notifications
enrollment123 gift_certificate google_product_search kit_definition
identifiers instant_payment_notifications internal options
payment_processing physical pricing pricing.tiers
realtime_pricing related reporting restriction
reviews salesforce shipping shipping.cases
tax third_party_email_marketing variations wishlist_member
shipping.destination_markups
shipping.destination_restrictions
shipping.distribution_centers
shipping.methods
shipping.package_requirements
*/
String expand = "kit_definition,options,shipping,tax,variations"; // just some random ones. contact us if you're unsure
Integer parentCategoryId = null;
String parentCategoryPath = null;
String since = null;
String sort = null;
ItemsResponse apiResponse = itemApi.getItems(parentCategoryId, parentCategoryPath, limit, offset, since,
sort, expand, false);
if (apiResponse.getItems() != null) {
return apiResponse.getItems();
}
return new ArrayList<>();
}
}
import {itemApi} from '../api.js';
export class GetItems {
/// <summary>
/// Execute the item retrieval example
/// </summary>
static async execute() {
/*
* This example illustrates how to retrieve items. When dealing with items, please note that categories are
* essentially folders to organize and store items. They are only used for that purpose and play no role in
* the checkout process or in the storefront display of items. So you may organize your items as best serves
* you. We're often asked why was use the word 'category' instead of 'folder'. We started down the road of
* item management 27 years ago with the word 'category', and it's too much trouble to change. So items are
* managed by categories, not folders. But they are folders. :)
* The call takes two possible parameters:
* 1) parentCategoryId: This is a number which uniquely identifies a category in our system. Not easy to determine.
* 2) parentCategoryPath: This is the folder path you wish to retrieve, starting with a forward slash "/"
* If you provide neither of these values, all items are returned.
*/
const items = [];
let iteration = 1;
let offset = 0;
const limit = 200;
let moreRecordsToFetch = true;
try {
while (moreRecordsToFetch) {
console.log(`executing iteration ${iteration}`);
const chunkOfItems = await this.getItemChunk(offset, limit);
items.push(...chunkOfItems);
offset += limit;
moreRecordsToFetch = chunkOfItems.length === limit;
iteration++;
}
} catch (e) {
console.log(`ApiException occurred on iteration ${iteration}`);
console.log(e);
throw e; // Equivalent to Environment.Exit(1), but better for async context
}
// this will be verbose...
for (const item of items) {
console.log(item);
}
}
/// <summary>
/// Get a chunk of items from the API
/// </summary>
/// <param name="offset">Starting offset for retrieval</param>
/// <param name="limit">Maximum number of records to retrieve</param>
/// <returns>List of retrieved items</returns>
static async getItemChunk(offset, limit) {
// The real devil in the getItem calls is the expansion, making sure you return everything you need without
// returning everything since these objects are extremely large.
// These are the possible expansion values.
/*
accounting amember auto_order auto_order.steps
ccbill channel_partner_mappings chargeback checkout
content content.assignments content.attributes content.multimedia
content.multimedia.thumbnails digital_delivery ebay email_notifications
enrollment123 gift_certificate google_product_search kit_definition
identifiers instant_payment_notifications internal options
payment_processing physical pricing pricing.tiers
realtime_pricing related reporting restriction
reviews salesforce shipping shipping.cases
tax third_party_email_marketing variations wishlist_member
shipping.destination_markups
shipping.destination_restrictions
shipping.distribution_centers
shipping.methods
shipping.package_requirements
*/
const expand = "kit_definition,options,shipping,tax,variations"; // just some random ones. contact us if you're unsure
const parentCategoryId = undefined;
const parentCategoryPath = undefined;
const since = undefined;
const sort = undefined;
const request = {
parentCategoryId: parentCategoryId,
parentCategoryPath: parentCategoryPath,
_limit: limit,
_offset: offset,
_since: since,
_sort: sort,
_expand: expand,
_placeholders: false
};
const apiResponse = await new Promise((resolve, reject) => {
itemApi.getItems(request, function (error, data, response) {
if (error) reject(error);
else resolve(data, response);
});
});
return apiResponse.items || [];
}
}
<?php
set_time_limit(3000); // pull all records could take a long time.
ini_set('max_execution_time', 3000);
ini_set('display_errors', 1);
/*
* This example illustrates how to retrieve items. When dealing with items, please note that categories are
* essentially folders to organize and store items. They are only used for that purpose and play no role in
* the checkout process or in the storefront display of items. So you may organize your items as best serves
* you. We're often asked why was use the word 'category' instead of 'folder'. We started down the road of
* item management 27 years ago with the word 'category', and it's too much trouble to change. So items are
* managed by categories, not folders. But they are folders. :)
* The call takes two possible parameters:
* 1) parentCategoryId: This is a number which uniquely identifies a category in our system. Not easy to determine.
* 2) parentCategoryPath: This is the folder path you wish to retrieve, starting with a forward slash "/"
* If you provide neither of these values, all items are returned.
*/
use ultracart\v2\api\ItemApi;
use ultracart\v2\ApiException;
require_once '../vendor/autoload.php';
require_once '../samples.php';
$item_api = Samples::getItemApi();
/**
* @throws ApiException
*/
function getItemChunk(ItemApi $item_api, int $offset, int $limit): array
{
// The real devil in the getItem calls is the expansion, making sure you return everything you need without
// returning everything since these objects are extremely large.
// These are the possible expansion values.
/*
accounting amember auto_order auto_order.steps
ccbill channel_partner_mappings chargeback checkout
content content.assignments content.attributes content.multimedia
content.multimedia.thumbnails digital_delivery ebay email_notifications
enrollment123 gift_certificate google_product_search kit_definition
identifiers instant_payment_notifications internal options
payment_processing physical pricing pricing.tiers
realtime_pricing related reporting restriction
reviews salesforce shipping shipping.cases
tax third_party_email_marketing variations wishlist_member
shipping.destination_markups
shipping.destination_restrictions
shipping.distribution_centers
shipping.methods
shipping.package_requirements
*/
$expand = "kit_definition,options,shipping,tax,variations"; // just some random ones. contact us if you're unsure
$parent_category_id = null;
$parent_category_path = null;
$_since = null;
$_sort = null;
$api_response = $item_api->getItems($parent_category_id, $parent_category_path, $limit, $offset, $_since,
$_sort, $expand, false);
if ($api_response->getItems() != null) {
return $api_response->getItems();
}
return [];
}
$items = [];
$iteration = 1;
$offset = 0;
$limit = 200;
$more_records_to_fetch = true;
try {
while ($more_records_to_fetch) {
echo "executing iteration " . $iteration . '<br>';
$chunk_of_items = getItemChunk($item_api, $offset, $limit);
$orders = array_merge($items, $chunk_of_items);
$offset = $offset + $limit;
$more_records_to_fetch = count($chunk_of_items) == $limit;
$iteration++;
}
} catch (ApiException $e) {
echo 'ApiException occurred on iteration ' . $iteration;
var_dump($e);
die(1);
}
// this will be verbose...
var_dump($items);
import sys
from ultracart.apis import ItemApi
from samples import api_client
def get_item_chunk(item_api, offset, limit):
"""
Retrieve a chunk of items with specified expansion.
Possible expansion values include:
accounting, amember, auto_order, auto_order.steps, ccbill, channel_partner_mappings,
chargeback, checkout, content, content.assignments, content.attributes,
content.multimedia, content.multimedia.thumbnails, digital_delivery, ebay,
email_notifications, enrollment123, gift_certificate, google_product_search,
kit_definition, identifiers, instant_payment_notifications, internal, options,
payment_processing, physical, pricing, pricing.tiers, realtime_pricing, related,
reporting, restriction, reviews, salesforce, shipping, shipping.cases,
shipping.destination_markups, shipping.destination_restrictions,
shipping.distribution_centers, shipping.methods, shipping.package_requirements,
tax, third_party_email_marketing, variations, wishlist_member
"""
# Expansion of commonly needed item details
expand = "kit_definition,options,shipping,tax,variations"
# Retrieve items with no category filtering
api_response = item_api.get_items(
parent_category_id=None,
parent_category_path=None,
limit=limit,
offset=offset,
since=None,
sort=None,
expand=expand,
active=False
)
return api_response.get_items() or []
def main():
"""
Retrieve all items in chunks.
Note: Categories in UltraCart are essentially folders to organize items.
They do not impact checkout or storefront display.
"""
# Create Item API client
item_api = ItemApi(api_client())
items = []
iteration = 1
offset = 0
limit = 200
more_records_to_fetch = True
try:
while more_records_to_fetch:
print(f"Executing iteration {iteration}")
chunk_of_items = get_item_chunk(item_api, offset, limit)
items.extend(chunk_of_items)
offset += limit
more_records_to_fetch = len(chunk_of_items) == limit
iteration += 1
except Exception as e:
print(f'Exception occurred on iteration {iteration}')
print(e)
sys.exit(1)
# Print all retrieved items (will be verbose)
print(items)
if __name__ == "__main__":
main()
require 'ultracart_api'
require_relative '../constants'
# Increase execution time for potentially long-running script
# Note: Ruby uses different methods for timeout management
# You may need to adjust based on your specific Ruby environment
# This example illustrates how to retrieve items. When dealing with items, please note that categories are
# essentially folders to organize and store items. They are only used for that purpose and play no role in
# the checkout process or in the storefront display of items. So you may organize your items as best serves
# you. We're often asked why we use the word 'category' instead of 'folder'. We started down the road of
# item management 27 years ago with the word 'category', and it's too much trouble to change. So items are
# managed by categories, not folders. But they are folders. :)
#
# The call takes two possible parameters:
# 1) parentCategoryId: This is a number which uniquely identifies a category in our system. Not easy to determine.
# 2) parentCategoryPath: This is the folder path you wish to retrieve, starting with a forward slash "/"
# If you provide neither of these values, all items are returned.
# Method to retrieve a chunk of items
def get_item_chunk(item_api, offset, limit)
# The real devil in the getItem calls is the expansion, making sure you return everything you need without
# returning everything since these objects are extremely large.
# These are the possible expansion values:
#
# accounting amember auto_order auto_order.steps
# ccbill channel_partner_mappings chargeback checkout
# content content.assignments content.attributes content.multimedia
# content.multimedia.thumbnails digital_delivery ebay email_notifications
# enrollment123 gift_certificate google_product_search kit_definition
# identifiers instant_payment_notifications internal options
# payment_processing physical pricing pricing.tiers
# realtime_pricing related reporting restriction
# reviews salesforce shipping shipping.cases
# tax third_party_email_marketing variations wishlist_member
# shipping.destination_markups
# shipping.destination_restrictions
# shipping.distribution_centers
# shipping.methods
# shipping.package_requirements
# Just some random ones. Contact us if you're unsure
expand = "kit_definition,options,shipping,tax,variations"
# Prepare options for API call
opts = {
'_parent_category_id' => nil,
'_parent_category_path' => nil,
'_limit' => limit,
'_offset' => offset,
'_since' => nil,
'_sort' => nil,
'_expand' => expand,
'_placeholders' => false
}
# Retrieve items
api_response = item_api.get_items(opts)
# Return items or empty array if none found
api_response.items || []
end
begin
# Initialize item API
item_api = UltracartClient::ItemApi.new_using_api_key(Constants::API_KEY)
# Pagination variables
items = []
iteration = 1
offset = 0
limit = 200
more_records_to_fetch = true
# Fetch items in chunks
while more_records_to_fetch
puts "executing iteration #{iteration}"
chunk_of_items = get_item_chunk(item_api, offset, limit)
items += chunk_of_items
offset += limit
more_records_to_fetch = chunk_of_items.length == limit
iteration += 1
end
# Output will be verbose...
p items
rescue UltracartClient::ApiException => e
puts "ApiException occurred on iteration #{iteration}"
p e
exit 1
end
import { itemApi } from '../api';
import { Item, ItemsResponse } from 'ultracart_rest_api_v2_typescript';
export class GetItems {
/// <summary>
/// Execute the item retrieval example
/// </summary>
public static async execute(): Promise<void> {
/*
* This example illustrates how to retrieve items. When dealing with items, please note that categories are
* essentially folders to organize and store items. They are only used for that purpose and play no role in
* the checkout process or in the storefront display of items. So you may organize your items as best serves
* you. We're often asked why was use the word 'category' instead of 'folder'. We started down the road of
* item management 27 years ago with the word 'category', and it's too much trouble to change. So items are
* managed by categories, not folders. But they are folders. :)
* The call takes two possible parameters:
* 1) parentCategoryId: This is a number which uniquely identifies a category in our system. Not easy to determine.
* 2) parentCategoryPath: This is the folder path you wish to retrieve, starting with a forward slash "/"
* If you provide neither of these values, all items are returned.
*/
const items: Item[] = [];
let iteration = 1;
let offset = 0;
const limit = 200;
let moreRecordsToFetch = true;
try {
while (moreRecordsToFetch) {
console.log(`executing iteration ${iteration}`);
const chunkOfItems = await this.getItemChunk(offset, limit);
items.push(...chunkOfItems);
offset += limit;
moreRecordsToFetch = chunkOfItems.length === limit;
iteration++;
}
} catch (e) {
console.log(`ApiException occurred on iteration ${iteration}`);
console.log(e);
throw e; // Equivalent to Environment.Exit(1), but better for async context
}
// this will be verbose...
for (const item of items) {
console.log(item);
}
}
/// <summary>
/// Get a chunk of items from the API
/// </summary>
/// <param name="offset">Starting offset for retrieval</param>
/// <param name="limit">Maximum number of records to retrieve</param>
/// <returns>List of retrieved items</returns>
private static async getItemChunk(offset: number, limit: number): Promise<Item[]> {
// The real devil in the getItem calls is the expansion, making sure you return everything you need without
// returning everything since these objects are extremely large.
// These are the possible expansion values.
/*
accounting amember auto_order auto_order.steps
ccbill channel_partner_mappings chargeback checkout
content content.assignments content.attributes content.multimedia
content.multimedia.thumbnails digital_delivery ebay email_notifications
enrollment123 gift_certificate google_product_search kit_definition
identifiers instant_payment_notifications internal options
payment_processing physical pricing pricing.tiers
realtime_pricing related reporting restriction
reviews salesforce shipping shipping.cases
tax third_party_email_marketing variations wishlist_member
shipping.destination_markups
shipping.destination_restrictions
shipping.distribution_centers
shipping.methods
shipping.package_requirements
*/
const expand = "kit_definition,options,shipping,tax,variations"; // just some random ones. contact us if you're unsure
const parentCategoryId: number | undefined = undefined;
const parentCategoryPath: string | undefined = undefined;
const since: string | undefined = undefined;
const sort: string | undefined = undefined;
const apiResponse: ItemsResponse = await itemApi.getItems({
parentCategoryId,
parentCategoryPath,
limit,
offset,
since,
sort,
expand: expand,
placeholders: false
});
return apiResponse.items ?? [];
}
}
Create a new item on the UltraCart account.
SDK Function Name: insertItem
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 |
using System;
namespace SdkSample.item
{
public class InsertItem
{
public static void Execute()
{
try
{
string itemId = ItemFunctions.InsertSampleItem();
ItemFunctions.DeleteSampleItem(itemId);
}
catch (Exception e)
{
Console.WriteLine("An Exception occurred. Please review the following error:");
Console.WriteLine(e.ToString()); // handle gracefully
Environment.Exit(1);
}
}
}
}
package item;
public class InsertItem {
public static void execute() {
try {
String itemId = ItemFunctions.insertSampleItem();
ItemFunctions.deleteSampleItem(itemId);
}
catch (Exception e) {
System.out.println("An Exception occurred. Please review the following error:");
System.out.println(e.toString()); // handle gracefully
System.exit(1);
}
}
}
import { ItemFunctions } from './itemFunctions.js';
/**
* Execute method containing all business logic
*/
export async function execute() {
try {
const itemId = await ItemFunctions.insertSampleItem();
await ItemFunctions.deleteSampleItem(itemId);
} catch (error) {
console.error("An Exception occurred. Please review the following error:");
console.error(error); // handle gracefully
process.exit(1);
}
}
<?php
use ultracart\v2\ApiException;
require_once '../vendor/autoload.php';
require_once '../samples.php';
require_once './item_functions.php'; // <-- see this file for details
try {
$item_id = insertSampleItem();
deleteSampleItem($item_id);
} catch (ApiException $e) {
echo 'An ApiException occurred. Please review the following error:';
var_dump($e); // <-- change_me: handle gracefully
die(1);
}
from item_functions import insert_sample_item, delete_sample_item
from ultracart.exceptions import ApiException
try:
item_id = insert_sample_item()
delete_sample_item(item_id)
except ApiException as e:
print('An ApiException occurred. Please review the following error:')
print(e)
exit(1)
require 'ultracart_api'
require_relative '../constants'
require_relative './item_functions'
begin
# Create and then delete a sample item
item_id = insert_sample_item
delete_sample_item(item_id)
rescue UltracartClient::ApiError => e
warn 'An ApiException occurred. Please review the following error:'
p e
exit(1)
end
import { ItemFunctions } from './ItemFunctions';
/**
* Execute method containing all business logic
*/
export async function execute(): Promise<void> {
try {
const itemId: string = await ItemFunctions.insertSampleItem();
await ItemFunctions.deleteSampleItem(itemId);
} catch (error) {
console.error("An Exception occurred. Please review the following error:");
console.error(error); // handle gracefully
process.exit(1);
}
}
Update multiple item on the UltraCart account.
SDK Function Name: updateItems
Parameter | Description | Location | Data Type | Required |
---|---|---|---|---|
items_request | Items to update (synchronous maximum 20 / asynchronous maximum 100) | body | ItemsRequest | 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 |
_async | True if the operation should be run async. No result returned | query | boolean | optional |
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;
using System;
using System.Collections.Generic;
using com.ultracart.admin.v2.Client;
namespace SdkSample.item
{
public class UpdateItems
{
public static void Execute()
{
try
{
string itemId1 = ItemFunctions.InsertSampleItem();
string itemId2 = ItemFunctions.InsertSampleItem();
ItemApi itemApi = new ItemApi(Constants.ApiKey);
// See one of the getItem or getItems samples for possible expansion values
// See also: https://www.ultracart.com/api/#resource_item.html
string expand = "pricing";
ItemResponse apiResponse = itemApi.GetItemByMerchantItemId(itemId1, expand, false);
Item item1 = apiResponse.Item;
apiResponse = itemApi.GetItemByMerchantItemId(itemId2, expand, false);
Item item2 = apiResponse.Item;
// update the price of the item.
item1.Pricing.Cost = 12.99m;
item2.Pricing.Cost = 14.99m;
ItemsRequest updateItemsRequest = new ItemsRequest();
updateItemsRequest.Items = new List<Item>{item1, item2};
ItemsResponse updateItemsResponse = itemApi.UpdateItems(updateItemsRequest, expand, false, false);
ItemFunctions.DeleteSampleItem(itemId1);
ItemFunctions.DeleteSampleItem(itemId2);
}
catch (ApiException e)
{
Console.WriteLine("An ApiException occurred. Please review the following error:");
Console.WriteLine(e); // <-- change_me: handle gracefully
Environment.Exit(1);
}
}
}
}
package item;
import com.ultracart.admin.v2.ItemApi;
import com.ultracart.admin.v2.models.Item;
import com.ultracart.admin.v2.models.ItemResponse;
import com.ultracart.admin.v2.models.ItemsRequest;
import com.ultracart.admin.v2.models.ItemsResponse;
import com.ultracart.admin.v2.util.ApiException;
import common.Constants;
import java.math.BigDecimal;
import java.util.Arrays;
public class UpdateItems {
public static void execute() {
try {
String itemId1 = ItemFunctions.insertSampleItem();
String itemId2 = ItemFunctions.insertSampleItem();
ItemApi itemApi = new ItemApi(Constants.API_KEY);
// See one of the getItem or getItems samples for possible expansion values
// See also: https://www.ultracart.com/api/#resource_item.html
String expand = "pricing";
ItemResponse apiResponse = itemApi.getItemByMerchantItemId(itemId1, expand, false);
Item item1 = apiResponse.getItem();
apiResponse = itemApi.getItemByMerchantItemId(itemId2, expand, false);
Item item2 = apiResponse.getItem();
// update the price of the item.
item1.getPricing().setCost(BigDecimal.valueOf(12.99));
item2.getPricing().setCost(BigDecimal.valueOf(14.99));
ItemsRequest updateItemsRequest = new ItemsRequest();
updateItemsRequest.setItems(Arrays.asList(item1, item2));
ItemsResponse updateItemsResponse = itemApi.updateItems(updateItemsRequest, expand, false, false);
ItemFunctions.deleteSampleItem(itemId1);
ItemFunctions.deleteSampleItem(itemId2);
}
catch (ApiException e) {
System.out.println("An ApiException occurred. Please review the following error:");
System.out.println(e); // <-- change_me: handle gracefully
System.exit(1);
}
}
}
import {itemApi} from '../api.js';
import {ItemFunctions} from './itemFunctions.js';
export class UpdateItems {
/**
* Updates multiple items by:
* 1. Inserting two sample items
* 2. Retrieving both items with pricing expansion
* 3. Updating the prices of both items
* 4. Performing a bulk update
* 5. Deleting the sample items
*
* See https://www.ultracart.com/api/#resource_item.html for possible expansion values
*/
static async execute() {
try {
// Insert two sample items
const itemId1 = await ItemFunctions.insertSampleItem();
const itemId2 = await ItemFunctions.insertSampleItem();
// Define expansion parameter
const expand = "pricing";
// Retrieve the first item
const apiResponse1 = await new Promise((resolve, reject) => {
itemApi.getItemByMerchantItemId(itemId1,
{_expand: expand}, function (error, data, response) {
if (error) {
reject(error);
} else {
resolve(data);
}
});
});
const item1 = apiResponse1.item;
// Retrieve the second item
const apiResponse2 = await new Promise((resolve, reject) => {
itemApi.getItemByMerchantItemId(
itemId2,
{_expand: expand}, function (error, data, response) {
if (error) {
reject(error);
} else {
resolve(data);
}
});
});
const item2 = apiResponse2.item;
// Ensure both items exist and have pricing
if (!item1 || !item1.pricing || !item2 || !item2.pricing) {
throw new Error('One or more items or their pricing information not found');
}
// Update the prices of the items
item1.pricing.cost = 12.99;
item2.pricing.cost = 14.99;
// Prepare items for bulk update
const updateItemsRequest = {
items: [item1, item2]
};
// Perform bulk update
const updateItemsResponse = await new Promise((resolve, reject) => {
itemApi.updateItems(updateItemsRequest,
{_expand: expand, async: false}, function (error, data, response) {
if (error) {
reject(error);
} else {
resolve(data);
}
});
});
// Delete the sample items
await ItemFunctions.deleteSampleItem(itemId1);
await ItemFunctions.deleteSampleItem(itemId2);
} catch (error) {
console.error("An error occurred while updating items:", error);
process.exit(1);
}
}
}
<?php
/** @noinspection SpellCheckingInspection */
/** @noinspection GrazieInspection */
use ultracart\v2\ApiException;
use ultracart\v2\models\ItemsRequest;
require_once '../vendor/autoload.php';
require_once '../samples.php';
require_once './item_functions.php'; // <-- see this file for details
try {
$item_id1 = insertSampleItem();
$item_id2 = insertSampleItem();
$item_api = Samples::getItemApi();
// See one of the getItem or getItems samples for possible expansion values
// See also: https://www.ultracart.com/api/#resource_item.html
$expand = "pricing";
$api_response = $item_api->getItemByMerchantItemId($item_id1, $expand, false);
$item1 = $api_response->getItem();
$api_response = $item_api->getItemByMerchantItemId($item_id2, $expand, false);
$item2 = $api_response->getItem();
// update the price of the item.
$item1->getPricing()->setCost(12.99);
$item2->getPricing()->setCost(14.99);
$update_items_request = new ItemsRequest();
$items = [$item1, $item2];
$update_items_request->setItems($items);
$api_response = $item_api->updateItems($update_items_request, $expand, false, false);
deleteSampleItem($item_id1);
deleteSampleItem($item_id2);
} catch (ApiException $e) {
echo 'An ApiException occurred. Please review the following error:';
var_dump($e); // <-- change_me: handle gracefully
die(1);
}
from flask import Flask
from ultracart import ApiException
from ultracart.apis import ItemApi
from ultracart.models import ItemsRequest
from samples import api_client
from item_functions import insert_sample_item, delete_sample_item
app = Flask(__name__)
@app.route('/update_multiple_items')
def update_multiple_items():
try:
# Insert two sample items
item_id1 = insert_sample_item()
item_id2 = insert_sample_item()
# Create Item API client
item_api = ItemApi(api_client())
# Expand pricing information
expand = "pricing"
# Get items by merchant item IDs
api_response = item_api.get_item_by_merchant_item_id(item_id1, expand=expand, _expand=False)
item1 = api_response.get_item()
api_response = item_api.get_item_by_merchant_item_id(item_id2, expand=expand, _expand=False)
item2 = api_response.get_item()
# Update prices of items
item1.get_pricing().set_cost(12.99)
item2.get_pricing().set_cost(14.99)
# Create items request
update_items_request = ItemsRequest()
items = [item1, item2]
update_items_request.items = items
# Update multiple items
item_api.update_items(update_items_request, expand=expand, _expand=False, _async=False)
# Delete sample items
delete_sample_item(item_id1)
delete_sample_item(item_id2)
return "Multiple items updated successfully"
except ApiException as e:
print('An ApiException occurred. Please review the following error:')
print(e)
return "Error updating items", 500
if __name__ == '__main__':
app.run(debug=True)
#!/usr/bin/env ruby
# frozen_string_literal: true
require 'ultracart_api'
require_relative '../constants'
require_relative './item_functions'
begin
# Insert two sample items
item_id1 = insert_sample_item()
item_id2 = insert_sample_item()
# Initialize the Item API
item_api = UltracartClient::ItemApi.new_using_api_key(Constants::API_KEY)
# See one of the getItem or getItems samples for possible expansion values
# See also: https://www.ultracart.com/api/#resource_item.html
opts = {
'_expand' => 'pricing',
'_placeholders' => false
}
# Retrieve the items
api_response = item_api.get_item_by_merchant_item_id(item_id1, opts)
item1 = api_response.item
api_response = item_api.get_item_by_merchant_item_id(item_id2, opts)
item2 = api_response.item
# Update the prices of the items
item1.pricing.cost = 12.99
item2.pricing.cost = 14.99
# Create items request for bulk update
update_items_request = UltracartClient::ItemsRequest.new(items: [item1, item2])
# Update multiple items
api_response = item_api.update_items(update_items_request, opts.merge('_check_groups' => false))
# Delete the sample items
delete_sample_item(item_id1)
delete_sample_item(item_id2)
rescue UltracartClient::ApiError => e
puts 'An ApiException occurred. Please review the following error:'
p e
exit(1)
end
import {itemApi} from '../api';
import {ItemFunctions} from './ItemFunctions';
import {
Item,
ItemResponse,
ItemsRequest,
ItemsResponse
} from 'ultracart_rest_api_v2_typescript';
export class UpdateItems {
/**
* Updates multiple items by:
* 1. Inserting two sample items
* 2. Retrieving both items with pricing expansion
* 3. Updating the prices of both items
* 4. Performing a bulk update
* 5. Deleting the sample items
*
* See https://www.ultracart.com/api/#resource_item.html for possible expansion values
*/
public static async execute(): Promise<void> {
try {
// Insert two sample items
const itemId1: string = await ItemFunctions.insertSampleItem();
const itemId2: string = await ItemFunctions.insertSampleItem();
// Define expansion parameter
const expand: string = "pricing";
// Retrieve the first item
const apiResponse1: ItemResponse = await itemApi.getItemByMerchantItemId({
merchantItemId: itemId1,
expand,
placeholders: false
});
const item1: Item | undefined = apiResponse1.item;
// Retrieve the second item
const apiResponse2: ItemResponse = await itemApi.getItemByMerchantItemId({
merchantItemId: itemId2,
expand,
placeholders: false
});
const item2: Item | undefined = apiResponse2.item;
// Ensure both items exist and have pricing
if (!item1 || !item1.pricing || !item2 || !item2.pricing) {
throw new Error('One or more items or their pricing information not found');
}
// Update the prices of the items
item1.pricing.cost = 12.99;
item2.pricing.cost = 14.99;
// Prepare items for bulk update
const updateItemsRequest: ItemsRequest = {
items: [item1, item2]
};
// Perform bulk update
const updateItemsResponse: ItemsResponse = await itemApi.updateItems({
itemsRequest: updateItemsRequest,
expand,
placeholders: false,
async: false
});
// Delete the sample items
await ItemFunctions.deleteSampleItem(itemId1);
await ItemFunctions.deleteSampleItem(itemId2);
} catch (error) {
console.error("An error occurred while updating items:", error);
process.exit(1);
}
}
}
Retrieve a list of item inventories. This method may be called once every 15 minutes. More than that will result in a 429 response.
SDK Function Name: getInventorySnapshot
using System;
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;
using Newtonsoft.Json;
namespace SdkSample.item
{
public class GetInventorySnapshot
{
public static void Execute()
{
try
{
// Retrieve a list of item inventories.
// This method may be called once every 15 minutes. More than that will result in a 429 response.
ItemApi itemApi = Samples.GetItemApi();
ItemInventorySnapshotResponse snapshotResponse = itemApi.GetInventorySnapshot();
foreach (ItemInventorySnapshot inventory in snapshotResponse.Inventories)
{
Console.WriteLine(JsonConvert.SerializeObject(inventory, new JsonSerializerSettings { Formatting = Formatting.Indented}));
}
}
catch (Exception e)
{
Console.WriteLine("An Exception occurred. Please review the following error:");
Console.WriteLine(e); // <-- change_me: handle gracefully
Environment.Exit(1);
}
}
}
}
import {itemApi} from '../api.js';
export class GetInventorySnapshot {
/**
* Retrieve a list of item inventories.
* Note: This method may be called once every 15 minutes.
* More frequent calls will result in a 429 response.
*/
static async execute() {
try {
// Retrieve inventory snapshot
const snapshotResponse = await new Promise((resolve, reject) => {
itemApi.getInventorySnapshot(function (error, data, response) {
if (error) {
reject(error);
} else {
resolve(data, response);
}
});
});
// Iterate and log each inventory item
snapshotResponse.inventories?.forEach((inventory) => {
console.log(JSON.stringify(inventory, null, 2));
});
} catch (error) {
console.error("An Exception occurred. Please review the following error:");
console.error(error);
process.exit(1);
}
}
}
// Optional: If you want to execute the method
// GetInventorySnapshot.execute().catch(console.error);
<?php
// Retrieve a list of item inventories.
// This method may be called once every 15 minutes. More than that will result in a 429 response.
use ultracart\v2\api\ItemApi;
use ultracart\v2\ApiException;
require_once '../vendor/autoload.php';
try {
$item_api = ItemApi::usingApiKey(Constants::API_KEY);
$api_response = $item_api->getInventorySnapshot();
$inventories = $api_response->getInventories();
foreach($inventories as $inventory){
var_dump($inventory);
}
} catch (ApiException $e) {
echo 'An ApiException occurred. Please review the following error:';
var_dump($e); // <-- change_me: handle gracefully
die(1);
}
# Retrieve a list of item inventories.
# This method may be called once every 15 minutes. More than that will result in a 429 response.
from ultracart.apis import ItemApi
from ultracart.api_client import ApiException
from samples import api_client
try:
# Create the Item API instance
item_api = ItemApi(api_client())
# Get the inventory snapshot
api_response = item_api.get_inventory_snapshot()
inventories = api_response.inventories
# Iterate and print inventories
for inventory in inventories:
print(inventory)
except ApiException as e:
print('An ApiException occurred. Please review the following error:')
print(e) # Handle gracefully as noted in original comment
exit(1)
require 'ultracart_api'
require_relative '../constants'
# Retrieve a list of item inventories.
# This method may be called once every 15 minutes. More than that will result in a 429 response.
begin
# Initialize the item API
item_api = UltracartClient::ItemApi.new_using_api_key(Constants::API_KEY)
# Retrieve inventory snapshot
api_response = item_api.get_inventory_snapshot
inventories = api_response.inventories
# Output each inventory item
inventories.each do |inventory|
p inventory
end
rescue UltracartClient::ApiException => e
puts 'An ApiException occurred. Please review the following error:'
p e # change_me: handle gracefully
exit 1
end
import { itemApi } from '../api';
import {
ItemInventorySnapshotResponse,
ItemInventorySnapshot
} from 'ultracart_rest_api_v2_typescript';
export class GetInventorySnapshot {
/**
* Retrieve a list of item inventories.
* Note: This method may be called once every 15 minutes.
* More frequent calls will result in a 429 response.
*/
public static async execute(): Promise<void> {
try {
// Retrieve inventory snapshot
const snapshotResponse: ItemInventorySnapshotResponse = await itemApi.getInventorySnapshot();
// Iterate and log each inventory item
snapshotResponse.inventories?.forEach((inventory: ItemInventorySnapshot) => {
console.log(JSON.stringify(inventory, null, 2));
});
} catch (error) {
console.error("An Exception occurred. Please review the following error:");
console.error(error);
process.exit(1);
}
}
}
// Optional: If you want to execute the method
// GetInventorySnapshot.execute().catch(console.error);
Retrieves a single item using the specified item id.
SDK Function Name: getItemByMerchantItemId
Parameter | Description | Location | Data Type | Required |
---|---|---|---|---|
merchant_item_id | The item id to retrieve. | path | string | 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 |
using System;
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;
namespace SdkSample.item
{
public class GetItemByMerchantItemId
{
/// <summary>
/// Execute the item retrieval example
/// </summary>
public static void Execute()
{
// Of the two getItem methods, you'll probably always use getItemByMerchantItemId instead of this one.
// Most item work is done with the item id, not the item oid. The latter is only meaningful as a primary
// key in the UltraCart databases. But here is an example of using getItem(). We take the long route here
// of retrieving the item using getItemByMerchantItemId to obtain the oid rather than hard-coding it. We do this
// because these samples are used in our quality control system and run repeatedly.
try
{
string itemId = ItemFunctions.InsertSampleItem();
ItemApi itemApi = new ItemApi(Constants.ApiKey);
// The real devil in the getItem calls is the expansion, making sure you return everything you need without
// returning everything since these objects are extremely large.
// These are the possible expansion values.
/*
accounting
amember
auto_order
auto_order.steps
ccbill
channel_partner_mappings
chargeback
checkout
content
content.assignments
content.attributes
content.multimedia
content.multimedia.thumbnails
digital_delivery
ebay
email_notifications
enrollment123
gift_certificate
google_product_search
kit_definition
identifiers
instant_payment_notifications
internal
options
payment_processing
physical
pricing
pricing.tiers
realtime_pricing
related
reporting
restriction
reviews
salesforce
shipping
shipping.cases
shipping.destination_markups
shipping.destination_restrictions
shipping.distribution_centers
shipping.methods
shipping.package_requirements
tax
third_party_email_marketing
variations
wishlist_member
*/
string expand = "kit_definition,options,shipping,tax,variations"; // just some random ones. contact us if you're unsure
ItemResponse apiResponse = itemApi.GetItemByMerchantItemId(itemId, expand, false);
Item item = apiResponse.Item;
Console.WriteLine("The following item was retrieved via getItemByMerchantItemId():");
Console.WriteLine(item.ToString());
ItemFunctions.DeleteSampleItem(itemId);
}
catch (com.ultracart.admin.v2.Client.ApiException e)
{
Console.WriteLine("An ApiException occurred. Please review the following error:");
Console.WriteLine(e.ToString()); // <-- change_me: handle gracefully
Environment.Exit(1);
}
}
}
}
package item;
import com.ultracart.admin.v2.ItemApi;
import com.ultracart.admin.v2.models.Item;
import com.ultracart.admin.v2.models.ItemResponse;
import com.ultracart.admin.v2.util.ApiException;
import common.Constants;
public class GetItemByMerchantItemId {
public static void execute() {
// Of the two getItem methods, you'll probably always use getItemByMerchantItemId instead of this one.
// Most item work is done with the item id, not the item oid. The latter is only meaningful as a primary
// key in the UltraCart databases. But here is an example of using getItem(). We take the long route here
// of retrieving the item using getItemByMerchantItemId to obtain the oid rather than hard-coding it. We do this
// because these samples are used in our quality control system and run repeatedly.
try {
String itemId = ItemFunctions.insertSampleItem();
ItemApi itemApi = new ItemApi(Constants.API_KEY);
// The real devil in the getItem calls is the expansion, making sure you return everything you need without
// returning everything since these objects are extremely large.
// These are the possible expansion values.
/*
accounting
amember
auto_order
auto_order.steps
ccbill
channel_partner_mappings
chargeback
checkout
content
content.assignments
content.attributes
content.multimedia
content.multimedia.thumbnails
digital_delivery
ebay
email_notifications
enrollment123
gift_certificate
google_product_search
kit_definition
identifiers
instant_payment_notifications
internal
options
payment_processing
physical
pricing
pricing.tiers
realtime_pricing
related
reporting
restriction
reviews
salesforce
shipping
shipping.cases
shipping.destination_markups
shipping.destination_restrictions
shipping.distribution_centers
shipping.methods
shipping.package_requirements
tax
third_party_email_marketing
variations
wishlist_member
*/
String expand = "kit_definition,options,shipping,tax,variations"; // just some random ones. contact us if you're unsure
ItemResponse apiResponse = itemApi.getItemByMerchantItemId(itemId, expand, false);
Item item = apiResponse.getItem();
System.out.println("The following item was retrieved via getItemByMerchantItemId():");
System.out.println(item.toString());
ItemFunctions.deleteSampleItem(itemId);
} catch (ApiException e) {
System.out.println("An ApiException occurred. Please review the following error:");
e.printStackTrace();
System.exit(1);
}
}
}
import {itemApi} from '../api.js';
import {ItemFunctions} from './itemFunctions.js';
export class GetItemByMerchantItemId {
/**
* Execute the item retrieval example
*
* Of the two getItem methods, you'll probably always use getItemByMerchantItemId instead of this one.
* Most item work is done with the item id, not the item oid. The latter is only meaningful as a primary
* key in the UltraCart databases. But here is an example of using getItem(). We take the long route here
* of retrieving the item using getItemByMerchantItemId to obtain the oid rather than hard-coding it. We do this
* because these samples are used in our quality control system and run repeatedly.
*/
static async execute() {
try {
// Insert a sample item
const itemId = await ItemFunctions.insertSampleItem();
// Possible expansion values:
/*
accounting
amember
auto_order
auto_order.steps
ccbill
channel_partner_mappings
chargeback
checkout
content
content.assignments
content.attributes
content.multimedia
content.multimedia.thumbnails
digital_delivery
ebay
email_notifications
enrollment123
gift_certificate
google_product_search
kit_definition
identifiers
instant_payment_notifications
internal
options
payment_processing
physical
pricing
pricing.tiers
realtime_pricing
related
reporting
restriction
reviews
salesforce
shipping
shipping.cases
shipping.destination_markups
shipping.destination_restrictions
shipping.distribution_centers
shipping.methods
shipping.package_requirements
tax
third_party_email_marketing
variations
wishlist_member
*/
const expand = "kit_definition,options,shipping,tax,variations"; // just some random ones. contact us if you're unsure
// Retrieve item by merchant item ID
const apiResponse = await new Promise((resolve, reject) => {
itemApi.getItemByMerchantItemId(itemId, {_expand: expand}, function (error, data, response) {
if (error) reject(error);
else resolve(data, response);
});
});
const item = apiResponse.item;
console.log("The following item was retrieved via getItemByMerchantItemId():");
console.log(item ? item.toString() : undefined); // Handle toString() in JS
// Delete the sample item
await ItemFunctions.deleteSampleItem(itemId);
} catch (error) {
console.error("An ApiException occurred. Please review the following error:");
console.error(error);
process.exit(1);
}
}
}
// Optional: If you want to execute the method
// GetItemByMerchantItemId.execute().catch(console.error);
<?php
/** @noinspection SpellCheckingInspection */
/** @noinspection GrazieInspection */
use ultracart\v2\ApiException;
require_once '../vendor/autoload.php';
require_once '../samples.php';
require_once './item_functions.php'; // <-- see this file for details
// Of the two getItem methods, you'll probably always use getItemByMerchantItemId instead of this one.
// Most item work is done with the item id, not the item oid. The latter is only meaningful as a primary
// key in the UltraCart databases. But here is an example of using getItem(). We take the long route here
// of retrieving the item using getItemByMerchantItemId to obtain the oid rather than hard-coding it. We do this
// because these samples are used in our quality control system and run repeatedly.
try {
$item_id = insertSampleItem();
$item_api = Samples::getItemApi();
// The real devil in the getItem calls is the expansion, making sure you return everything you need without
// returning everything since these objects are extremely large.
// These are the possible expansion values.
/*
accounting
amember
auto_order
auto_order.steps
ccbill
channel_partner_mappings
chargeback
checkout
content
content.assignments
content.attributes
content.multimedia
content.multimedia.thumbnails
digital_delivery
ebay
email_notifications
enrollment123
gift_certificate
google_product_search
kit_definition
identifiers
instant_payment_notifications
internal
options
payment_processing
physical
pricing
pricing.tiers
realtime_pricing
related
reporting
restriction
reviews
salesforce
shipping
shipping.cases
shipping.destination_markups
shipping.destination_restrictions
shipping.distribution_centers
shipping.methods
shipping.package_requirements
tax
third_party_email_marketing
variations
wishlist_member
*/
$expand = "kit_definition,options,shipping,tax,variations"; // just some random ones. contact us if you're unsure
$api_response = $item_api->getItemByMerchantItemId($item_id, $expand, false);
$item = $api_response->getItem();
echo 'The following item was retrieved via getItemByMerchantItemId():';
var_dump($item);
deleteSampleItem($item_id);
} catch (ApiException $e) {
echo 'An ApiException occurred. Please review the following error:';
var_dump($e); // <-- change_me: handle gracefully
die(1);
}
from ultracart.apis import ItemApi
from samples import api_client
from item_functions import insert_sample_item, delete_sample_item
try:
"""
Most item work is done with the item id, not the item oid.
The latter is only meaningful as a primary key in the UltraCart databases.
"""
# Insert a sample item
item_id = insert_sample_item()
# Create Item API client
item_api = ItemApi(api_client())
"""
Possible expansion values include:
accounting, amember, auto_order, auto_order.steps, ccbill, channel_partner_mappings,
chargeback, checkout, content, content.assignments, content.attributes,
content.multimedia, content.multimedia.thumbnails, digital_delivery, ebay,
email_notifications, enrollment123, gift_certificate, google_product_search,
kit_definition, identifiers, instant_payment_notifications, internal, options,
payment_processing, physical, pricing, pricing.tiers, realtime_pricing, related,
reporting, restriction, reviews, salesforce, shipping, shipping.cases,
shipping.destination_markups, shipping.destination_restrictions,
shipping.distribution_centers, shipping.methods, shipping.package_requirements,
tax, third_party_email_marketing, variations, wishlist_member
"""
expand = "kit_definition,options,shipping,tax,variations"
api_response = item_api.get_item_by_merchant_item_id(item_id, expand=expand, active=False)
item = api_response.get_item()
print('The following item was retrieved via get_item_by_merchant_item_id():')
print(item)
delete_sample_item(item_id)
except Exception as e:
print('An exception occurred. Please review the following error:')
print(e)
raise
require 'ultracart_api'
require_relative '../constants'
require_relative './item_functions'
begin
# Of the two getItem methods, you'll probably always use getItemByMerchantItemId instead of this one.
# Most item work is done with the item id, not the item oid. The latter is only meaningful as a primary
# key in the UltraCart databases. But here is an example of using getItem(). We take the long route here
# of retrieving the item using getItemByMerchantItemId to obtain the oid rather than hard-coding it. We do this
# because these samples are used in our quality control system and run repeatedly.
# Insert a sample item
item_id = insert_sample_item
# Initialize item API
item_api = UltracartClient::ItemApi.new_using_api_key(Constants::API_KEY)
# The real devil in the getItem calls is the expansion, making sure you return everything you need without
# returning everything since these objects are extremely large.
# These are the possible expansion values:
#
# accounting
# amember
# auto_order
# auto_order.steps
# ccbill
# channel_partner_mappings
# chargeback
# checkout
# content
# content.assignments
# content.attributes
# content.multimedia
# content.multimedia.thumbnails
# digital_delivery
# ebay
# email_notifications
# enrollment123
# gift_certificate
# google_product_search
# kit_definition
# identifiers
# instant_payment_notifications
# internal
# options
# payment_processing
# physical
# pricing
# pricing.tiers
# realtime_pricing
# related
# reporting
# restriction
# reviews
# salesforce
# shipping
# shipping.cases
# shipping.destination_markups
# shipping.destination_restrictions
# shipping.distribution_centers
# shipping.methods
# shipping.package_requirements
# tax
# third_party_email_marketing
# variations
# wishlist_member
#
# just some random ones. contact us if you're unsure
expand = "kit_definition,options,shipping,tax,variations"
# Retrieve item by merchant item ID with expansions
api_response = item_api.get_item_by_merchant_item_id(
item_id,
opts = { '_expand' => expand, '_placeholders' => false }
)
item = api_response.item
# Output the retrieved item
puts 'The following item was retrieved via getItemByMerchantItemId():'
p item
# Clean up sample item
delete_sample_item(item_id)
rescue UltracartClient::ApiException => e
puts 'An ApiException occurred. Please review the following error:'
p e # change_me: handle gracefully
exit 1
end
import {itemApi} from '../api';
import {
ItemResponse,
Item
} from 'ultracart_rest_api_v2_typescript';
import {ItemFunctions} from './ItemFunctions';
export class GetItemByMerchantItemId {
/**
* Execute the item retrieval example
*
* Of the two getItem methods, you'll probably always use getItemByMerchantItemId instead of this one.
* Most item work is done with the item id, not the item oid. The latter is only meaningful as a primary
* key in the UltraCart databases. But here is an example of using getItem(). We take the long route here
* of retrieving the item using getItemByMerchantItemId to obtain the oid rather than hard-coding it. We do this
* because these samples are used in our quality control system and run repeatedly.
*/
public static async execute(): Promise<void> {
try {
// Insert a sample item
const itemId = await ItemFunctions.insertSampleItem();
// Possible expansion values:
/*
accounting
amember
auto_order
auto_order.steps
ccbill
channel_partner_mappings
chargeback
checkout
content
content.assignments
content.attributes
content.multimedia
content.multimedia.thumbnails
digital_delivery
ebay
email_notifications
enrollment123
gift_certificate
google_product_search
kit_definition
identifiers
instant_payment_notifications
internal
options
payment_processing
physical
pricing
pricing.tiers
realtime_pricing
related
reporting
restriction
reviews
salesforce
shipping
shipping.cases
shipping.destination_markups
shipping.destination_restrictions
shipping.distribution_centers
shipping.methods
shipping.package_requirements
tax
third_party_email_marketing
variations
wishlist_member
*/
const expand = "kit_definition,options,shipping,tax,variations"; // just some random ones. contact us if you're unsure
// Retrieve item by merchant item ID
const apiResponse: ItemResponse = await itemApi.getItemByMerchantItemId({
merchantItemId: itemId,
expand,
placeholders: false
});
const item: Item | undefined = apiResponse.item;
console.log("The following item was retrieved via getItemByMerchantItemId():");
console.log(item?.toString());
// Delete the sample item
await ItemFunctions.deleteSampleItem(itemId);
} catch (error) {
console.error("An ApiException occurred. Please review the following error:");
console.error(error);
process.exit(1);
}
}
}
// Optional: If you want to execute the method
// GetItemByMerchantItemId.execute().catch(console.error);
Delete an item on the UltraCart account.
SDK Function Name: deleteItem
Parameter | Description | Location | Data Type | Required |
---|---|---|---|---|
merchant_item_oid | The item oid to delete. | path | integer (int32) | required |
using System;
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;
using SdkSample.item;
namespace SdkSample.item
{
public class DeleteItem
{
public static void Execute()
{
try
{
int itemOid = ItemFunctions.InsertSampleItemAndGetOid();
ItemFunctions.DeleteSampleItemByOid(itemOid);
}
catch (Exception e)
{
Console.WriteLine("An Exception occurred. Please review the following error:");
Console.WriteLine(e); // <-- change_me: handle gracefully
Environment.Exit(1);
}
}
}
}
package item;
public class DeleteItem {
public static void execute() {
try {
int itemOid = ItemFunctions.insertSampleItemAndGetOid();
ItemFunctions.deleteSampleItemByOid(itemOid);
} catch (Exception e) {
System.err.println("An Exception occurred. Please review the following error:");
e.printStackTrace();
System.exit(1);
}
}
}
import {ItemFunctions} from './itemFunctions.js'; // Assuming ItemFunctions is in a separate file
export class DeleteItem {
static async execute() {
try {
const itemOid = await ItemFunctions.insertSampleItemAndGetOid();
await ItemFunctions.deleteSampleItemByOid(itemOid);
} catch (e) {
console.log("An Exception occurred. Please review the following error:");
console.log(e); // <-- change_me: handle gracefully
throw e; // Equivalent to Environment.Exit(1), but better for async context
}
}
}
<?php
use ultracart\v2\ApiException;
require_once '../vendor/autoload.php';
require_once '../samples.php';
require_once './item_functions.php'; // <-- see this file for details
try {
$item_oid = insertSampleItem();
deleteSampleItem($item_oid);
} catch (ApiException $e) {
echo 'An ApiException occurred. Please review the following error:';
var_dump($e); // <-- change_me: handle gracefully
die(1);
}
# Sample item operations script
from ultracart.api_client import ApiException
from item_functions import insert_sample_item, delete_sample_item
try:
item_oid = insert_sample_item()
delete_sample_item(item_oid)
except ApiException as e:
print('An ApiException occurred. Please review the following error:')
print(e) # Handle gracefully as noted in original comment
exit(1)
require 'ultracart_api'
require_relative '../constants'
require_relative './item_functions'
begin
item_id = insert_sample_item
delete_sample_item(item_id)
rescue UltracartClient::ApiException => e
puts 'An ApiException occurred. Please review the following error:'
p e
exit(1)
end
import {ItemFunctions} from './ItemFunctions'; // Assuming ItemFunctions is in a separate file
export class DeleteItem {
public static async execute(): Promise<void> {
try {
const itemOid: number = await ItemFunctions.insertSampleItemAndGetOid();
await ItemFunctions.deleteSampleItemByOid(itemOid);
} catch (e) {
console.log("An Exception occurred. Please review the following error:");
console.log(e); // <-- change_me: handle gracefully
throw e; // Equivalent to Environment.Exit(1), but better for async context
}
}
}
Retrieves a single item using the specified item oid.
SDK Function Name: getItem
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 |
using System;
using System.Collections.Generic;
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;
namespace SdkSample.item
{
public class GetItem
{
/// <summary>
/// Execute the item retrieval example
/// </summary>
public static void Execute()
{
// Of the two getItem methods, you'll probably always use getItemByMerchantItemId instead of this one.
// Most item work is done with the item id, not the item oid. The latter is only meaningful as a primary
// key in the UltraCart databases. But here is an example of using getItem(). We take the long route here
// of retrieving the item using getItemByMerchantItemId to obtain the oid rather than hard-coding it. We do this
// because these samples are used in our quality control system and run repeatedly.
try
{
ItemApi itemApi = new ItemApi(Constants.ApiKey);
int itemOid = ItemFunctions.InsertSampleItemAndGetOid();
CustomerApi customerApi = new CustomerApi(Constants.ApiKey); // only needed for accessing reviewer information below.
// Yes, I'm creating an item, getting that item in order to get the item id, then getting the item yet again
// using a different method. All to illustrate GetItemByMerchantItemId
string itemId = itemApi.GetItem(itemOid).Item.MerchantItemId;
// the expand variable is null in the following call. we just need the base object this time.
ItemResponse apiResponse = itemApi.GetItemByMerchantItemId(itemId, null, false);
Item item = apiResponse.Item; // assuming this succeeded
int merchantItemOid = item.MerchantItemOid;
// This is the actual call for this script.
// The real devil in the getItem calls is the expansion, making sure you return everything you need without
// returning everything since these objects are extremely large.
// These are the possible expansion values.
/*
accounting
amember
auto_order
auto_order.steps
ccbill
channel_partner_mappings
chargeback
checkout
content
content.assignments
content.attributes
content.multimedia
content.multimedia.thumbnails
digital_delivery
ebay
email_notifications
enrollment123
gift_certificate
google_product_search
kit_definition
identifiers
instant_payment_notifications
internal
options
payment_processing
physical
pricing
pricing.tiers
realtime_pricing
related
reporting
restriction
reviews
reviews.individual_reviews
salesforce
shipping
shipping.cases
shipping.destination_markups
shipping.destination_restrictions
shipping.distribution_centers
shipping.methods
shipping.package_requirements
tax
third_party_email_marketing
variations
wishlist_member
*/
// string expand = "kit_definition,options,shipping,tax,variations"; // just some random ones. contact us if you're unsure
string expand = "reviews,reviews.individual_reviews"; // changed the random above to reviews to illustrate accessing product reviews.
apiResponse = itemApi.GetItem(merchantItemOid, expand, false);
item = apiResponse.Item;
ItemReviews itemReviews = item.Reviews;
List<ItemReview> individualReviews = itemReviews.IndividualReviews;
// do whatever you wish with the reviews. iterate them, print them, etc.
// if you need the reviewer information
foreach (ItemReview individualReview in individualReviews)
{
// if you need reviewer profile questions, such as "How often do you use this product?", access the
// rating names and scores. these are configurable by merchant, so we do not know what your questions may be.
// See Home -> Configuration -> Items -> Reviews -> Settings
// Or this URL: https://secure.ultracart.com/merchant/item/review/reviewSettingsLoad.do
string ratingName1 = individualReview.RatingName1; // <-- this will not be the full question, but a key string.
decimal ratingScore1 = individualReview.RatingScore1;
// if you need the review information, access that via their customer object. Be careful. This can result
// in a LOT of API calls and exhaust your limit. You may wish to add 'Sleep' calls to your loop and cache
// these results daily or weekly.
CustomerResponse customerResponse = customerApi.GetCustomer(individualReview.CustomerProfileOid, "reviewer");
Customer customer = customerResponse.Customer;
CustomerReviewer reviewer = customer.Reviewer;
}
Console.WriteLine("The following item was retrieved via getItem():");
Console.WriteLine(item.ToString());
ItemFunctions.DeleteSampleItemByOid(itemOid);
}
catch (com.ultracart.admin.v2.Client.ApiException e)
{
Console.WriteLine("An ApiException occurred. Please review the following error:");
Console.WriteLine(e.ToString()); // <-- change_me: handle gracefully
Environment.Exit(1);
}
}
}
}
package item;
import com.ultracart.admin.v2.CustomerApi;
import com.ultracart.admin.v2.ItemApi;
import com.ultracart.admin.v2.models.*;
import com.ultracart.admin.v2.util.ApiException;
import common.Constants;
import java.math.BigDecimal;
import java.util.List;
public class GetItem {
public static void execute() {
try {
ItemApi itemApi = new ItemApi(Constants.API_KEY);
int itemOid = ItemFunctions.insertSampleItemAndGetOid();
CustomerApi customerApi = new CustomerApi(Constants.API_KEY);
String itemId = itemApi.getItem(itemOid, null, false).getItem().getMerchantItemId();
ItemResponse apiResponse = itemApi.getItemByMerchantItemId(itemId, null, false);
Item item = apiResponse.getItem();
int merchantItemOid = item.getMerchantItemOid();
String expand = "reviews,reviews.individual_reviews";
apiResponse = itemApi.getItem(merchantItemOid, expand, false);
item = apiResponse.getItem();
ItemReviews itemReviews = item.getReviews();
List<ItemReview> individualReviews = itemReviews.getIndividualReviews();
for (ItemReview individualReview : individualReviews) {
String ratingName1 = individualReview.getRatingName1();
BigDecimal ratingScore1 = individualReview.getRatingScore1();
CustomerResponse customerResponse = customerApi.getCustomer(individualReview.getCustomerProfileOid(), "reviewer");
Customer customer = customerResponse.getCustomer();
CustomerReviewer reviewer = customer.getReviewer();
}
System.out.println("The following item was retrieved via getItem():");
System.out.println(item.toString());
ItemFunctions.deleteSampleItemByOid(itemOid);
} catch (ApiException e) {
System.out.println("An ApiException occurred. Please review the following error:");
e.printStackTrace();
System.exit(1);
}
}
}
import {itemApi} from '../api.js';
import {customerApi} from '../api.js';
import {ItemFunctions} from './itemFunctions.js'; // Assuming ItemFunctions is in a separate file
export class GetItem {
/// <summary>
/// Execute the item retrieval example
/// </summary>
static async execute() {
try {
const itemOid = await ItemFunctions.insertSampleItemAndGetOid();
// Yes, I'm creating an item, getting that item in order to get the item id, then getting the item yet again
// using a different method. All to illustrate GetItemByMerchantItemId
const itemId = (await new Promise((resolve, reject) => {
itemApi.getItem(itemOid, {}, function (error, data, response) {
if (error) reject(error);
else resolve(data, response);
});
})).item?.merchant_item_id;
if (itemId === undefined) {
console.error("itemId should not be undefined. Something went wrong with sample item creation most likely.");
return;
}
// the expand variable is undefined in the following call. we just need the base object this time.
const apiResponse = await new Promise((resolve, reject) => {
itemApi.getItemByMerchantItemId(itemId, {}, function (error, data, response) {
if (error) reject(error);
else resolve(data, response);
});
});
const item = apiResponse.item; // assuming this succeeded
const merchantItemOid = item?.merchant_item_oid || 0;
if (merchantItemOid === 0) {
console.error("getItemByMerchantItemId failed.");
return;
}
// This is the actual call for this script.
// The real devil in the getItem calls is the expansion, making sure you return everything you need without
// returning everything since these objects are extremely large.
// These are the possible expansion values.
/*
accounting
amember
auto_order
auto_order.steps
ccbill
channel_partner_mappings
chargeback
checkout
content
content.assignments
content.attributes
content.multimedia
content.multimedia.thumbnails
digital_delivery
ebay
email_notifications
enrollment123
gift_certificate
google_product_search
kit_definition
identifiers
instant_payment_notifications
internal
options
payment_processing
physical
pricing
pricing.tiers
realtime_pricing
related
reporting
restriction
reviews
reviews.individual_reviews
salesforce
shipping
shipping.cases
shipping.destination_markups
shipping.destination_restrictions
shipping.distribution_centers
shipping.methods
shipping.package_requirements
tax
third_party_email_marketing
variations
wishlist_member
*/
// const expand = "kit_definition,options,shipping,tax,variations"; // just some random ones. contact us if you're unsure
const expand = "reviews,reviews.individual_reviews"; // changed the random above to reviews to illustrate accessing product reviews.
const apiResponse2 = await new Promise((resolve, reject) => {
itemApi.getItem(merchantItemOid, {}, function (error, data, response) {
if (error) reject(error);
else resolve(data, response);
});
});
const itemWithReviews = apiResponse2.item;
const itemReviews = itemWithReviews?.reviews;
const individualReviews = itemReviews?.individual_reviews;
if (individualReviews !== undefined) {
// do whatever you wish with the reviews. iterate them, print them, etc.
// if you need the reviewer information
for (const individualReview of individualReviews) {
// if you need reviewer profile questions, such as "How often do you use this product?", access the
// rating names and scores. these are configurable by merchant, so we do not know what your questions may be.
// See Home -> Configuration -> Items -> Reviews -> Settings
// Or this URL: https://secure.ultracart.com/merchant/item/review/reviewSettingsLoad.do
const ratingName1 = individualReview.rating_name1; // <-- this will not be the full question, but a key string.
const ratingScore1 = individualReview.rating_score1;
// if you need the review information, access that via their customer object. Be careful. This can result
// in a LOT of API calls and exhaust your limit. You may wish to add 'Sleep' calls to your loop and cache
// these results daily or weekly.
if (individualReview.customer_profile_oid !== undefined) {
const customerResponse = await new Promise((resolve, reject) => {
customerApi.getCustomer(individualReview.customer_profile_oid, {_expand: "reviewer"}, function (error, data, response) {
if (error) reject(error);
else resolve(data, response);
});
});
const customer = customerResponse.customer;
const reviewer = customer?.reviewer;
}
}
}
console.log("The following item was retrieved via getItem():");
console.log(itemWithReviews);
await ItemFunctions.deleteSampleItemByOid(itemOid);
} catch (e) {
console.log("An ApiException occurred. Please review the following error:");
console.log(e); // <-- change_me: handle gracefully
throw e; // Equivalent to Environment.Exit(1), but better suited for async context
}
}
}
<?php
/** @noinspection SpellCheckingInspection */
/** @noinspection GrazieInspection */
use ultracart\v2\ApiException;
require_once '../vendor/autoload.php';
require_once '../samples.php';
require_once './item_functions.php'; // <-- see this file for details
// Of the two getItem methods, you'll probably always use getItemByMerchantItemId instead of this one.
// Most item work is done with the item id, not the item oid. The latter is only meaningful as a primary
// key in the UltraCart databases. But here is an example of using getItem(). We take the long route here
// of retrieving the item using getItemByMerchantItemId to obtain the oid rather than hard-coding it. We do this
// because these samples are used in our quality control system and run repeatedly.
try {
$item_id = insertSampleItem();
$item_api = Samples::getItemApi();
$customer_api = Samples::getCustomerApi(); // only needed for accessing reviewer information below.
// the _expand variable is null in the following call. we just need the base object this time.
$api_response = $item_api->getItemByMerchantItemId($item_id, null, false);
$item = $api_response->getItem(); // assuming this succeeded
$merchant_item_oid = $item->getMerchantItemOid();
// This is the actual call for this script.
// The real devil in the getItem calls is the expansion, making sure you return everything you need without
// returning everything since these objects are extremely large.
// These are the possible expansion values.
/*
accounting
amember
auto_order
auto_order.steps
ccbill
channel_partner_mappings
chargeback
checkout
content
content.assignments
content.attributes
content.multimedia
content.multimedia.thumbnails
digital_delivery
ebay
email_notifications
enrollment123
gift_certificate
google_product_search
kit_definition
identifiers
instant_payment_notifications
internal
options
payment_processing
physical
pricing
pricing.tiers
realtime_pricing
related
reporting
restriction
reviews
reviews.individual_reviews
salesforce
shipping
shipping.cases
shipping.destination_markups
shipping.destination_restrictions
shipping.distribution_centers
shipping.methods
shipping.package_requirements
tax
third_party_email_marketing
variations
wishlist_member
*/
// $expand = "kit_definition,options,shipping,tax,variations"; // just some random ones. contact us if you're unsure
$expand = "reviews,reviews.individual_reviews"; // changed the random above to reviews to illustrate accessing product reviews.
$api_response = $item_api->getItem($merchant_item_oid, $expand, false);
$item = $api_response->getItem();
$item_reviews = $item->getReviews();
$individual_reviews = $item_reviews->getIndividualReviews();
// do whatever you wish with the reviews. iterate them, print them, etc.
// if you need the reviewer information
foreach ($individual_reviews as $individual_review) {
// if you need reviewer profile questions, such as "How often do you use this product?", access the
// rating names and scores. these are configurable by merchant, so we do not know what your questions may be.
// See Home -> Configuration -> Items -> Reviews -> Settings
// Or this URL: https://secure.ultracart.com/merchant/item/review/reviewSettingsLoad.do
$individual_review->getRatingName1(); // <-- this will not be the full question, but a key string.
$individual_review->getRatingScore1();
// if you need the review information, access that via their customer object. Be careful. This can result
// in a LOT of API calls and exhaust your limit. You may wish to add 'sleep' calls to your loop and cache
// these results daily or weekly.
$customer_response = $customer_api->getCustomer($individual_review->getCustomerProfileOid(), "reviewer");
$customer = $customer_response->getCustomer();
$reviewer = $customer->getReviewer();
}
echo 'The following item was retrieved via getItem():';
var_dump($item);
deleteSampleItem($item_oid);
} catch (ApiException $e) {
echo 'An ApiException occurred. Please review the following error:';
var_dump($e); // <-- change_me: handle gracefully
die(1);
}
from ultracart.apis import ItemApi, CustomerApi
from samples import api_client
from item_functions import insert_sample_item, delete_sample_item
try:
"""
Of the two getItem methods, you'll probably always use get_item_by_merchant_item_id instead of this one.
Most item work is done with the item id, not the item oid. The latter is only meaningful as a primary
key in the UltraCart databases. But here is an example of using get_item(). We take the long route here
of retrieving the item using get_item_by_merchant_item_id to obtain the oid rather than hard-coding it.
We do this because these samples are used in our quality control system and run repeatedly.
"""
# Insert a sample item
item_id = insert_sample_item()
# Create API clients
item_api = ItemApi(api_client())
customer_api = CustomerApi(api_client()) # only needed for accessing reviewer information below
# The expand variable is None in the following call. We just need the base object this time.
api_response = item_api.get_item_by_merchant_item_id(item_id, expand=None, active=False)
item = api_response.get_item() # assuming this succeeded
merchant_item_oid = item.get_merchant_item_oid()
"""
The real devil in the getItem calls is the expansion, making sure you return everything you need without
returning everything since these objects are extremely large.
These are the possible expansion values:
accounting, amember, auto_order, auto_order.steps, ccbill, channel_partner_mappings,
chargeback, checkout, content, content.assignments, content.attributes, content.multimedia,
content.multimedia.thumbnails, digital_delivery, ebay, email_notifications, enrollment123,
gift_certificate, google_product_search, kit_definition, identifiers,
instant_payment_notifications, internal, options, payment_processing, physical, pricing,
pricing.tiers, realtime_pricing, related, reporting, restriction, reviews,
reviews.individual_reviews, salesforce, shipping, shipping.cases, shipping.destination_markups,
shipping.destination_restrictions, shipping.distribution_centers, shipping.methods,
shipping.package_requirements, tax, third_party_email_marketing, variations, wishlist_member
"""
# Expand reviews to illustrate accessing product reviews
expand = "reviews,reviews.individual_reviews"
api_response = item_api.get_item(merchant_item_oid, expand=expand, active=False)
item = api_response.get_item()
item_reviews = item.get_reviews()
individual_reviews = item_reviews.get_individual_reviews()
# Iterate through individual reviews
for individual_review in individual_reviews:
# Access rating names and scores (configurable by merchant)
# See Home -> Configuration -> Items -> Reviews -> Settings
# Or this URL: https://secure.ultracart.com/merchant/item/review/reviewSettingsLoad.do
rating_name1 = individual_review.get_rating_name1() # Not the full question, but a key string
rating_score1 = individual_review.get_rating_score1()
# Retrieve reviewer information (careful: can result in many API calls)
# Consider adding sleep calls and caching results daily or weekly
customer_response = customer_api.get_customer(
individual_review.get_customer_profile_oid(),
expand="reviewer"
)
customer = customer_response.get_customer()
reviewer = customer.get_reviewer()
print('The following item was retrieved via get_item():')
print(item)
# Delete the sample item
delete_sample_item(merchant_item_oid)
except Exception as e:
print('An exception occurred. Please review the following error:')
print(e)
raise
require 'ultracart_api'
require_relative '../constants'
require_relative './item_functions'
begin
# Of the two getItem methods, you'll probably always use getItemByMerchantItemId instead of this one.
# Most item work is done with the item id, not the item oid. The latter is only meaningful as a primary
# key in the UltraCart databases. But here is an example of using getItem(). We take the long route here
# of retrieving the item using getItemByMerchantItemId to obtain the oid rather than hard-coding it.
# We do this because these samples are used in our quality control system and run repeatedly.
# Insert a sample item
item_id = insert_sample_item
# Initialize APIs
item_api = UltracartClient::ItemApi.new_using_api_key(Constants::API_KEY)
customer_api = UltracartClient::CustomerApi.new_using_api_key(Constants::API_KEY)
# Retrieve item by merchant item ID (base object only)
base_response = item_api.get_item_by_merchant_item_id(item_id, opts = { '_expand' => nil, '_placeholders' => false })
item = base_response.item
merchant_item_oid = item.merchant_item_oid
# Possible expansion values documented in comments
# Expansion demonstrates accessing product reviews
expand_options = "reviews,reviews.individual_reviews"
# Retrieve full item details with expansions
full_response = item_api.get_item(merchant_item_oid, opts = { '_expand' => expand_options, '_placeholders' => false })
full_item = full_response.item
# Access item reviews
item_reviews = full_item.reviews
individual_reviews = item_reviews.individual_reviews
# Iterate through individual reviews
individual_reviews.each do |individual_review|
# Access rating names and scores (configurable by merchant)
rating_name = individual_review.get_rating_name1
rating_score = individual_review.get_rating_score1
# Retrieve reviewer information (cautiously to avoid API call limits)
customer_response = customer_api.get_customer(
individual_review.customer_profile_oid,
opts = { '_expand' => "reviewer" }
)
customer = customer_response.customer
reviewer = customer.reviewer
end
# Output the retrieved item
puts 'The following item was retrieved via getItem():'
p full_item
# Clean up sample item
delete_sample_item(merchant_item_oid)
rescue UltracartClient::ApiException => e
puts 'An ApiException occurred. Please review the following error:'
p e # change_me: handle gracefully
exit 1
end
import {itemApi} from '../api';
import {customerApi} from '../api';
import {
Item,
ItemResponse,
ItemReview,
ItemReviews,
Customer,
CustomerResponse,
CustomerReviewer
} from 'ultracart_rest_api_v2_typescript';
import {ItemFunctions} from './ItemFunctions'; // Assuming ItemFunctions is in a separate file
export class GetItem {
/// <summary>
/// Execute the item retrieval example
/// </summary>
public static async execute(): Promise<void> {
try {
const itemOid: number = await ItemFunctions.insertSampleItemAndGetOid();
// Yes, I'm creating an item, getting that item in order to get the item id, then getting the item yet again
// using a different method. All to illustrate GetItemByMerchantItemId
const itemId: string | undefined = (await itemApi.getItem({merchantItemOid: itemOid}))?.item?.merchant_item_id;
if (itemId === undefined) {
console.error("itemId should not be undefined. Something went wrong with sample item creation most likely.");
return;
}
// the expand variable is undefined in the following call. we just need the base object this time.
const apiResponse: ItemResponse = await itemApi.getItemByMerchantItemId({
merchantItemId: itemId,
expand: undefined,
placeholders: false
});
const item: Item | undefined = apiResponse.item; // assuming this succeeded
const merchantItemOid: number = item?.merchant_item_oid || 0;
if (merchantItemOid === 0) {
console.error("getItemByMerchantItemId failed.");
return;
}
// This is the actual call for this script.
// The real devil in the getItem calls is the expansion, making sure you return everything you need without
// returning everything since these objects are extremely large.
// These are the possible expansion values.
/*
accounting
amember
auto_order
auto_order.steps
ccbill
channel_partner_mappings
chargeback
checkout
content
content.assignments
content.attributes
content.multimedia
content.multimedia.thumbnails
digital_delivery
ebay
email_notifications
enrollment123
gift_certificate
google_product_search
kit_definition
identifiers
instant_payment_notifications
internal
options
payment_processing
physical
pricing
pricing.tiers
realtime_pricing
related
reporting
restriction
reviews
reviews.individual_reviews
salesforce
shipping
shipping.cases
shipping.destination_markups
shipping.destination_restrictions
shipping.distribution_centers
shipping.methods
shipping.package_requirements
tax
third_party_email_marketing
variations
wishlist_member
*/
// const expand = "kit_definition,options,shipping,tax,variations"; // just some random ones. contact us if you're unsure
const expand = "reviews,reviews.individual_reviews"; // changed the random above to reviews to illustrate accessing product reviews.
const apiResponse2: ItemResponse = await itemApi.getItem({
merchantItemOid: merchantItemOid,
expand: expand,
placeholders: false
});
const itemWithReviews: Item | undefined = apiResponse2.item;
const itemReviews: ItemReviews | undefined = itemWithReviews?.reviews;
const individualReviews: ItemReview[] | undefined = itemReviews?.individual_reviews;
if (individualReviews !== undefined) {
// do whatever you wish with the reviews. iterate them, print them, etc.
// if you need the reviewer information
for (const individualReview of individualReviews) {
// if you need reviewer profile questions, such as "How often do you use this product?", access the
// rating names and scores. these are configurable by merchant, so we do not know what your questions may be.
// See Home -> Configuration -> Items -> Reviews -> Settings
// Or this URL: https://secure.ultracart.com/merchant/item/review/reviewSettingsLoad.do
const ratingName1: string | undefined = individualReview.rating_name1; // <-- this will not be the full question, but a key string.
const ratingScore1: number | undefined = individualReview.rating_score1;
// if you need the review information, access that via their customer object. Be careful. This can result
// in a LOT of API calls and exhaust your limit. You may wish to add 'Sleep' calls to your loop and cache
// these results daily or weekly.
if (individualReview.customer_profile_oid !== undefined) {
const customerResponse: CustomerResponse = await customerApi.getCustomer({
customerProfileOid: individualReview.customer_profile_oid,
expand: "reviewer"
});
const customer: Customer | undefined = customerResponse.customer;
const reviewer: CustomerReviewer | undefined = customer?.reviewer;
}
}
}
console.log("The following item was retrieved via getItem():");
console.log(itemWithReviews);
await ItemFunctions.deleteSampleItemByOid(itemOid);
} catch (e) {
console.log("An ApiException occurred. Please review the following error:");
console.log(e); // <-- change_me: handle gracefully
throw e; // Equivalent to Environment.Exit(1), but better suited for async context
}
}
}
Update a new item on the UltraCart account.
SDK Function Name: updateItem
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 |
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;
using System;
using com.ultracart.admin.v2.Client;
namespace SdkSample.item
{
public class UpdateItem
{
public static void Execute()
{
try
{
string itemId = ItemFunctions.InsertSampleItem();
ItemApi itemApi = new ItemApi(Constants.ApiKey);
// See one of the getItem or getItems samples for possible expansion values
// See also: https://www.ultracart.com/api/#resource_item.html
string expand = "pricing";
ItemResponse apiResponse = itemApi.GetItemByMerchantItemId(itemId, expand, false);
Item item = apiResponse.Item;
decimal originalPrice = item.Pricing.Cost;
// update the price of the item.
ItemPricing itemPricing = item.Pricing;
itemPricing.Cost = 12.99m;
apiResponse = itemApi.UpdateItem(item.MerchantItemOid, item, expand, false);
Item updatedItem = apiResponse.Item;
// ensure the price was updated.
Console.WriteLine("Original Price: " + originalPrice);
Console.WriteLine("Updated Price: " + updatedItem.Pricing.Cost);
ItemFunctions.DeleteSampleItem(itemId);
}
catch (ApiException e)
{
Console.WriteLine("An ApiException occurred. Please review the following error:");
Console.WriteLine(e); // <-- change_me: handle gracefully
Environment.Exit(1);
}
}
}
}
package item;
import com.ultracart.admin.v2.ItemApi;
import com.ultracart.admin.v2.models.Item;
import com.ultracart.admin.v2.models.ItemPricing;
import com.ultracart.admin.v2.models.ItemResponse;
import com.ultracart.admin.v2.util.ApiException;
import common.Constants;
import java.math.BigDecimal;
public class UpdateItem {
public static void execute() {
try {
String itemId = ItemFunctions.insertSampleItem();
ItemApi itemApi = new ItemApi(Constants.API_KEY);
// See one of the getItem or getItems samples for possible expansion values
// See also: https://www.ultracart.com/api/#resource_item.html
String expand = "pricing";
ItemResponse apiResponse = itemApi.getItemByMerchantItemId(itemId, expand, false);
Item item = apiResponse.getItem();
BigDecimal originalPrice = item.getPricing().getCost();
// update the price of the item.
ItemPricing itemPricing = item.getPricing();
itemPricing.setCost(BigDecimal.valueOf(12.99));
apiResponse = itemApi.updateItem(item.getMerchantItemOid(), item, expand, false);
Item updatedItem = apiResponse.getItem();
// ensure the price was updated.
System.out.println("Original Price: " + originalPrice);
System.out.println("Updated Price: " + updatedItem.getPricing().getCost());
ItemFunctions.deleteSampleItem(itemId);
}
catch (ApiException e) {
System.out.println("An ApiException occurred. Please review the following error:");
System.out.println(e); // <-- change_me: handle gracefully
System.exit(1);
}
}
}
import {itemApi} from '../api.js';
import {ItemFunctions} from './itemFunctions.js';
export class UpdateItem {
/**
* Updates an item by:
* 1. Inserting a sample item
* 2. Retrieving the item with pricing expansion
* 3. Updating the item's cost
* 4. Verifying the price update
* 5. Deleting the sample item
*
* See https://www.ultracart.com/api/#resource_item.html for possible expansion values
*/
static async execute() {
try {
// Insert a sample item and get its merchant item ID
const itemId = await ItemFunctions.insertSampleItem();
// Define expansion parameter
const expand = "pricing";
// Retrieve the item by merchant item ID
const apiResponse = await new Promise((resolve, reject) => {
itemApi.getItemByMerchantItemId(itemId,
{_expand: expand}, function (error, data, response) {
if (error) {
reject(error);
} else {
resolve(data);
}
});
});
const item = apiResponse.item;
if (item === undefined || item.merchant_item_oid === undefined) {
console.error("Unable to retrieve item for update");
return;
}
// Ensure the item exists
if (!item || !item.pricing) {
throw new Error('Item or pricing information not found');
}
// Store the original price
const originalPrice = item.pricing.cost ?? 0;
// Update the item's pricing
const itemPricing = item.pricing;
itemPricing.cost = 12.99;
// Update the item
const updatedApiResponse = await new Promise((resolve, reject) => {
itemApi.updateItem(
item.merchant_item_oid,
item,
{_expand: expand}, function (error, data, response) {
if (error) {
reject(error);
} else {
resolve(data);
}
});
});
const updatedItem = updatedApiResponse.item;
// Verify the price update
if (!updatedItem?.pricing) {
throw new Error('Updated item or pricing information not found');
}
console.log(`Original Price: ${originalPrice}`);
console.log(`Updated Price: ${updatedItem.pricing.cost}`);
// Delete the sample item
await ItemFunctions.deleteSampleItem(itemId);
} catch (error) {
console.error("An error occurred while updating the item:", error);
process.exit(1);
}
}
}
<?php
/** @noinspection SpellCheckingInspection */
/** @noinspection GrazieInspection */
use ultracart\v2\ApiException;
require_once '../vendor/autoload.php';
require_once '../samples.php';
require_once './item_functions.php'; // <-- see this file for details
try {
$item_id = insertSampleItem();
$item_api = Samples::getItemApi();
// See one of the getItem or getItems samples for possible expansion values
// See also: https://www.ultracart.com/api/#resource_item.html
$expand = "pricing";
$api_response = $item_api->getItemByMerchantItemId($item_id, $expand, false);
$item = $api_response->getItem();
$original_price = $item->getPricing()->getCost();
// update the price of the item.
$item_pricing = $item->getPricing();
$item_pricing->setCost(12.99);
$api_response = $item_api->updateItem($item->getMerchantItemOid(), $item, $expand, false);
$updated_item = $api_response->getItem();
// ensure the price was updated.
echo 'Original Price: ' . $original_price;
echo 'Updated Price: ' . $updated_item->getPricing()->getCost();
deleteSampleItem($item_id);
} catch (ApiException $e) {
echo 'An ApiException occurred. Please review the following error:';
var_dump($e); // <-- change_me: handle gracefully
die(1);
}
from flask import Flask
from ultracart import ApiException
from ultracart.apis import ItemApi
from samples import api_client
from item_functions import insert_sample_item, delete_sample_item
app = Flask(__name__)
@app.route('/update_item')
def update_item():
try:
# Insert a sample item
item_id = insert_sample_item()
# Create Item API client
item_api = ItemApi(api_client())
# Expand pricing information
expand = "pricing"
# Get the item by merchant item ID
api_response = item_api.get_item_by_merchant_item_id(item_id, expand=expand, _expand=False)
item = api_response.get_item()
# Store original price
original_price = item.get_pricing().get_cost()
# Update the item's price
item_pricing = item.get_pricing()
item_pricing.set_cost(12.99)
# Update the item
api_response = item_api.update_item(item.get_merchant_item_oid(), item, expand=expand, _expand=False)
updated_item = api_response.get_item()
# Print price changes
print(f'Original Price: {original_price}')
print(f'Updated Price: {updated_item.get_pricing().get_cost()}')
# Delete the sample item
delete_sample_item(item_id)
return "Item update successful"
except ApiException as e:
print('An ApiException occurred. Please review the following error:')
print(e)
return "Error updating item", 500
if __name__ == '__main__':
app.run(debug=True)
#!/usr/bin/env ruby
# frozen_string_literal: true
require 'ultracart_api'
require_relative '../constants'
require_relative './item_functions'
begin
# Insert a sample item
item_id = insert_sample_item()
# Initialize the Item API
item_api = UltracartClient::ItemApi.new_using_api_key(Constants::API_KEY)
# See one of the getItem or getItems samples for possible expansion values
# See also: https://www.ultracart.com/api/#resource_item.html
opts = {
'_expand' => 'pricing',
'_placeholders' => false
}
# Retrieve the item
api_response = item_api.get_item_by_merchant_item_id(item_id, opts)
item = api_response.item
original_price = item.pricing.cost
# Update the price of the item
item_pricing = item.pricing
item_pricing.cost = 12.99
# Update the item
api_response = item_api.update_item(item.merchant_item_oid, item, opts)
updated_item = api_response.item
# Output the price changes
puts "Original Price: #{original_price}"
puts "Updated Price: #{updated_item.pricing.cost}"
# Delete the sample item
delete_sample_item(item_id)
rescue UltracartClient::ApiError => e
puts 'An ApiException occurred. Please review the following error:'
p e
exit(1)
end
import {itemApi} from '../api';
import {ItemFunctions} from './ItemFunctions';
import {
Item,
ItemResponse,
ItemPricing
} from 'ultracart_rest_api_v2_typescript';
export class UpdateItem {
/**
* Updates an item by:
* 1. Inserting a sample item
* 2. Retrieving the item with pricing expansion
* 3. Updating the item's cost
* 4. Verifying the price update
* 5. Deleting the sample item
*
* See https://www.ultracart.com/api/#resource_item.html for possible expansion values
*/
public static async execute(): Promise<void> {
try {
// Insert a sample item and get its merchant item ID
const itemId: string = await ItemFunctions.insertSampleItem();
// Define expansion parameter
const expand: string = "pricing";
// Retrieve the item by merchant item ID
const apiResponse: ItemResponse = await itemApi.getItemByMerchantItemId({
merchantItemId: itemId,
expand,
placeholders: false
});
const item: Item | undefined = apiResponse.item;
if (item === undefined || item.merchant_item_oid === undefined) {
console.error("Unable to retrieve item for update");
return;
}
// Ensure the item exists
if (!item || !item.pricing) {
throw new Error('Item or pricing information not found');
}
// Store the original price
const originalPrice: number = item.pricing.cost ?? 0;
// Update the item's pricing
const itemPricing: ItemPricing = item.pricing;
itemPricing.cost = 12.99;
// Update the item
const updatedApiResponse: ItemResponse = await itemApi.updateItem({
merchantItemOid: item.merchant_item_oid,
item,
expand,
placeholders: false
});
const updatedItem: Item | undefined = updatedApiResponse.item;
// Verify the price update
if (!updatedItem?.pricing) {
throw new Error('Updated item or pricing information not found');
}
console.log(`Original Price: ${originalPrice}`);
console.log(`Updated Price: ${updatedItem.pricing.cost}`);
// Delete the sample item
await ItemFunctions.deleteSampleItem(itemId);
} catch (error) {
console.error("An error occurred while updating the item:", error);
process.exit(1);
}
}
}
Update an item content attribute, creating it new if it does not yet exist.
SDK Function Name: insertUpdateItemContentAttribute
Parameter | Description | Location | Data Type | Required |
---|---|---|---|---|
item_attribute | Item content attribute to upsert | body | ItemContentAttribute | required |
merchant_item_oid | The item oid to modify. | path | integer (int32) | required |
using System;
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;
namespace SdkSample.item
{
public class InsertUpdateItemContentAttribute
{
public static void Execute()
{
/*
While UltraCart provides a means for updating item content, it is StoreFront specific. This method allows for
item-wide update of content, such as SEO fields. The content attribute has three fields:
1) name
2) value
3) type: boolean,color,definitionlist,html,integer,mailinglist,multiline,rgba,simplelist,string,videolist
The SEO content has the following names:
Item Meta Title = "storefrontSEOTitle"
Item Meta Description = "storefrontSEODescription"
Item Meta Keywords = "storefrontSEOKeywords"
The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your item's oid, call
ItemApi.GetItemByMerchantItemId() to retrieve the item, and then it's oid item.MerchantItemOid
Success will return back a status code of 204 (No Content)
*/
ItemApi itemApi = new ItemApi(Constants.ApiKey);
int merchantItemOid = 12345;
ItemContentAttribute attribute = new ItemContentAttribute();
attribute.Name = "storefrontSEOKeywords";
attribute.Value = "dog,cat,fish";
attribute.Type = "string";
itemApi.InsertUpdateItemContentAttribute(merchantItemOid, attribute);
}
}
}
package item;
import com.ultracart.admin.v2.ItemApi;
import com.ultracart.admin.v2.models.*;
import com.ultracart.admin.v2.util.ApiException;
import common.Constants;
public class InsertUpdateItemContentAttribute {
public static void execute() throws ApiException {
/*
While UltraCart provides a means for updating item content, it is StoreFront specific. This method allows for
item-wide update of content, such as SEO fields. The content attribute has three fields:
1) name
2) value
3) type: boolean,color,definitionlist,html,integer,mailinglist,multiline,rgba,simplelist,string,videolist
The SEO content has the following names:
Item Meta Title = "storefrontSEOTitle"
Item Meta Description = "storefrontSEODescription"
Item Meta Keywords = "storefrontSEOKeywords"
The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your item's oid, call
ItemApi.GetItemByMerchantItemId() to retrieve the item, and then it's oid item.MerchantItemOid
Success will return back a status code of 204 (No Content)
*/
ItemApi itemApi = new ItemApi(Constants.API_KEY);
int merchantItemOid = 12345;
ItemContentAttribute attribute = new ItemContentAttribute();
attribute.setName("storefrontSEOKeywords");
attribute.setValue("dog,cat,fish");
attribute.setType("string");
itemApi.insertUpdateItemContentAttribute(merchantItemOid, attribute);
}
}
import { itemApi } from '../api.js';
export class InsertUpdateItemContentAttribute {
/**
* While UltraCart provides a means for updating item content, it is StoreFront specific. This method allows for
* item-wide update of content, such as SEO fields. The content attribute has three fields:
* 1) name
* 2) value
* 3) type: boolean,color,definitionlist,html,integer,mailinglist,multiline,rgba,simplelist,string,videolist
*
* The SEO content has the following names:
* Item Meta Title = "storefrontSEOTitle"
* Item Meta Description = "storefrontSEODescription"
* Item Meta Keywords = "storefrontSEOKeywords"
*
* The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your item's oid, call
* ItemApi.GetItemByMerchantItemId() to retrieve the item, and then it's oid item.MerchantItemOid
*
* Success will return back a status code of 204 (No Content)
*/
static async execute() {
const merchantItemOid = 12345;
const attribute = {
name: "storefrontSEOKeywords",
value: "dog,cat,fish",
type: "string"
};
await new Promise((resolve, reject) => {
itemApi.insertUpdateItemContentAttribute(merchantItemOid, attribute, function (error, data, response) {
if (error) {
reject(error);
} else {
resolve(data, response);
}
});
});
}
}
<?php
ini_set('display_errors', 1);
/*
While UltraCart provides a means for updating item content, it is StoreFront specific. This method allows for
item-wide update of content, such as SEO fields. The content attribute has three fields:
1) name
2) value
3) type: boolean,color,definitionlist,html,integer,mailinglist,multiline,rgba,simplelist,string,videolist
The SEO content has the following names:
Item Meta Title = "storefrontSEOTitle"
Item Meta Description = "storefrontSEODescription"
Item Meta Keywords = "storefrontSEOKeywords"
The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your item's oid, call
ItemApi.getItemByMerchantItemId() to retrieve the item, and then it's oid $item->getMerchantItemOid()
Success will return back a status code of 204 (No Content)
*/
use ultracart\v2\api\ItemApi;
require_once '../vendor/autoload.php';
require_once '../constants.php';
$item_api = ItemApi::usingApiKey(Constants::API_KEY);
$merchant_item_oid = 12345;
$attribute = new \ultracart\v2\models\ItemContentAttribute();
$attribute->setName("storefrontSEOKeywords");
$attribute->setValue('dog,cat,fish');
$attribute->setType("string");
$item_api->insertUpdateItemContentAttribute($merchant_item_oid, $attribute);
from samples import api_client
from ultracart.apis import ItemApi
from ultracart.models import ItemContentAttribute
"""
While UltraCart provides a means for updating item content, it is StoreFront specific. This method allows for
item-wide update of content, such as SEO fields. The content attribute has three fields:
1) name
2) value
3) type: boolean,color,definitionlist,html,integer,mailinglist,multiline,rgba,simplelist,string,videolist
The SEO content has the following names:
Item Meta Title = "storefrontSEOTitle"
Item Meta Description = "storefrontSEODescription"
Item Meta Keywords = "storefrontSEOKeywords"
The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your item's oid, call
ItemApi.getItemByMerchantItemId() to retrieve the item, and then it's oid $item->getMerchantItemOid()
Success will return back a status code of 204 (No Content)
"""
# Initialize Item API
item_api = ItemApi(api_client())
# Specify the merchant item OID
merchant_item_oid = 12345
# Create content attribute
attribute = ItemContentAttribute(
name="storefrontSEOKeywords",
value='dog,cat,fish',
type="string"
)
# Insert or update the content attribute
item_api.insert_update_item_content_attribute(merchant_item_oid, attribute)
#!/usr/bin/env ruby
# frozen_string_literal: true
require 'ultracart_api'
require_relative '../constants'
=begin
While UltraCart provides a means for updating item content, it is StoreFront specific. This method allows for
item-wide update of content, such as SEO fields. The content attribute has three fields:
1) name
2) value
3) type: boolean,color,definitionlist,html,integer,mailinglist,multiline,rgba,simplelist,string,videolist
The SEO content has the following names:
Item Meta Title = "storefrontSEOTitle"
Item Meta Description = "storefrontSEODescription"
Item Meta Keywords = "storefrontSEOKeywords"
The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your item's oid, call
ItemApi.getItemByMerchantItemId() to retrieve the item, and then it's oid $item->getMerchantItemOid()
Success will return back a status code of 204 (No Content)
=end
# Initialize the Item API
item_api = UltracartClient::ItemApi.new_using_api_key(Constants::API_KEY)
merchant_item_oid = 12345
# Create the content attribute
attribute = UltracartClient::ItemContentAttribute.new(
name: "storefrontSEOKeywords",
value: 'dog,cat,fish',
type: "string"
)
# Insert or update the item content attribute
item_api.insert_update_item_content_attribute(merchant_item_oid, attribute)
import { itemApi } from '../api';
import { ItemContentAttribute } from 'ultracart_rest_api_v2_typescript';
export class InsertUpdateItemContentAttribute {
/**
* While UltraCart provides a means for updating item content, it is StoreFront specific. This method allows for
* item-wide update of content, such as SEO fields. The content attribute has three fields:
* 1) name
* 2) value
* 3) type: boolean,color,definitionlist,html,integer,mailinglist,multiline,rgba,simplelist,string,videolist
*
* The SEO content has the following names:
* Item Meta Title = "storefrontSEOTitle"
* Item Meta Description = "storefrontSEODescription"
* Item Meta Keywords = "storefrontSEOKeywords"
*
* The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your item's oid, call
* ItemApi.GetItemByMerchantItemId() to retrieve the item, and then it's oid item.MerchantItemOid
*
* Success will return back a status code of 204 (No Content)
*/
public static async execute(): Promise<void> {
const merchantItemOid: number = 12345;
const attribute: ItemContentAttribute = {
name: "storefrontSEOKeywords",
value: "dog,cat,fish",
type: "string"
};
await itemApi.insertUpdateItemContentAttribute({merchantItemOid, itemAttribute:attribute});
}
}
Retrieve item reviews.
SDK Function Name: getReviews
Parameter | Description | Location | Data Type | Required |
---|---|---|---|---|
merchant_item_oid | The item oid the review is associated with. | path | integer (int32) | required |
using System;
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;
using System.Collections.Generic;
namespace SdkSample.item
{
public class GetReviews
{
/// <summary>
/// Execute method containing all business logic
/// </summary>
public static void Execute()
{
/*
* Retrieves all user reviews for an item.
*
* The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your item's oid, call
* ItemApi.GetItemByMerchantItemId() to retrieve the item, and then it's oid item.MerchantItemOid
*/
ItemApi itemApi = new ItemApi(Constants.ApiKey);
int merchantItemOid = 123456;
ItemReviewsResponse apiResponse = itemApi.GetReviews(merchantItemOid);
if (apiResponse.Error != null)
{
Console.Error.WriteLine(apiResponse.Error.DeveloperMessage);
Console.Error.WriteLine(apiResponse.Error.UserMessage);
Environment.Exit(1);
}
List<ItemReview> reviews = apiResponse.Reviews;
foreach (ItemReview review in reviews)
{
Console.WriteLine(review.ToString());
}
}
}
}
package item;
import com.ultracart.admin.v2.ItemApi;
import com.ultracart.admin.v2.models.*;
import com.ultracart.admin.v2.util.ApiException;
import common.Constants;
import java.util.List;
public class GetReviews {
/// <summary>
/// Execute method containing all business logic
/// </summary>
public static void execute() throws ApiException {
/*
* Retrieves all user reviews for an item.
*
* The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your item's oid, call
* ItemApi.GetItemByMerchantItemId() to retrieve the item, and then it's oid item.MerchantItemOid
*/
ItemApi itemApi = new ItemApi(Constants.API_KEY);
int merchantItemOid = 123456;
ItemReviewsResponse apiResponse = itemApi.getReviews(merchantItemOid);
if (apiResponse.getError() != null) {
System.err.println(apiResponse.getError().getDeveloperMessage());
System.err.println(apiResponse.getError().getUserMessage());
System.exit(1);
}
List<ItemReview> reviews = apiResponse.getReviews();
for (ItemReview review : reviews) {
System.out.println(review.toString());
}
}
}
import { itemApi } from '../api.js';
/**
* Execute method containing all business logic
*/
export async function execute() {
/*
* Retrieves all user reviews for an item.
*
* The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your item's oid, call
* ItemApi.GetItemByMerchantItemId() to retrieve the item, and then it's oid item.MerchantItemOid
*/
const merchantItemOid = 123456;
try {
const apiResponse = await new Promise((resolve, reject) => {
itemApi.getReviews(merchantItemOid, function (error, data, response) {
if (error) reject(error);
else resolve(data, response);
});
});
if (apiResponse.error) {
console.error(apiResponse.error.developer_message);
console.error(apiResponse.error.user_message);
process.exit(1);
}
const reviews = apiResponse.reviews || [];
reviews.forEach((review) => {
console.log(review ? review.toString() : undefined); // Handle toString() in JS
});
} catch (error) {
console.error("An error occurred while fetching reviews:", error);
process.exit(1);
}
}
<?php
use ultracart\v2\api\ItemApi;
ini_set('display_errors', 1);
/*
Retrieves all user reviews for an item.
The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your item's oid, call
ItemApi.getItemByMerchantItemId() to retrieve the item, and then it's oid $item->getMerchantItemOid()
*/
require_once '../vendor/autoload.php';
require_once '../constants.php';
$item_api = ItemApi::usingApiKey(Constants::API_KEY);
$merchant_item_oid = 123456;
$api_response = $item_api->getReviews($merchant_item_oid);
if ($api_response->getError() != null) {
error_log($api_response->getError()->getDeveloperMessage());
error_log($api_response->getError()->getUserMessage());
exit();
}
$reviews = $api_response->getReviews();
echo '<html lang="en"><body><pre>';
foreach ($reviews as $review) {
var_dump($review);
}
echo '</pre></body></html>';
from samples import api_client
from ultracart.apis import ItemApi
"""
Retrieves all user reviews for an item.
The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your item's oid, call
ItemApi.getItemByMerchantItemId() to retrieve the item, and then it's oid $item->getMerchantItemOid()
"""
# Initialize the Item API
item_api = ItemApi(api_client())
# Specify the merchant item OID
merchant_item_oid = 123456
# Retrieve reviews
api_response = item_api.get_item_reviews(merchant_item_oid)
# Check for errors
if api_response.error is not None:
print(f"Developer Message: {api_response.error.developer_message}")
print(f"User Message: {api_response.error.user_message}")
exit()
# Process and print reviews
reviews = api_response.reviews
for review in reviews:
print(review)
require 'ultracart_api'
require_relative '../constants'
=begin
Retrieves all user reviews for an item.
The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your item's oid, call
ItemApi.get_item_by_merchant_item_id() to retrieve the item, and then its oid item.merchant_item_oid
=end
# Initialize the item API
item_api = UltracartClient::ItemApi.new_using_api_key(Constants::API_KEY)
# Set merchant item OID
merchant_item_oid = 123456
begin
# Get reviews for the specified merchant item
api_response = item_api.get_reviews(merchant_item_oid)
# Check for errors
if api_response.error
warn api_response.error.developer_message
warn api_response.error.user_message
exit
end
# Print each review
api_response.reviews.each do |review|
p review
end
rescue UltracartClient::ApiError => e
warn "API Error: #{e.message}"
exit(1)
end
import { itemApi } from '../api';
import {
ItemReviewsResponse,
ItemReview
} from 'ultracart_rest_api_v2_typescript';
/**
* Execute method containing all business logic
*/
export async function execute(): Promise<void> {
/*
* Retrieves all user reviews for an item.
*
* The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your item's oid, call
* ItemApi.GetItemByMerchantItemId() to retrieve the item, and then it's oid item.MerchantItemOid
*/
const merchantItemOid: number = 123456;
try {
const apiResponse: ItemReviewsResponse = await itemApi.getReviews({merchantItemOid});
if (apiResponse.error) {
console.error(apiResponse.error.developer_message);
console.error(apiResponse.error.user_message);
process.exit(1);
}
const reviews: ItemReview[] = apiResponse.reviews || [];
reviews.forEach((review: ItemReview) => {
console.log(review.toString());
});
} catch (error) {
console.error("An error occurred while fetching reviews:", error);
process.exit(1);
}
}
Insert a item review.
SDK Function Name: insertReview
Parameter | Description | Location | Data Type | Required |
---|---|---|---|---|
review | Review to insert | body | ItemReview | required |
merchant_item_oid | The item oid the review is associated with. | path | integer (int32) | required |
using System;
using System.Collections.Generic;
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;
namespace SdkSample.item
{
/// <summary>
/// Sample code for inserting a product review
/// </summary>
public class InsertReview
{
public static void Execute()
{
try
{
// To insert a review, you'll need an item's OID (Object Identifier) first. So for this example, we create
// a sample item first, then retrieve it by item id to fetch the item oid.
Console.WriteLine("<pre>");
string itemId = ItemFunctions.InsertSampleItem();
Console.WriteLine("</pre>");
ItemApi itemApi = Samples.GetItemApi(); // convenience function for getting an api handle.
string expand = "reviews"; // expand string is 'reviews' because we'll need to update the sample item's review template below.
// list of expansions for item object: https://www.ultracart.com/api/#resource_item.html
ItemResponse itemResponse = itemApi.GetItemByMerchantItemId(itemId, expand, null);
Item item = itemResponse.Item;
int itemOid = item.MerchantItemOid;
// The target item must have a review template associated before you may attach a review.
// You may create a review template here:
// https://secure.ultracart.com/merchant/item/review/reviewTemplateListLoad.do
// We're using a review template from our development system and it will not work for you.
// Once you have a review template, update your item either via our gui or the rest api.
// GUI: secure.ultracart.com -> Home -> Items -> <your item> -> Edit -> Review tab
// Since we're using a sample item we just created above (line 17), we'll update via the rest api.
// The rest api requires the review template oid, which is found on the template screen (url on line 25 above)
int reviewTemplateOid = 402;
ItemReviews reviews = new ItemReviews();
reviews.ReviewTemplateOid = reviewTemplateOid;
item.Reviews = reviews;
item = itemApi.UpdateItem(itemOid, item, expand, null).Item;
// You will need to know what your product review looks like.
ItemReview review = new ItemReview();
review.Title = "Best Product Ever!";
review.Review = "I loved this product. I bought it for my wife and she was so happy she cried. blah blah blah";
review.ReviewedNickname = "Bob420";
review.Featured = true; // featured? sure. why not? this is a great review.
review.RatingName1 = "Durability";
review.RatingName2 = "Price";
review.RatingName3 = "Performance";
review.RatingName4 = "Appearance";
review.RatingScore1 = 4.5m;
review.RatingScore2 = 3.5m;
review.RatingScore3 = 2.5m;
review.RatingScore4 = 1.5m;
review.Overall = 5.0m; // hooray!
review.ReviewerLocation = "Southside Chicago";
review.Status = ItemReview.StatusEnum.Approved;
// insert the review and update our local variable to see how the review looks now.
review = itemApi.InsertReview(itemOid, review).Review;
Console.WriteLine("<br>This is my review object:<br><pre>");
Console.WriteLine(review.ToString());
Console.WriteLine("</pre>");
// This will clean up the sample item, but you may wish to review the item in the backend or on your website first.
// DeleteSampleItem(itemId);
}
catch (Exception e)
{
Console.WriteLine("An Exception occurred. Please review the following error:");
Console.WriteLine(e.ToString()); // handle gracefully
Environment.Exit(1);
}
}
}
}
package item;
import com.ultracart.admin.v2.ItemApi;
import com.ultracart.admin.v2.models.*;
import common.Constants;
import java.math.BigDecimal;
/// <summary>
/// Sample code for inserting a product review
/// </summary>
public class InsertReview {
public static void execute() {
try {
// To insert a review, you'll need an item's OID (Object Identifier) first. So for this example, we create
// a sample item first, then retrieve it by item id to fetch the item oid.
System.out.println("<pre>");
String itemId = ItemFunctions.insertSampleItem();
System.out.println("</pre>");
ItemApi itemApi = new ItemApi(Constants.API_KEY);
String expand = "reviews"; // expand string is 'reviews' because we'll need to update the sample item's review template below.
// list of expansions for item object: https://www.ultracart.com/api/#resource_item.html
ItemResponse itemResponse = itemApi.getItemByMerchantItemId(itemId, expand, null);
Item item = itemResponse.getItem();
int itemOid = item.getMerchantItemOid();
// The target item must have a review template associated before you may attach a review.
// You may create a review template here:
// https://secure.ultracart.com/merchant/item/review/reviewTemplateListLoad.do
// We're using a review template from our development system and it will not work for you.
// Once you have a review template, update your item either via our gui or the rest api.
// GUI: secure.ultracart.com -> Home -> Items -> <your item> -> Edit -> Review tab
// Since we're using a sample item we just created above (line 17), we'll update via the rest api.
// The rest api requires the review template oid, which is found on the template screen (url on line 25 above)
int reviewTemplateOid = 402;
ItemReviews reviews = new ItemReviews();
reviews.setReviewTemplateOid(reviewTemplateOid);
item.setReviews(reviews);
item = itemApi.updateItem(itemOid, item, expand, null).getItem();
// You will need to know what your product review looks like.
ItemReview review = new ItemReview();
review.setTitle("Best Product Ever!");
review.setReview("I loved this product. I bought it for my wife and she was so happy she cried. blah blah blah");
review.setReviewedNickname("Bob420");
review.setFeatured(true); // featured? sure. why not? this is a great review.
review.setRatingName1("Durability");
review.setRatingName2("Price");
review.setRatingName3("Performance");
review.setRatingName4("Appearance");
review.setRatingScore1(new BigDecimal("4.5"));
review.setRatingScore2(new BigDecimal("3.5"));
review.setRatingScore3(new BigDecimal("2.5"));
review.setRatingScore4(new BigDecimal("1.5"));
review.setOverall(new BigDecimal("5.0")); // hooray!
review.setReviewerLocation("Southside Chicago");
review.setStatus(ItemReview.StatusEnum.APPROVED);
// insert the review and update our local variable to see how the review looks now.
review = itemApi.insertReview(itemOid, review).getReview();
System.out.println("<br>This is my review object:<br><pre>");
System.out.println(review.toString());
System.out.println("</pre>");
// This will clean up the sample item, but you may wish to review the item in the backend or on your website first.
// ItemFunctions.deleteSampleItem(itemId);
}
catch (Exception e) {
System.out.println("An Exception occurred. Please review the following error:");
System.out.println(e.toString()); // handle gracefully
System.exit(1);
}
}
}
import {itemApi} from '../api.js';
import {ItemFunctions} from './itemFunctions.js';
/**
* Sample code for inserting a product review
*/
export async function execute() {
try {
// To insert a review, you'll need an item's OID (Object Identifier) first. So for this example, we create
// a sample item first, then retrieve it by item id to fetch the item oid.
const itemId = await ItemFunctions.insertSampleItem();
const expand = "reviews"; // expand string is 'reviews' because we'll need to update the sample item's review template below.
// list of expansions for item object: https://www.ultracart.com/api/#resource_item.html
const itemResponse = await new Promise((resolve, reject) => {
itemApi.getItemByMerchantItemId(itemId, {_expand: expand}, function (error, data, response) {
if (error) {
reject(error);
} else {
resolve(data, response);
}
});
});
const item = itemResponse.item;
if (!item) {
throw new Error("Unable to retrieve item");
}
const itemOid = item.merchant_item_oid || 0; // TODO: In a real script, add logic for undefined.
// The target item must have a review template associated before you may attach a review.
// You may create a review template here:
// https://secure.ultracart.com/merchant/item/review/reviewTemplateListLoad.do
// We're using a review template from our development system and it will not work for you.
// Once you have a review template, update your item either via our gui or the rest api.
// GUI: secure.ultracart.com -> Home -> Items -> <your item> -> Edit -> Review tab
// Since we're using a sample item we just created above (line 17), we'll update via the rest api.
// The rest api requires the review template oid, which is found on the template screen (url on line 25 above)
const reviewTemplateOid = 402;
const reviews = {review_template_oid: reviewTemplateOid};
item.reviews = reviews;
const updatedItemResponse = await new Promise((resolve, reject) => {
itemApi.updateItem(
itemOid,
item,
{_expand: expand}, function (error, data, response) {
if (error) {
reject(error);
} else {
resolve(data, response);
}
});
});
const updatedItemMaybe = updatedItemResponse.item;
// You will need to know what your product review looks like.
const review = {
title: "Best Product Ever!",
review: "I loved this product. I bought it for my wife and she was so happy she cried. blah blah blah",
reviewed_nickname: "Bob420",
featured: true, // featured? sure. why not? this is a great review.
rating_name1: "Durability",
rating_name2: "Price",
rating_name3: "Performance",
rating_name4: "Appearance",
rating_score1: 4.5,
rating_score2: 3.5,
rating_score3: 2.5,
rating_score4: 1.5,
overall: 5.0, // hooray!
reviewer_location: "Southside Chicago",
status: "Approved"
};
// insert the review and update our local variable to see how the review looks now.
const insertedReviewResponse = await new Promise((resolve, reject) => {
itemApi.insertReview(itemOid, review, function (error, data, response) {
if (error) {
reject(error);
} else {
resolve(data, response);
}
});
});
const insertedReview = insertedReviewResponse.review;
console.log("This is my review object:");
console.log(insertedReview?.toString());
// This will clean up the sample item, but you may wish to review the item in the backend or on your website first.
// await ItemFunctions.deleteSampleItem(itemId);
} catch (error) {
console.error("An Exception occurred. Please review the following error:");
console.error(error); // handle gracefully
process.exit(1);
}
}
<?php
/** @noinspection SpellCheckingInspection */
/** @noinspection GrazieInspection */
use ultracart\v2\ApiException;
require_once '../vendor/autoload.php';
require_once '../samples.php';
require_once './item_functions.php'; // <-- see this file for details
try {
// To insert a review, you'll need an item's OID (Object Identifier) first. So for this example, we create
// a sample item first, then retrieve it by item id to fetch the item oid.
echo '<pre>';
$item_id = insertSampleItem();
echo '</pre>';
$item_api = Samples::getItemApi(); // convenience fuction for getting an api handle.
$expand = 'reviews'; // expand string is 'reviews' because we'll need to update the sample item's review template below.
// list of expansions for item object: https://www.ultracart.com/api/#resource_item.html
$item_response = $item_api->getItemByMerchantItemId($item_id, $expand, null);
$item = $item_response->getItem();
$item_oid = $item->getMerchantItemOid();
// The target item must have a review template associated before you may attach a review.
// You may create a review template here:
// https://secure.ultracart.com/merchant/item/review/reviewTemplateListLoad.do
// We're using a review template from our development system and it will not work for you.
// Once you have a review template, update your item either via our gui or the rest api.
// GUI: secure.ultracart.com -> Home -> Items -> <your item> -> Edit -> Review tab
// Since we're using a sample item we just created above (line 17), we'll update via the rest api.
// The rest api requires the review template oid, which is found on the template screen (url on line 25 above)
$review_template_oid = 402;
$reviews = new ultracart\v2\models\ItemReviews();
$reviews->setReviewTemplateOid($review_template_oid);
$item->setReviews($reviews);
$item = $item_api->updateItem($item_oid, $item, $expand, null)->getItem();
// You will need to know what your product review looks like.
$review = new ultracart\v2\models\ItemReview();
$review->setTitle('Best Product Ever!');
$review->setReview("I loved this product. I bought it for my wife and she was so happy she cried. blah blah blah");
$review->setReviewedNickname("Bob420");
$review->setFeatured(true); // featured? sure. why not? this is a great review.
$review->setRatingName1('Durability');
$review->setRatingName2('Price');
$review->setRatingName3('Performance');
$review->setRatingName4('Appearance');
$review->setRatingScore1(4.5);
$review->setRatingScore2(3.5);
$review->setRatingScore3(2.5);
$review->setRatingScore4(1.5);
$review->setOverall(5.0); // hooray!
$review->setReviewerLocation("Southside Chicago");
$review->setStatus('approved');
// insert the review and update our local variable to see how the review looks now.
$review = $item_api->insertReview($item_oid, $review)->getReview();
echo '<br>This is my review object:<br><pre>';
var_dump($review);
echo '</pre>';
// This will clean up the sample item, but you may wish to review the item in the backend or on your website first.
// deleteSampleItem($item_id);
} catch (ApiException $e) {
echo 'An ApiException occurred. Please review the following error:';
var_dump($e); // <-- change_me: handle gracefully
die(1);
}
from ultracart.apis import ItemApi
from samples import api_client
from item_functions import insert_sample_item
from ultracart.exceptions import ApiException
from ultracart.models import ItemReviews, ItemReview
try:
# Create a sample item
item_id = insert_sample_item()
# Initialize Item API
item_api = ItemApi(api_client())
# Expand reviews to update item with review template
expand = 'reviews'
# Retrieve item by merchant item ID
item_response = item_api.get_item_by_merchant_item_id(item_id, expand=expand)
item = item_response.item
item_oid = item.merchant_item_oid
# Set review template
review_template_oid = 402
reviews = ItemReviews()
reviews.review_template_oid = review_template_oid
item.reviews = reviews
# Update item with review template
item = item_api.update_item(item_oid, item, expand=expand).item
# Create a new review
review = ItemReview(
title='Best Product Ever!',
review="I loved this product. I bought it for my wife and she was so happy she cried. blah blah blah",
reviewed_nickname="Bob420",
featured=True,
rating_name1='Durability',
rating_name2='Price',
rating_name3='Performance',
rating_name4='Appearance',
rating_score1=4.5,
rating_score2=3.5,
rating_score3=2.5,
rating_score4=1.5,
overall=5.0,
reviewer_location="Southside Chicago",
status='approved'
)
# Insert the review
review = item_api.insert_review(item_oid, review).review
# Print the review
print("Inserted Review:")
print(review)
except ApiException as e:
print('An ApiException occurred. Please review the following error:')
print(e)
exit(1)
#!/usr/bin/env ruby
# frozen_string_literal: true
require 'ultracart_api'
require_relative '../constants'
require_relative './item_functions'
begin
# To insert a review, you'll need an item's OID (Object Identifier) first. So for this example, we create
# a sample item first, then retrieve it by item id to fetch the item oid.
item_id = insert_sample_item()
# Initialize the Item API
item_api = UltracartClient::ItemApi.new_using_api_key(Constants::API_KEY)
# Expand string is 'reviews' because we'll need to update the sample item's review template below.
# List of expansions for item object: https://www.ultracart.com/api/#resource_item.html
opts = {
'_expand' => 'reviews'
}
# Retrieve the item by merchant item ID
item_response = item_api.get_item_by_merchant_item_id(item_id, opts)
item = item_response.item
item_oid = item.merchant_item_oid
# The target item must have a review template associated before you may attach a review.
# You may create a review template here:
# https://secure.ultracart.com/merchant/item/review/reviewTemplateListLoad.do
# We're using a review template from our development system and it will not work for you.
# Once you have a review template, update your item either via our gui or the rest api.
# GUI: secure.ultracart.com -> Home -> Items -> <your item> -> Edit -> Review tab
# Since we're using a sample item we just created above, we'll update via the rest api.
# The rest api requires the review template oid, which is found on the template screen
review_template_oid = 402
reviews = UltracartClient::ItemReviews.new(review_template_oid: review_template_oid)
item.reviews = reviews
item = item_api.update_item(item_oid, item, opts).item
# You will need to know what your product review looks like.
review = UltracartClient::ItemReview.new(
title: 'Best Product Ever!',
review: "I loved this product. I bought it for my wife and she was so happy she cried. blah blah blah",
reviewed_nickname: "Bob420",
featured: true, # featured? sure. why not? this is a great review.
rating_name1: 'Durability',
rating_name2: 'Price',
rating_name3: 'Performance',
rating_name4: 'Appearance',
rating_score1: 4.5,
rating_score2: 3.5,
rating_score3: 2.5,
rating_score4: 1.5,
overall: 5.0, # hooray!
reviewer_location: "Southside Chicago",
status: 'approved'
)
# Insert the review and update our local variable to see how the review looks now.
review = item_api.insert_review(item_oid, review).review
# Output the review object
p review
# This will clean up the sample item, but you may wish to review the item in the backend or on your website first.
# delete_sample_item(item_id)
rescue UltracartClient::ApiError => e
puts 'An ApiException occurred. Please review the following error:'
p e
exit(1)
end
import {itemApi} from '../api';
import {
ItemResponse,
Item,
ItemReviews,
ItemReview
} from 'ultracart_rest_api_v2_typescript';
import {ItemFunctions} from './ItemFunctions';
import {ItemReviewStatusEnum} from "ultracart_rest_api_v2_typescript/src/models/ItemReview";
/**
* Sample code for inserting a product review
*/
export async function execute(): Promise<void> {
try {
// To insert a review, you'll need an item's OID (Object Identifier) first. So for this example, we create
// a sample item first, then retrieve it by item id to fetch the item oid.
const itemId: string = await ItemFunctions.insertSampleItem();
const expand: string = "reviews"; // expand string is 'reviews' because we'll need to update the sample item's review template below.
// list of expansions for item object: https://www.ultracart.com/api/#resource_item.html
const itemResponse: ItemResponse = await itemApi.getItemByMerchantItemId({merchantItemId: itemId, expand});
const item: Item | undefined = itemResponse.item;
if (!item) {
throw new Error("Unable to retrieve item");
}
const itemOid: number = item.merchant_item_oid || 0; // TODO: In a real script, add logic for undefined.
// The target item must have a review template associated before you may attach a review.
// You may create a review template here:
// https://secure.ultracart.com/merchant/item/review/reviewTemplateListLoad.do
// We're using a review template from our development system and it will not work for you.
// Once you have a review template, update your item either via our gui or the rest api.
// GUI: secure.ultracart.com -> Home -> Items -> <your item> -> Edit -> Review tab
// Since we're using a sample item we just created above (line 17), we'll update via the rest api.
// The rest api requires the review template oid, which is found on the template screen (url on line 25 above)
const reviewTemplateOid: number = 402;
const reviews: ItemReviews = {review_template_oid: reviewTemplateOid};
item.reviews = reviews;
const updatedItemResponse = await itemApi.updateItem({
merchantItemOid: itemOid,
item,
expand,
placeholders: undefined
});
const updatedItemMaybe: Item | undefined = updatedItemResponse.item;
// You will need to know what your product review looks like.
const review: ItemReview = {
title: "Best Product Ever!",
review: "I loved this product. I bought it for my wife and she was so happy she cried. blah blah blah",
reviewed_nickname: "Bob420",
featured: true, // featured? sure. why not? this is a great review.
rating_name1: "Durability",
rating_name2: "Price",
rating_name3: "Performance",
rating_name4: "Appearance",
rating_score1: 4.5,
rating_score2: 3.5,
rating_score3: 2.5,
rating_score4: 1.5,
overall: 5.0, // hooray!
reviewer_location: "Southside Chicago",
status: ItemReviewStatusEnum.Approved
};
// insert the review and update our local variable to see how the review looks now.
const insertedReviewResponse = await itemApi.insertReview({merchantItemOid: itemOid, review});
const insertedReview: ItemReview | undefined = insertedReviewResponse.review;
console.log("This is my review object:");
console.log(insertedReview?.toString());
// This will clean up the sample item, but you may wish to review the item in the backend or on your website first.
// await ItemFunctions.deleteSampleItem(itemId);
} catch (error) {
console.error("An Exception occurred. Please review the following error:");
console.error(error); // handle gracefully
process.exit(1);
}
}
Delete an item review.
SDK Function Name: deleteReview
Parameter | Description | Location | Data Type | Required |
---|---|---|---|---|
review_oid | The review oid to delete. | path | integer (int32) | required |
merchant_item_oid | The item oid the review is associated with. | path | integer (int32) | required |
using System;
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;
using SdkSample.item;
namespace SdkSample.item
{
public class DeleteReview
{
/*
Deletes a specific user review for an item. This would most likely be used by a merchant who has cached all
reviews on a separate site and then wishes to remove a particular review.
The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your item's oid, call
ItemApi.GetItemByMerchantItemId() to retrieve the item, and then it's oid item.MerchantItemOid
The review_oid is a unique identifier used by UltraCart. If you do not know a review's oid, call
ItemApi.GetReviews() to get all reviews where you can then grab the oid from an item.
Success returns back a status code of 204 (No Content)
*/
public static void Execute()
{
ItemApi itemApi = new ItemApi(Constants.ApiKey);
int merchantItemOid = 123456;
int reviewOid = 987654;
itemApi.DeleteReview(reviewOid, merchantItemOid);
}
}
}
package item;
import com.ultracart.admin.v2.ItemApi;
import com.ultracart.admin.v2.util.ApiException;
import common.Constants;
public class DeleteReview {
/**
* Deletes a specific user review for an item. Used by merchants who cache reviews
* on a separate site and wish to remove a particular review.
*
*/
public static void execute() throws ApiException {
ItemApi itemApi = new ItemApi(Constants.API_KEY);
int merchantItemOid = 123456;
int reviewOid = 987654;
itemApi.deleteReview(reviewOid, merchantItemOid);
}
}
import {itemApi} from '../api.js';
export class DeleteReview {
/*
Deletes a specific user review for an item. This would most likely be used by a merchant who has cached all
reviews on a separate site and then wishes to remove a particular review.
The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your item's oid, call
ItemApi.GetItemByMerchantItemId() to retrieve the item, and then it's oid item.MerchantItemOid
The review_oid is a unique identifier used by UltraCart. If you do not know a review's oid, call
ItemApi.GetReviews() to get all reviews where you can then grab the oid from an item.
Success returns back a status code of 204 (No Content)
*/
static async execute() {
const merchantItemOid = 123456;
const reviewOid = 987654;
const gcResponse = await new Promise((resolve, reject) => {
itemApi.deleteReview(reviewOid, merchantItemOid, function (error, data, response) {
if (error) {
reject(error);
} else {
resolve(data, response);
}
});
});
}
}
<?php
use ultracart\v2\api\ItemApi;
ini_set('display_errors', 1);
/*
Deletes a specific user review for an item. This would most likely be used by a merchant who has cached all
reviews on a separate site and then wishes to remove a particular review.
The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your item's oid, call
ItemApi.getItemByMerchantItemId() to retrieve the item, and then it's oid $item->getMerchantItemOid()
The review_oid is a unique identifier used by UltraCart. If you do not know a review's oid, call
ItemApi.getReviews() to get all reviews where you can then grab the oid from an item.
Success returns back a status code of 204 (No Content)
*/
require_once '../vendor/autoload.php';
require_once '../constants.php';
$item_api = ItemApi::usingApiKey(Constants::API_KEY);
$merchant_item_oid = 123456;
$review_oid = 987654;
$item_api->deleteReview($review_oid, $merchant_item_oid);
# Delete a specific user review for an item
#
# This would most likely be used by a merchant who has cached all
# reviews on a separate site and then wishes to remove a particular review.
#
# The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your item's oid, call
# ItemApi.get_item_by_merchant_item_id() to retrieve the item, and then get its oid
#
# The review_oid is a unique identifier used by UltraCart. If you do not know a review's oid, call
# ItemApi.get_reviews() to get all reviews where you can then grab the oid from an item.
#
# Success returns back a status code of 204 (No Content)
from ultracart.apis import ItemApi
from samples import api_client
# Create item API instance
item_api = ItemApi(api_client())
# Specify item and review OIDs
merchant_item_oid = 123456
review_oid = 987654
# Delete the review
item_api.delete_review(review_oid, merchant_item_oid)
require 'ultracart_api'
require_relative '../constants'
# Deletes a specific user review for an item. This would most likely be used by a merchant who has cached all
# reviews on a separate site and then wishes to remove a particular review.
#
# The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your item's oid, call
# ItemApi.get_item_by_merchant_item_id() to retrieve the item, and then it's oid item.merchant_item_oid
#
# The review_oid is a unique identifier used by UltraCart. If you do not know a review's oid, call
# ItemApi.get_reviews() to get all reviews where you can then grab the oid from an item.
#
# Success returns back a status code of 204 (No Content)
item_api = UltracartClient::ItemApi.new_using_api_key(Constants::API_KEY)
merchant_item_oid = 123456
review_oid = 987654
item_api.delete_review(review_oid, merchant_item_oid)
import {itemApi} from '../api';
export class DeleteReview {
/*
Deletes a specific user review for an item. This would most likely be used by a merchant who has cached all
reviews on a separate site and then wishes to remove a particular review.
The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your item's oid, call
ItemApi.GetItemByMerchantItemId() to retrieve the item, and then it's oid item.MerchantItemOid
The review_oid is a unique identifier used by UltraCart. If you do not know a review's oid, call
ItemApi.GetReviews() to get all reviews where you can then grab the oid from an item.
Success returns back a status code of 204 (No Content)
*/
public static async execute(): Promise<void> {
const merchantItemOid: number = 123456;
const reviewOid: number = 987654;
await itemApi.deleteReview({
reviewOid: reviewOid,
merchantItemOid: merchantItemOid
});
}
}
Retrieve an item review.
SDK Function Name: getReview
Parameter | Description | Location | Data Type | Required |
---|---|---|---|---|
review_oid | The review oid to retrieve. | path | integer (int32) | required |
merchant_item_oid | The item oid the review is associated with. | path | integer (int32) | required |
using System;
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;
namespace SdkSample.item
{
public class GetReview
{
/// <summary>
/// Execute method containing all business logic
/// </summary>
public static void Execute()
{
/*
* Retrieves a specific user review for an item. This would most likely be used by a merchant who has cached all
* reviews on a separate site and then wishes to update a particular review. It's always best to "get" the object,
* make changes to it, then call the update instead of trying to recreate the object from scratch.
*
* The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your item's oid, call
* ItemApi.GetItemByMerchantItemId() to retrieve the item, and then it's oid item.MerchantItemOid
*
* The review_oid is a unique identifier used by UltraCart. If you do not know a review's oid, call
* ItemApi.GetReviews() to get all reviews where you can then grab the oid from an item.
*/
ItemApi itemApi = new ItemApi(Constants.ApiKey);
int merchantItemOid = 123456;
int reviewOid = 987654;
ItemReviewResponse apiResponse = itemApi.GetReview(reviewOid, merchantItemOid);
if (apiResponse.Error != null)
{
Console.Error.WriteLine(apiResponse.Error.DeveloperMessage);
Console.Error.WriteLine(apiResponse.Error.UserMessage);
Environment.Exit(1);
}
ItemReview review = apiResponse.Review;
Console.WriteLine("<html lang=\"en\"><body><pre>");
Console.WriteLine(review.ToString());
Console.WriteLine("</pre></body></html>");
}
}
}
package item;
import com.ultracart.admin.v2.ItemApi;
import com.ultracart.admin.v2.models.*;
import com.ultracart.admin.v2.util.ApiException;
import common.Constants;
public class GetReview {
/// <summary>
/// Execute method containing all business logic
/// </summary>
public static void execute() throws ApiException {
/*
* Retrieves a specific user review for an item. This would most likely be used by a merchant who has cached all
* reviews on a separate site and then wishes to update a particular review. It's always best to "get" the object,
* make changes to it, then call the update instead of trying to recreate the object from scratch.
*
* The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your item's oid, call
* ItemApi.GetItemByMerchantItemId() to retrieve the item, and then it's oid item.MerchantItemOid
*
* The review_oid is a unique identifier used by UltraCart. If you do not know a review's oid, call
* ItemApi.GetReviews() to get all reviews where you can then grab the oid from an item.
*/
ItemApi itemApi = new ItemApi(Constants.API_KEY);
int merchantItemOid = 123456;
int reviewOid = 987654;
ItemReviewResponse apiResponse = itemApi.getReview(reviewOid, merchantItemOid);
if (apiResponse.getError() != null) {
System.err.println(apiResponse.getError().getDeveloperMessage());
System.err.println(apiResponse.getError().getUserMessage());
System.exit(1);
}
ItemReview review = apiResponse.getReview();
System.out.println("<html lang=\"en\"><body><pre>");
System.out.println(review.toString());
System.out.println("</pre></body></html>");
}
}
import { itemApi } from '../api.js';
/**
* Execute method containing all business logic
*/
export async function execute() {
/*
* Retrieves a specific user review for an item. This would most likely be used by a merchant who has cached all
* reviews on a separate site and then wishes to update a particular review. It's always best to "get" the object,
* make changes to it, then call the update instead of trying to recreate the object from scratch.
*
* The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your item's oid, call
* ItemApi.GetItemByMerchantItemId() to retrieve the item, and then it's oid item.MerchantItemOid
*
* The review_oid is a unique identifier used by UltraCart. If you do not know a review's oid, call
* ItemApi.GetReviews() to get all reviews where you can then grab the oid from an item.
*/
const merchantItemOid = 123456;
const reviewOid = 987654;
try {
const apiResponse = await new Promise((resolve, reject) => {
itemApi.getReview(reviewOid, merchantItemOid, function (error, data, response) {
if (error) reject(error);
else resolve(data, response);
});
});
if (apiResponse.error) {
console.error(apiResponse.error.developer_message);
console.error(apiResponse.error.user_message);
process.exit(1);
}
const review = apiResponse.review;
console.log(review ? review.toString() : undefined); // Handle toString() in JS
} catch (error) {
console.error("An error occurred while fetching the review:", error);
process.exit(1);
}
}
<?php
use ultracart\v2\api\ItemApi;
ini_set('display_errors', 1);
/*
Retrieves a specific user review for an item. This would most likely be used by a merchant who has cached all
reviews on a separate site and then wishes to update a particular review. It's always best to "get" the object,
make changes to it, then call the update instead of trying to recreate the object from scratch.
The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your item's oid, call
ItemApi.getItemByMerchantItemId() to retrieve the item, and then it's oid $item->getMerchantItemOid()
The review_oid is a unique identifier used by UltraCart. If you do not know a review's oid, call
ItemApi.getReviews() to get all reviews where you can then grab the oid from an item.
*/
require_once '../vendor/autoload.php';
require_once '../constants.php';
$item_api = ItemApi::usingApiKey(Constants::API_KEY);
$merchant_item_oid = 123456;
$review_oid = 987654;
$api_response = $item_api->getReview($review_oid, $merchant_item_oid);
if ($api_response->getError() != null) {
error_log($api_response->getError()->getDeveloperMessage());
error_log($api_response->getError()->getUserMessage());
exit();
}
$review = $api_response->getReview();
echo '<html lang="en"><body><pre>';
var_dump($review);
echo '</pre></body></html>';
from ultracart.apis import ItemApi
from samples import api_client
"""
Retrieves a specific user review for an item. This would most likely be used by a merchant
who has cached all reviews on a separate site and then wishes to update a particular review.
It's always best to "get" the object, make changes to it, then call the update instead of
trying to recreate the object from scratch.
The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your
item's oid, call ItemApi.get_item_by_merchant_item_id() to retrieve the item, and then
get its oid via $item.get_merchant_item_oid()
The review_oid is a unique identifier used by UltraCart. If you do not know a review's oid,
call ItemApi.get_reviews() to get all reviews where you can then grab the oid from an item.
"""
# Create Item API client
item_api = ItemApi(api_client())
# Example OIDs (replace with actual values)
merchant_item_oid = 123456
review_oid = 987654
# Retrieve the specific review
api_response = item_api.get_review(review_oid, merchant_item_oid)
# Check for errors
if api_response.get_error() is not None:
error = api_response.get_error()
print(f"Developer Message: {error.get_developer_message()}")
print(f"User Message: {error.get_user_message()}")
raise Exception("Review retrieval failed")
# Get the review
review = api_response.get_review()
# Print the review
print(review)
require 'ultracart_api'
require_relative '../constants'
=begin
Retrieves a specific user review for an item. This would most likely be used by a merchant who has cached all
reviews on a separate site and then wishes to update a particular review. It's always best to "get" the object,
make changes to it, then call the update instead of trying to recreate the object from scratch.
The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your item's oid, call
ItemApi.get_item_by_merchant_item_id() to retrieve the item, and then it's oid item.merchant_item_oid
The review_oid is a unique identifier used by UltraCart. If you do not know a review's oid, call
ItemApi.get_reviews() to get all reviews where you can then grab the oid from an item.
=end
# Initialize the item API
item_api = UltracartClient::ItemApi.new_using_api_key(Constants::API_KEY)
# Set merchant item and review OIDs
merchant_item_oid = 123456
review_oid = 987654
# Get the review with opts hash
begin
api_response = item_api.get_review(review_oid, merchant_item_oid)
# Check for errors
if api_response.error
warn api_response.error.developer_message
warn api_response.error.user_message
exit
end
# Print the review
p api_response.review
rescue UltracartClient::ApiError => e
warn "API Error: #{e.message}"
exit(1)
end
import { itemApi } from '../api';
import {
ItemReviewResponse,
ItemReview
} from 'ultracart_rest_api_v2_typescript';
/**
* Execute method containing all business logic
*/
export async function execute(): Promise<void> {
/*
* Retrieves a specific user review for an item. This would most likely be used by a merchant who has cached all
* reviews on a separate site and then wishes to update a particular review. It's always best to "get" the object,
* make changes to it, then call the update instead of trying to recreate the object from scratch.
*
* The merchant_item_oid is a unique identifier used by UltraCart. If you do not know your item's oid, call
* ItemApi.GetItemByMerchantItemId() to retrieve the item, and then it's oid item.MerchantItemOid
*
* The review_oid is a unique identifier used by UltraCart. If you do not know a review's oid, call
* ItemApi.GetReviews() to get all reviews where you can then grab the oid from an item.
*/
const merchantItemOid: number = 123456;
const reviewOid: number = 987654;
try {
const apiResponse: ItemReviewResponse = await itemApi.getReview({reviewOid, merchantItemOid});
if (apiResponse.error) {
console.error(apiResponse.error.developer_message);
console.error(apiResponse.error.user_message);
process.exit(1);
}
const review: ItemReview | undefined = apiResponse.review;
console.log(review?.toString());
} catch (error) {
console.error("An error occurred while fetching the review:", error);
process.exit(1);
}
}
Update an item review.
SDK Function Name: updateReview
Parameter | Description | Location | Data Type | Required |
---|---|---|---|---|
review | Review to update | body | ItemReview | required |
review_oid | The review oid to update. | path | integer (int32) | required |
merchant_item_oid | The item oid the review is associated with. | path | integer (int32) | required |
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;
using System;
using com.ultracart.admin.v2.Client;
namespace SdkSample.item
{
public class UpdateReview
{
public static void Execute()
{
try
{
// To update a review, you'll need an item's OID (Object Identifier) and the review oid first.
int merchantItemOid = 99998888; // if you don't know your oid, call GetItemByMerchantItemId() to get your item, then get the oid.
int reviewOid = 123456; // this is the particular oid you wish to update.
ItemApi itemApi = new ItemApi(Constants.ApiKey); // convenience function for getting an api handle.
ItemReview review = itemApi.GetReview(merchantItemOid, reviewOid).Review;
// You will need to know what your product review looks like.
review.Title = "Best Product Ever!";
review.Review = "I loved this product. I bought it for my wife and she was so happy she cried. blah blah blah";
review.ReviewedNickname = "Bob420";
review.Featured = true; // featured? sure. why not? this is a great review.
review.RatingName1 = "Durability";
review.RatingName2 = "Price";
review.RatingName3 = "Performance";
review.RatingName4 = "Appearance";
review.RatingScore1 = 4.5m;
review.RatingScore2 = 3.5m;
review.RatingScore3 = 2.5m;
review.RatingScore4 = 1.5m;
review.Overall = 5.0m; // hooray!
review.ReviewerLocation = "Southside Chicago";
review.Status = ItemReview.StatusEnum.Approved;
// insert the review and update our local variable to see how the review looks now.
review = itemApi.UpdateReview(reviewOid, merchantItemOid, review).Review;
Console.WriteLine("This is my review object:");
Console.WriteLine(review);
// This will clean up the sample item, but you may wish to review the item in the backend or on your website first.
// DeleteSampleItem(itemId);
}
catch (ApiException e)
{
Console.WriteLine("An ApiException occurred. Please review the following error:");
Console.WriteLine(e); // <-- change_me: handle gracefully
Environment.Exit(1);
}
}
}
}
package item;
import com.ultracart.admin.v2.ItemApi;
import com.ultracart.admin.v2.models.ItemReview;
import com.ultracart.admin.v2.util.ApiException;
import common.Constants;
import java.math.BigDecimal;
public class UpdateReview {
public static void execute() {
try {
// To update a review, you'll need an item's OID (Object Identifier) and the review oid first.
int merchantItemOid = 99998888; // if you don't know your oid, call GetItemByMerchantItemId() to get your item, then get the oid.
int reviewOid = 123456; // this is the particular oid you wish to update.
ItemApi itemApi = new ItemApi(Constants.API_KEY); // convenience function for getting an api handle.
ItemReview review = itemApi.getReview(merchantItemOid, reviewOid).getReview();
// You will need to know what your product review looks like.
review.setTitle("Best Product Ever!");
review.setReview("I loved this product. I bought it for my wife and she was so happy she cried. blah blah blah");
review.setReviewedNickname("Bob420");
review.setFeatured(true); // featured? sure. why not? this is a great review.
review.setRatingName1("Durability");
review.setRatingName2("Price");
review.setRatingName3("Performance");
review.setRatingName4("Appearance");
review.setRatingScore1(BigDecimal.valueOf(4.5));
review.setRatingScore2(BigDecimal.valueOf(3.5));
review.setRatingScore3(BigDecimal.valueOf(2.5));
review.setRatingScore4(BigDecimal.valueOf(1.5));
review.setOverall(BigDecimal.valueOf(5.0)); // hooray!
review.setReviewerLocation("Southside Chicago");
review.setStatus(ItemReview.StatusEnum.APPROVED);
// insert the review and update our local variable to see how the review looks now.
review = itemApi.updateReview(reviewOid, merchantItemOid, review).getReview();
System.out.println("This is my review object:");
System.out.println(review);
// This will clean up the sample item, but you may wish to review the item in the backend or on your website first.
// DeleteSampleItem(itemId);
}
catch (ApiException e) {
System.out.println("An ApiException occurred. Please review the following error:");
System.out.println(e); // <-- change_me: handle gracefully
System.exit(1);
}
}
}
import { itemApi } from '../api.js';
export class UpdateReview {
/**
* Updates an existing item review with new details
*
* Note: To update a review, you'll need:
* 1. The merchant item's OID (Object Identifier)
* 2. The specific review's OID you wish to update
*
* If you don't know the item's OID, call GetItemByMerchantItemId() to retrieve it
*/
static async execute() {
try {
// Merchant item OID and review OID to update
const merchantItemOid = 99998888; // Replace with your actual merchant item OID
const reviewOid = 123456; // Replace with the specific review OID to update
// Retrieve the existing review
const reviewResponse = await new Promise((resolve, reject) => {
itemApi.getReview(merchantItemOid, reviewOid, function (error, data, response) {
if (error) {
reject(error);
} else {
resolve(data);
}
});
});
const review = reviewResponse.review;
// Ensure the review exists before updating
if (!review) {
throw new Error('Review not found');
}
// Update review details
review.title = "Best Product Ever!";
review.review = "I loved this product. I bought it for my wife and she was so happy she cried. blah blah blah";
review.reviewed_nickname = "Bob420";
review.featured = true;
// Update rating details
review.rating_name1 = "Durability";
review.rating_name2 = "Price";
review.rating_name3 = "Performance";
review.rating_name4 = "Appearance";
review.rating_score1 = 4.5;
review.rating_score2 = 3.5;
review.rating_score3 = 2.5;
review.rating_score4 = 1.5;
review.overall = 5.0;
// Additional review metadata
review.reviewer_location = "Southside Chicago";
review.status = "Approved";
// Update the review and retrieve the updated version
const updatedReviewResponse = await new Promise((resolve, reject) => {
itemApi.updateReview(
reviewOid,
merchantItemOid,
review
, function (error, data, response) {
if (error) {
reject(error);
} else {
resolve(data);
}
});
});
const updatedReview = updatedReviewResponse.review;
// Log the updated review details
console.log("Updated Review Object:");
console.log(JSON.stringify(updatedReview, null, 2));
} catch (error) {
console.error("An error occurred while updating the review:", error);
process.exit(1);
}
}
}
<?php
/** @noinspection SpellCheckingInspection */
/** @noinspection GrazieInspection */
use ultracart\v2\ApiException;
require_once '../vendor/autoload.php';
require_once '../samples.php';
require_once './item_functions.php'; // <-- see this file for details
try {
// To update a review, you'll need an item's OID (Object Identifier) and the review oid first.
$merchant_item_oid = 99998888; // if you don't know your oid, call getItemByMerchantItemId() to get your item, then get the oid.
$review_oid = 123456; // this is the particular oid you wish to update.
$item_api = Samples::getItemApi(); // convenience fuction for getting an api handle.
$review = $item_api->getReview($merchant_item_oid, $review_oid)->getReview();
// You will need to know what your product review looks like.
$review->setTitle('Best Product Ever!');
$review->setReview("I loved this product. I bought it for my wife and she was so happy she cried. blah blah blah");
$review->setReviewedNickname("Bob420");
$review->setFeatured(true); // featured? sure. why not? this is a great review.
$review->setRatingName1('Durability');
$review->setRatingName2('Price');
$review->setRatingName3('Performance');
$review->setRatingName4('Appearance');
$review->setRatingScore1(4.5);
$review->setRatingScore2(3.5);
$review->setRatingScore3(2.5);
$review->setRatingScore4(1.5);
$review->setOverall(5.0); // hooray!
$review->setReviewerLocation("Southside Chicago");
$review->setStatus('approved');
// insert the review and update our local variable to see how the review looks now.
$review = $item_api->updateReview($review_oid, $merchant_item_oid, $review)->getReview();
echo '<br>This is my review object:<br><pre>';
var_dump($review);
echo '</pre>';
// This will clean up the sample item, but you may wish to review the item in the backend or on your website first.
// deleteSampleItem($item_id);
} catch (ApiException $e) {
echo 'An ApiException occurred. Please review the following error:';
var_dump($e); // <-- change_me: handle gracefully
die(1);
}
from flask import Flask
from ultracart import ApiException
from ultracart.apis import ItemApi
from samples import api_client
app = Flask(__name__)
@app.route('/update_review')
def update_review():
try:
# Predefined OIDs for merchant item and review
merchant_item_oid = 99998888
review_oid = 123456
# Create Item API client
item_api = ItemApi(api_client())
# Get existing review
review = item_api.get_review(merchant_item_oid, review_oid).get_review()
# Update review details
review.set_title('Best Product Ever!')
review.set_review("I loved this product. I bought it for my wife and she was so happy she cried. blah blah blah")
review.set_reviewed_nickname("Bob420")
review.set_featured(True)
# Set rating names
review.set_rating_name1('Durability')
review.set_rating_name2('Price')
review.set_rating_name3('Performance')
review.set_rating_name4('Appearance')
# Set rating scores
review.set_rating_score1(4.5)
review.set_rating_score2(3.5)
review.set_rating_score3(2.5)
review.set_rating_score4(1.5)
review.set_overall(5.0)
# Additional review details
review.set_reviewer_location("Southside Chicago")
review.set_status('approved')
# Update review
updated_review = item_api.update_review(review_oid, merchant_item_oid, review).get_review()
# Print updated review details
print("Updated Review:", updated_review)
return "Review updated successfully"
except ApiException as e:
print('An ApiException occurred. Please review the following error:')
print(e)
return "Error updating review", 500
if __name__ == '__main__':
app.run(debug=True)
#!/usr/bin/env ruby
# frozen_string_literal: true
require 'ultracart_api'
require_relative '../constants'
require_relative './item_functions'
begin
# To update a review, you'll need an item's OID (Object Identifier) and the review oid first.
# If you don't know your oid, call getItemByMerchantItemId() to get your item, then get the oid.
merchant_item_oid = 99998888
review_oid = 123456 # This is the particular oid you wish to update.
# Initialize the Item API
item_api = UltracartClient::ItemApi.new_using_api_key(Constants::API_KEY)
# Retrieve the existing review
review = item_api.get_review(merchant_item_oid, review_oid).review
# Update the review details
review = UltracartClient::ItemReview.new(
title: 'Best Product Ever!',
review: "I loved this product. I bought it for my wife and she was so happy she cried. blah blah blah",
reviewed_nickname: "Bob420",
featured: true, # featured? sure. why not? this is a great review.
rating_name1: 'Durability',
rating_name2: 'Price',
rating_name3: 'Performance',
rating_name4: 'Appearance',
rating_score1: 4.5,
rating_score2: 3.5,
rating_score3: 2.5,
rating_score4: 1.5,
overall: 5.0, # hooray!
reviewer_location: "Southside Chicago",
status: 'approved'
)
# Update the review and retrieve the updated review
review = item_api.update_review(review_oid, merchant_item_oid, review).review
# Output the review object
p review
# This will clean up the sample item, but you may wish to review the item in the backend or on your website first.
# delete_sample_item(item_id)
rescue UltracartClient::ApiError => e
puts 'An ApiException occurred. Please review the following error:'
p e
exit(1)
end
import {itemApi} from '../api';
import {
ItemReview,
ItemReviewResponse
} from 'ultracart_rest_api_v2_typescript';
import {ItemReviewStatusEnum} from "ultracart_rest_api_v2_typescript/src/models/ItemReview";
export class UpdateReview {
/**
* Updates an existing item review with new details
*
* Note: To update a review, you'll need:
* 1. The merchant item's OID (Object Identifier)
* 2. The specific review's OID you wish to update
*
* If you don't know the item's OID, call GetItemByMerchantItemId() to retrieve it
*/
public static async execute(): Promise<void> {
try {
// Merchant item OID and review OID to update
const merchantItemOid: number = 99998888; // Replace with your actual merchant item OID
const reviewOid: number = 123456; // Replace with the specific review OID to update
// Retrieve the existing review
const reviewResponse: ItemReviewResponse = await itemApi.getReview({merchantItemOid, reviewOid});
const review: ItemReview | undefined = reviewResponse.review;
// Ensure the review exists before updating
if (!review) {
throw new Error('Review not found');
}
// Update review details
review.title = "Best Product Ever!";
review.review = "I loved this product. I bought it for my wife and she was so happy she cried. blah blah blah";
review.reviewed_nickname = "Bob420";
review.featured = true;
// Update rating details
review.rating_name1 = "Durability";
review.rating_name2 = "Price";
review.rating_name3 = "Performance";
review.rating_name4 = "Appearance";
review.rating_score1 = 4.5;
review.rating_score2 = 3.5;
review.rating_score3 = 2.5;
review.rating_score4 = 1.5;
review.overall = 5.0;
// Additional review metadata
review.reviewer_location = "Southside Chicago";
review.status = ItemReviewStatusEnum.Approved;
// Update the review and retrieve the updated version
const updatedReviewResponse: ItemReviewResponse = await itemApi.updateReview({
reviewOid,
merchantItemOid,
review
});
const updatedReview: ItemReview | undefined = updatedReviewResponse.review;
// Log the updated review details
console.log("Updated Review Object:");
console.log(JSON.stringify(updatedReview, null, 2));
} catch (error) {
console.error("An error occurred while updating the review:", error);
process.exit(1);
}
}
}
Retrieves the pricing tiers
SDK Function Name: getPricingTiers
Parameter | Description | Location | Data Type | Required |
---|---|---|---|---|
_expand | The object expansion to perform on the result. See documentation for examples | query | string | optional |
using System;
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;
namespace SdkSample.item
{
public class GetPricingTiers
{
/// <summary>
/// Execute method containing all business logic
/// </summary>
public static void Execute()
{
ItemApi itemApi = new ItemApi(Constants.ApiKey);
try
{
/*
* Possible expansion values for PricingTier object:
* approval_notification
* signup_notification
*/
string expand = "approval_notification,signup_notification";
PricingTiersResponse apiResponse = itemApi.GetPricingTiers(expand);
// Display pricing tiers
foreach (PricingTier pricingTier in apiResponse.PricingTiers)
{
Console.WriteLine(pricingTier);
}
}
catch (Exception e)
{
Console.WriteLine("Exception occurred.");
Console.WriteLine(e);
Environment.Exit(1);
}
}
}
}
package item;
import com.ultracart.admin.v2.ItemApi;
import com.ultracart.admin.v2.models.*;
import common.Constants;
public class GetPricingTiers {
/// <summary>
/// Execute method containing all business logic
/// </summary>
public static void execute() {
ItemApi itemApi = new ItemApi(Constants.API_KEY);
try {
/*
* Possible expansion values for PricingTier object:
* approval_notification
* signup_notification
*/
String expand = "approval_notification,signup_notification";
PricingTiersResponse apiResponse = itemApi.getPricingTiers(expand);
// Display pricing tiers
for (PricingTier pricingTier : apiResponse.getPricingTiers()) {
System.out.println(pricingTier);
}
} catch (Exception e) {
System.out.println("Exception occurred.");
System.out.println(e);
System.exit(1);
}
}
}
import {itemApi} from '../api.js';
/**
* Execute method containing all business logic
*/
export async function execute() {
try {
/*
* Possible expansion values for PricingTier object:
* approval_notification
* signup_notification
*/
const expand = "approval_notification,signup_notification";
const apiResponse = await new Promise((resolve, reject) => {
itemApi.getPricingTiers({_expand: expand}, function (error, data, response) {
if (error) reject(error);
else resolve(data, response);
});
});
// Display pricing tiers
apiResponse.pricingTiers?.forEach((pricingTier) => {
console.log(pricingTier);
});
} catch (error) {
console.error("Exception occurred.");
console.error(error);
process.exit(1);
}
}
<?php
use ultracart\v2\ApiException;
require_once '../vendor/autoload.php';
require_once '../samples.php';
$item_api = Samples::getItemApi();
try {
/*
* Possible expansion values for PricingTier object:
* approval_notification
* signup_notification
*/
$expand = "approval_notification,signup_notification";
$api_response = $item_api->getPricingTiers($expand);
} catch (ApiException $e) {
echo 'ApiException occurred.';
var_dump($e);
die(1);
}
var_dump($api_response->getPricingTiers());
from ultracart.apis import ItemApi
from samples import api_client
try:
"""
Possible expansion values for PricingTier object:
- approval_notification
- signup_notification
"""
item_api = ItemApi(api_client())
expand = "approval_notification,signup_notification"
api_response = item_api.get_pricing_tiers(expand=expand)
except Exception as e:
print('Exception occurred.')
print(e)
raise
print(api_response.get_pricing_tiers())
require 'ultracart_api'
require_relative '../constants'
# Possible expansion values for PricingTier object:
# - approval_notification
# - signup_notification
begin
# Initialize the item API using the API key from constants
item_api = UltracartClient::ItemApi.new_using_api_key(Constants::API_KEY)
# Define expand options in the opts hash
opts = {
'_expand' => 'approval_notification,signup_notification'
}
# Get pricing tiers with expand options
api_response = item_api.get_pricing_tiers(opts)
# Print the pricing tiers
p api_response.pricing_tiers
rescue UltracartClient::ApiError => e
puts 'ApiException occurred.'
p e
exit(1)
end
import { itemApi } from '../api';
import {
PricingTiersResponse,
PricingTier
} from 'ultracart_rest_api_v2_typescript';
/**
* Execute method containing all business logic
*/
export async function execute(): Promise<void> {
try {
/*
* Possible expansion values for PricingTier object:
* approval_notification
* signup_notification
*/
const expand = "approval_notification,signup_notification";
const apiResponse: PricingTiersResponse = await itemApi.getPricingTiers({expand});
// Display pricing tiers
apiResponse.pricingTiers?.forEach((pricingTier: PricingTier) => {
console.log(pricingTier);
});
} catch (error) {
console.error("Exception occurred.");
console.error(error);
process.exit(1);
}
}
Uploads an image and returns back meta information about the image as well as the identifier needed for the item update.
SDK Function Name: uploadTemporaryMultimedia
Parameter | Description | Location | Data Type | Required |
---|---|---|---|---|
file | File to upload | formData | file | required |
// This method is used internally by UltraCart.
// We don't envision a scenario where a merchant would ever need to call this.
// As such, we're not providing a sample for it. If you can think of a use for this
// method, contact us, and we'll help you work through it.
// This method is used internally by UltraCart.
// We don't envision a scenario where a merchant would ever need to call this.
// As such, we're not providing a sample for it. If you can think of a use for this
// method, contact us, and we'll help you work through it.
// This method is used internally by UltraCart.
// We don't envision a scenario where a merchant would ever need to call this.
// As such, we're not providing a sample for it. If you can think of a use for this
// method, contact us, and we'll help you work through it.
<?php
// This method is used internally by UltraCart.
// We don't envision a scenario where a merchant would ever need to call this.
// As such, we're not providing a sample for it. If you can think of a use for this
// method, contact us, and we'll help you work through it.
# This method is used internally by UltraCart.
# We don't envision a scenario where a merchant would ever need to call this.
# As such, we're not providing a sample for it. If you can think of a use for this
# method, contact us, and we'll help you work through it.
# This method is used internally by UltraCart.
# We don't envision a scenario where a merchant would ever need to call this.
# As such, we're not providing a sample for it. If you can think of a use for this
# method, contact us, and we'll help you work through it.
// This method is used internally by UltraCart.
// We don't envision a scenario where a merchant would ever need to call this.
// As such, we're not providing a sample for it. If you can think of a use for this
// method, contact us, and we'll help you work through it.
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 |
Name | Data Type | Description |
---|---|---|
uom | string | Unit of measure
Allowed Values
|
value | number | The distance measured in UOM |
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 |
object_id | string | Object id that the error is associated with |
user_message | string | An end-user friendly message suitable for display to the customer |
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 |
warning | Warning | Warning object if a non-fatal issue or side-effect occurs |
Name | Data Type | Description |
---|---|---|
accounting | ItemAccounting | Accounting such as QuickBooks codes |
amember | ItemAmember | Amember configuration |
auto_order | ItemAutoOrder | Auto Order |
ccbill | ItemCCBill | CCBill.com (Deprecated) |
channel_partner_item_mappings | array of ItemChannelPartnerMapping | Channel Partner Item Mapping |
chargeback | ItemChargeback | Chargeback (deprecated) |
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 |
fulfillment_addons | array of ItemFulfillmentAddon | Fulfillment Add-ons |
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_component_only | boolean | True if this item can only be usd as a kit component |
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. |
parent_category_path | string | Parent category path. / indicates the root folder. |
payment_processing | ItemPaymentProcessing | Payment Processing |
physical | ItemPhysical | Physical characters like weight and measurements |
pricing | ItemPricing | Pricing |
properties | array of ItemProperty | Properties |
realtime_pricing | ItemRealtimePricing | Real-time Pricing |
recommend_replenishment_days | integer (int32) | Number of days to recommend replenishment after. Null is not configured. Set to zero to disable. |
related | ItemRelated | Related items |
reporting | ItemReporting | Reporting |
restriction | ItemRestriction | Restrictions |
revguard | ItemRevguard | Revguard.com (Deprecated) |
reviews | ItemReviews | Reviews |
salesforce | ItemSalesforce | Salesforce.com configuration |
shipping | ItemShipping | Shipping |
tags | ItemTags | Tags |
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 |
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 |
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 |
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_charge_minimum_balance | boolean | If true, the cost of the cancel item will be the remaining balance of the minimum rebill or lifetime value |
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_cancel_minimum_life_time_count | integer (int32) | The minimum life time count that must be billed in order to not be charged the cancellation item. |
auto_order_cancel_minimum_life_time_value | number | The minimum life time value that must be paid in order to not be charged the cancellation item. |
auto_order_cancel_minimum_rebill_count | integer (int32) | The minimum rebill count that must be billed in order to not be charged the cancellation item. |
auto_order_cancel_minimum_rebill_value | number | The minimum rebill value that must be paid in order to not be charged the cancellation item. |
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_prohibit_expiring_cards | integer (int32) | Minimum number of months before expiration for the card. Overrides the account level setting if higher. Set to zero to disable. |
auto_order_schedules | array of string | The user selectable schedules that are available
Allowed Values
|
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 |
refund_other_auto_orders | boolean | True if other auto orders for this customer should refunded if this item is refunded. |
steps | array of ItemAutoOrderStep | The rebill steps if this auto order is an upsell |
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
|
pause_days | integer (int32) | Number of days to pause |
pause_until_date | string (dateTime) | Wait for this step to happen until the specified date |
pause_until_day_of_month | integer (int32) | Pause until a specific day of the month |
pause_until_minimum_delay_days | integer (int32) | Pause at least this many days between the last order and the calculated next day of month |
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
|
subscribe_email_list_name | string | Email list name to subscribe the customer to when the rebill occurs (decommissioned email engine) |
subscribe_email_list_oid | integer (int32) | Email list identifier to subscribe the customer to when this rebill occurs (decommissioned email engine) |
type | string | Type of step (item, kit only, loop or pause)
Allowed Values
|
Name | Data Type | Description |
---|---|---|
arbitrary_unit_cost | number | Arbitrary unit cost |
retry_days | integer (int32) | Retry days |
Name | Data Type | Description |
---|---|---|
on_or_before_date | string (dateTime) | On or before date |
unit_cost | number | Unit cost |
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 |
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_catalog_number | string | Buyer catalog number (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 |
cost | number | Cost given to this channel partner |
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) |
Name | Data Type | Description |
---|---|---|
addendums | array of ItemChargebackAddendum | Addendums (deprecated) |
adjustment_requests | array of ItemChargebackAdjustmentRequest | Adjustment requests (deprecated) |
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 |
Name | Data Type | Description |
---|---|---|
chargeback_adjustment_request_oid | integer (int32) | Chargeback adjustment request object identifier |
description | string | Description |
reason_code | string | Reason code |
Name | Data Type | Description |
---|---|---|
suppress_buysafe | boolean | True to suppress buySAFE (deprecated) |
terms | string(10000) | Terms for purchasing this item |
terms_if_auto_order | boolean | Terms only apply if the item is on auto order |
terms_translated_text_instance_oid | (read only) integer (int32) | Terms translated text instance identifier |
Name | Data Type | Description |
---|---|---|
assignments | array of ItemContentAssignment | StoreFront assignments |
attributes | array of ItemContentAttribute | StoreFront attributes |
custom_thank_you_url | string | Custom Thank You URL |
exclude_from_search | boolean | Exclude from search |
exclude_from_sitemap | boolean | Exclude from the sitemap for the StoreFront |
exclude_from_top_sellers | boolean | Exclude from the top sellers list in the StoreFront |
extended_description | string(10000) | Extended description (max 10000 characters) |
extended_description_translated_text_instance_oid | (read only) integer (int32) | Extended description text translation instance identifier |
meta_description | string | SEO meta description used by Storefronts |
meta_keywords | string | SEO meta keywords used by Storefronts |
meta_title | string | SEO meta title used by Storefronts |
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) |
Name | Data Type | Description |
---|---|---|
default_assignment | boolean | True if this group is the default assignment for this item |
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 |
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
|
value | string(100000) | Attribute value |
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
|
url | string | URL to download file (on new multimedia record this can be a URL for UltraCart to fetch) |
width | integer (int32) | Width of the image |
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 |
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
|
digital_items | array of ItemDigitalItem | Digital items that customer can download when this item is purchased |
Name | Data Type | Description |
---|---|---|
click_wrap_agreement | string | Click wrap agreement is presented to the customer before they can purchase your product. |
creation_dts | (read only) string (dateTime) | File creation date |
description | string(200) | Description of the digital item |
digital_item_oid | integer (int32) | The Digital item oid is a primary key used internally by UltraCart. You should not set or change this value. Doing so will have no effect. |
external_id | string(100) | External Id useful for syncing with a remote filesystem, this may be an MD5 hash or whatever suits your needs. |
file_size | (read only) integer (int64) | File size |
import_from_url | string | This url is sourced to create or update a digital file in your digital library. It is only considered during an insert or update operation. |
mime_type | (read only) string(100) | Mime type associated with the file |
original_filename | string(250) | Original filename |
pdf_meta | ItemDigitalItemPdfMeta | Additional properties for pdf files |
Name | Data Type | Description |
---|---|---|
assembly_allowed | boolean | Assembly allowed |
copy_allowed | boolean | Copy/Paste is allowed |
custom_footer | string(8000) | A custom footer for each pdf page |
custom_header | string(8000) | A custom header for each pdf page |
degraded_printing_allowed | boolean | Degraded printing allowed |
fillin_allowed | boolean | Fillin is allowed |
modify_annotations_allowed | boolean | Modifying annotations is allowed |
modify_contents_allowed | boolean | Modifying contents is allowed |
printing_allowed | boolean | Printing is allowed |
screen_readers_allowed | boolean | Screen readers are allowed |
tagged | boolean | PDF is tagged |
Name | Data Type | Description |
---|---|---|
digital_item | ItemDigitalItem | Digital item |
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 |
warning | Warning | Warning object if a non-fatal issue or side-effect occurs |
Name | Data Type | Description |
---|---|---|
digital_items | array of ItemDigitalItem | digital_items |
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 |
warning | Warning | Warning object if a non-fatal issue or side-effect occurs |
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) |
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
|
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 |
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
|
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
|
start_time | (read only) string | Date/time of the auction start |
status | string | Status of the item's listing
Allowed Values
|
target_dispatch_time_max | integer (int32) | Typical number of days it will take to ship the item |
Name | Data Type | Description |
---|---|---|
name | string | Name of the category specification field |
value | string | Value |
Name | Data Type | Description |
---|---|---|
auction_id | string | Auction ID |
price | number | Price |
seller | string | Seller |
shipping | number | Shipping |
total | number | Total |
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 |
Name | Data Type | Description |
---|---|---|
skip_receipt | boolean | Skip receipt email to customer |
skip_shipment_notification | boolean | Skip shipment notification to customer |
Name | Data Type | Description |
---|---|---|
enrollment123_product_code | string | Enrolment 123 product code |
Name | Data Type | Description |
---|---|---|
add_item_id | (read only) string | Add Item Id |
add_item_oid | integer (int32) | Add Item object identifier |
initial_order_only | boolean | Initial Order Only |
once_per_order | boolean | Once Per Order |
quantity | integer (int32) | Quantity |
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) |
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(100) | 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 |
shippingLabel | string | |
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 |
Name | Data Type | Description |
---|---|---|
barcode | string(30) | Barcode |
barcode_gtin12 | string(12) | Barcode - GTIN 12 |
barcode_gtin14 | string(14) | Barcode - GTIN 14 |
barcode_upc11 | string(11) | Barcode - UPC 11 |
barcode_upc12 | string(12) | Barcode - UPC 12 |
manufacturer_name | string(50) | Manufacturer Name |
manufacturer_sku | string(25) | Manufacturer SKU |
unspsc | string(20) | UNSPSC |
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 |
Name | Data Type | Description |
---|---|---|
notifications | array of ItemInstantPaymentNotification | Notifications |
Name | Data Type | Description |
---|---|---|
memo | string(250) | Memo |
Name | Data Type | Description |
---|---|---|
allocated_to_placed_orders | integer (int32) | |
allocated_to_shopping_carts | integer (int32) | |
available_to_allocate | integer (int32) | |
distribution_centers | array of ItemInventorySnapshotDistributionCenter | |
merchant_item_id | string | |
quantity | integer (int32) |
Name | Data Type | Description |
---|---|---|
allocated_to_placed_orders | integer (int32) | |
allocated_to_shopping_carts | integer (int32) | |
available_to_allocate | integer (int32) | |
code | string | |
quantity | integer (int32) |
Name | Data Type | Description |
---|---|---|
error | Error | Error object if unsuccessful |
inventories | array of ItemInventorySnapshot | inventories |
metadata | ResponseMetadata | Meta-data about the response such as payload or paging information |
success | boolean | Indicates if API call was successful |
warning | Warning | Warning object if a non-fatal issue or side-effect occurs |
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 |
Name | Data Type | Description |
---|---|---|
components | array of ItemKitComponent | Components |
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
|
values | array of ItemOptionValue | Values |
Name | Data Type | Description |
---|---|---|
additional_dimension_application | string | Additional dimensions application
Allowed Values
|
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) |
Name | Data Type | Description |
---|---|---|
additional_merchant_item_id | string | Additional item id |
additional_merchant_item_oid | integer (int32) | Additional item object identifier |
Name | Data Type | Description |
---|---|---|
digital_item_oid | integer (int32) | Digital item object identifier |
original_filename | string | Original filename |
Name | Data Type | Description |
---|---|---|
block_prepaid | boolean | True if prepaid cards should be blocked from buying this item |
block_refunds | boolean | True if this item should block any refund attempts, set to false otherwise, null value will not update the field |
credit_card_transaction_type | string | Credit card transaction type
Allowed Values
|
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
|
rotating_transaction_gateway_codes | array of string | Rotating transaction gateway codes |
Name | Data Type | Description |
---|---|---|
height | Distance | Height |
length | Distance | Length |
weight | Weight | Weight |
width | Distance | Width |
Name | Data Type | Description |
---|---|---|
allow_arbitrary_cost | boolean | Allow arbitrary cost |
arbitrary_cost_velocity_code | string(10000) | Arbitrary cost velocity code |
auto_order_cost | number | Cost if customer selects to receive item on auto order. Set to zero to delete. |
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
|
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 |
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 |
Name | Data Type | Description |
---|---|---|
cost | number | Cost |
quantity | integer (int32) | Quantity |
Name | Data Type | Description |
---|---|---|
cumulative_order_limit | integer (int32) | Cumulative order limit |
exempt_from_minimum_item_count | boolean | Exempt from Minimum Item Count |
individual_order_limit | integer (int32) | Individual order limit |
multiple_quantity | integer (int32) | Multiple quantity |
payment_method_validity | array of string | Payment method validity
Allowed Values
|
Name | Data Type | Description |
---|---|---|
expirationDts | (read only) string (dateTime) | Expiration of the property |
name | string(100) | Property name |
value | string(1000) | Property value |
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 |
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 |
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
|
Name | Data Type | Description |
---|---|---|
report_as_upsell | boolean | Report as an upsell |
report_pickable_quantities | array of integer (int32) | Report pickable quantities (deprecated) |
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 |
warning | Warning | Warning object if a non-fatal issue or side-effect occurs |
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 |
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
|
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 |
Name | Data Type | Description |
---|---|---|
customer_profile_oid | integer (int32) | Customer profile object identifier |
featured | boolean | |
helperful_no_votes | integer (int32) | |
helpful_yes_votes | integer (int32) | |
merchant_reply | string(10000) | Merchant Reply (set to an empty string to remove) |
order_id | string | |
overall | number | |
rating_name1 | string(100) | Rating Name 1 |
rating_name10 | string(100) | Rating Name 10 |
rating_name2 | string(100) | Rating Name 2 |
rating_name3 | string(100) | Rating Name 3 |
rating_name4 | string(100) | Rating Name 4 |
rating_name5 | string(100) | Rating Name 5 |
rating_name6 | string(100) | Rating Name 6 |
rating_name7 | string(100) | Rating Name 7 |
rating_name8 | string(100) | Rating Name 8 |
rating_name9 | string(100) | Rating Name 9 |
rating_score1 | number | |
rating_score10 | number | |
rating_score2 | number | |
rating_score3 | number | |
rating_score4 | number | |
rating_score5 | number | |
rating_score6 | number | |
rating_score7 | number | |
rating_score8 | number | |
rating_score9 | number | |
recommend_store_to_friend | integer (int32) | |
recommend_to_friend | boolean | |
review | string(10000) | Review |
review_oid | integer (int32) | |
reviewed_nickname | string(25) | Nickname |
reviewer_email | string(100) | Reviewer Email |
reviewer_location | string(25) | Location |
status | string | Status of the review
Allowed Values
|
store_feedback | string(10000) | Store Feedback |
submitted_dts | string (dateTime) | Date/time of review submission |
title | string(250) | Title |
Name | Data Type | Description |
---|---|---|
error | Error | Error object if unsuccessful |
metadata | ResponseMetadata | Meta-data about the response such as payload or paging information |
review | ItemReview | Review |
success | boolean | Indicates if API call was successful |
warning | Warning | Warning object if a non-fatal issue or side-effect occurs |
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 |
individual_reviews | array of ItemReview | |
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 |
share_reviews_with_merchant_item_id | (read only) string | Share reviews with item id. To set, use the share_reviews_with_merchant_item_oid field. |
share_reviews_with_merchant_item_oid | integer (int32) | Share reviews with item oid. To null out this field, set teh value to zero. |
Name | Data Type | Description |
---|---|---|
error | Error | Error object if unsuccessful |
metadata | ResponseMetadata | Meta-data about the response such as payload or paging information |
reviews | array of ItemReview | reviews |
success | boolean | Indicates if API call was successful |
warning | Warning | Warning object if a non-fatal issue or side-effect occurs |
Name | Data Type | Description |
---|---|---|
sfdc_pricebook_id | string | Salesforce.com pricebook id |
sfdc_product_id | string | Salesforce.com product id |
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 |
collect_serial_numbers | boolean | This item is on pre-order |
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 |
hold_for_transmission | boolean | Hold for transmission |
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
|
ship_separately_width | Distance | Ship separately box width |
special_product_type | string | Special product type (USPS Media Mail)
Allowed Values
|
track_inventory | boolean | Track inventory |
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 |
Name | Data Type | Description |
---|---|---|
adult_signature_required | boolean | Adult Signature Required (only updated if not-null value provided) |
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 |
Name | Data Type | Description |
---|---|---|
country_code | string(2) | Country code (ISO-3166 two letter) |
state | string(32) | State |
validity | string | Validity
Allowed Values
|
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 |
cogs | (read only) number | Cost of goods sold override at the distribution center level |
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 |
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
|
signature_required | boolean | Signature required |
Name | Data Type | Description |
---|---|---|
package_name | string | Package name |
package_oid | integer (int32) | Package object identifier |
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 |
warning | Warning | Warning object if a non-fatal issue or side-effect occurs |
Name | Data Type | Description |
---|---|---|
tagType | string | tag_tpe
Allowed Values
|
tagValue | string(100) | tag_value |
Name | Data Type | Description |
---|---|---|
exemptions | array of ItemTaxExemption | Exemptions |
tax_free | boolean | True if tax free |
tax_product_type | string | Tax product type
Allowed Values
|
taxable_cost | number | Taxable cost if different than regular cost |
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 |
Name | Data Type | Description |
---|---|---|
add_tags | array of string | Add tags |
provider_name | string | Provider name
Allowed Values
|
remove_tags | array of string | Remove tags |
subscribe_lists | array of string | Subscribe to lists |
unsubscribe_lists | array of string | Unsubscribe from lists |
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 |
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 |
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 |
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 |
Name | Data Type | Description |
---|---|---|
allow_3rd_party_billing | boolean | Allow 3rd party billing |
allow_cod | boolean | Allow COD |
allow_purchase_order | boolean | Allow purchase order |
allow_quote_request | boolean | Allow quote request |
approval_notification | PricingTierNotification | Approval notification |
auto_approve_cod | boolean | Auto approve COD |
auto_approve_purchase_order | boolean | Auto approve purchase order |
currency_code | string | Any currency code specified on this pricing tier will force a shopping cart into that currency |
default_on_wholesale_signup | boolean | Default on wholesale signup |
default_percentage_discount | number | Default percentage discount |
default_shipping_method_oid | integer (int32) | Default shipping method oid |
default_tier | boolean | Default tier |
display_on_wholesale_signup | boolean | Display on wholesale signup |
exclude_from_free_promotion | boolean | Exclude from free promotion |
exempt_loyalty_rewards | boolean | Exempt from Loyalty Rewards |
exempt_shipping_handling_charge | boolean | Exempt shipping handling charge |
free_shipping | boolean | Free shipping |
free_shipping_minimum | number | Free shipping minimum |
maximum_item_count | integer (int32) | Maximum item count |
minimum_item_count | integer (int32) | Minimum item count |
minimum_subtotal | number | Minimum subtotal |
name | string(50) | Name |
no_coupons | boolean | No coupons |
no_free_shipping | boolean | No free shipping |
no_realtime_charge | boolean | No realtime charge |
not_valid_when_coupon_present | boolean | Not valid when coupon present |
pricing_tier_oid | integer (int32) | Pricing Tier Oid |
realtime_percentage_discount | number | Realtime percentage discount |
restrict_to_distribution_center_oid | integer (int32) | Restrict inventory to this distribution center oid |
signup_notification | PricingTierNotification | Signup notification |
suppress_buysafe | boolean | Suppress buySAFE (deprecated) |
suppress_mailing_list | boolean | Suppress mailing list |
tax_exempt | boolean | Tax Exempt |
track_separately | boolean | Track separately |
Name | Data Type | Description |
---|---|---|
format | string(16) | Notification format |
subject | string(100) | Notification subject |
text | string | Notification text |
Name | Data Type | Description |
---|---|---|
error | Error | Error object if unsuccessful |
metadata | ResponseMetadata | Meta-data about the response such as payload or paging information |
pricingTiers | array of PricingTier | pricing_tiers |
success | boolean | Indicates if API call was successful |
warning | Warning | Warning object if a non-fatal issue or side-effect occurs |
Name | Data Type | Description |
---|---|---|
payload_name | string | Payload name |
result_set | ResultSet | Result set |
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. |
Name | Data Type | Description |
---|---|---|
filename | string(75) | Filename |
height | (read only) integer (int32) | Height |
multimedia_type | string | Multimedia type
Allowed Values
|
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 |
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 |
warning | Warning | Warning object if a non-fatal issue or side-effect occurs |
Name | Data Type | Description |
---|---|---|
more_info | string | Additional information often a link to additional documentation |
warning_message | string | A technical message meant to be read by a developer |
Name | Data Type | Description |
---|---|---|
uom | string | Unit of measure
Allowed Values
|
value | number | Weight |
Name | Data Type | Description |
---|---|---|
UC-REST-ERROR | string | Contains human readable error message |
Name | Data Type |
---|---|
body | ErrorResponse |
Name | Data Type | Description |
---|---|---|
UC-REST-ERROR | string | Contains human readable error message |
Name | Data Type |
---|---|
body | ErrorResponse |
Name | Data Type | Description |
---|---|---|
UC-REST-ERROR | string | Contains human readable error message |
Name | Data Type |
---|---|
body | ErrorResponse |
Name | Data Type | Description |
---|---|---|
UC-REST-ERROR | string | Contains human readable error message |
Name | Data Type |
---|---|
body | ErrorResponse |
Name | Data Type | Description |
---|---|---|
UC-REST-ERROR | string | Contains human readable error message |
Name | Data Type |
---|---|
body | ErrorResponse |