API Reference > Products API

Products API

Last Updated: 2026-07-02

List Products

GET/open/v1/productsScope: catalog:read

Returns a paginated list of products accessible to your app. Results are ordered by creation date (newest first).

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number (default: 1)
limit	integer	No	Items per page, max 100 (default: 20)
seller_id	string	No	Filter by seller ID
category_id	string	No	Filter by category ID
status	string	No	Filter by status: active, inactive, draft
updated_after	ISO 8601	No	Only return products updated after this timestamp

Example Request

curl -X GET "https://api.mallplus.com/open/v1/products?page=1&limit=10" \
  -H "X-MallPlus-Partner-Id: app_ck9x2mf3w0001" \
  -H "X-MallPlus-Timestamp: 1713254400" \
  -H "X-MallPlus-Signature: a1b2c3d4e5f6..."

Example Response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "prod_abc123",
        "name": "Premium Leather Wallet",
        "sku": "WALLET-BLK-001",
        "status": "active",
        "price": 259900,
        "currency": "PHP",
        "category_id": "cat_accessories",
        "seller_id": "seller_xyz789",
        "images": [
          "https://cdn.mallplus.com/products/wallet-1.jpg"
        ],
        "created_at": "2026-03-15T10:30:00Z",
        "updated_at": "2026-04-10T14:22:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 342,
      "total_pages": 35
    }
  }
}

Note: price is always in centavos (integer). Divide by 100 for display. 259900 = PHP 2,599.00.

Get Product

GET/open/v1/products/:idScope: catalog:read

Returns a single product by ID, including full details such as variants, images, and category information.

Path Parameters

Parameter	Type	Description
id	string	The product ID (e.g., prod_abc123)

Example Request

curl -X GET "https://api.mallplus.com/open/v1/products/prod_abc123" \
  -H "X-MallPlus-Partner-Id: app_ck9x2mf3w0001" \
  -H "X-MallPlus-Timestamp: 1713254400" \
  -H "X-MallPlus-Signature: a1b2c3d4e5f6..."

Example Response

{
  "success": true,
  "data": {
    "id": "prod_abc123",
    "name": "Premium Leather Wallet",
    "sku": "WALLET-BLK-001",
    "description": "Handcrafted genuine leather bi-fold wallet...",
    "status": "active",
    "price": 259900,
    "compare_at_price": 349900,
    "currency": "PHP",
    "category_id": "cat_accessories",
    "seller_id": "seller_xyz789",
    "brand": "LeatherCraft",
    "weight_grams": 120,
    "variants": [
      {
        "id": "var_001",
        "sku": "WALLET-BLK-001",
        "option": "Black",
        "price": 259900,
        "inventory_quantity": 45
      },
      {
        "id": "var_002",
        "sku": "WALLET-BRN-001",
        "option": "Brown",
        "price": 259900,
        "inventory_quantity": 32
      }
    ],
    "images": [
      "https://cdn.mallplus.com/products/wallet-1.jpg",
      "https://cdn.mallplus.com/products/wallet-2.jpg"
    ],
    "created_at": "2026-03-15T10:30:00Z",
    "updated_at": "2026-04-10T14:22:00Z"
  }
}

Create Product

POST/open/v1/productsScope: catalog:write

Creates a new product in the catalog. The product will be created in draft status and must be activated separately.

Request Body

Field	Type	Required	Description
name	string	Yes	Product name (max 255 chars)
sku	string	Yes	Unique stock keeping unit
description	string	No	Product description (HTML allowed)
price	integer	Yes	Price in centavos (e.g., 259900 = PHP 2,599.00)
category_id	string	Yes	Category ID to assign the product to
seller_id	string	Yes	Seller who owns this product
images	string[]	No	Array of image URLs (max 10)
variants	object[]	No	Product variants with sku, option, price, inventory_quantity

Example Request

curl -X POST "https://api.mallplus.com/open/v1/products" \
  -H "Content-Type: application/json" \
  -H "X-MallPlus-Partner-Id: app_ck9x2mf3w0001" \
  -H "X-MallPlus-Timestamp: 1713254400" \
  -H "X-MallPlus-Signature: a1b2c3d4e5f6..." \
  -d '{
    "name": "Organic Cotton T-Shirt",
    "sku": "TSHIRT-WHT-M",
    "description": "100% organic cotton, pre-shrunk",
    "price": 89900,
    "category_id": "cat_apparel",
    "seller_id": "seller_xyz789",
    "images": ["https://example.com/tshirt-1.jpg"]
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "prod_new456",
    "name": "Organic Cotton T-Shirt",
    "sku": "TSHIRT-WHT-M",
    "status": "draft",
    "price": 89900,
    "currency": "PHP",
    "category_id": "cat_apparel",
    "seller_id": "seller_xyz789",
    "created_at": "2026-04-16T08:00:00Z",
    "updated_at": "2026-04-16T08:00:00Z"
  }
}

Update Product

PUT/open/v1/products/:idScope: catalog:write

Updates an existing product. Only the fields included in the request body will be updated; omitted fields remain unchanged (partial update / PATCH semantics).

Path Parameters

Parameter	Type	Description
id	string	The product ID to update

Example Request

