Introduction

Copyright Notice

Overview

This manual documents the calling conventions and functionality provided by the Pinnacle Cart API. This document is provided as a courtesy for Pinnacle Cart 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 Pinnacle Cart API as part of our support services.

The Pinnacle Cart 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

Compliance

The Pinnacle Cart Unified API meets the requirements necessary to maintain PA-DSS / PCI compliance as set forth by the PCI Security Standards Council. More detailed information about this standard can be found at: https://www.pcisecuritystandards.org/security_standards/pci_pa_dss.shtml

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.

API URL Structure

https://www.YourSiteName.com/content/admin/plugins/openapi/index.php?username=<YourApiUserName>&password=<YourApiPassword>&token=<YourApiToken>&apiType=<xml|soap|json>&call=<CallName>&<Arg1>=<Arg1Value>&<Arg2>=<Arg2Value>&<Arg3>=<Arg3Value>...

Call Reference

This section lists the API calls currently available within the Pinnacle Cart 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.

Description:

Gets all of the foos in the bar

Input:

GetFooRequest

Bar type

integer

Baz type

integer

Output:

GetFooResponse

return type

ApiFooOut

FooOut1 type
string
FooOut2 type
string

Example usage

Protocol: XML

Request

https://www.YourSiteName.com/content/admin/plugins/openapi/index.php?username=YourApiUserName&password=YourApiPassword&token=YourApiToken&apiType=xml&call=GetFoo&Bar=1&Baz=myBazValue

Response

<Response>
    <FooOut>
        <FooOut1>This is the fooout1 value</FooOut1>
        <FooOut2>This is the fooout2 value</FooOut2>
    </FooOut>
</Response>

GetCustomerCount

Description:

Get the total number of customers

Input:

GetCustomerCountRequest

Output:

GetCustomerCountResponse

return type

integer

Example usage

Protocol: XML

Request

https://www.YourSiteName.com/content/admin/plugins/openapi/index.php?username=YourApiUserName&password=YourApiPassword&token=YourApiToken&apiType=xml&call=GetCustomerCount

Response

<Response>5734</Response>

GetCustomers

Description:

Get all of your customers

Input:

GetCustomersRequest

StartNumber type

integer

BatchSize type

integer

Output:

GetCustomersResponse

return type

ApiCustomerArray

- array of type

ApiCustomer

UserId type
integer
UserName type
string
Billing type
ApiBillingInfo
- FullName type
  string
- FirstName type
  string
- LastName type
  string
- Email type
  integer
- Company type
  integer
- Phone type
  integer
- Address type
  ApiAddress
  - Name type
    string
  - Street1 type
    string
  - Street2 type
    string
  - City type
    string
  - State type
    string
  - Zip type
    string
  - Country type
    string
AddressBook type
ApiAddressArray
- array of type
ApiAddress
- Name type
  string
- Street1 type
  string
- Street2 type
  string
- City type
  string
- State type
  string
- Zip type
  string
- Country type
  string

Example usage

Protocol: XML

Request

https://www.YourSiteName.com/content/admin/plugins/openapi/index.php?username=YourApiUserName&password=YourApiPassword&token=YourApiToken&apiType=xml&call=GetCustomers&StartNumber=0&BatchSize=100

Response

