Popecho Third Merchant Product API Documentation

1. API Overview

This API allows partner merchants to submit or update products on Popecho. The product data structure is consistent with the platform's internal product structure and supports:

Product name, subtitle, summary, and details

Product main images, category, and base price

SKUs, inventory, and SKU images

Sales attributes

SPU tiered pricing

Optional editor template JSON

Products submitted by merchants are not published immediately. After each creation or update, the product enters the Pending Review state and remains unavailable for sale. It is published only after platform approval.

Merchant products are finished products. After selecting a SKU and quantity, the customer proceeds directly through the regular cart and payment flow. The customer does not enter the customization editor and does not need to upload a design or reference image.

2. Environment Information

Environment	Base URL
Test	Provided by Popecho, for example `https://opentest.popecho.art/`
Production	Provided by Popecho, for example `https://open.popecho.art/`

The internal service uses port 7010 by default. Third parties must only use the HTTPS gateway address provided by the platform and must not access the internal service port directly.

3. Authentication

Popecho assigns an ApiKey and an ApiSecret to each merchant. Include them in the request headers:

Important:

Do not put the ApiSecret in frontend code or a public repository.

Do not print complete request headers in logs.

The server identifies the merchant from the ApiKey. Do not include merchantId in the request body.

Requests are rejected when the merchant is disabled or the credentials are invalid.

Merchant account creation, activation or deactivation, and API credential generation or reset are managed by the Popecho platform and are not part of the third-party open API.

If a self-service merchant profile API is provided later, a merchant will only be able to update the profile associated with its current credentials and will not be able to change its status or API credentials.

4. Upload Product Images

A third party does not need to already have image URLs under a Popecho domain. Upload local images through this API first, and then use the returned url in the product main images, SKU images, or editor template.

Request

The files form field may be repeated to upload multiple images. A request may contain up to 20 images. Only image files are accepted, and each file may be up to 10 MB.

Success Response

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "bucketName": "popecho",
      "fileName": "c18f4f8f.jpg",
      "url": "https://popecho.art/api/file/openFile/popecho/309f17d92e86450998bed1a49e382ba1.jpg",
      "coverUrl": "https://popecho.art/api/file/openFile/popecho-cover/309f17d92e86450998bed1a49e382ba1.webp"
    }
  ]
}

Use url when the original image is required in product data. coverUrl may be used for list thumbnails and similar scenarios. Public image URLs hosted by the third party are not transferred to Popecho automatically. Upload images through this API before submitting the final product.

A merchant logo or avatar is also uploaded through this API. The platform saves the returned original-image url as the merchant profile's logoUrl, which is displayed on the merchant aggregation page in the storefront.

5. Submit or Update a Product

Request

The first submission of an externalProductId by a merchant creates a product. Submitting the same externalProductId again updates the existing product. Use a stable and unique product ID from the merchant's own system.

Request Body Structure

Field	Type	Required	Description
`externalProductId`	string	Yes	Unique product ID in the merchant system, up to 128 characters
`product`	object	Yes	Product body, using the same structure as the Madbuz product save model
`product.spu`	object	Yes	Basic SPU information
`product.skus`	array	Yes	SKU list containing at least one item
`product.skuAttributeValues`	array	No	Associations between SKUs and sales attribute values
`product.spuLadderPrices`	array	No	SPU tiered prices
`product.attributeJson`	array	No	Product sales attribute definitions
`editorTemplateJson`	string	No	Raw JSON string exported by the editor

Platform fields supplied by a third party, including spu.id, spu.spuCode, spu.saleable, spu.verifyStatus, spu.custom, sku.id, and sku.spuId, cannot be used to bypass platform rules. The platform generates internal IDs for new products. The platform always sets spu.custom to 2, which identifies a finished merchant product.

Complete Example

{
  "externalProductId": "IP-PRODUCT-10001",
  "product": {
    "spu": {
      "spuName": "IP Collaboration Custom Canvas Bag",
      "slug": "ip-custom-canvas-bag",
      "subTitle": "Upload an image to create your own canvas bag",
      "categoryId": 1001,
      "brandId": 2001,
      "mainImage": [
        "https://popecho.art/api/file/openFile/popecho/309f17d92e86450998bed1a49e382ba1.jpg",
        "https://popecho.art/api/file/openFile/popecho-cover/309f17d92e86450998bed1a49e382ba1.webp"
      ],
      "price": 19.90,
      "discount": 1.00,
      "description": "Product summary",
      "detailHtml": "<p>Product details</p>",
      "weight": 0.25,
      "volume": 0.001,
      "minOrderQty": 1,
      "ladderPriceSupport": 1
    },
    "skus": [
      {
        "skuName": "White / Standard",
        "price": 19.90,
        "costPrice": 10.00,
        "marketPrice": 29.90,
        "stock": 9999,
        "lowStock": 10,
        "mainImage": "https://cdn.example.com/products/10001/white.jpg",
        "enabled": 1,
        "weight": "0.25"
      }
    ],
    "attributeJson": [
      {
        "attributeId": 10,
        "attributeName": "Color",
        "attributeValueId": "101",
        "attributeValueName": "White",
        "valueText": "White"
      }
    ],
    "skuAttributeValues": [
      {
        "attributeId": 10,
        "attributeValueId": 101,
        "valueText": "White"
      }
    ],
    "spuLadderPrices": [
      {
        "minQuantity": 1,
        "maxQuantity": 9,
        "price": 19.90,
        "discount": 1.00
      },
      {
        "minQuantity": 10,
        "maxQuantity": 49,
        "price": 17.90,
        "discount": 0.90
      },
      {
        "minQuantity": 50,
        "maxQuantity": null,
        "price": 15.90,
        "discount": 0.80
      }
    ]
  },
  "editorTemplateJson": "{\"schemaVersion\":\"1.0\",\"surfaces\":[],\"slots\":[]}"
}