curl -X PUT "https://api.mallplus.com/open/v1/products/prod_abc123" \
  -H "Content-Type: application/json" \
  -H "X-MallPlus-Partner-Id: app_ck9x2mf3w0001" \
  -H "X-MallPlus-Timestamp: 1713254400" \
  -H "X-MallPlus-Signature: a1b2c3d4e5f6..." \
  -d '{
    "price": 229900,
    "status": "active"
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "prod_abc123",
    "name": "Premium Leather Wallet",
    "sku": "WALLET-BLK-001",
    "status": "active",
    "price": 229900,
    "currency": "PHP",
    "updated_at": "2026-04-16T09:15:00Z"
  }
}

Get Variant Prices

GET/open/v1/products/:id/variant-pricesScope: catalog:read

Returns the current price of every variant of a product so you can mirror MallPlus pricing in your own system. All prices are integer centavos in PHP (e.g. 229900 is ₱2,299.00).

Seller-scoped: this endpoint requires a seller access token. Send the X-MallPlus-Access-Token and X-MallPlus-Seller-Id headers alongside the HMAC headers. See Seller Authorization. A product that is missing or not owned by the seller returns 404 NOT_FOUND.

Response Fields

Field	Description
variant_id	Variant identifier.
sku	Stock-keeping unit for the variant.
original_price	Base catalogue price in centavos. Always present.
sale_price	Promotional price in centavos. Present only when a promotional price exists alongside the base price.

Example Response

{
  "success": true,
  "data": [
    {
      "variant_id": "variant_blk_m",
      "sku": "WALLET-BLK-001",
      "original_price": 229900,
      "sale_price": 199900
    },
    {
      "variant_id": "variant_brn_m",
      "sku": "WALLET-BRN-001",
      "original_price": 229900
    }
  ]
}

Update Variant Prices

PUT/open/v1/products/:id/priceScope: catalog:write

Updates the price of one or more variants of a seller-owned product. Push price changes programmatically without logging into Seller Center. Prices are integer centavos and must be greater than 0.

Seller-scoped: send the X-MallPlus-Access-Token and X-MallPlus-Seller-Id headers alongside the HMAC headers. See Seller Authorization.

Atomic batch: up to 50 variant updates per request. Every variant_id must belong to the product and every price must be greater than 0. If any update is invalid the whole batch is rejected and no price is changed.

Example Request

curl -X PUT "https://api.mallplus.com/open/v1/products/prod_abc123/price" \
  -H "Content-Type: application/json" \
  -H "X-MallPlus-Partner-Id: app_ck9x2mf3w0001" \
  -H "X-MallPlus-Timestamp: 1713254400" \
  -H "X-MallPlus-Signature: a1b2c3d4e5f6..." \
  -H "X-MallPlus-Access-Token: at_xxxxxxxxxxxx" \
  -H "X-MallPlus-Seller-Id: seller_nike_ph" \
  -d '{
    "updates": [
      { "variant_id": "variant_blk_m", "price": 199900 },
      { "variant_id": "variant_brn_m", "price": 209900 }
    ]
  }'

Errors

Code	HTTP	Cause
VALIDATION_ERROR	400	A `variant_id` is not part of the product, or a price is not a positive integer.
NOT_FOUND	404	The product does not exist or is not owned by the seller.

Example Response

{
  "success": true,
  "data": [
    { "variant_id": "variant_blk_m", "sku": "WALLET-BLK-001", "original_price": 199900 },
    { "variant_id": "variant_brn_m", "sku": "WALLET-BRN-001", "original_price": 209900 }
  ]
}

Delete Product

DELETE/open/v1/products/:idScope: catalog:write

Delete (archive) a product. The product will be marked as archived and removed from active listings. This is a soft delete — the product data is preserved for order history purposes.

Example Request

curl -X DELETE "https://api.mallplus.com/open/v1/products/prod_abc123" \
  -H "X-MallPlus-Partner-Id: app_ck9x2mf3w0001" \
  -H "X-MallPlus-Timestamp: 1713254400" \
  -H "X-MallPlus-Signature: a1b2c3d4e5f6..."

Example Response

{
  "success": true,
  "data": { "id": "prod_abc123", "deleted": true }
}

Bulk Create Products

POST/open/v1/products/bulkScope: catalog:write

Create multiple products in a single request. Maximum 50 products per batch. Returns a summary with successfully created products and any errors for failed items.

Example Request

curl -X POST "https://api.mallplus.com/open/v1/products/bulk" \
  -H "Content-Type: application/json" \
  -H "X-MallPlus-Partner-Id: app_ck9x2mf3w0001" \
  -H "X-MallPlus-Timestamp: 1713254400" \
  -H "X-MallPlus-Signature: a1b2c3d4e5f6..." \
  -d '{
    "products": [
      { "title": "Product A", "status": "draft", "price": 9900 },
      { "title": "Product B", "status": "draft", "price": 19900 }
    ]
  }'

Example Response

{
  "success": true,
  "data": {
    "created": [
      { "id": "prod_new001", "title": "Product A", "status": "draft" },
      { "id": "prod_new002", "title": "Product B", "status": "draft" }
    ],
    "errors": [],
    "summary": { "total": 2, "succeeded": 2, "failed": 0 }
  }
}