csharp
java
javascript
php
python
ruby
typescript

item

/item

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

Software Development Kit (SDK)

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

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

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

Instantiating the API

There are four steps to instantiating the API.

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

Expansion

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

Retrieve digital items from the digital library which are digital files that may be attached to normal items

Permissions:
  • item_read

Produces: application/json
get
/item/digital_library

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

Parameters
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
  • merchant_item_id
  • description
query string optional
_expand The object expansion to perform on the result. See documentation for examples query string optional
_placeholders Whether or not placeholder values should be returned in the result. Useful for UIs that consume this REST API. query boolean optional
Responses
Status Code Reason Response Model
200
Successful response ItemDigitalItemsResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500
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

Permissions:
  • item_write

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

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

Parameters
Parameter Description Location Data Type Required
digital_item Digital item to create body ItemDigitalItem required
Responses
Status Code Reason Response Model
200
Successful response ItemDigitalItemResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500
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

Permissions:
  • item_read

Produces: application/json
get
/item/digital_library/by_external/{external_id}

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

Parameters
Parameter Description Location Data Type Required
external_id The external id to match against. path string required
Responses
Status Code Reason Response Model
200
Successful response ItemDigitalItemsResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500
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);

Retrieve digital items from the digital library (which are digital files that may be attached to normal items) not yet associated with actual items

Permissions:
  • item_read

Produces: application/json
get
/item/digital_library/unassociated

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

Parameters
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
  • merchant_item_id
  • description
query string optional
_expand The object expansion to perform on the result. See documentation for examples query string optional
_placeholders Whether or not placeholder values should be returned in the result. Useful for UIs that consume this REST API. query boolean optional
Responses
Status Code Reason Response Model
200
Successful response ItemDigitalItemsResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500
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, which is a file within the digital library, not an actual merchant item

Permissions:
  • item_write

Produces: application/json
delete
/item/digital_library/{digital_item_oid}

Delete a digital item on the UltraCart account.

SDK Function Name: deleteDigitalItem

Parameters
Parameter Description Location Data Type Required
digital_item_oid The digital item oid to delete. path integer (int32) required
Responses
Status Code Reason Response Model
204
No Content
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500
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
        }
    }
}

Retrieve a digital item from the digital library, which are digital files that may be attached to normal items

Permissions:
  • item_read

Produces: application/json
get
/item/digital_library/{digital_item_oid}

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

Parameters
Parameter Description Location Data Type Required
digital_item_oid The digital item oid to retrieve. path integer (int32) required
Responses
Status Code Reason Response Model
200
Successful response ItemDigitalItemResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500
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

Permissions:
  • item_write

Consumes: application/json
Produces: application/json
put
/item/digital_library/{digital_item_oid}

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

Parameters
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
Responses
Status Code Reason Response Model
200
Successful response ItemDigitalItemResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500
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);
        }
    }
}

Retrieve items

Permissions:
  • item_read

Produces: application/json
get
/item/items

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

SDK Function Name: getItems

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

Permissions:
  • item_write

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

Create a new item on the UltraCart account.

SDK Function Name: insertItem

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

Permissions:
  • item_write

Consumes: application/json
Produces: application/json
put
/item/items/batch

Update multiple item on the UltraCart account.

SDK Function Name: updateItems

Parameters
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
Responses
Status Code Reason Response Model
200
Successful response ItemsResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500
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.

Permissions:
  • item_read

Produces: application/json
get
/item/items/inventory_snapshot

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

Responses
Status Code Reason Response Model
200
Successful response ItemInventorySnapshotResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500
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);

Retrieve an item by item id

Permissions:
  • item_read

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

Retrieves a single item using the specified item id.

SDK Function Name: getItemByMerchantItemId

Parameters
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
Responses
Status Code Reason Response Model
200
Successful response ItemResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500
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

Permissions:
  • item_write

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

Delete an item on the UltraCart account.

SDK Function Name: deleteItem

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

Retrieve an item

Permissions:
  • item_read

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

Retrieves a single item using the specified item oid.

SDK Function Name: getItem

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

Permissions:
  • item_write

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

Update a new item on the UltraCart account.

SDK Function Name: updateItem

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

Upsert an item content attribute

Permissions:
  • item_write

Consumes: application/json
Produces: application/json
post
/item/items/{merchant_item_oid}/content/attributes

Update an item content attribute, creating it new if it does not yet exist.

SDK Function Name: insertUpdateItemContentAttribute

Parameters
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
Responses
Status Code Reason Response Model
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500
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});
    }
}

Get reviews for an item

Permissions:
  • item_read

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

Retrieve item reviews.

SDK Function Name: getReviews

