Introduction

Getting Started

Call Reference

Pinnacle Api Docs

Introduction

Copyright Notice

Copyright 2009-2019, 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

Compliance

The PinnacleCart 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 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.

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 PinnacleCart application
Input:
GetVersionRequest
Output:
GetVersionResponse
return type
integer

PinnacleCart is eCommerce Shopping Cart Software that helps you sell more online. © 2009-2019