Introduction

Copyright Notice

Copyright 2009-2016, PinnacleCart, Inc.

Overview

This manual documents the calling conventions and functionality provided by the PinnacleCart API. This document is provided as a courtesy for PinnacleCart clients and developers who wish to integrate the software with their existing business operations or other software applications. It is intended for qualified software developers and assumes that the reader has some level of experience with HTTP, XML, JSON and other web-based technologies. We regret that we cannot provide support or assistance with the PinnacleCart API as part of our support services.

The PinnacleCart Unified API currently supports the following protocols: XML RPC, SOAP, and JSON. The API is permission based and allows access to product, order, and customer data. To use the API you need to create a username, password and generate an api security token. This is done through the control panel at the following location: Marketing » Cart Plugins » Data Export » Cart API.

You can also login to the control panel (administrative area) and direct your browser to: http://www.yoursitename.com/admin.php?p=plugin&plugin_id=openapi

Getting Started

Supported Protocols

SOAP/WSDL

SOAP, or Simple Object Access Protocol, is a protocol for exchanging information. It is a widely adopted standard for communication between web services and consumers.
Support for SOAP is built into almost every major IDE and/or framework upon which components expected to communicate with the web are built.
WSDL, or Web Services Description Language (WSDL, pronounced 'wiz-dəl'), is an XML-based language that provides a model for describing Web services.
SOAP Web-services are often described using WSDL.
The advantage of SOAP is its wide acceptence and strong-typing and predefined call description, which makes integration nearly automatic in many frameworks.
The disadvantage is, compared to XML or JSON, it is a bit more difficult for the average developer to use.

The pinnacle WSDL file can be found at:
https://www.YourSiteName.com/content/admin/plugins/openapi/index.php?username=YourApiUserName&password=YourApiPassword&token=YourApiToken&apiType=soap&wsdl=1

XML

XML, or eXtensible Markup Language, is a widely-used language for exhanging information.
Every major modern language/framework has an XML parser.
The advantage of XML is its wide acceptence and ease of use.

JSON

JSON, or Javascript Object Notation, is a widely-used language for exhanging information, usually bewteen web-clients and servers via AJAX.

Call Reference

This section lists the API calls currently available within the PinnacleCart API.
The calls are documented in a general sense, and not for any particular format or protocol.
Examples will be provided for specific protocols for your reference.

For most protocols, the inputs will be passed to the API via HTTP POST or GET headers.
For some protocols, such as SOAP, the inputs will be encapsulated in a typed object and passed via some other method (SOAP headers in the case of SOAP).

Please note: All API calls must be secure (https://)

Example Call: GetFoo

In the example below, the call is named GetFoo.
It has 2 inputs, Bar (a string) and Baz (an integer).
It has 2 outputs, FooOut1 (a string) and FooOut2 (a string).
Note that the input and output descriptions describe "request" and "response" types, which are only used for typed protocols that support encapsulated objects.

GetProductCount

GetProducts

Get your products based on the
passed criteria. The
ExtraArgs parameter provides a mechanism for
passing a wide assortment of criteria for getting
only the products you wish.

You MUST pass either the PrimaryCategory OR ExtraArgs.
If you pass PrimaryCategory, ExtraArgs will be ignored.

If you would like to get ALL products in ALL categories, you can
pass a PrimaryCategory of -1.
Or alternately, you can use "search" mode with no search criteria.

If you use ExtraArgs, you must pass at least the "mode" argument. The "mode" argument can bet set to "search", "home", "hot", "new", "manufacturer", or "catalog"

Input:

GetProductsRequest

StartNumber
DEPRECATED
type

integer
StartNumber is no longer used and has no functional effect. You may pass any integer as the value.

BatchSizetype

integer

BatchPagetype

integer

PrimaryCategorytype

integer

ExtraArgstype

string

For protocols where arguments are passed using HTTP POST or GET and the request object is not typed (such as XML-RPC),
ExtraArgs consists of any additional POST or GET argument that is passed.

For typed protocols (such as SOAP),
ExtraArgs is its own parameter which accepts a string array as a value.
The string array type is defined in the wsdl.
Each item in the array must be in the format of ArgName:ArgValue

ExtraArgs is meant to be a dynamic paramter to give you many options when getting your products.
Some of the available arguments are:

mode (search, home, hot, new, manufacturer, and catalog [default])

CatalogPriceRangeMin (float)

CatalogPriceRangeMax (float)

NOTE: CatalogPriceRangeMin and CatalogPriceRangeMax must be used together. You cannot specify just one of them

ProductGroup (integer)

Output:

GetProductsResponse

returntype

ApiProductArray

- array of type

ApiProduct

PID
type

integer

ProductId
type

string

Qoh
type

integer

Price
type

float

Cost
type

float

Taxable
type

string

Weight
type

float

UPC
type

string

Title
type

string

URL
type

string

ThumbnailImageUrl
type

string

ImageUrl
type

string

Discontinued
type

string

Options
type

ApiProductOptionArray

- array of type

ApiProductOption

Title
type

string

Caption
type

string

OptionId
type

string

Price
type

float

Type
type

string

Weight
type

float

Cost
type

string

Priority
type

string

Options
type

ApiProductOptionArray

- array of type

ApiProductOption

... is
recursive

Special input:

ExtraArgs

ExtraArgs is a special paramater

For protocols where arguments are passed using HTTP POST or GET and the request object is not typed (such as XML-RPC),
ExtraArgs consists of any additional argument that is passed.

For typed protocols (such as SOAP),
ExtraArgs is its own parameter which accepts a string array as a value.
Each item in the array wmust be in the format of ArgName:ArgValue

Note that in either case, each argument value can also pass a list of values by using comma seperators. Please reference the example below

Example usage

Protocol: XML

RequestIn the example below, "mode", "keywords", and "CatalogSortBy" are ExtraArgs