Product Set Collection API
Use this guide to create collections used in Shops.
You can use this API to add metadata to a product set, such as a cover image and description. Such product sets are then ready to be used as collections in Commerce Manager to customize your Facebook or Instagram Shop (otherwise, Collections are manually created).
Learn more how to Create a Collection in Commerce Manager, Business Help Center.
POST (Create/Update API)
Creating and updating product sets remains the same. However, there are a few new optional fields to note:
| Field | Description |
|---|---|
| Optional. Parent parameter for metadata block for collections. |
Metadata Fields
| Field | Description |
|---|---|
| Optional. URL of the cover image for the collection. |
| Optional. Customer-facing description for the product set. |
| Optional. URL of the collection. This URL is not shown to consumers, but serves as a default when creating ads that promote your product set. |
Example — Payload
{
"name": "Best sellers",
"filter": {
"retailer_id": {
"is_any": [
"pid1",
"pid2"
]
}
},
"metadata": {
"cover_image_url": "https://foo.com/image.jpg" (https://foo.com/image.jpg%E2%80%9D),
"external_url": "https://foo.com/best-sellers",
"description":"Our best selling products"
}
}Create a Product Set
Create a product set with collection metadata that matches specific product IDs:
curl \
-F "name=Best Sellers" \
-F "filter={'retailer_id': {'is_any': ['pid1', 'pid2']}}"
-F "metadata={'cover_image_url':'https://foo.com/image.jpg', 'external_url':'https://foo.com/best-sellers', 'description':'Our best selling products'}" \
-F "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/API_VERSION/PRODUCT_CATALOG_ID/product_setsGET (Read API)
On the GET node, the live_metadata field returns metadata that is published and live on a particular product set, while the latest_metadata field returns the metadata that was last sent to the API. These fields may differ if, for example, an image was changed upon update and was rejected for integrity reasons.
All fields are non-default fields and should be explicitly called in the Graph API as field parameters.
| Field | Description |
|---|---|
| Latest metadata information that was sent. May not be the same as |
| Current, live metadata for this product set. |
Metadata Fields
| Field | Description |
|---|---|
| URL of the customer-facing cover image for the product set. |
| Customer-facing description for the product set. |
| URL of the collection. This URL is not shown to consumers, but serves as a default when creating ads that promote your product set. |
| Integrity review status. Can be one of |
Example — Read a product set to see what metadata is live:
curl -G \
-d "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/<PRODUCT_SET_ID>/?fields=id,name,latest_metadata{cover_image_url, description, review_status},live_metadata{cover_image_url, description, review_status}Response:
{
"id": 1234567890,
"name": "Best sellers",
"latest_metadata": {
"cover_image_url": "https://foo.com/some_new_image.jpg" (https://foo.com/image.jpg%E2%80%9D),
"description":"Our best selling products",
"integrity_review_status": "REJECTED"
},
"live_metadata": {
"cover_image_url": "https://foo.com/some_good_image.jpg",
"description":"Our best selling products",
"integrity_review_status": "APPROVED"
}
}FAQ
Q: What is the minimum, acceptable aspect ratio for a cover image?
A: Images must be at least 600x600 (although edit cropping is unavailable at this ratio). If uploading 800x800 or larger, a square aspect ratio is selected as default. For best results, we recommend an aspect ratio of 1080x1080.
Q: What is the maximum filesize for a cover image?
A: The maximum file size is 8 MB.
Q: What file formats are supported for cover images?
A: JPG and PNG are supported.
Q: Are there length restrictions on description?
A: There is no minimum length for description. The maximum length is 200 characters.