Parameters
Parameter Description Location Data Type Required
merchant_item_oid The item oid the review is associated with. path integer (int32) required
Responses
Status Code Reason Response Model
200
Successful response ItemReviewsResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500
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 review

Permissions:
  • item_write

Consumes: application/json
Produces: application/json
post
/item/items/{merchant_item_oid}/reviews

Insert a item review.

SDK Function Name: insertReview

Parameters
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
Responses
Status Code Reason Response Model
200
Successful response ItemReviewResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500
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 a review

Permissions:
  • item_write

Consumes: application/json
Produces: application/json
delete
/item/items/{merchant_item_oid}/reviews/{review_oid}

Delete an item review.

SDK Function Name: deleteReview

Parameters
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
Responses
Status Code Reason Response Model
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500
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
        });
    }
}

Get a review

Permissions:
  • item_read

Consumes: application/json
Produces: application/json
get
/item/items/{merchant_item_oid}/reviews/{review_oid}

Retrieve an item review.

SDK Function Name: getReview

Parameters
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
Responses
Status Code Reason Response Model
200
Successful response ItemReviewResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500
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 a review

Permissions:
  • item_write

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

Update an item review.

SDK Function Name: updateReview

Parameters
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
Responses
Status Code Reason Response Model
200
Successful response ItemReviewResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500
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);
        }
    }
}

Retrieve pricing tiers

Permissions:
  • item_read

Produces: application/json
get
/item/pricing_tiers

Retrieves the pricing tiers

SDK Function Name: getPricingTiers

Parameters
Parameter Description Location Data Type Required
_expand The object expansion to perform on the result. See documentation for examples query string optional
Responses
Status Code Reason Response Model
200
Successful response PricingTiersResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500
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);
    }
}

Upload an image to the temporary multimedia.

Permissions:
  • item_write

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

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

SDK Function Name: uploadTemporaryMultimedia

Parameters
Parameter Description Location Data Type Required
file File to upload formData file required
Responses
Status Code Reason Response Model
200
Successful response TempMultimediaResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500
// 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.

Webhooks

The following webhook events are generated for this resource.

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

Distance

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

Error

Attributes
Name Data Type Description
developer_message string A technical message meant to be read by a developer
error_code string HTTP status code
more_info string Additional information often a link to additional documentation
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

ErrorResponse

Attributes
Name Data Type Description
error Error Error object if unsuccessful
metadata ResponseMetadata Meta-data about the response such as payload or paging information
success boolean Indicates if API call was successful
warning Warning Warning object if a non-fatal issue or side-effect occurs

Item

Attributes
Name Data Type Description
accounting ItemAccounting Accounting such as QuickBooks codes
amember ItemAmember Amember configuration
auto_order ItemAutoOrder Auto Order
ccbill ItemCCBill CCBill.com (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

ItemAccounting

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

ItemAmember

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

ItemAutoOrder

Attributes
Name Data Type Description
auth_future_amount number Amount to try and authorize for the future rebill
auth_test_amount number Amount to try and test authorize
auto_order_cancel_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
  • Weekly
  • Every 10 Days
  • Biweekly
  • Every 24 Days
  • Every 28 Days
  • Monthly
  • Every 45 Days
  • Every 2 Months
  • Every 3 Months
  • Every 4 Months
  • Every 5 Months
  • Every 6 Months
  • Yearly
  • Every 4 Weeks
  • Every 6 Weeks
  • Every 8 Weeks
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

ItemAutoOrderStep

Attributes
Name Data Type Description
arbitrary_schedule_days integer (int32) If the schedule is arbitrary, then this is the number of days
arbitrary_unit_cost number Arbitrary unit cost used to override the regular item cost
arbitrary_unit_cost_schedules array of ItemAutoOrderStepArbitraryUnitCostSchedule Arbitrary unit costs schedules for more advanced discounting by rebill attempt
grandfather_pricing array of ItemAutoOrderStepGrandfatherPricing Grand-father pricing configuration if the rebill schedule has changed over time
managed_by string Managed by (defaults to UltraCart)
Allowed Values
  • UltraCart
  • CCBill
  • PayPal
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
  • Weekly
  • Every...
  • Every 10 Days
  • Biweekly
  • Every 24 Days
  • Every 28 Days
  • Monthly
  • Every 45 Days
  • Every 2 Months
  • Every 3 Months
  • Every 4 Months
  • Every 5 Months
  • Every 6 Months
  • Yearly
  • Every 4 Weeks
  • Every 6 Weeks
  • Every 8 Weeks
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
  • item
  • pause
  • loop
  • kit only
  • pause until

ItemAutoOrderStepArbitraryUnitCostSchedule

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

ItemAutoOrderStepGrandfatherPricing

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

ItemCCBill

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

ItemChannelPartnerMapping

Attributes
Name Data Type Description
barcode_ua string Barcode UA (EDI only)
barcode_uc string Barcode UC (EDI only)
barcode_ui string Barcode UI (EDI only)
barcode_uk string Barcode UK (EDI only)
buyer_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)