<Response>
  <Customer>
    <UserId>1</UserId>
    <UserName>John</UserName>
    <BillingInfo>
      <FullName>John Doe</FullName>
      <FirstName>John</FirstName>
      <LastName>Doe</LastName>
      <Email>johndoe@johnsdomain.com</Email>
      <Company></Company>
      <Phone>6025551212</Phone>
      <Address>
        <Name></Name>
        <Street1>786876 West test Street</Street1>
        <Street2></Street2>
        <City>Phoenix</City>
        <State>AZ</State>
        <Zip>85050</Zip>
        <Country>US</Country>
      </Address>
    </BillingInfo>
    <AddressBook>
      <Address>
        <Name>John Doe</Name>
        <Street1>786876 West test Street</Street1>
        <Street2></Street2>
        <City>Phoenix</City>
        <State>AZ</State>
        <Zip>85050</Zip>
        <Country>US</Country>
      </Address>
    </AddressBook>
  </Customer>
  <Customer>
    <UserId>2</UserId>
    <UserName>Jane</UserName>
    <BillingInfo>
      <FullName>Jane Doe</FullName>
      <FirstName>Jane</FirstName>
      <LastName>Doe</LastName>
      <Email>janedoe@janesdomain.com</Email>
      <Company></Company>
      <Phone>6025551212</Phone>
      <Address>
        <Name></Name>
        <Street1>5452 East test Lane</Street1>
        <Street2></Street2>
        <City>Phoenix</City>
        <State>AZ</State>
        <Zip>85050</Zip>
        <Country>US</Country>
      </Address>
    </BillingInfo>
    <AddressBook>
      <Address>
        <Name>Jane Doe</Name>
        <Street1>PO Box 5565</Street1>
        <Street2></Street2>
        <City>Phoenix</City>
        <State>AZ</State>
        <Zip>85050</Zip>
        <Country>US</Country>
      </Address>
    </AddressBook>
  </Customer>
</Response>

GetInventory

Description:

Get your store inventory

Input:

GetInventoryRequest

StartNumber type

integer

BatchSize type

integer

Output:

GetInventoryResponse

return type

ApiProductQohArray

- array of type

ApiProductQoh

PID type
integer
Qoh type
integer
ProductId type
string

GetOrderCount

Description:

Get the total number of order that match the passed criteria

Input:

GetOrderCountRequest

Status type

string

CustomerId type

integer

LastOrder type

integer

LastDate type

string

Output:

GetOrderCountResponse

return type

integer

GetOrders

Description:

Get all of your orders based on the passed criteria

Input:

GetOrdersRequest

Status type

string

CustomerId type

integer

LastOrder type

integer

LastDate type

string

StartNumber type

integer

BatchSize type

integer

Output:

GetOrdersResponse

return type

ApiOrderArray

- array of type

ApiOrder

OrderId type
integer
OrderNumber type
integer
OrderDate type
string
Status type
string
StatusDate type
string
PaymentMethod type
string
PaymentStatus type
string
ShippingCarrierId type
string
ShippingMethodId type
string
ShippingMethodName type
string
ShippingAmount type
float
ShippingTaxable type
string
ShippingTaxRate type
float
ShippintTaxAmount type
float
ShippingTaxDescription type
string
HandlingSeparated type
string
HandlingFee type
float
HandlingFeeType type
string
HandlingAmount type
float
HandlingTaxable type
string
HandlingTaxRate type
float
HandlingTaxAmount type
float
HandlingTaxDescription type
string
HandlingText type
string
SubtotalAmount type
float
DiscountAmount type
float
DiscountValue type
float
DiscountType type
string
PromoDiscountAmount type
float
PromoDiscountValue type
float
PromoDiscountType type
string
TaxAmount type
float
TotalAmount type
float
GiftMessage type
string
Billing type
ApiBillingInfo
- FullName type
  string
- FirstName type
  string
- LastName type
  string
- Email type
  integer
- Company type
  integer
- Phone type
  integer
- Address type
  ApiAddress
  - Name type
    string
  - Street1 type
    string
  - Street2 type
    string
  - City type
    string
  - State type
    string
  - Zip type
    string
  - Country type
    string
Shipping type
ApiShippingInfo
- FullName type
  string
- Email type
  integer
- Company type
  integer
- Phone type
  integer
- Address type
  ApiAddress
  - Name type
    string
  - Street1 type
    string
  - Street2 type
    string
  - City type
    string
  - State type
    string
  - Zip type
    string
  - Country type
    string
OrderItems type
ApiOrderItemArray
- array of type
ApiOrderItem
- PID type
  integer
- Quantity type
  integer
- Price type
  float
- Taxable type
  string
- Weight type
  float
- FreeShipping type
  string
- ShippingPrice type
  float
- TaxRate type
  float
- TaxDescription type
  string
- DigitalProduct type
  string
- UpdatedQuanity type
  integer
