Commerce
Methods of @cobuntu/embed for products and the cross-origin cart. Setup, sessions and errors are on the
client overview; each method links to its endpoint in the
REST API reference.
products (marketplace)
products.list
list(params?)
Route: GET /products
Returns: { products, pagination, hasMore, nextCursor }. Params below.
products.facets
facets({ q?, minPrice?, maxPrice? })
Route: GET /products/facets
Returns: ProductFacets: counts per category, sub-category, type, price and seller
products.get
get(idOrSku)
Route: GET /products/:idOrSku
Returns: Product. 404 for a miss and for a product the viewer may not see.
products.refund
refund(sku, { saleId, reason, amount?, token? })
Route: POST /products/:sku/sales/me/refund
Returns: The refund request. Member session, or the guest order-link token. amount is in the smallest unit; omit it for a full refund.
products.donate
donate(sku, { donation, customer?, successUrl, cancelUrl })
Route: POST /products/:sku/donate
Returns: { checkoutUrl, sessionId }. donation.amount in cents; customer.email without a session. INVALID_DONATION_AMOUNT
products.donationsSummary
donationsSummary(sku)
Route: GET /products/:sku/donations/summary
Returns: { total, count, currency }
| Param | Values | Meaning |
|---|---|---|
q | text, max 200 | Every word must match the name, sku, description, category names, tags or seller (case- and accent-insensitive). |
sort | "newest" (default) | "price_asc" | "price_desc" | "name" | |
price | "free" | "paid" | On the card price. |
minPrice, maxPrice | integer, smallest unit | Inclusive, on the card price. |
seller | "community" | "member" | Sold by the community itself, or by one of its members. |
type | "DIGITAL" | "PHYSICAL" | |
category, subcategory | id | An unknown id returns an empty page. |
limit, offset, cursor | Page size (1-100, default 20). Walk nextCursor until hasMore is false. |
The card price is the cheapest live variant when the product has variants, else
the product's own price. Each product carries seller: { type, name, usertag, imageUrl } and variants[] with capacity, remaining, soldOut, hasForm,
memberPrice / memberPriceMode (with a member session) and publicMemberOffers
(for everyone). With client.as(token) members also see members-only products.
cart (cross-origin cart)
Publishable or secret key with WRITE_CART. Every method but create takes
the guest cart token and sends it as X-Cobuntu-Cart-Token. Keep the token in
your own cookie; never put it in a URL. See the Cart and handoff guide.
cart.create
create()
Route: POST /cart
Returns: { cart: CartView, token }. Store token.
cart.get
get(cartToken)
Route: GET /cart
Returns: CartView: { id, items: CartLine[], subtotal, currency, totalItems }, prices resolved live. 404 NOT_FOUND for an unknown token: mint a new cart.
cart.addItem
addItem(cartToken, { productId, tierId?, quantity? })
Route: POST /cart/items
Returns: CartView. Same product and variant again raises the quantity. Max 50 lines, quantity 99.
cart.updateItem
updateItem(cartToken, itemId, quantity)
Route: PATCH /cart/items/:itemId
Returns: CartView. 0 removes the line.
cart.removeItem
removeItem(cartToken, itemId)
Route: DELETE /cart/items/:itemId
Returns: CartView
cart.merge
merge(cartToken)
Route: POST /cart/merge
Returns: CartView. Needs a signed-in community app session, which an embed session is not: from your server it answers 401.
cart.handoff
handoff(cartToken)
Route: POST /cart/handoff
Returns: { code, expiresAt }: a one-time code (about 60 seconds), the only cart credential allowed in a URL.
cart.claim
claim(code, cartToken?)
Route: POST /cart/claim
Returns: { cart, token } on the receiving origin. An expired or used code is 404.
A line's checkoutProductId (not productId) is what checkout and quote key
on for a variant line. To pay for the whole cart, pass the token straight to
checkout.create({ cartToken, successUrl, cancelUrl }).