ItemChargeback

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

ItemChargebackAddendum

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

ItemChargebackAdjustmentRequest

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

ItemCheckout

Attributes
Name Data Type Description
suppress_buysafe boolean True to suppress buySAFE (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

ItemContent

Attributes
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)

ItemContentAssignment

Attributes
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

ItemContentAttribute

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

ItemContentMultimedia

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

ItemContentMultimediaThumbnail

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

ItemDigitalDelivery

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

ItemDigitalItem

Attributes
Name Data Type Description
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

ItemDigitalItemPdfMeta

Attributes
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

ItemDigitalItemResponse

Attributes
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

ItemDigitalItemsResponse

Attributes
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

ItemEbay

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

ItemEbayCategorySpecific

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

ItemEbayMarketListing

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

ItemEbayMarketPlaceAnalysis

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

ItemEmailNotifications

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

ItemEnrollment123

Attributes
Name Data Type Description
enrollment123_product_code string Enrolment 123 product code

ItemFulfillmentAddon

Attributes
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

ItemGiftCertificate

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

ItemGoogleProductSearch

Attributes
Name Data Type Description
adwords_grouping string(50) Adwords grouping
adwords_label1 string(50) Adwords label 1
adwords_label2 string(50) Adwords label 2
adwords_label3 string(50) Adwords label 3
adwords_label4 string(50) Adwords label 4
adwords_label5 string(50) Adwords label 5
age_group string(5) Age group
available_at_physical_store boolean Available at physical store
book_author string(50) Book - author
book_format string(50) Book - format
book_isbn string(20) Bood - ISBN
book_publisher string(50) Book - publisher
category_description string(1000) Category description
color string(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

ItemIdentifiers

Attributes
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

ItemInstantPaymentNotification

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

ItemInstantPaymentNotifications

Attributes
Name Data Type Description
notifications array of ItemInstantPaymentNotification Notifications

ItemInternal

Attributes
Name Data Type Description
memo string(250) Memo

ItemInventorySnapshot

Attributes
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)

ItemInventorySnapshotDistributionCenter

Attributes
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)

ItemInventorySnapshotResponse

Attributes
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

ItemKitComponent

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

ItemKitDefinition

Attributes
Name Data Type Description
components array of ItemKitComponent Components

ItemOption

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

ItemOptionValue

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

ItemOptionValueAdditionalItem

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

ItemOptionValueDigitalItem

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

ItemPaymentProcessing

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

ItemPhysical

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

ItemPricing

Attributes
Name Data Type Description
allow_arbitrary_cost boolean Allow arbitrary cost
arbitrary_cost_velocity_code string(10000) Arbitrary cost velocity code
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
  • ARS
  • AUD
  • BRL
  • CAD
  • CHF
  • COP
  • EUR
  • GBP
  • JPY
  • MXN
  • MYR
  • NOK
  • NZD
  • RUB
  • SEK
  • SGD
  • TRY
  • USD
manufacturer_suggested_retail_price number Manufacturer suggested retail price
maximum_arbitrary_cost number Maximum arbitrary cost
minimum_advertised_price number Minimum advertised price
minimum_arbitrary_cost number Minimum arbitrary cost
mix_and_match_group string Mix and match group
mix_and_match_group_oid integer (int32) Mix and match group object identifier
sale_cost number Sale cost
sale_end string (dateTime) If sale_cost specified
Sale end
sale_start string (dateTime) If sale_cost specified
Sale start
tiers array of ItemPricingTier Tiers

ItemPricingTier

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

ItemPricingTierDiscount

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

ItemPricingTierLimit

Attributes
Name Data Type Description
cumulative_order_limit integer (int32) Cumulative order limit
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
  • +Affirm
  • -Affirm
  • +Amazon
  • -Amazon
  • +AMEX
  • -AMEX
  • +CASH
  • -CASH
  • +Check
  • -Check
  • +COD
  • -COD
  • +Diners Club
  • -Diners Club
  • +Discover
  • -Discover
  • +eCheck
  • -eCheck
  • +JCB
  • -JCB
  • +LoanHero
  • -LoanHero
  • +MasterCard
  • -MasterCard
  • +Money Order
  • -Money Order
  • +PayPal
  • -PayPal
  • +Purchase Order
  • -Purchase Order
  • +Quote Request
  • -Quote Request
  • +VISA
  • -VISA
  • -Wire Transfer
  • +Wire Transfer

ItemProperty

Attributes
Name Data Type Description
expirationDts (read only) string (dateTime) Expiration of the property
name string(100) Property name
value string(1000) Property value

ItemRealtimePricing

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

