Products API
Store offerings are called products. Before products can be displayed in a store, they must be created. There are three different types of products:
While merchants can always create products, only stores whose sites are on the Starter plan or better can actually sell products. And some plans have restrictions on the quantity and type of products that can be sold. More info on plans here.
- Physical: products that are tangible and are delivered to the customer. These can have shipping fees associated with them.
- Service: products that are not tangible, like landscaping or babysitting.
- Digital: products that are actually files that the customer downloads. These can have download limits based on time or on the number of downloads. (Note that digital products cannot be created using the API).
While merchants can always create products, only stores whose sites are on the Starter plan or better can actually sell products. And some plans have restrictions on the quantity and type of products that can be sold. More info on plans here.
Tip: Use plan_level on the Site API to determine the site's current plan.
Products can be assigned to categories in order to group similar items together. And like categories, products can have one or more images used for display in the store. Products can be taxable (by default they are) and can have a sale price and a regular price.
Products are made up of an array of SKUs. A SKU is the combination of a product option and a product option choice (more about how merchants create options in the Weebly UI here). Options are things like Color and have an array of choices, like red, green, and blue. For example, a T-shirt might have the options Color and Size. The option Color might have an array of choices like red and yellow, while the option Size might have choices of Small, Medium, and Large. So one SKU might have the option choices of red and medium. Another SKU might have red and large as option choices.
Each SKU can have a different price, a different image, etc. When you create a Product, you must provide an array of SKU objects, even if there is only one in the array.
Any changes to products that have more than one option choice must be done at the Product level. You can't change an option to add a new choice. You need to change the product to add a new option choice and new array of SKU objects that includes that new choice. For example, if you wanted to add yellow as an option for the T-shirt, you'd need to do a PUT with the new option choice of yellow, and an array of all the SKUs available, which would now be all the size and color combinations, including yellow. After you update the product with the new SKUs, you can then update choices on the Product Option to change the order of the colors, so that maybe yellow comes first.
Once created, you can change the individual product SKUs. For example, you might change the price.
Use the Products API to manage the product catalog for a site's store and to change the options and skus available for a product. Use the following APIs to manage different aspects of a product:
Products are made up of an array of SKUs. A SKU is the combination of a product option and a product option choice (more about how merchants create options in the Weebly UI here). Options are things like Color and have an array of choices, like red, green, and blue. For example, a T-shirt might have the options Color and Size. The option Color might have an array of choices like red and yellow, while the option Size might have choices of Small, Medium, and Large. So one SKU might have the option choices of red and medium. Another SKU might have red and large as option choices.
Each SKU can have a different price, a different image, etc. When you create a Product, you must provide an array of SKU objects, even if there is only one in the array.
Any changes to products that have more than one option choice must be done at the Product level. You can't change an option to add a new choice. You need to change the product to add a new option choice and new array of SKU objects that includes that new choice. For example, if you wanted to add yellow as an option for the T-shirt, you'd need to do a PUT with the new option choice of yellow, and an array of all the SKUs available, which would now be all the size and color combinations, including yellow. After you update the product with the new SKUs, you can then update choices on the Product Option to change the order of the colors, so that maybe yellow comes first.
Once created, you can change the individual product SKUs. For example, you might change the price.
Use the Products API to manage the product catalog for a site's store and to change the options and skus available for a product. Use the following APIs to manage different aspects of a product:
- Product Options: Use view current options (like Size or Color) and to change the order that options are displayed for a product. For example, you might want Size to come before Color.
- Product SKUs: Use this API to view the current SKUs for a product, and to set prices, inventory, and weight on individual SKUs (like a red T-shirt in size small) when they are different from a parent product.
- Product SKU Option Choices: Use to view the current option choices for a given SKU.
- Product Images: Use to view, create, and delete images used to display the product.
Note: To authenticate with the Weebly API, you need to use OAuth. This will allow you to access resources based on a particular user and site.
In this topic:
Fields
The following table shows all fields that exist for this API, those that are returned when you retrieve a list, those that are required using a POST or PUT, those that are replaceable using PUT, and those that are changeable using PATCH. All fields are returned when you retrieve a single item.
Name |
Description |
Type |
List |
Reqd |
Replace- able |
Change- able |
user_id |
The unique ID of the user authenticated during the OAuth process. |
string |
X |
|||
site_id |
ID of a Weebly site, unique to the currently authenticated user. |
string |
X |
X |
||
url |
URL to the product's page in the website, for example: https://mysite.weebly.com/store/p1/Apples.html" |
string |
X |
|||
product_id |
Unique ID (to this store) for the product. |
string |
X |
|||
name |
Name of the product |
string |
X |
X |
X |
X |
short_ description |
Description given to the product. |
string |
X |
X |
||
published |
Whether or not the product is displayed on the published site. Valid values are:
|
bool-ean |
X |
X |
X |
|
taxable |
Whether or not the product is taxable in this store. Valid values are:
|
bool-ean |
X |
X |
||
price_low |
Lowest price for this product based on prices for all SKUs of this product. |
inte- ger |
X |
|||
price_high |
Highest price for this product based on prices for all SKUs of this product. |
inte- ger |
X |
|||
sale_price_ low |
Lowest sale price for this product based on sale prices for all SKUs of this product. |
inte- ger |
X |
|||
sale_price_ high |
Highest sale price for this product based on sale prices for all SKUs of this product. |
inte- ger |
X |
|||
inventory |
The cumulative amount of SKUs currently on hand for this product. |
inte- ger |
X |
|||
category_ids |
IDs for all categories that this product is assigned to. |
string |
||||
coupon_ids |
IDs for all coupons that currently affect this product. |
string |
||||
created_ date |
Date this product was first created. |
Unix time stamp |
||||
updated_ date |
Date this product was last changed. |
Unix time stamp |
||||
skus |
Array of SKUs for this product. The array includes each possible combination of options and their values. |
array of skus |
X |
X |
||
images |
Array of image objects used to display this product on the site. |
array of images |
X |
X |
||
options |
Array of options created for this sku, for example Color, Size. |
array of opt- ions |
X |
|||
available |
Whether or not the product is sellable. A product is sellable if the site's plan allows the product to be sold. While merchants can always create products, only stores whose sites are on the Starter plan or better can actually sell products. And some plans have restrictions on the quantity and type of products that can be sold. More info on plans here. Use plan_level on the Site API to determine the site's current plan. |
bool- ean |
X |
|||
image_order |
An ordered list of the product's images by their product_image_id. For example, if a product has three images whose IDs are 3, 6, 7, the array shows the order in which those images are displayed. Note that by default, images are displayed in the order they are uploaded. While that order can't be changed using the API, site owners can change the order from the Weebly editor. Returns null if there are no images. |
array of product_image_ids |
X |
Note: Any fields returned that are not documented are currently unsupported and can be safely ignored.
Retrieve a List of Products for a Site
Endpoint URL
Returns all products created for this site.
Scope: read:store-catalog
Note: This response is paginated and so only the first page of results are returned. You need to use the page parameter to return subsequent pages.
Query Parameters
Parameter |
Description |
Type |
page |
Which page of results to return. Start is 1. Note: Only the first 25 results are returned by default. If the result set is expected to be over 25, you must implement pagination. |
integer |
limit |
Number of results per page to return. Default is 25. Max is 200. |
integer |
query |
Use to retrieve only products that have a full-text match with the query string. |
string |
filterby |
Field name to set a filter on. |
string |
filterfor |
Value to search the filterby field for. You can use the following URL encoded operators with your filterfor parameter:
|
string |
sortby |
Field to sort on. |
string |
sortdir |
Sort direction. Valid values are:
|
string |
Request
Example returning all products:
Example of filtered request
Response
Response
Retrieve Details for a Product
Enpoint URL
Returns the details for a product.
Scope: read:store-catalog
Scope: read:store-catalog
Request
Example request
Response
See Fields table. All fields for the product are returned.
Example response
Retrieve the Number of Products in a Site
Endpoint URL
Returns the number of products that exist for the given site.
Scope: read:store-catalog
Scope: read:store-catalog
Request
Example request
Response
Example response
Create a Product
Endpoint URL
Creates a new product for the given site.
Scope: write:store-catalog
Scope: write:store-catalog
POST body:
You can populate the following fields when creating a product.
Name |
Description |
Type |
Notes |
name |
Name of the product. |
string |
Required |
skus |
When creating a product, you need to create an array of product SKUS: price and product_type are required. See Product SKU for more details. |
array of skus |
Required |
short_ description |
Description given to the product. |
string |
|
images |
Array of image objects used to display this product on the site. |
array of images |
|
options |
Array of options created for this sku, for example Color, Size. |
array of options |
Request
Example request
Response
Example response
Request to create a product with options
This example shows how to create a product with two options - Color with one choice of Red, and Size with two choices, Small and Large. One SKU is created - a tshirt in red and small.
Example request to create a product with options
Example response
Replace (Copy) a Product
Endpoint URL
Replaces the given product. Use this to copy an existing product by replacing the product_id and updating other fields. Any fields not sent will be copied from the product used in the request.
Also use this endpoint to add/change/delete the SKUs for a product. For example, if you wanted to add the color option of yellow to a product, you'd use PUT to add the option choice of yellow and replace skus with all the available options, including yellow. You can then use the PATCH endpoint from the Product Options API to change the order.
Scope: write:store-catalog
Also use this endpoint to add/change/delete the SKUs for a product. For example, if you wanted to add the color option of yellow to a product, you'd use PUT to add the option choice of yellow and replace skus with all the available options, including yellow. You can then use the PATCH endpoint from the Product Options API to change the order.
Scope: write:store-catalog
PUT body:
These fields can be replaced:
Name |
Description |
Type |
Notes |
name |
Name of the product. |
string |
Required |
skus |
When creating a product, you need to create an array of product SKUS: price and product_type are required. See Product SKU for more details. |
array of skus |
Required |
product_id |
Unique ID (to this store) for the product. |
string |
|
short_description |
Description given to the product. |
string |
|
published |
Whether or not the product is displayed on the published site. Valid values are:
|
boolean |
|
taxable |
Whether or not the product is taxable in this store. Valid values are:
|
boolean |
|
images |
Array of image objects used to display this product on the site. |
array of images |
|
options |
Array of options created for this sku, for example Color, Size. |
array of options |
Required if product includes options |
Request to copy a product
Example request to copy an existing product
Response
Example response
Example request to add options to a product
This request shows adding the option choice of Yellow for color and adding a new sku that has the option choice of Yellow for Color and Small for Size. Note that the existing SKU of Red and Small still needs to be sent in the request.
Example request to add options
Example response
Update a Product
Endpoint URL
Updates the given product.
Scope: write:store-catalog
Scope: write:store-catalog
Updateable Fields
These fields can be updated.
Name |
Description |
Type |
product_id |
Unique ID (to this store) for the product. |
string |
name |
Name of the product. |
string |
short_description |
Description given to the product. |
string |
published |
Whether or not the product is displayed on the published site. Valid values are:
|
boolean |
taxable |
Whether or not the product is taxable in this store. Valid values are:
|
boolean |
If you want to add/change/delete the SKUs for a product, use the PUT endpoint instead. For example, if you wanted to add the color option of yellow to a product, you'd use PUT and replace sku with all the available options, including yellow. You can then use the PATCH endpoint from the Product Options API to change the order.
Request
Example request
Response
Example response
Delete a Product
Endpoint URL
Deletes the given product.
Scope: write:store-catalog
Scope: write:store-catalog
Request
Example request
Response
There is no response to a delete request.