- UpdatedPrice type
  float
- ProductId type
  string
- ProductSubId type
  string
- SKU type
  string
- UPC type
  string
- Title type
  string
- LineItemWeight type
  float
- ProductWeight type
  float
- Options type
  ApiOrderItemOptionArray
  - array of type
  ApiOrderItemOption
  - Title type
    string
  - SelectedOption type
    string
  - Price type
    float
  - Weight type
    float

GetCategories

Description:

Get all of the product categories

Input:

GetCategoriesRequest

Output:

GetCategoriesResponse

return type

ApiProductCategoryArray

Title type
string
CategoryId type
string
Children
ApiProductCategoryArray

GetProductCount

Description:

Get the total number of products

Input:

GetProductCountRequest

Output:

GetProductCountResponse

return type

integer

GetProducts

Description:

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.

BatchSize type

integer

BatchPage type

integer

PrimaryCategory type

integer

ExtraArgs type

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

return type

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

Request In the example below, "mode", "keywords", and "CatalogSortBy" are ExtraArgs

https://www.YourSiteName.com/content/admin/plugins/openapi/index.php?username=YourApiUserName&password=YourApiPassword&token=YourApiToken&apiType=xml&call=GetProducts&BatchSize=100&mode=search&keywords=test1,or,test2,or,test3,or,Widget1&CatalogSortBy=title

Response

<Response>
  <Product>
    <Price>23.00000</Price>
    <Cost>12.00000</Cost>
    <Taxable>Yes</Taxable>
    <Weight>23.30</Weight>
    <UPC>12312313</UPC>
    <Title>Widget1</Title>
    <URL>
    http://www.YourSiteName.com/evan/index.php?p=product&amp;id=1</URL>
    <ThumbnailImageUrl>
    http://www.YourSiteName.com/evanimages/products/thumbs/widget1.jpg</ThumbnailImageUrl>
    <ImageUrl>
    http://www.YourSiteName.com/evanimages/products/widget1.jpg</ImageUrl>
    <Discontinued>No</Discontinued>
    <Options>
      <ProductOption>
        <Title>sdfgsdfg</Title>
        <Caption>sdfg sdfgsdg</Caption>
        <OptionId>1</OptionId>
        <Type>select</Type>
        <Price>0</Price>
        <Cost>0</Cost>
        <Weight></Weight>
        <Priority>5</Priority>
        <Options>
          <ProductOption>
            <Title>Small</Title>
            <Caption></Caption>
            <OptionId>1-Small</OptionId>
            <Type></Type>
            <Price>-25.00</Price>
            <Cost>-25.00</Cost>
            <Weight>-0.25</Weight>
            <Priority>1</Priority>
            <Options></Options>
          </ProductOption>
          <ProductOption>
            <Title>Medium</Title>
            <Caption></Caption>
            <OptionId>1-Medium</OptionId>
            <Type></Type>
            <Price>-2.30</Price>
            <Cost>-2.30</Cost>
            <Weight>1.00</Weight>
            <Priority>2</Priority>
            <Options></Options>
          </ProductOption>
          <ProductOption>
            <Title>Large</Title>
            <Caption></Caption>
            <OptionId>1-Large</OptionId>
            <Type></Type>
            <Price>0.00</Price>
            <Cost>0.00</Cost>
            <Weight>2.00</Weight>
            <Priority>3</Priority>
            <Options></Options>
          </ProductOption>
          <ProductOption>
            <Title>X-Large</Title>
            <Caption></Caption>
            <OptionId>1-X-Large</OptionId>
            <Type></Type>
            <Price>10.00</Price>
            <Cost>10.00</Cost>
            <Weight>0.00</Weight>
            <Priority>4</Priority>
            <Options></Options>
          </ProductOption>
        </Options>
      </ProductOption>
    </Options>
    <PID>1</PID>
    <ProductId>Widget1</ProductId>
    <Qoh>343</Qoh>
  </Product>
</Response>

GetVersion

Description:

Get the version number of the Pinnacle Cart application

Input:

GetVersionRequest

Output:

GetVersionResponse

return type

integer