Intro
A set of endpoints for creating, listing, updating, and deleting products — either your own, or on behalf of an active sub-merchant in your marketplace.Context
These endpoints sit alongside the merchant-management endpoints (Create Merchant, List Merchants, etc.) but operate on catalog data rather than the merchant relationship itself. A product created here can have its variant tree managed via Create/Replace Product Variants and Get Product Variants. Products belonging to any of your active sub-merchants are reachable through these same endpoints by passingmerchant_id — you don’t need the sub-merchant’s own API key to manage their catalog.
Hows
Endpoints
Create a product
string
required
Product title.
string
required
Product type.
integer
Create the product on behalf of one of your active sub-merchants instead of yourself. Must be an active merchant in your marketplace — omit to create the product under your own account.
integer
default:"0"
Price in the smallest currency unit.
string
Currency code.
string
Thumbnail image URL.
string
Product description.
boolean
default:"false"
Whether the product is publicly visible.
object
Sell the product in installments.
{ "enabled": true, "installments": [{ "position", "label", "type", "amount" }] } — at least two installments, positions 1, 2, 3 …, one type (percentage adding up to 100, or amount in minor units). Send { "enabled": false } to stop. See Installments. Returned on product reads (null when not sold in installments).installment_plan; the raw has_payment_split, number_of_payment_split and payment_split fields are ignored.
Response — 201
List products
integer
Restrict results to one active sub-merchant’s products. Omit to get your own products plus every active sub-merchant’s products combined.
string
Filter by product type.
boolean
Filter by publish state.
string
Case-insensitive substring match against
title.integer
default:"1"
integer
default:"20"
Maximum
100.string
default:"createdAt"
One of
createdAt, title, price, type, is_published.string
default:"DESC"
ASC or DESC.merchant_id field identifying its owner, plus pagination metadata matching the shape used by List Merchants.
Get / update / delete a single product
GET, PATCH, and DELETE all take a productId path parameter and work on any product you own or that belongs to one of your active sub-merchants. GET includes the product’s variant tree in a variation field (null if no variants are configured).
PATCH accepts any updatable product field in the body, including installment_plan — educator_id, slug, is_live, source, and merchant_id cannot be changed through this endpoint and are silently stripped if present. An invalid installment_plan answers 422 VALIDATION_FAILED with the rule it broke.
DELETE unpublishes the product by default (sets is_published: false) rather than deleting it. Pass ?hard=true to permanently delete the row instead:
Error Codes
Whys
Letting an operator create and manage products on a sub-merchant’s behalf (viamerchant_id) matters for marketplaces where the operator, not the merchant, does the catalog data entry — bulk uploads, standardized listings, or merchants who don’t have their own technical integration. Requiring merchant_id to resolve to an active relationship (not just any past relationship) keeps a suspended merchant’s catalog from being silently editable by the operator after the relationship ends.
Unlike the merchant-management endpoints, these product endpoints don’t require marketplace mode to be enabled at all — creating and listing your own products through the partner API is a baseline capability independent of whether you operate a marketplace. The marketplace-specific behavior (managing a sub-merchant’s products via merchant_id) only works once that merchant is actively linked.
Why nots
These endpoints do not manage variants directly — pricing/stock variations are a separate resource, handled by Create/Replace Product Variants and Get Product Variants.DELETE without ?hard=true does not remove the product record — it only unpublishes it; don’t rely on soft-delete to free up a slug or fully remove data. Product ownership cannot be reassigned through PATCH — merchant_id and educator_id are stripped from update bodies, so a product can’t be moved between merchants after creation.