Contents
API Context
The Catalog Web Services API allows an external system to retrieve packages as well as create products and services for publishing in the store which are made available for customers to browse and purchase.
Concepts
The following provides an overview of the purpose that some components of the Catalog Web Services API provide.
Associated Property (requires-property)
If requires-property is true, then the product requires the customer to select a property (i.e. the address registered to their account) when it is purchased.
Product Specific Attributes (product-attributes)
In some cases, an external system may require specific information to be associated with a product to assist with the provisioning process.
Adding a Product Specific Attribute to a product creates a form field that can be completed by the product manager. When the product is purchased (as part of a product offer), an order is created that will contain the specified Product Specific Attributes.
A Product Specific Attribute is specified as follows:
- Provisioning Field - Specify the name of the field as it will appear to the product manager.
- Provisioning Field Value - Specify the value for the field. Information in this field is provided to the supplier.
The following is an example of a Product Specific Attributes as specified in XML:
<product-attributes>
<field key="favourite-key">some-value</field>
<field key="another-key">some-value</field>
</product-attributes>
Customer Specific Attributes (customer-attributes)
In some cases, the external system responsible for provisioning the product may require customer specific information to be associated with a product to assist with the provisioning process.
Adding a Customer Specific Attribute to a product creates a form field that can be completed by the customer at the time of purchase. When the product is purchased (as part of a product offer), an order is created for the supplier that will contain the completed Customer Specific Attributes.
A Customer Specific Attribute is specified as follows:
- Key - Information in this field is provided to the supplier. It is not visible to the customer.
- Label - the name of the field as it will appear to the customer.
- Help Text - Contextual help displayed to the customer to assist them complete the field.
The following is an example of a Customer Specific Attributes as specified in XML:
<customer-attributes>
<i8ln-field key="customer-key">
<i8ln-field-detail lang="en" label="Favorite colour"
help-text="What's your favourite colour"/>
</i8ln-field>
</customer-attributes>
Variations and Variation Options
A product manager can add a set of variations to a product. Specifying variations provides the customer with one or more options for a product that is included with a product offer.
When the product is purchased (as part of a product offer), an order is created that will contain the specified Variation Options chosen by the customer.
A Variation is specified as follows:
- Variation Name - the name of the variation as it will appear to the customer.
- Variation Key - the key for the variation. Information in this field is provided to the supplier.
A Variation has two or more Variation Options. A Variation Option is specified as follows:
- Variation Option Name - the name of the variation option as it will appear to the customer.
- Variation Option Key - the key for the variation option.
- Base Variation Option - Defines the variation as the 'base' option, from which other variation options are added. There can only be one variation option selected as the base per variation.
The following is an example of a variation and variation options as specified in XML:
<variations>
<variation key="speed">
<name>Broadband speed</name>
<description>How fast do you want it?</description>
<variation-options>
<variation-option key="256">
<base>true</base>
<name>256 kbps</name>
</variation-option>
<variation-option key="512">
<base>false</base>
<name>512 kbps</name>
</variation-option>
<variation-option key="1500">
<base>false</base>
<name>1500 kbps</name>
</variation-option>
</variation-options>
</variation>
<variation key="modem-colour">
<name>Modem Colour</name>
<variation-options>
<variation-option key="red">
<base>true</base>
<name>Red</name>
</variation-option>
<variation-option key="green">
<base>false</base>
<name>Green</name>
</variation-option>
</variation-options>
</variation>
</variations>
URL
Using the leapcities.com SSL certificate
https://{your_company_name}.leapcities.com/api/v1/store
Using your own SSL certificate
https://api.{your_domain}.com/api/v1/store
API
Retrieve all published packages
This enables an external system to retrieve all published packages available in the store.
When you have multiple communities in your instance
URL:
store/communityKey
Where communityKey is the key for the community.
For a single community
URL:
store/
Parameters:
- limit - number of results to return. Optional - default is 100. Maximum limit is 100.
- offset - number of results to skip. Used to page through results.
Method: GET
Response Codes:
- 200 Successful
Example Request/Response:
<packages> <package identifier="P-000001" url="http://localhost:8083/store/television/P-000001/bundle-with-variations"> <name>Bundle With Variations</name> <tag-line></tag-line> <summary>Bundle With Variations</summary> <price min-setup="$ 99.00" min-recurring="$ 150.00" recurring-period="Monthly">Overridden price description</price> <small-image url="http://localhost:8083/image/small/5.image"/> <large-image url="http://localhost:8083/image/large/5.image"/> <category url="http://localhost:8083/store/television">Television</category> </package> <package identifier="P-000004" url="http://localhost:8083/store/food/P-000004/foodies-bundle"> <name>Foodies Bundle</name> <tag-line>Mmm... food</tag-line> <summary>Food is good</summary> <price on-quote="true"></price> <small-image url="http://localhost:8083/image/small/9.image"/> <large-image url="http://localhost:8083/image/large/9.image"/> <category url="http://localhost:8083/store/food">Food</category> <promoted/> </package> </packages>