Marketplace Partner Seller API
Every product in your catalog must have a seller associated with it. Each product must include a seller, but sellers can have multiple products.
It’s recommended to first upload partner sellers, followed by the products associated with the sellers. If a product is uploaded before the associated seller, the product won’t be distributed on Facebook Marketplace.
To upload, update, or delete your sellers on Facebook Marketplace you will use the GraphAPI interface.
| HTTP |
|---|
POST /v20.0/{product-catalog-id}/marketplace_partner_sellers_details HTTP/1.1 |
If you want to learn how to use the Graph API, read our Using Graph API guide.
Params
| Parameter | Description |
|---|---|
requests | The method and fields for each seller in an array of sellers. |
The request parameter is where you will define the method and the data of your request.
| Field | Description |
|---|---|
method | The action you wish to perform for a given partner seller. Options are: |
data | The information about the partner seller to be created, updated, or deleted. |
Example requests parameter
[
{
"method": "CREATE",
"data": {
"seller_name": "Plush Seller Inc.0",
"seller_id": "partnerID1",
"seller_review_count": 7,
"seller_positive_ratings_pct": 1.0,
"seller_member_since": 2019,
}
},
{
"method": "UPDATE",
"data": {
"seller_name": "Plush Seller Inc.0",
"seller_id": "partnerID2",
"seller_review_count": 13,
"seller_positive_ratings_pct": 0.8,
"seller_member_since": 2015,
}
},
{... next seller},
]
API Rate Limit
To prevent throttling please follow these recommendations:
- Do not exceed 200 calls per hour. Anything above will cause throttling.
- Batch sellers in one API call, up to 5000.
Seller Ban
If we suspect a seller of using Marketplace to sell as a business, we will ban them and stop distribution of their listings on Marketplace. Sellers may be flagged as a business based on their listings. If you believe a seller has been incorrectly blocked, you can unblock them by deleting suspected business listings using the itemAPI.
Product Item Fields
| Parameter | Type | Required/ Optional | Description |
|---|---|---|---|
| String | Required | The name of the seller displayed on the products. |
| String | Required | The id of the seller. The id must match the partner product field partner_seller_id to connect the partner seller with the products. The id must be unique for each seller in a partnership catalog. If not unique, uploading a seller with the same seller_id as another seller in the same catalog will override the previous seller. If an item is available in multiple countries, be sure to reuse the same seller_id for all catalogs. |
| Number | Optional | The number of reviews a seller has received. |
| Float between 0.0 and 1.0 | Optional | The positive ratings percentage of a seller displayed on Marketplace out of 5 stars. For example, a seller_positive_ratings_pct of 0.8 would be displayed on Marketplace as 4 / 5 stars. |
| Number | Optional | The year the seller joined your platform. |
Check Status of Upload
After submitting a create, update, or delete request, a ‘session_id’ field will be returned to you. You can then check the result of the submission with another request.
The data -> status will be set to “completed” upon completion and the errors will be displayed.
| HTTP |
|---|
GET /v20.0/{product-catalog-id}/check_marketplace_partner_sellers_status?session_id={your session id} |
Example return
{
"data": [
"session_id": "session_id",
"status": "completed",
"sample_errors": [
{
"error_type": "property_value_string_exceeds_length",
"line": 1,
"properties": "seller_id"
},
{
"error_type": "property_value_string_exceeds_length",
"line": 2,
"properties": "seller_id"
}
]
]
}
View and Manage Products
To view or manage uploaded products on Commerce Manager. Any issues with your products will appear on Commerce Manager and may be resolved in the tool. For example, if products have been uploaded with a partner_seller_id for a seller that does not exist yet, the error will be displayed under ‘Issues’.
