Difference between revisions of "Channel Advisor WebServices Plugin/Documentation"
WikiEditTask (talk | contribs) m (Auto-upload documentation) |
WikiEditTask (talk | contribs) m (Auto-upload documentation) |
||
Line 266: | Line 266: | ||
<li>length (new in version 2)</li> | <li>length (new in version 2)</li> | ||
<li>width (new in version 2)</li> | <li>width (new in version 2)</li> | ||
+ | <li>labels (Specifies the list of Labels to add or remove from the Inventory Item. If you wish to REMOVE a Label from the Item, simply specify the name of the Label prefixed by a minus sign.)</li> | ||
</ul> | </ul> | ||
Latest revision as of 13:09, 20 October 2014
Channel Advisor WebServices Plugin User Guide
Integrates FileMaker with ChannelAdvisor.
Related Links
<a href="http://developer.channeladvisor.com/display/cadn/FAQ">http://developer.channeladvisor.com/display/cadn/FAQ</a>
360Works Plugin Setup Guides
See Plugins_101 for Error reporting, installation, registration, and more.
Function Summary
- CHA_AddInventoryImage ( placementName ; filenameOrUrl { ; folderName } ) — Adds an image to the most recently added inventory item, as sent to CHA_InventorySyncAdd.
- CHA_AddMarketplaceAdForSkuList ( developerKey ; password ; accountId ; skuList { ; key1=value1 ; key2=value2 ; ... } ) — Creates a new Marketplace Ad for each SKU provided in the parameter array.
- CHA_CarrierList ( developerKey ; password ; accountId ) — Returns carrier lists.
- CHA_CarrierValue ( key ) — Gets a carrier value for the current carrier, as set by {@link #CHA_NextCarrier}.
- CHA_DeleteInventory ( developerKey ; password ; accountId ; sku ) — Deletes an inventory item from ChannelAdvisor.
- CHA_DeleteMarketplaceAd ( developerKey ; password ; accountId ; marketplaceAdId ) —
- CHA_DistributionCenterList ( developerKey ; password ; accountId ) — Returns all distribution centers as
code: name
values separated by newlines. - CHA_GetClassificationConfigurationInformation ( developerKey ; password ; accountId ) — Fetch all classification user-defined fields for an account.
- CHA_InventoryList ( developerKey ; password ; accountID ; filter1=value1 ; filter2=value2 ; ... ) — Fetches inventory from the ChannelAdvisor server.
- CHA_InventorySyncAdd ( sku { ; key1=value1 ; key2=value2 ; ... ) — Add an inventory item to the current sync batch.
- CHA_InventorySyncBegin ( ) — Call this before beginning the inventory synchronization process.
- CHA_InventorySyncClassificationInfo ( name ; value ) — Sets a single classification attribute on the most recently added inventory item created via CHA_InventorySyncAdd.
- CHA_InventorySyncCommit ( developerKey ; password ; accountId ) — Commits any inventory items in the current sync batch.
- CHA_InventoryValue ( key ) — Returns a specific value for the current inventory, as set by {@link #CHA_NextInventory()}.
- CHA_LastError ( ) — Returns the last CHA_-related error which occurred.
- CHA_LicenseInfo ( ) — Returns information about the license used.
- CHA_LineItemValue ( key ) — Gets a line item value for the currently iterated line item, as set by {@link #CHA_NextLineItem}.
- CHA_NextCarrier ( ) — Iterate to the next carrier, as returned by {@link #CHA_CarrierList(String, String, String)}.
- CHA_NextInventory ( ) — Iterate to the next inventory, as returned by {@link #CHA_InventoryList(String, String, String, String[])}.
- CHA_NextLineItem ( ) — Iterates to the next line item for the current order.
- CHA_NextOrder ( ) — Iterate to the next order fetched with {@link #CHA_OrderList}.
- CHA_OrderLineItemInvoiceWithKey ( key ) — Returns a value from the current order
lineItemInvoiceList.
- CHA_OrderList ( developerKey ; password ; accountID { ; filter1=value1 ; filter2=value2 ; ... ) — Fetches orders from the ChannelAdvisor server.
- CHA_OrderShipped ( developerKey ; password ; accountID ; orderID ; dateShipped ; carrierCode ; classCode ; trackingNumber { ; shipmentCost ; insuranceCost ; fulfillmentId ; shipmentTaxCost } ) — Marks an existing order with a status of shipped.
- CHA_OrderShippedPartial ( developerKey ; password ; accountID ; orderID ; dateShipped ; carrierCode ; classCode ; trackingNumber ; shipmentCost ; insuranceCost ; fulfillmentId ; shipmentTaxCost ; lineItems ) —
- CHA_OrderValue ( key ) — Gets an order value from the current order, as set by {@link #CHA_NextOrder}.
- CHA_Ping ( developerKey ; password ) — This should be the first method you use when you connect to any service, to make sure that your connectivity and credentials are working properly.
- CHA_Register ( licenseKey ; registeredTo ) — Registers the plugin.
- CHA_SetErrorCapture ( errorCapture ) —
- CHA_Version ( ) — Returns the version of the plugin which is installed.
Function Detail
CHA_AddInventoryImage ( placementName ; filenameOrUrl { ; folderName } )
Adds an image to the most recently added inventory item, as sent to CHA_InventorySyncAdd. You must add the inventory item, then call this method to add the image for that item
Parameters:
placementName
- Specifies the Image Placement for this Image when associating with the Inventory Item (required). This is typically one of: top, bottom, left, right
filenameOrUrl
- Specifies the source of the Image (required). Specifying a simple Filename assumes that you will OR have already uploaded the specified Image into your Account
folderName
- Specifies the Image Folder to associate with this Image (optional)
See also: CHA_InventorySyncAdd
Returns: 1 if the image was successfully added, "ERROR" if an error occurred (use the CHA_LastError function to get a detailed error message).
CHA_AddMarketplaceAdForSkuList ( developerKey ; password ; accountId ; skuList { ; key1=value1 ; key2=value2 ; ... } )
Creates a new Marketplace Ad for each SKU provided in the parameter array.
This returns a list of skus, followed by the numeric identifier of the newly created marketplace ad. For example:
sku12344:8650952
sku12347:8650953
sku12348:8650959
etc...
If any skus are not successfully uploaded, you can get a list of the skus and their error messages by calling CHA_LastError. This will return a list of skus and error messages, for example:
sku12345:Unknown sku
sku12346:Marketplace ad denied for some reason
sku12323:Unknown sku
etc...
You can specify additional parameters with the following keys:
- postingTemplate
- adTemplate
- schedule
- flagstyle: one of "blueflag", "exclamationpoint", "greenflag", "noflag", "notavailable", "price", "questionmark", "redflag", "yellowflag"
- flagDescription
- primaryCategory: If the associated Posting Template already has a Primary Category specified, then this property will be defaulted to that value.
- secondaryCategory: If the associated Posting Template already has a Primary Category specified, then this property will be defaulted to that value.
- primaryStoreCategory: If the associated Posting Template already has a Primary Category specified, then this property will be defaulted to that value.
- secondaryStoreCategory: If the associated Posting Template already has a Primary Category specified, then this property will be defaulted to that value.
Parameters:
developerKey
- Your ChannelAdvisor developer key
password
- Your ChannelAdvisor password
accountID
- The accountID to create ads for
skuList
- a return-separated list of SKus
keyValuePairs
- additional parameters
Returns: the number of sku ads which were successfully processed.
CHA_CarrierList ( developerKey ; password ; accountId )
Returns carrier lists.
Parameters:
developerKey
-
password
-
accountID
-
Returns:
CHA_CarrierValue ( key )
Gets a carrier value for the current carrier, as set by CHA_NextCarrier.
key
must be one of the following values:
- carrierId: Numeric identifier for a shipping carrier
- classId: Numeric identifier for a shipping carrier class
- carrierName: Name for a carrier
- carrierCode: String identifier for a carrier. This is used in other shipping api calls to identify a carrier.
- classCode: String identifier for a carrier class. This is used in shipping api calls to identify a carrier class.
- className: Name for a carrier class.
Parameters:
key
- name of the property to retrieve from the current carrier.
Returns: the value of the key
field for the current carrier. Returns "ERROR" on error (use the CHA_LastError function to get a detailed error message).
CHA_DeleteInventory ( developerKey ; password ; accountId ; sku )
Deletes an inventory item from ChannelAdvisor.
Parameters:
developerKey
- Your ChannelAdvisor developer key
password
- Your ChannelAdvisor password
accountId
- The accountId to delete inventory from
sku
- The sku being deleted
Returns: 1 if the image was successfully added, "ERROR" if an error occurred (use the CHA_LastError function to get a detailed error message).
CHA_DeleteMarketplaceAd ( developerKey ; password ; accountId ; marketplaceAdId )
Parameters:
developerKey
- Your ChannelAdvisor developer key
password
- Your ChannelAdvisor password
accountID
- A unique identifier representing the ChannelAdvisor account you wish to access.
marketplaceAdId
- The unique identifier for the Marketplace Ad returned when the Ad was created.
Returns: 1 on success, "ERROR" if an error occurred (use the CHA_LastError function to get a detailed error message).
CHA_DistributionCenterList ( developerKey ; password ; accountId )
Returns all distribution centers as code: name
values separated by newlines.
Parameters:
developerKey
- Your ChannelAdvisor developer key
password
- Your ChannelAdvisor password
accountID
- A unique identifier representing the ChannelAdvisor account you wish to access.
Returns: return-separated list of distribution centers.
CHA_GetClassificationConfigurationInformation ( developerKey ; password ; accountId )
Fetch all classification user-defined fields for an account. This returns a return-separated list of classification names, followed by attribute names. classification names after the first are prefaced by an empty line. For example:
class1
attr1
attr2
attr3
class2
attrA
attrB
attrC
class3
etc...
Parameters:
developerKey
- Your ChannelAdvisor developer key
password
- Your ChannelAdvisor password
accountID
- Your ChannelAdvisor account ID
Returns: the a return-separate list of classification definitions, or "ERROR" on error (use the CHA_LastError function to get a detailed error message).
CHA_InventoryList ( developerKey ; password ; accountID ; filter1=value1 ; filter2=value2 ; ... )
Fetches inventory from the ChannelAdvisor server.
You can specify optional filters with the following keys:
- dateRangeField: Either "createdate" or "lastupdatedate" - Specifies the Date Field property of an Inventory Item to filter on. MUST be set in order to use the DateRangeStartGMT and DateRangeEndGMT fields.
- dateRangeStartGMT
- dateRangeEndGMT
Parameters:
developerKey
- Your ChannelAdvisor developer key
password
- Your ChannelAdvisor password
accountID
- Your ChannelAdvisor account ID
filters
- key=value filter options
Returns: the number of inventory items found, or "ERROR" on error (use the CHA_LastError function to get a detailed error message).
CHA_InventorySyncAdd ( sku { ; key1=value1 ; key2=value2 ; ... )
Add an inventory item to the current sync batch.
The following are the valid key values for the optional inventory arguments (see http://developer.channeladvisor.com/display/cadn/InventoryItemSubmit for descriptions):
- title: The title specified here will be used as the title for any ads you create for this inventory item.
- subtitle: This field can be used as subtitle in the store or in any ads you create for this inventory item.
- shortdescription: The short description is used to describe items in the Upsell portion of the ChannelAdvisor Checkout. Depending on the Search Layout, it can also appear in the search results page of your ChannelAdvisor store. This description should be limited to 1000 characters.
- description: The description field may contain information use to describe the inventory item when it is posted to the marketplace.
- metadescription: Use this field to provide the description for the item that will appear in the description meta tag on the item detail page in the store. If this field is left blank, the first 200 characters of the store description will be used. Search engine crawlers look at the description meta tag to understand the meaning of that page.
- weight (should be a decimal number with no unit of measure): Enter the weight of this item. This weight will be used to calculate shipping costs if you are using the Third Party Shipping Calculator in your ads or for the Checkout.
- suppliercode
- warehouselocation: Identify the physical location of an item inside your company warehouse. This code is generally made up of an aisle, shelf or bin drawer location.
- taxproductcode
- flagtype: one of "blueflag", "exclamationpoint", "greenflag", "noflag", "notavailable", "price", "questionmark", "redflag", "yellowflag"
- flagdescription
- blocked
- blockcomment
- qty: The quantity should indicate the total number of units available for sale for this item.
- cost
- retailprice
- startingprice
- reserveprice
- takeitprice
- secondchanceofferprice: the Second Chance Offer Price field will be used when the Automatic Second Chance Offer feature is enabled in the Sales Settings.
- storeprice
- isinrelationship
- relationshipname
- isparent
- parentsku
- displayinstore
- storetitle
- storedescription
- categoryid
- distributioncentercode: Select the location where this item will be shipped from when it is sent to the buyer.
- classification: Specifies the name of the Inventory Item Classification to associate with the Inventory Item. If the specified Classification does NOT exist, it WILL BE CREATED.
- manufacturer (new in version 2)
- brand (new in version 2)
- condition (new in version 2)
- ASIN (new in version 2)
- ISBN (new in version 2)
- UPC (new in version 2)
- MPN (new in version 2)
- EAN (new in version 2)
- warranty (new in version 2)
- productMargin (new in version 2)
- supplierPO (new in version 2)
- harmonizedCode (new in version 2)
- height (new in version 2)
- length (new in version 2)
- width (new in version 2)
- labels (Specifies the list of Labels to add or remove from the Inventory Item. If you wish to REMOVE a Label from the Item, simply specify the name of the Label prefixed by a minus sign.)
Parameters:
sku
- The SKU (Stock Keeping Unit) is a unique identifier that is associated with a product for inventory tracking purposes.
array
- key=value pairs for the given inventory item
Returns: 1 if successful. Returns "ERROR" on error (use the CHA_LastError function to get a detailed error message).
CHA_InventorySyncBegin ( )
Call this before beginning the inventory synchronization process.
See also: CHA_InventorySyncAdd, CHA_InventorySyncCommit
Returns: 1 if successful. Returns "ERROR" on error (use the CHA_LastError function to get a detailed error message).
CHA_InventorySyncClassificationInfo ( name ; value )
Sets a single classification attribute on the most recently added inventory item created via CHA_InventorySyncAdd. The call to CHA_InventorySyncAdd must have included a classification name for this function to work correctly.
Parameters:
name
- the classification attribute name.
value
- the classification attribute value.
Returns: 1 on success, "ERROR" on failure (use the CHA_LastError for more details on the error)
CHA_InventorySyncCommit ( developerKey ; password ; accountId )
Commits any inventory items in the current sync batch.
Parameters:
developerKey
- Your ChannelAdvisor developer key
password
- Your ChannelAdvisor password
accountId
- Your ChannelAdvisor account id
See also: CHA_InventorySyncBegin, CHA_InventorySyncAdd
Returns: 1 if successful. Returns "ERROR" on error (use the CHA_LastError function to get a detailed error message).
CHA_InventoryValue ( key )
Returns a specific value for the current inventory, as set by CHA_NextInventory.
Keys:
- sku
- title
- subtitle
- shortDescription
- description
- weight
- supplierCode
- warehouseLocation
- taxProductCode
- flagStyle
- flagDescription
- isBlocked
- blockComment
- quantityInfo
- priceInfo
- classificationInfo
- variationInfo
- storeInfo
- imageList
- shippingInfo
Parameters:
key
- the inventory key to fetch.
Returns: Inventory value, or ERROR
if an unknown key is specified.
CHA_LastError ( )
Returns the last CHA_-related error which occurred.
This should be called any time that a plugin function returns "ERROR" to get a user-readable description of the error.
Returns: Error text, or ""
if there was no error.
CHA_LicenseInfo ( )
Returns information about the license used.
Returns: description of the active license
CHA_LineItemValue ( key )
Gets a line item value for the currently iterated line item, as set by CHA_NextLineItem.
key
must be one of the following values:
- LineItemType
- UnitPrice
- LineItemID
- AllowNegativeQuantity
- Quantity
- ItemSaleSource
- SKU
- Title
- BuyerUserID
- BuyerFeedbackRating
- SalesSourceID
- VATRate
- UnitWeight: this includes the unit of measure
- WarehouseLocation
- TaxCost (new in 2.0)
- ShippingCost (new in 2.0)
- ShippingTaxCost (new in 2.0)
- GiftWrapCost (new in 2.0)
- GiftWrapTaxCost (new in 2.0)
- GiftMessage (new in 2.0)
- GiftWrapLevel (new in 2.0)
- ItemPromoList (new in 2.0)
- RecyclingFee (new in 2.0)
- FulfillmentType (new in 2.0)
- UserName (new in 2.0)
- DistributionCenterCode (new in 2.0)
- IsExternallyFulfilled (new in 2.0)
- ItemSaleSourceTransactionID (new in 2.0)
Parameters:
key
- name of the property to retrieve from the current line item.
Returns: value of the key
property for the current line item.
CHA_NextCarrier ( )
Iterate to the next carrier, as returned by CHA_CarrierList.
Returns: 1 if iteration happened, 0 if at end of carrier list
CHA_NextInventory ( )
Iterate to the next inventory, as returned by CHA_InventoryList.
Returns: 1 if successful, 0 if at end of inventory list
CHA_NextLineItem ( )
Iterates to the next line item for the current order. Note: this returns both line items and promos. Check the "type" of the line item to determine whether it's a promo or a regular line item or promo (type="Promotion").
Returns: 1 if there was another line item in the current order, 0 otherwise. Returns "ERROR" on error (use the CHA_LastError function to get a detailed error message).
CHA_NextOrder ( )
Iterate to the next order fetched with CHA_OrderList.
Returns: 1 if there is another order in the list of fetched orders, 0 if not. Returns "ERROR" on error (use the CHA_LastError function to get a detailed error message).
CHA_OrderLineItemInvoiceWithKey ( key )
Returns a value from the current order lineItemInvoiceList.orderLinItemInvoice
values.
Parameters:
key,
- e.g. "SalesTax" or "Shipping" or "ShippingInsurance" or "VATShipping"
Returns: the numeric value for the indicated key.
CHA_OrderList ( developerKey ; password ; accountID { ; filter1=value1 ; filter2=value2 ; ... )
Fetches orders from the ChannelAdvisor server. You can specify optional filters with the following keys:
- checkoutstatuscode: one of "NoChange", "NotVisited", "Completed", "Visited", "Cancelled", "CompletedOffline", "OnHold"
- exportstate: one of "Unknown", "NotExported"
- ordercreationfilterbegintime: Only return orders created on or after this date and time
- ordercreationfilterendtime: Only return orders created on or before this date and time
- orderids: a comma-separated list of order ids
- orderstate: one of "Active", "Archived", "Cancelled"
- paymentstatus: one of "NoChange", "NotSubmitted", "Cleared", "Submitted", "Failed", "Deposited"
- shippingstatus: one of "NoChange", "Unshipped", "Shipped", "PartiallyShipped"
- statusupdatefilterbegintime: Only return orders whose status was set after this date and time
- statusupdatefilterendtime: Only return orders whose status was set before this date and time
See http://developer.channeladvisor.com/display/cadn/OrderCriteria for criteria docs
Parameters:
developerKey
- Your ChannelAdvisor developer key
password
- Your ChannelAdvisor password
accountID
- Your ChannelAdvisor account ID
filters
- key=value filter options
Returns: the number of orders found, or "ERROR" on error (use the CHA_LastError function to get a detailed error message).
CHA_OrderShipped ( developerKey ; password ; accountID ; orderID ; dateShipped ; carrierCode ; classCode ; trackingNumber { ; shipmentCost ; insuranceCost ; fulfillmentId ; shipmentTaxCost } )
Marks an existing order with a status of shipped.
Parameters:
developerKey
- Your ChannelAdvisor developer key
password
- Your ChannelAdvisor password
accountID
- the accountId of the channelAdvisor account
orderID
- the order ID being shipped
dateShipped
- the date of shipment
carrierCode
- the carrier code
classCode
- the class code
trackingNumber
- the tracking number
Returns: 1 on success, or "ERROR" on error (use the CHA_LastError function to get a detailed error message).
CHA_OrderShippedPartial ( developerKey ; password ; accountID ; orderID ; dateShipped ; carrierCode ; classCode ; trackingNumber ; shipmentCost ; insuranceCost ; fulfillmentId ; shipmentTaxCost ; lineItems )
Parameters:
CHA_OrderValue ( key )
Gets an order value from the current order, as set by CHA_NextOrder.
key
must be one of the following values:
- NumberOfMatches
- OrderTimeGMT
- LastUpdateDate
- TotalOrderAmount
- OrderState
- DateCancelledGMT
- OrderID
- ClientOrderIdentifier
- SellerOrderId (new in 2.0)
- BuyerIpAddress (new in 2.0)
- TransactionNotes (new in 2.0)
- FlagDescription (new in 2.0)
- FlagStyle (new in 2.0)
- OrderStatus.CheckoutStatus
- OrderStatus.CheckoutDateGMT
- OrderStatus.PaymentStatus
- OrderStatus.PaymentDateGMT
- OrderStatus.ShippingStatus
- OrderStatus.ShippingDateGMT
- OrderStatus.OrderRefundStatus (new in 2.0)
- ResellerID
- BuyerEmailAddress
- EmailOptIn
- PaymentInfo.PaymentType
- PaymentInfo.CreditCardLast4
- PaymentInfo.PaypalID
- PaymentInfo.MerchantReferenceNumber
- PaymentInfo.PaypalTransactionID
- ShippingInfo.ShipmentInstructions
- ShippingInfo.ShipmentList: returns a return-separated list of shipments. Each line contains the carrier followed by a space, then the shipping code, then a colon, then the tracking number.
- BillingInfo.CompanyName
- BillingInfo.Title
- BillingInfo.FirstName
- BillingInfo.LastName
- BillingInfo.Suffix
- BillingInfo.PhoneNumberDay
- BillingInfo.PhoneNumberEvening
- BillingInfo.AddressLine1
- BillingInfo.AddressLine2
- BillingInfo.City
- BillingInfo.Region
- BillingInfo.PostalCode
- BillingInfo.CountryCode
- ShippingInfo.CompanyName
- ShippingInfo.Title
- ShippingInfo.FirstName
- ShippingInfo.LastName
- ShippingInfo.Suffix
- ShippingInfo.PhoneNumberDay
- ShippingInfo.PhoneNumberEvening
- ShippingInfo.AddressLine1
- ShippingInfo.AddressLine2
- ShippingInfo.City
- ShippingInfo.Region
- ShippingInfo.PostalCode
- ShippingInfo.CountryCode
- ShippingInfo.CompanyName
- ShippingInfo.Title
- ShippingInfo.FirstName
- ShippingInfo.LastName
- ShippingInfo.Suffix
- ShippingInfo.PhoneNumberDay
- ShippingInfo.PhoneNumberEvening
- ShippingInfo.AddressLine1
- ShippingInfo.AddressLine2
- ShippingInfo.City
- ShippingInfo.Region
- ShippingInfo.EstimatedShipDate (new in 2.0)
- ShippingInfo.DeliveryDate (new in 2.0)
- ShippingInfo.PostalCode
- ShippingInfo.CountryCode
- ShoppingCart.CartID
- ShoppingCart.VATGiftWrapOption (new in 2.0)
- ShoppingCart.CheckoutSource
- ShoppingCart.VATTaxCalculationOption
- ShoppingCart.VATShippingOption
- ShoppingCart.VATShippingOption
Parameters:
key
- name of the property to retrieve from the current order
Returns: the value of the key
field. Returns "ERROR" on error (use the CHA_LastError function to get a detailed error message).
CHA_Ping ( developerKey ; password )
This should be the first method you use when you connect to any service, to make sure that your connectivity and credentials are working properly.
Parameters:
developerKey
- Your ChannelAdvisor developer key
password
- Your ChannelAdvisor password
Returns: 1 if the service is available and credentials are correct, "ERROR" if an error occurs (use the CHA_LastError function to get a detailed error message).
CHA_Register ( licenseKey ; registeredTo )
Registers the plugin.
Parameters:
licenseKey
- a valid license key
registeredTo
- the company the plugin is registered to
Returns: 1 on success, or "ERROR"
on failure.
CHA_SetErrorCapture ( errorCapture )
Parameters:
CHA_Version ( )
Returns the version of the plugin which is installed.
Returns: the version number of the plugin