ItemRelated

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

ItemRelatedItem

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

ItemReporting

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

ItemResponse

Attributes
Name Data Type Description
error Error Error object if unsuccessful
item Item Item
metadata ResponseMetadata Meta-data about the response such as payload or paging information
success boolean Indicates if API call was successful
warning Warning Warning object if a non-fatal issue or side-effect occurs

ItemRestriction

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

ItemRestrictionItem

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

ItemRevguard

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

ItemReview

Attributes
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
  • approved
  • unapproved
  • rejected
  • multimedia processing
store_feedback string(10000) Store Feedback
submitted_dts string (dateTime) Date/time of review submission
title string(250) Title

ItemReviewResponse

Attributes
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

ItemReviews

Attributes
Name Data Type Description
has_approved_review (read only) boolean True if the item has an approved review
has_review (read only) boolean True if the item has a review
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.

ItemReviewsResponse

Attributes
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

ItemSalesforce

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

ItemShipping

Attributes
Name Data Type Description
allow_back_order boolean Allow back order
amazon_fba boolean Fulfillment by Amazon.com
case_inner_packs integer (int32) Case inner packs
case_units integer (int32) Case units
cases array of ItemShippingCase Cases
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
  • Crate
  • FedEx: Box
  • FedEx: Small Box
  • FedEx: Medium Box
  • FedEx: Large Box
  • FedEx: Extra Large Box
  • FedEx: Envelope
  • FedEx: Pak
  • FedEx: Tube
  • Pallet Other
  • Pallet 48 x 40
  • Pallet 48 x 48
  • Pallet 60 x 48
  • Pallet 120 x 80
  • Pallet 120 x 100
  • Pallet 120 x 120
  • UPS: Express Box
  • UPS: Letter
  • UPS: Pak
  • UPS: Tube
  • USPS: Express Mail Flat Rate Envelope
  • USPS: Express Mail Padded Flat Rate Envelope
  • USPS: Priority Mail Medium Flat Rate Box
  • USPS: Priority Mail Large Flat Rate Box
  • USPS: Priority Mail Small Flat Rate Box
  • USPS: Priority Mail Regional Rate A Box
  • USPS: Priority Mail Regional Rate B Box
  • USPS: Priority Mail Regional Rate C Box
  • USPS: Priority Mail Flat Rate Envelope
  • USPS: Priority Mail Padded Flat Rate Envelope
  • USPS: Priority Mail Legal Flat Rate Envelope
ship_separately_width Distance Ship separately box width
special_product_type string Special product type (USPS Media Mail)
Allowed Values
  • Book or Software
  • Music
  • Editorial
track_inventory boolean Track inventory

ItemShippingCase

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

ItemShippingDestinationMarkup

Attributes
Name Data Type Description
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

ItemShippingDestinationRestriction

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

ItemShippingDistributionCenter

Attributes
Name Data Type Description
allocated_to_placed_orders (read only) number Allocated to placed orders
allocated_to_shopping_carts (read only) number Allocated to shopping carts
available_to_allocate (read only) number Available to allocate
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

ItemShippingMethod

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

ItemShippingPackageRequirement

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

ItemsRequest

Attributes
Name Data Type Description
items array of Item items

ItemsResponse

Attributes
Name Data Type Description
error Error Error object if unsuccessful
items array of Item items
metadata ResponseMetadata Meta-data about the response such as payload or paging information
success boolean Indicates if API call was successful
warning Warning Warning object if a non-fatal issue or side-effect occurs

ItemTag

Attributes
Name Data Type Description
tagType string tag_tpe
Allowed Values
  • item
  • order
  • customer
tagValue string(100) tag_value

ItemTags

Attributes
Name Data Type Description
tags array of ItemTag tags

ItemTax

Attributes
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
  • digital
  • physical
  • service
taxable_cost number Taxable cost if different than regular cost

ItemTaxExemption

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

ItemThirdPartyEmailMarketing

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

ItemVariantItem

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

ItemVariation

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

ItemVariationOption

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

ItemWishlistMember

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

PricingTier

Attributes
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

PricingTierNotification

Attributes
Name Data Type Description
format string(16) Notification format
subject string(100) Notification subject
text string Notification text

PricingTiersResponse

Attributes
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

ResponseMetadata

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

ResultSet

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

TempMultimedia

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

TempMultimediaResponse

Attributes
Name Data Type Description
error Error Error object if unsuccessful
metadata ResponseMetadata Meta-data about the response such as payload or paging information
success boolean Indicates if API call was successful
temp_multimedia TempMultimedia Temporary multimedia
warning Warning Warning object if a non-fatal issue or side-effect occurs

Warning

Attributes
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

Weight

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

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

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

401
Status Code 401: invalid credentials supplied

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

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

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

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

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

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

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