editorTemplateJson is currently stored exactly as the submitted string. If the merchant does not have an editor template, omit the field or send null. Image replacement and rendering rules for the template will be defined by a future editor protocol.

Success Response

{
  "code": 0,
  "msg": "success",
  "data": {
    "relationId": 123,
    "spuId": 456,
    "externalProductId": "IP-PRODUCT-10001",
    "auditStatus": 0
  }
}

Field descriptions:

Field	Description
`relationId`	Merchant-product association record ID, which may be provided to the platform when troubleshooting
`spuId`	Popecho platform product ID
`externalProductId`	Merchant product ID
`auditStatus`	`0` Pending Review, `1` Approved, `2` Rejected

6. Review and Publication Workflow

The merchant calls the image upload API and obtains platform image URLs.

The merchant places the platform image URLs in the product data and calls the product submission API.

popecho validates the ApiKey, ApiSecret, and merchant status.

popecho obtains a trusted merchantId from the credentials and calls the internal popecho-product API.

popecho converts the request into the platform's complete product model and saves the SPU, SKUs, sales attributes, tiered prices, and merchant-product association in one complete save operation.

The product is forced into the Pending Review and unavailable-for-sale states.

Platform operations personnel review the product.

After approval, the platform marks the product as approved and publishes it. If rejected, the product remains unavailable for sale and the rejection reason is recorded.

If an approved product is submitted again with changes, it returns to Pending Review and is taken off sale.

Product updates use complete-replacement semantics. The SKU list, sales attributes, and tiered prices in the request replace the corresponding existing data. Therefore, an update must also contain the complete product data rather than only the changed fields.

Customer Ordering Mode

The spu.custom field in product details distinguishes the customer ordering flow:

`spu.custom`	Ordering mode
`0`	Editor-customized product; the customer must complete a design
`1`	Manual quotation product; the customer may submit reference images and requirements
`2`	Finished merchant product; the customer only selects a SKU and quantity and proceeds through the regular cart and payment flow

Products created or updated through the merchant open API are always type 2. The productInfo, originalPictureInfo, and resourceInfo fields in the regular cart API are optional for this mode.

For finished merchant products, the platform uses the first valid image in spu.mainImage as the cart and order display image. Provide at least one main image and place the preferred customer-facing image first in the array.

7. Common Failure Reasons

Scenario	Description
Missing request headers	`X-Api-Key` or `X-Api-Secret` was not provided
Invalid credentials	The ApiKey does not exist, the merchant is disabled, or the ApiSecret is incorrect
Missing product ID	`externalProductId` is empty
Missing SPU	`product.spu` is empty
Missing SKU	`product.skus` is empty; a product requires at least one SKU
Invalid fields	Category, brand, attribute, image, or other data does not comply with platform rules
Internal service failure	The product service is unavailable or product data could not be saved

The third party should record the request time, externalProductId, and response content, but must redact the X-Api-Secret.

7. cURL Example

8. Versioning

This is the first version of the API. Adding optional fields is not considered a breaking change. If a field is removed, its meaning changes, or its required status changes, a new API version must be released and merchants must be notified in advance.

En Docs

Popecho Third Merchant Product API Documentation

1. API Overview

2. Environment Information

3. Authentication

4. Upload Product Images

Request

Success Response

5. Submit or Update a Product

Request

Request Body Structure

Complete Example

Success Response

6. Review and Publication Workflow

Customer Ordering Mode

7. Common Failure Reasons

7. cURL Example

8. Versioning

请求参数

请求示例代码

返回响应

En Docs

Popecho Third Merchant Product API Documentation#

1. API Overview#

2. Environment Information#

3. Authentication#

4. Upload Product Images#

Request#

Success Response#

5. Submit or Update a Product#

Request#

Request Body Structure#

Complete Example#

Success Response#

6. Review and Publication Workflow#

Customer Ordering Mode#

7. Common Failure Reasons#

7. cURL Example#

8. Versioning#

请求参数

请求示例代码

返回响应

Popecho Third Merchant Product API Documentation

1. API Overview

2. Environment Information

3. Authentication

4. Upload Product Images

Request

Success Response

5. Submit or Update a Product

Request

Request Body Structure

Complete Example

Success Response

6. Review and Publication Workflow

Customer Ordering Mode

7. Common Failure Reasons

7. cURL Example

8. Versioning