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
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
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
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
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
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
Output:
GetOrderCountResponse
GetOrders
Description:
Get all of your orders based on
the passed criteria
Input:
GetOrdersRequest
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
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.
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&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