mirror of
https://github.com/hanzo-cpp/sdk.git
synced 2026-11-20 19:55:32 +00:00
The lock sat at 574d1f1d while the product moved on. The team surface stopped at rooms — no messages path, no way to open one — so anything built on this client had to reach past it with its own HTTP calls, which is the duplication a generated client exists to prevent.
1773 lines
215 KiB
C++
1773 lines
215 KiB
C++
/**
|
|
* Hanzo Cloud API
|
|
* The Hanzo Cloud API as a customer calls it: every operation under /v1/ except the operator's admin product, relay routes, legacy spellings and capabilities still reached by flag. Tagged by product: the first path segment after /v1/.
|
|
*
|
|
* The version of the OpenAPI document: v1
|
|
*
|
|
* NOTE: This class is auto generated by OpenAPI-Generator 7.14.0.
|
|
* https://openapi-generator.tech
|
|
* Do not edit the class manually.
|
|
*/
|
|
|
|
/*
|
|
* CommerceApi.h
|
|
*
|
|
*
|
|
*/
|
|
|
|
#ifndef HANZO_API_CommerceApi_H_
|
|
#define HANZO_API_CommerceApi_H_
|
|
|
|
|
|
|
|
#include "hanzo/ApiClient.h"
|
|
|
|
#include "hanzo/model/Cart.h"
|
|
#include "hanzo/model/CartItemSet.h"
|
|
#include "hanzo/model/CartOpen.h"
|
|
#include "hanzo/model/Liveness.h"
|
|
#include <cpprest/details/basic_types.h>
|
|
#include <boost/optional.hpp>
|
|
|
|
namespace hanzo {
|
|
namespace api {
|
|
|
|
using namespace hanzo::model;
|
|
|
|
|
|
|
|
class CommerceApi
|
|
{
|
|
public:
|
|
|
|
explicit CommerceApi( std::shared_ptr<const ApiClient> apiClient );
|
|
|
|
virtual ~CommerceApi();
|
|
|
|
/// <summary>
|
|
/// Delete a collection, keeping a recoverable copy
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A collection is a merchandising group a storefront renders — a slug and name, copy and media, flat lists of the product and variant ids it holds, published, preorder and out-of-stock flags, and an availability window. Membership lives on the collection as those id lists rather than as a join, so putting a product into a collection is a write here and not on the product. Removes the addressed row and answers 204 with no body. Before the live row goes it is written once more under a deleted tombstone kind, so a deletion leaves a recoverable copy rather than destroying the record outright — and a tombstone that cannot be written fails the call with 500 before anything is removed. The id is resolved inside the caller org's own namespace, so an absent or foreign id is 404. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The token must also carry Admin or WriteCollection.
|
|
/// </remarks>
|
|
/// <param name="collectionid"></param>
|
|
pplx::task<void> deleteCommerceCollectionByCollectionid(
|
|
utility::string_t collectionid
|
|
) const;
|
|
/// <summary>
|
|
/// Delete a disclosure, keeping a recoverable copy
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A disclosure is a published-document record — a publication body, a content hash, a type and a named receiver. The hash LOOKS like a field you set and is in fact derived, but only on update: a freshly created disclosure keeps whatever hash the caller sent until the first replace or patch recomputes it, so a new row's hash attests to nothing. This kind lives in commerce's demo tree — a live writable resource in your tenant's real store that nothing else in commerce reads. Removes the addressed row and answers 204 with no body. Before the live row goes it is written once more under a deleted tombstone kind, so a deletion leaves a recoverable copy rather than destroying the record outright — and a tombstone that cannot be written fails the call with 500 before anything is removed. The id is resolved inside the caller org's own namespace, so an absent or foreign id is 404. Any valid access token reaches it. The per-kind permission table has no entry for disclosure, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="disclosureid"></param>
|
|
pplx::task<void> deleteCommerceDisclosureByDisclosureid(
|
|
utility::string_t disclosureid
|
|
) const;
|
|
/// <summary>
|
|
/// Delete a discount, keeping a recoverable copy
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A discount is a price rule: a type (flat, percent, free-shipping, free-item or bulk), a window, a scope naming the store, collection, product or variant it applies to, a target, and rules pairing a trigger — a price or quantity threshold — with an action, an amount off or a percentage. It is ENABLED BY DEFAULT, so a bare create makes a live discount rather than a draft. The rule engine caches per replica for about thirty seconds, so a discount switched off here can keep applying briefly on other replicas. Removes the addressed row and answers 204 with no body. Before the live row goes it is written once more under a deleted tombstone kind, so a deletion leaves a recoverable copy rather than destroying the record outright — and a tombstone that cannot be written fails the call with 500 before anything is removed. The id is resolved inside the caller org's own namespace, so an absent or foreign id is 404. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The per-kind permission table has no entry for discount, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="discountid"></param>
|
|
pplx::task<void> deleteCommerceDiscountByDiscountid(
|
|
utility::string_t discountid
|
|
) const;
|
|
/// <summary>
|
|
/// Delete a movie, keeping a recoverable copy
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A movie is a film catalog record — a slug plus EIDR and IMDB ids, all three required, with title and synopsis copy, artwork, screenshots, trailers, cast and crew, and available and hidden flags. It carries NO price: the money for a film lives on the product that sells it. Removes the addressed row and answers 204 with no body. Before the live row goes it is written once more under a deleted tombstone kind, so a deletion leaves a recoverable copy rather than destroying the record outright — and a tombstone that cannot be written fails the call with 500 before anything is removed. The id is resolved inside the caller org's own namespace, so an absent or foreign id is 404. Any valid access token reaches it. The per-kind permission table has no entry for movie, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="movieid"></param>
|
|
pplx::task<void> deleteCommerceMovieByMovieid(
|
|
utility::string_t movieid
|
|
) const;
|
|
/// <summary>
|
|
/// Delete a note, keeping a recoverable copy
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A note is a timestamped free-text log line — a caller-supplied time, a source, a message and an enabled flag. That time is the caller's own field and is distinct from the row's creation stamp; the note search filters on it, so a note written without one is a zero-time note the ops log will never surface. Removes the addressed row and answers 204 with no body. Before the live row goes it is written once more under a deleted tombstone kind, so a deletion leaves a recoverable copy rather than destroying the record outright — and a tombstone that cannot be written fails the call with 500 before anything is removed. The id is resolved inside the caller org's own namespace, so an absent or foreign id is 404. Any valid access token reaches it. The per-kind permission table has no entry for note, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="noteid"></param>
|
|
pplx::task<void> deleteCommerceNoteByNoteid(
|
|
utility::string_t noteid
|
|
) const;
|
|
/// <summary>
|
|
/// Remove a plan from the authority
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Deletes the addressed plan and answers 204. It removes the plan from the catalog buyers choose from; it does not touch subscriptions already sold against it, which keep their stored plan id. PLATFORM admin only — an org-level admin is refused 403 — and an unknown slug is 404.
|
|
/// </remarks>
|
|
/// <param name="slug"></param>
|
|
pplx::task<void> deleteCommercePlansEntriesBySlug(
|
|
utility::string_t slug
|
|
) const;
|
|
/// <summary>
|
|
/// Delete a product, keeping a recoverable copy
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A product is a sellable catalog item: slug, SKU and UPC, name and copy, media, availability and preorder flags, a reservation block, and its money — currency, price, MSRP, list price and inventory cost in minor units, inventory count, taxability, and the subscription interval when it is subscribeable. Its variants and options are carried as a denormalized JSON snapshot inside the product, separate from the standalone variant rows, and nothing keeps the two in step for you. Removes the addressed row and answers 204 with no body. Before the live row goes it is written once more under a deleted tombstone kind, so a deletion leaves a recoverable copy rather than destroying the record outright — and a tombstone that cannot be written fails the call with 500 before anything is removed. The id is resolved inside the caller org's own namespace, so an absent or foreign id is 404. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The token must also carry Admin or WriteProduct.
|
|
/// </remarks>
|
|
/// <param name="productid"></param>
|
|
pplx::task<void> deleteCommerceProductByProductid(
|
|
utility::string_t productid
|
|
) const;
|
|
/// <summary>
|
|
/// Remove a rate outright
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Deletes the row. ARCHIVING is usually what is wanted instead — a deleted rate cannot price a historical charge, so a past invoice that has to re-resolve its rate finds nothing to read. Reach for status=archived unless the rate never priced anything. SuperAdmin only.
|
|
/// </remarks>
|
|
/// <param name="product"></param>
|
|
/// <param name="meter"></param>
|
|
pplx::task<void> deleteCommerceRatesEntriesByProductByMeter(
|
|
utility::string_t product,
|
|
utility::string_t meter
|
|
) const;
|
|
/// <summary>
|
|
/// Delete a return, keeping a recoverable copy
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A return is an RMA — the store, user and order it belongs to, the line items coming back, a fulfillment block carrying its own type, status and pricing, a summary, and eight lifecycle timestamps from submitted through delivered and processed. Its status is a FREE STRING with no enumeration behind it, and there is no refund amount on the return itself: the money sits inside the line items and the fulfillment pricing. Removes the addressed row and answers 204 with no body. Before the live row goes it is written once more under a deleted tombstone kind, so a deletion leaves a recoverable copy rather than destroying the record outright — and a tombstone that cannot be written fails the call with 500 before anything is removed. The id is resolved inside the caller org's own namespace, so an absent or foreign id is 404. Any valid access token reaches it. The token must also carry Admin or WriteReturn.
|
|
/// </remarks>
|
|
/// <param name="returnid"></param>
|
|
pplx::task<void> deleteCommerceReturnByReturnid(
|
|
utility::string_t returnid
|
|
) const;
|
|
/// <summary>
|
|
/// Delete a sales channel, keeping a recoverable copy
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A sales channel is a named selling surface — a name, a description, a disabled flag and metadata. The flag is NEGATIVE, so a channel created from an empty body is enabled. Nothing on this row links products, prices or stock to the channel; here it is a label other surfaces scope themselves by. Removes the addressed row and answers 204 with no body. Before the live row goes it is written once more under a deleted tombstone kind, so a deletion leaves a recoverable copy rather than destroying the record outright — and a tombstone that cannot be written fails the call with 500 before anything is removed. The id is resolved inside the caller org's own namespace, so an absent or foreign id is 404. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The per-kind permission table has no entry for saleschannel, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="saleschannelid"></param>
|
|
pplx::task<void> deleteCommerceSaleschannelBySaleschannelid(
|
|
utility::string_t saleschannelid
|
|
) const;
|
|
/// <summary>
|
|
/// Delete a stock location, keeping a recoverable copy
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A stock location is a physical address inventory can be held at — a name, street lines, city, province, country, postal code and a phone. None of it is validated, there are no coordinates, and the row carries no enabled flag and no inventory link, so deleting it is the only way to retire one. Removes the addressed row and answers 204 with no body. Before the live row goes it is written once more under a deleted tombstone kind, so a deletion leaves a recoverable copy rather than destroying the record outright — and a tombstone that cannot be written fails the call with 500 before anything is removed. The id is resolved inside the caller org's own namespace, so an absent or foreign id is 404. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The per-kind permission table has no entry for stocklocation, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="stocklocationid"></param>
|
|
pplx::task<void> deleteCommerceStocklocationByStocklocationid(
|
|
utility::string_t stocklocationid
|
|
) const;
|
|
/// <summary>
|
|
/// Delete a storefront, keeping a recoverable copy
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Removes the addressed store and answers 204 with no body. Before the live row goes, the entity is written once more under a tombstone kind, so the deletion leaves a recoverable copy rather than destroying the record outright; the store's listing overrides live inside that row and go with it. The id is resolved inside the caller org's own namespace, so an unknown or foreign id is 404. Requires an admin or store-write token.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
pplx::task<void> deleteCommerceStoreByStoreid(
|
|
utility::string_t storeid
|
|
) const;
|
|
/// <summary>
|
|
/// Remove a listing override
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Drops the key from the store's listing map and re-saves the store, answering 204 with no body. It UN-OVERRIDES rather than deletes: the product, variant or bundle itself is untouched and simply reverts to its catalog values on this storefront. A key that is not present is 404, and so is a store id outside the caller org's namespace. Admin-gated.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
/// <param name="key"></param>
|
|
pplx::task<void> deleteCommerceStoreByStoreidListingByKey(
|
|
utility::string_t storeid,
|
|
utility::string_t key
|
|
) const;
|
|
/// <summary>
|
|
/// Delete a submission, keeping a recoverable copy
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A submission is one filled-in form from a site visitor — an email, an optional user id, the client details the server observed (user agent, referer, geography) and the form's own fields as free metadata. It carries no form id, so the link back to the form that produced it is not stored on the row. Removes the addressed row and answers 204 with no body. Before the live row goes it is written once more under a deleted tombstone kind, so a deletion leaves a recoverable copy rather than destroying the record outright — and a tombstone that cannot be written fails the call with 500 before anything is removed. The id is resolved inside the caller org's own namespace, so an absent or foreign id is 404. Any valid access token reaches it. The per-kind permission table has no entry for submission, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="submissionid"></param>
|
|
pplx::task<void> deleteCommerceSubmissionBySubmissionid(
|
|
utility::string_t submissionid
|
|
) const;
|
|
/// <summary>
|
|
/// Delete a subscriber, keeping a recoverable copy
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A subscriber is a mailing-list member — name, email, the form id that captured them, unsubscribed state and date, client details, tags and metadata. Writing one FIRES A WEBHOOK: subscriber.created on create and subscriber.updated on replace or patch, emitted BEFORE the write is known to have succeeded and carrying the row as sent, so the payload holds the raw email rather than the normalized one that gets stored. Removes the addressed row and answers 204 with no body. Before the live row goes it is written once more under a deleted tombstone kind, so a deletion leaves a recoverable copy rather than destroying the record outright — and a tombstone that cannot be written fails the call with 500 before anything is removed. The id is resolved inside the caller org's own namespace, so an absent or foreign id is 404. Any valid access token reaches it. The token must also carry Admin or WriteSubscriber.
|
|
/// </remarks>
|
|
/// <param name="subscriberid"></param>
|
|
pplx::task<void> deleteCommerceSubscriberBySubscriberid(
|
|
utility::string_t subscriberid
|
|
) const;
|
|
/// <summary>
|
|
/// Delete a token transaction, keeping a recoverable copy
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A token transaction records a transfer between two identified parties — amount and fees, a timestamp, sending and receiving addresses, names, user ids, states and countries, a flag per side, a protocol name and a transaction hash. Nothing here touches a chain: the hash is an unvalidated string and the flags are plain writable booleans with no screening behind them. Amounts are floating-point rather than the exact minor units every real money field in commerce uses, and there is no currency field at all — this kind lives in commerce's demo tree, so it is a live writable resource in your tenant's store that nothing else in commerce reads, and it must never carry real money. Removes the addressed row and answers 204 with no body. Before the live row goes it is written once more under a deleted tombstone kind, so a deletion leaves a recoverable copy rather than destroying the record outright — and a tombstone that cannot be written fails the call with 500 before anything is removed. The id is resolved inside the caller org's own namespace, so an absent or foreign id is 404. Any valid access token reaches it. The per-kind permission table has no entry for tokentransaction, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="tokentransactionid"></param>
|
|
pplx::task<void> deleteCommerceTokentransactionByTokentransactionid(
|
|
utility::string_t tokentransactionid
|
|
) const;
|
|
/// <summary>
|
|
/// Delete a transfer, keeping a recoverable copy
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A transfer records that a payable WAS PAID — the annotation a human writes after paying out of band. Commerce executes no payout: creating one moves no money, and it marks the referenced payable settled. It carries the payable and payee ids, the amount it settles and the amount actually sent (which may be a different asset), a type of eth, wire or other, the transaction hash or wire reference, when it was paid and who recorded it; amounts are exact decimal strings with an asset, not cents. It is admin-gated because writing one settles money we owe, and nothing enforces uniqueness on the reference — so posting the same transfer twice settles the payable twice. Removes the addressed row and answers 204 with no body. Before the live row goes it is written once more under a deleted tombstone kind, so a deletion leaves a recoverable copy rather than destroying the record outright — and a tombstone that cannot be written fails the call with 500 before anything is removed. The id is resolved inside the caller org's own namespace, so an absent or foreign id is 404. The token must carry the ADMIN permission; an ordinary access token is refused. The per-kind permission table has no entry for transfer, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="transferid"></param>
|
|
pplx::task<void> deleteCommerceTransferByTransferid(
|
|
utility::string_t transferid
|
|
) const;
|
|
/// <summary>
|
|
/// Delete a variant, keeping a recoverable copy
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A variant is one purchasable SKU of a product — its product id, SKU and UPC, name, media, availability, the option name and value pairs that distinguish it, a sold counter, and its own money and stock: currency, price, MSRP, inventory cost, inventory count and taxability. Inventory and sold are plain writable numbers with no decrement logic behind them here. The same variant also exists as a JSON copy inside its product, and writing one does not update the other. Removes the addressed row and answers 204 with no body. Before the live row goes it is written once more under a deleted tombstone kind, so a deletion leaves a recoverable copy rather than destroying the record outright — and a tombstone that cannot be written fails the call with 500 before anything is removed. The id is resolved inside the caller org's own namespace, so an absent or foreign id is 404. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The token must also carry Admin or WriteVariant.
|
|
/// </remarks>
|
|
/// <param name="variantid"></param>
|
|
pplx::task<void> deleteCommerceVariantByVariantid(
|
|
utility::string_t variantid
|
|
) const;
|
|
/// <summary>
|
|
/// Delete a wallet, keeping a recoverable copy
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A wallet is a container of custodial blockchain accounts, and its only field is that account list — each account carrying a name, an address, a chain type, and the ENCRYPTED private key with its salt. Creating a wallet through this table generates NO KEYS: key generation lives on the account routes, so a wallet made here is an empty shell and an account posted into one is stored exactly as sent, with no key generation and no validation behind it. Know what a read renders: the plaintext private key is never marshalled and never stored, but the encrypted blob and its salt ARE returned, so whoever can read a wallet can attack it offline down to the strength of the owner's passphrase. That is why this kind is admin-gated. Removes the addressed row and answers 204 with no body. Before the live row goes it is written once more under a deleted tombstone kind, so a deletion leaves a recoverable copy rather than destroying the record outright — and a tombstone that cannot be written fails the call with 500 before anything is removed. The id is resolved inside the caller org's own namespace, so an absent or foreign id is 404. The token must carry the ADMIN permission; an ordinary access token is refused. The per-kind permission table has no entry for wallet, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="walletid"></param>
|
|
pplx::task<void> deleteCommerceWalletByWalletid(
|
|
utility::string_t walletid
|
|
) const;
|
|
/// <summary>
|
|
/// Delete a watchlist, keeping a recoverable copy
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A watchlist is a viewer's saved list of movies — a user id, an email, and the movies themselves. It stores WHOLE MOVIE SNAPSHOTS rather than movie ids, so a list goes stale the moment a film record changes and grows without bound as it fills. Removes the addressed row and answers 204 with no body. Before the live row goes it is written once more under a deleted tombstone kind, so a deletion leaves a recoverable copy rather than destroying the record outright — and a tombstone that cannot be written fails the call with 500 before anything is removed. The id is resolved inside the caller org's own namespace, so an absent or foreign id is 404. Any valid access token reaches it. The per-kind permission table has no entry for watchlist, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="watchlistid"></param>
|
|
pplx::task<void> deleteCommerceWatchlistByWatchlistid(
|
|
utility::string_t watchlistid
|
|
) const;
|
|
/// <summary>
|
|
/// Delete a webhook, keeping a recoverable copy
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A webhook is a merchant-registered endpoint that receives commerce event callbacks — a name, a URL, live and all flags, a per-event map, an enabled flag, and the shared access token each delivery posts IN THE BODY. Two things to know before registering one: that token is a plainly readable field, so anyone who may read webhooks reads every endpoint's secret, and delivery consults only the all flag and the event map — it does NOT consult enabled or live, so setting enabled false does not stop delivery and deleting the row is the only thing that does. Delivery is a single POST with a twenty-second timeout and no retry. Removes the addressed row and answers 204 with no body. Before the live row goes it is written once more under a deleted tombstone kind, so a deletion leaves a recoverable copy rather than destroying the record outright — and a tombstone that cannot be written fails the call with 500 before anything is removed. The id is resolved inside the caller org's own namespace, so an absent or foreign id is 404. The token must carry the ADMIN permission; an ordinary access token is refused. The per-kind permission table has no entry for webhook, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="webhookid"></param>
|
|
pplx::task<void> deleteCommerceWebhookByWebhookid(
|
|
utility::string_t webhookid
|
|
) const;
|
|
/// <summary>
|
|
/// Discard a cart the shopper abandoned
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Discards a cart the shopper abandoned, and answers it in its final state. A discarded cart is CLOSED, not deleted: the row stays, so abandoned-basket reporting and any follow-up that keys on it still have something to read. It stops being a cart anything will check out, which is the point — it is how a storefront says \"this basket is over\" without destroying the evidence that it existed. Discarding is idempotent: a cart already discarded answers its stored state rather than failing, so a retry is safe. The cart is resolved inside the caller's own org namespace, so another tenant's id answers 404. A named handler, not a closure, so zipdoc can lift this prose into the registry.
|
|
/// </remarks>
|
|
/// <param name="id">ID is the cart's id, as the open call answered it.</param>
|
|
pplx::task<std::shared_ptr<Cart>> discardCart(
|
|
utility::string_t id
|
|
) const;
|
|
/// <summary>
|
|
/// Read one cart with its lines and totals
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Reads one cart: its lines, its status and what it comes to. This is what a storefront calls to render the basket, and what a support agent calls to see what a shopper is looking at. The totals are the cart's STORED tally — shipping and tax stay zero until checkout resolves a shipping option and a tax region, so a cart total before checkout is the merchandise total and is meant to be. The org scopes the read by construction: the store is namespaced to it, so a cart id belonging to another tenant is simply not found rather than found and then filtered, and answers 404 rather than 403 so the id space cannot be probed. A named handler, not a closure, so zipdoc can lift this prose into the registry.
|
|
/// </remarks>
|
|
/// <param name="id">ID is the cart's id, as the open call answered it.</param>
|
|
pplx::task<std::shared_ptr<Cart>> getCart(
|
|
utility::string_t id
|
|
) const;
|
|
/// <summary>
|
|
/// The catalog projection with cost and margin included
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns the brand-scoped catalog carrying the administrative economics the public projection withholds — upstream cost and margin percentage — for the margin surface the platform console administrates. The brand comes from the query and defaults to hanzo. PLATFORM admin only, enforced by the handler on top of the route's IAM gate: an ORG-level admin is refused 403 precisely so upstream cost and margin never reach a tenant.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceAdminCatalog(
|
|
) const;
|
|
/// <summary>
|
|
/// The public product catalog projection for a brand
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns the brand's published catalog — the shared source docs, the console sidebar and the pricing pages all read — with the brand taken from the query and defaulting to hanzo. It is public and cacheable, and it is the projection that deliberately omits cost and margin; those live only on the platform-admin projection.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceCatalog(
|
|
) const;
|
|
/// <summary>
|
|
/// The raw catalog entries, including the unpublished ones
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns every catalog row as stored — the admin view, which unlike the public projection includes entries that are not published. It is cross-tenant platform data, so the gate is a PLATFORM admin: an org-level admin is refused 403 no matter how privileged they are inside their own org, enforced by the handler itself and not only by the route's token middleware.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceCatalogEntries(
|
|
) const;
|
|
/// <summary>
|
|
/// List your org's collections, as a page
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A collection is a merchandising group a storefront renders — a slug and name, copy and media, flat lists of the product and variant ids it holds, published, preorder and out-of-stock flags, and an availability window. Membership lives on the collection as those id lists rather than as a join, so putting a product into a collection is a write here and not on the product. Answers a pagination envelope — the page and display echoed back, the rows under models, a total count and a facets array — read from the caller org's own namespaced store, so one tenant can never list another's. Sorting defaults to the slug and is overridable with sort. display is the page size and page applies only alongside it; either one that is not a positive integer is refused with 500 rather than silently ignored, and the limit query overrides the reported COUNT only, never the rows returned. No search backend is wired, so the datastore is the one and only list path and facets is always empty. A request resolving no org namespace is served an EMPTY page rather than an unscoped scan: the namespace IS the tenant filter, so without one there is nothing safe to return. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The token must also carry Admin or the Collection list scope.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceCollection(
|
|
) const;
|
|
/// <summary>
|
|
/// Fetch one collection
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A collection is a merchandising group a storefront renders — a slug and name, copy and media, flat lists of the product and variant ids it holds, published, preorder and out-of-stock flags, and an availability window. Membership lives on the collection as those id lists rather than as a join, so putting a product into a collection is a write here and not on the product. Reads the addressed row from the caller org's own namespaced store. An id that is not there is 404 — and another tenant's id is not there by construction, so it reads exactly like a typo instead of confirming the row exists somewhere else. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The token must also carry Admin or ReadCollection.
|
|
/// </remarks>
|
|
/// <param name="collectionid"></param>
|
|
pplx::task<void> getCommerceCollectionByCollectionid(
|
|
utility::string_t collectionid
|
|
) const;
|
|
/// <summary>
|
|
/// The reference currency list the price and settings pickers render
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns every reference currency as one global list, so a store settings form or a product price picker binds real rows instead of a hardcoded array. It is a default-namespace read shared by every tenant rather than per-org data, and it is public and cacheable.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceCurrencies(
|
|
) const;
|
|
/// <summary>
|
|
/// Read the crypto deposit watcher's runtime state, asset by asset
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Reports whether the deposit watcher is running, its poll interval, and one row per armed asset: chain, token, contract, pooled address and the last block that asset's cursor reached. That last block is the only way to see a watcher that is up but no longer advancing, which is what a stalled deposit rail looks like from outside. SuperAdmin only — the reserved admin org's owner claim; an authenticated caller without it is refused 403 and an anonymous one 401. It is READ-ONLY by design: arming an asset stays a CRYPTO_DEPOSIT_* deployment act and is deliberately not a button here, so there is nothing on this surface that can start crediting a customer's balance. The asset's RPC endpoint is reduced to scheme://host before it is returned, because a managed node URL carries its API key in the path or query and echoing it verbatim would publish that credential to every reader of this status.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceDeposits(
|
|
) const;
|
|
/// <summary>
|
|
/// List your org's disclosures, as a page
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A disclosure is a published-document record — a publication body, a content hash, a type and a named receiver. The hash LOOKS like a field you set and is in fact derived, but only on update: a freshly created disclosure keeps whatever hash the caller sent until the first replace or patch recomputes it, so a new row's hash attests to nothing. This kind lives in commerce's demo tree — a live writable resource in your tenant's real store that nothing else in commerce reads. Answers a pagination envelope — the page and display echoed back, the rows under models, a total count and a facets array — read from the caller org's own namespaced store, so one tenant can never list another's. Sorting defaults to the last-updated time and is overridable with sort. display is the page size and page applies only alongside it; either one that is not a positive integer is refused with 500 rather than silently ignored, and the limit query overrides the reported COUNT only, never the rows returned. No search backend is wired, so the datastore is the one and only list path and facets is always empty. A request resolving no org namespace is served an EMPTY page rather than an unscoped scan: the namespace IS the tenant filter, so without one there is nothing safe to return. Any valid access token reaches it. The per-kind permission table has no entry for disclosure, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceDisclosure(
|
|
) const;
|
|
/// <summary>
|
|
/// Fetch one disclosure
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A disclosure is a published-document record — a publication body, a content hash, a type and a named receiver. The hash LOOKS like a field you set and is in fact derived, but only on update: a freshly created disclosure keeps whatever hash the caller sent until the first replace or patch recomputes it, so a new row's hash attests to nothing. This kind lives in commerce's demo tree — a live writable resource in your tenant's real store that nothing else in commerce reads. Reads the addressed row from the caller org's own namespaced store. An id that is not there is 404 — and another tenant's id is not there by construction, so it reads exactly like a typo instead of confirming the row exists somewhere else. Any valid access token reaches it. The per-kind permission table has no entry for disclosure, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="disclosureid"></param>
|
|
pplx::task<void> getCommerceDisclosureByDisclosureid(
|
|
utility::string_t disclosureid
|
|
) const;
|
|
/// <summary>
|
|
/// List your org's discounts, as a page
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A discount is a price rule: a type (flat, percent, free-shipping, free-item or bulk), a window, a scope naming the store, collection, product or variant it applies to, a target, and rules pairing a trigger — a price or quantity threshold — with an action, an amount off or a percentage. It is ENABLED BY DEFAULT, so a bare create makes a live discount rather than a draft. The rule engine caches per replica for about thirty seconds, so a discount switched off here can keep applying briefly on other replicas. Answers a pagination envelope — the page and display echoed back, the rows under models, a total count and a facets array — read from the caller org's own namespaced store, so one tenant can never list another's. Sorting defaults to the last-updated time and is overridable with sort. display is the page size and page applies only alongside it; either one that is not a positive integer is refused with 500 rather than silently ignored, and the limit query overrides the reported COUNT only, never the rows returned. No search backend is wired, so the datastore is the one and only list path and facets is always empty. A request resolving no org namespace is served an EMPTY page rather than an unscoped scan: the namespace IS the tenant filter, so without one there is nothing safe to return. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The per-kind permission table has no entry for discount, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceDiscount(
|
|
) const;
|
|
/// <summary>
|
|
/// Fetch one discount
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A discount is a price rule: a type (flat, percent, free-shipping, free-item or bulk), a window, a scope naming the store, collection, product or variant it applies to, a target, and rules pairing a trigger — a price or quantity threshold — with an action, an amount off or a percentage. It is ENABLED BY DEFAULT, so a bare create makes a live discount rather than a draft. The rule engine caches per replica for about thirty seconds, so a discount switched off here can keep applying briefly on other replicas. Reads the addressed row from the caller org's own namespaced store. An id that is not there is 404 — and another tenant's id is not there by construction, so it reads exactly like a typo instead of confirming the row exists somewhere else. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The per-kind permission table has no entry for discount, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="discountid"></param>
|
|
pplx::task<void> getCommerceDiscountByDiscountid(
|
|
utility::string_t discountid
|
|
) const;
|
|
/// <summary>
|
|
/// Answers ok whenever the commerce subsystem is mounted.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Answers ok whenever the commerce subsystem is mounted. It is registered before the module embed boots, so it keeps answering even when the embed failed and every business route serves the fail-closed 503 — which is the point: it reports that the process is reachable, never that the money plane is healthy. Unauthenticated: a probe that needs a credential is a probe that reports the credential. A named handler, not a closure, so zipdoc can lift this prose into the registry.
|
|
/// </remarks>
|
|
pplx::task<std::shared_ptr<Liveness>> getCommerceHealth(
|
|
) const;
|
|
/// <summary>
|
|
/// List your org's movies, as a page
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A movie is a film catalog record — a slug plus EIDR and IMDB ids, all three required, with title and synopsis copy, artwork, screenshots, trailers, cast and crew, and available and hidden flags. It carries NO price: the money for a film lives on the product that sells it. Answers a pagination envelope — the page and display echoed back, the rows under models, a total count and a facets array — read from the caller org's own namespaced store, so one tenant can never list another's. Sorting defaults to the slug and is overridable with sort. display is the page size and page applies only alongside it; either one that is not a positive integer is refused with 500 rather than silently ignored, and the limit query overrides the reported COUNT only, never the rows returned. No search backend is wired, so the datastore is the one and only list path and facets is always empty. A request resolving no org namespace is served an EMPTY page rather than an unscoped scan: the namespace IS the tenant filter, so without one there is nothing safe to return. Any valid access token reaches it. The per-kind permission table has no entry for movie, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceMovie(
|
|
) const;
|
|
/// <summary>
|
|
/// Fetch one movie
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A movie is a film catalog record — a slug plus EIDR and IMDB ids, all three required, with title and synopsis copy, artwork, screenshots, trailers, cast and crew, and available and hidden flags. It carries NO price: the money for a film lives on the product that sells it. Reads the addressed row from the caller org's own namespaced store. An id that is not there is 404 — and another tenant's id is not there by construction, so it reads exactly like a typo instead of confirming the row exists somewhere else. Any valid access token reaches it. The per-kind permission table has no entry for movie, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="movieid"></param>
|
|
pplx::task<void> getCommerceMovieByMovieid(
|
|
utility::string_t movieid
|
|
) const;
|
|
/// <summary>
|
|
/// List your org's notes, as a page
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A note is a timestamped free-text log line — a caller-supplied time, a source, a message and an enabled flag. That time is the caller's own field and is distinct from the row's creation stamp; the note search filters on it, so a note written without one is a zero-time note the ops log will never surface. Answers a pagination envelope — the page and display echoed back, the rows under models, a total count and a facets array — read from the caller org's own namespaced store, so one tenant can never list another's. Sorting defaults to the last-updated time and is overridable with sort. display is the page size and page applies only alongside it; either one that is not a positive integer is refused with 500 rather than silently ignored, and the limit query overrides the reported COUNT only, never the rows returned. No search backend is wired, so the datastore is the one and only list path and facets is always empty. A request resolving no org namespace is served an EMPTY page rather than an unscoped scan: the namespace IS the tenant filter, so without one there is nothing safe to return. Any valid access token reaches it. The per-kind permission table has no entry for note, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceNote(
|
|
) const;
|
|
/// <summary>
|
|
/// Fetch one note
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A note is a timestamped free-text log line — a caller-supplied time, a source, a message and an enabled flag. That time is the caller's own field and is distinct from the row's creation stamp; the note search filters on it, so a note written without one is a zero-time note the ops log will never surface. Reads the addressed row from the caller org's own namespaced store. An id that is not there is 404 — and another tenant's id is not there by construction, so it reads exactly like a typo instead of confirming the row exists somewhere else. Any valid access token reaches it. The per-kind permission table has no entry for note, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="noteid"></param>
|
|
pplx::task<void> getCommerceNoteByNoteid(
|
|
utility::string_t noteid
|
|
) const;
|
|
/// <summary>
|
|
/// The public org configuration a checkout page boots from
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Answers the branding, identity issuer and client id, identity-verification config, enabled payment providers, return-URL allowlist and public payment application config for the org the request HOST resolves to. It is genuinely public and unauthenticated — a checkout page calls it before anyone has signed in — and it carries the same public payment config the authenticated config read does, so the card iframe can never initialize against a different application than the one that will be charged. Only ENABLED providers are listed and no credential path is ever projected. An unresolvable host answers a constant 404 that does not echo the host, so the endpoint cannot be used to enumerate orgs; a successful answer is cacheable for a minute.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceOrg(
|
|
) const;
|
|
/// <summary>
|
|
/// The raw plan authority rows
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns every plan row as stored — the administrative view behind the public plan catalog. The plan authority is cross-tenant pricing data, so the gate is a PLATFORM admin enforced by the handler itself: an org-level admin is refused 403 no matter what they may do inside their own org.
|
|
/// </remarks>
|
|
pplx::task<void> getCommercePlansEntries(
|
|
) const;
|
|
/// <summary>
|
|
/// List your org's products, as a page
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A product is a sellable catalog item: slug, SKU and UPC, name and copy, media, availability and preorder flags, a reservation block, and its money — currency, price, MSRP, list price and inventory cost in minor units, inventory count, taxability, and the subscription interval when it is subscribeable. Its variants and options are carried as a denormalized JSON snapshot inside the product, separate from the standalone variant rows, and nothing keeps the two in step for you. Answers a pagination envelope — the page and display echoed back, the rows under models, a total count and a facets array — read from the caller org's own namespaced store, so one tenant can never list another's. Sorting defaults to the slug and is overridable with sort. display is the page size and page applies only alongside it; either one that is not a positive integer is refused with 500 rather than silently ignored, and the limit query overrides the reported COUNT only, never the rows returned. No search backend is wired, so the datastore is the one and only list path and facets is always empty. A request resolving no org namespace is served an EMPTY page rather than an unscoped scan: the namespace IS the tenant filter, so without one there is nothing safe to return. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The token must also carry Admin or the Product list scope.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceProduct(
|
|
) const;
|
|
/// <summary>
|
|
/// Fetch one product
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A product is a sellable catalog item: slug, SKU and UPC, name and copy, media, availability and preorder flags, a reservation block, and its money — currency, price, MSRP, list price and inventory cost in minor units, inventory count, taxability, and the subscription interval when it is subscribeable. Its variants and options are carried as a denormalized JSON snapshot inside the product, separate from the standalone variant rows, and nothing keeps the two in step for you. Reads the addressed row from the caller org's own namespaced store. An id that is not there is 404 — and another tenant's id is not there by construction, so it reads exactly like a typo instead of confirming the row exists somewhere else. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The token must also carry Admin or ReadProduct.
|
|
/// </remarks>
|
|
/// <param name="productid"></param>
|
|
pplx::task<void> getCommerceProductByProductid(
|
|
utility::string_t productid
|
|
) const;
|
|
/// <summary>
|
|
/// List what one unit of each metered thing costs
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns the rate authority's rows — the prices every metered charge resolves against. Narrow with ?product= to show one surface at a time rather than every rate at once. SuperAdmin only: a rate is cross-tenant money, so the handler asks for the reserved admin org's owner claim itself rather than trusting the bundle's token gate.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceRatesEntries(
|
|
) const;
|
|
/// <summary>
|
|
/// List your org's returns, as a page
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A return is an RMA — the store, user and order it belongs to, the line items coming back, a fulfillment block carrying its own type, status and pricing, a summary, and eight lifecycle timestamps from submitted through delivered and processed. Its status is a FREE STRING with no enumeration behind it, and there is no refund amount on the return itself: the money sits inside the line items and the fulfillment pricing. Answers a pagination envelope — the page and display echoed back, the rows under models, a total count and a facets array — read from the caller org's own namespaced store, so one tenant can never list another's. Sorting defaults to the last-updated time and is overridable with sort. display is the page size and page applies only alongside it; either one that is not a positive integer is refused with 500 rather than silently ignored, and the limit query overrides the reported COUNT only, never the rows returned. No search backend is wired, so the datastore is the one and only list path and facets is always empty. A request resolving no org namespace is served an EMPTY page rather than an unscoped scan: the namespace IS the tenant filter, so without one there is nothing safe to return. Any valid access token reaches it. The token must also carry Admin or the Return list scope.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceReturn(
|
|
) const;
|
|
/// <summary>
|
|
/// Fetch one return
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A return is an RMA — the store, user and order it belongs to, the line items coming back, a fulfillment block carrying its own type, status and pricing, a summary, and eight lifecycle timestamps from submitted through delivered and processed. Its status is a FREE STRING with no enumeration behind it, and there is no refund amount on the return itself: the money sits inside the line items and the fulfillment pricing. Reads the addressed row from the caller org's own namespaced store. An id that is not there is 404 — and another tenant's id is not there by construction, so it reads exactly like a typo instead of confirming the row exists somewhere else. Any valid access token reaches it. The token must also carry Admin or ReadReturn.
|
|
/// </remarks>
|
|
/// <param name="returnid"></param>
|
|
pplx::task<void> getCommerceReturnByReturnid(
|
|
utility::string_t returnid
|
|
) const;
|
|
/// <summary>
|
|
/// List your org's sales channels, as a page
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A sales channel is a named selling surface — a name, a description, a disabled flag and metadata. The flag is NEGATIVE, so a channel created from an empty body is enabled. Nothing on this row links products, prices or stock to the channel; here it is a label other surfaces scope themselves by. Answers a pagination envelope — the page and display echoed back, the rows under models, a total count and a facets array — read from the caller org's own namespaced store, so one tenant can never list another's. Sorting defaults to the last-updated time and is overridable with sort. display is the page size and page applies only alongside it; either one that is not a positive integer is refused with 500 rather than silently ignored, and the limit query overrides the reported COUNT only, never the rows returned. No search backend is wired, so the datastore is the one and only list path and facets is always empty. A request resolving no org namespace is served an EMPTY page rather than an unscoped scan: the namespace IS the tenant filter, so without one there is nothing safe to return. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The per-kind permission table has no entry for saleschannel, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceSaleschannel(
|
|
) const;
|
|
/// <summary>
|
|
/// Fetch one sales channel
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A sales channel is a named selling surface — a name, a description, a disabled flag and metadata. The flag is NEGATIVE, so a channel created from an empty body is enabled. Nothing on this row links products, prices or stock to the channel; here it is a label other surfaces scope themselves by. Reads the addressed row from the caller org's own namespaced store. An id that is not there is 404 — and another tenant's id is not there by construction, so it reads exactly like a typo instead of confirming the row exists somewhere else. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The per-kind permission table has no entry for saleschannel, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="saleschannelid"></param>
|
|
pplx::task<void> getCommerceSaleschannelBySaleschannelid(
|
|
utility::string_t saleschannelid
|
|
) const;
|
|
/// <summary>
|
|
/// List your org's stock locations, as a page
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A stock location is a physical address inventory can be held at — a name, street lines, city, province, country, postal code and a phone. None of it is validated, there are no coordinates, and the row carries no enabled flag and no inventory link, so deleting it is the only way to retire one. Answers a pagination envelope — the page and display echoed back, the rows under models, a total count and a facets array — read from the caller org's own namespaced store, so one tenant can never list another's. Sorting defaults to the last-updated time and is overridable with sort. display is the page size and page applies only alongside it; either one that is not a positive integer is refused with 500 rather than silently ignored, and the limit query overrides the reported COUNT only, never the rows returned. No search backend is wired, so the datastore is the one and only list path and facets is always empty. A request resolving no org namespace is served an EMPTY page rather than an unscoped scan: the namespace IS the tenant filter, so without one there is nothing safe to return. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The per-kind permission table has no entry for stocklocation, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceStocklocation(
|
|
) const;
|
|
/// <summary>
|
|
/// Fetch one stock location
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A stock location is a physical address inventory can be held at — a name, street lines, city, province, country, postal code and a phone. None of it is validated, there are no coordinates, and the row carries no enabled flag and no inventory link, so deleting it is the only way to retire one. Reads the addressed row from the caller org's own namespaced store. An id that is not there is 404 — and another tenant's id is not there by construction, so it reads exactly like a typo instead of confirming the row exists somewhere else. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The per-kind permission table has no entry for stocklocation, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="stocklocationid"></param>
|
|
pplx::task<void> getCommerceStocklocationByStocklocationid(
|
|
utility::string_t stocklocationid
|
|
) const;
|
|
/// <summary>
|
|
/// List your org's storefronts as a page
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Answers a pagination envelope — page, display, the rows, and a total count — read from the caller org's OWN namespaced database, so one tenant can never list another's stores. Sorting defaults to the store slug and is overridable with sort; display is the page size and page applies only alongside it, and either one that is not a positive integer is refused rather than silently ignored. The limit query overrides the reported COUNT only and never the rows returned. A request that resolves no org namespace is served an empty page, never an unscoped scan. Readable with an admin token, a store-scoped token, or the anonymous published storefront key.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceStore(
|
|
) const;
|
|
/// <summary>
|
|
/// Whether a store is entitled to trade, and why
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Answers allowed, the store id, and a status of trial, active, payment_required, store_required or unavailable — the entitlement check a merchant surface gates on. The rule that surprises people is that entitlement is PER STORE, not per org: the store needs its own current subscription on the entry plan, either trialing with a trial end still ahead or active with a period end still ahead, so an org-wide balance or a sibling store's plan unlocks nothing here. The store comes from the X-Store-Id header and otherwise falls back to the org's first store; neither resolving is store_required with allowed false, and a backing-store failure is 503 with status unavailable — a retry signal, not a denial.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceStoreAccess(
|
|
) const;
|
|
/// <summary>
|
|
/// Fetch one storefront
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Reads the addressed store from the caller org's own namespaced database, so an id belonging to another tenant is simply absent there and answers 404 rather than leaking its existence. The body is the stored entity including its embedded listing override map. Readable with an admin or store-read token and also with the anonymous published storefront key, which is what lets a logged-out storefront resolve the store it is rendering.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
pplx::task<void> getCommerceStoreByStoreid(
|
|
utility::string_t storeid
|
|
) const;
|
|
/// <summary>
|
|
/// Fetch a bundle as this storefront sells it
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns the stored bundle with the store's listing for it laid over the top — every non-empty listing field wins, and the currency is forced to the store's own — so the caller reads what this storefront actually sells rather than the catalog-wide record. The overlay is keyed by the item's ID: a listing filed only under a slug or SKU does not reach it, unlike the listing reads, which do fall back to those. An unknown store or key is 404. Readable with an admin token or the anonymous published storefront key.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
/// <param name="key"></param>
|
|
pplx::task<void> getCommerceStoreByStoreidBundleByKey(
|
|
utility::string_t storeid,
|
|
utility::string_t key
|
|
) const;
|
|
/// <summary>
|
|
/// The storefront's whole listing override map
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns every override this store applies to catalog items — name, price, list price, media, availability and the hidden flag — keyed by product or variant id, in one read. A listing is an OVERRIDE, not a product: the catalog item exists independently and this map only says how this storefront presents it. Read from the caller org's own namespaced database, so a store id belonging to another tenant is 404. Readable with an admin token or the anonymous published storefront key.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
pplx::task<void> getCommerceStoreByStoreidListing(
|
|
utility::string_t storeid
|
|
) const;
|
|
/// <summary>
|
|
/// Fetch one listing override, by item id or by its slug or SKU
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Looks the key up in the store's listing map first and, failing that, matches it against each listing's slug and then its SKU — so a storefront holding only a product's URL slug can still resolve the override. That fallback is unique to the listing reads; the item overlay routes match by id alone. A key matching none of the three is 404, as is a store id outside the caller org's namespace. Readable with an admin token or the anonymous published storefront key.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
/// <param name="key"></param>
|
|
pplx::task<void> getCommerceStoreByStoreidListingByKey(
|
|
utility::string_t storeid,
|
|
utility::string_t key
|
|
) const;
|
|
/// <summary>
|
|
/// Fetch a product as this storefront sells it
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns the stored product with the store's listing for it laid over the top — non-empty listing fields replace the catalog values and the currency is forced to the store's own — which is what lets two storefronts sell the same catalog product at their own price, name and media. The overlay is keyed by the product's ID, so a listing filed only under a slug or SKU does not apply here. An unknown store or key is 404. Readable with an admin token or the anonymous published storefront key.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
/// <param name="key"></param>
|
|
pplx::task<void> getCommerceStoreByStoreidProductByKey(
|
|
utility::string_t storeid,
|
|
utility::string_t key
|
|
) const;
|
|
/// <summary>
|
|
/// Fetch a variant as this storefront sells it
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns the stored variant with the store's listing for it overlaid — non-empty listing fields replace the catalog values and the currency is forced to the store's own — which is what makes per-storefront pricing of a shared variant possible. The overlay is keyed by the variant's ID, never by its slug or SKU. An unknown store or key is 404. Readable with an admin token or the anonymous published storefront key.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
/// <param name="key"></param>
|
|
pplx::task<void> getCommerceStoreByStoreidVariantByKey(
|
|
utility::string_t storeid,
|
|
utility::string_t key
|
|
) const;
|
|
/// <summary>
|
|
/// Resolve your org's active storefront without naming an id
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns the caller org's store resolved FROM THE AUTHENTICATED ORG rather than from a path id — which is how an admin dashboard or a storefront edge learns the store id it should then read and write against. An X-Store-Id header selects a specific store, resolved only inside the caller's own namespace, so a foreign id cannot cross the tenant boundary and answers 404 instead. With no header the org's first store is returned, and an org that has none yet has its canonical default provisioned lazily and idempotently, carrying no payment credentials. Only when there is no org in context, or provisioning fails, does it fall back to a placeholder store literally named default, which a storefront edge should treat as unconfigured.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceStoreCurrent(
|
|
) const;
|
|
/// <summary>
|
|
/// List your org's submissions, as a page
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A submission is one filled-in form from a site visitor — an email, an optional user id, the client details the server observed (user agent, referer, geography) and the form's own fields as free metadata. It carries no form id, so the link back to the form that produced it is not stored on the row. Answers a pagination envelope — the page and display echoed back, the rows under models, a total count and a facets array — read from the caller org's own namespaced store, so one tenant can never list another's. Sorting defaults to the last-updated time and is overridable with sort. display is the page size and page applies only alongside it; either one that is not a positive integer is refused with 500 rather than silently ignored, and the limit query overrides the reported COUNT only, never the rows returned. No search backend is wired, so the datastore is the one and only list path and facets is always empty. A request resolving no org namespace is served an EMPTY page rather than an unscoped scan: the namespace IS the tenant filter, so without one there is nothing safe to return. Any valid access token reaches it. The per-kind permission table has no entry for submission, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceSubmission(
|
|
) const;
|
|
/// <summary>
|
|
/// Fetch one submission
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A submission is one filled-in form from a site visitor — an email, an optional user id, the client details the server observed (user agent, referer, geography) and the form's own fields as free metadata. It carries no form id, so the link back to the form that produced it is not stored on the row. Reads the addressed row from the caller org's own namespaced store. An id that is not there is 404 — and another tenant's id is not there by construction, so it reads exactly like a typo instead of confirming the row exists somewhere else. Any valid access token reaches it. The per-kind permission table has no entry for submission, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="submissionid"></param>
|
|
pplx::task<void> getCommerceSubmissionBySubmissionid(
|
|
utility::string_t submissionid
|
|
) const;
|
|
/// <summary>
|
|
/// List your org's subscribers, as a page
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A subscriber is a mailing-list member — name, email, the form id that captured them, unsubscribed state and date, client details, tags and metadata. Writing one FIRES A WEBHOOK: subscriber.created on create and subscriber.updated on replace or patch, emitted BEFORE the write is known to have succeeded and carrying the row as sent, so the payload holds the raw email rather than the normalized one that gets stored. Answers a pagination envelope — the page and display echoed back, the rows under models, a total count and a facets array — read from the caller org's own namespaced store, so one tenant can never list another's. Sorting defaults to the last-updated time and is overridable with sort. display is the page size and page applies only alongside it; either one that is not a positive integer is refused with 500 rather than silently ignored, and the limit query overrides the reported COUNT only, never the rows returned. No search backend is wired, so the datastore is the one and only list path and facets is always empty. A request resolving no org namespace is served an EMPTY page rather than an unscoped scan: the namespace IS the tenant filter, so without one there is nothing safe to return. Any valid access token reaches it. The token must also carry Admin or the Subscriber list scope.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceSubscriber(
|
|
) const;
|
|
/// <summary>
|
|
/// Fetch one subscriber
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A subscriber is a mailing-list member — name, email, the form id that captured them, unsubscribed state and date, client details, tags and metadata. Writing one FIRES A WEBHOOK: subscriber.created on create and subscriber.updated on replace or patch, emitted BEFORE the write is known to have succeeded and carrying the row as sent, so the payload holds the raw email rather than the normalized one that gets stored. Reads the addressed row from the caller org's own namespaced store. An id that is not there is 404 — and another tenant's id is not there by construction, so it reads exactly like a typo instead of confirming the row exists somewhere else. Any valid access token reaches it. The token must also carry Admin or ReadSubscriber.
|
|
/// </remarks>
|
|
/// <param name="subscriberid"></param>
|
|
pplx::task<void> getCommerceSubscriberBySubscriberid(
|
|
utility::string_t subscriberid
|
|
) const;
|
|
/// <summary>
|
|
/// List your org's token transactions, as a page
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A token transaction records a transfer between two identified parties — amount and fees, a timestamp, sending and receiving addresses, names, user ids, states and countries, a flag per side, a protocol name and a transaction hash. Nothing here touches a chain: the hash is an unvalidated string and the flags are plain writable booleans with no screening behind them. Amounts are floating-point rather than the exact minor units every real money field in commerce uses, and there is no currency field at all — this kind lives in commerce's demo tree, so it is a live writable resource in your tenant's store that nothing else in commerce reads, and it must never carry real money. Answers a pagination envelope — the page and display echoed back, the rows under models, a total count and a facets array — read from the caller org's own namespaced store, so one tenant can never list another's. Sorting defaults to the last-updated time and is overridable with sort. display is the page size and page applies only alongside it; either one that is not a positive integer is refused with 500 rather than silently ignored, and the limit query overrides the reported COUNT only, never the rows returned. No search backend is wired, so the datastore is the one and only list path and facets is always empty. A request resolving no org namespace is served an EMPTY page rather than an unscoped scan: the namespace IS the tenant filter, so without one there is nothing safe to return. Any valid access token reaches it. The per-kind permission table has no entry for tokentransaction, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceTokentransaction(
|
|
) const;
|
|
/// <summary>
|
|
/// Fetch one token transaction
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A token transaction records a transfer between two identified parties — amount and fees, a timestamp, sending and receiving addresses, names, user ids, states and countries, a flag per side, a protocol name and a transaction hash. Nothing here touches a chain: the hash is an unvalidated string and the flags are plain writable booleans with no screening behind them. Amounts are floating-point rather than the exact minor units every real money field in commerce uses, and there is no currency field at all — this kind lives in commerce's demo tree, so it is a live writable resource in your tenant's store that nothing else in commerce reads, and it must never carry real money. Reads the addressed row from the caller org's own namespaced store. An id that is not there is 404 — and another tenant's id is not there by construction, so it reads exactly like a typo instead of confirming the row exists somewhere else. Any valid access token reaches it. The per-kind permission table has no entry for tokentransaction, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="tokentransactionid"></param>
|
|
pplx::task<void> getCommerceTokentransactionByTokentransactionid(
|
|
utility::string_t tokentransactionid
|
|
) const;
|
|
/// <summary>
|
|
/// List your org's transfers, as a page
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A transfer records that a payable WAS PAID — the annotation a human writes after paying out of band. Commerce executes no payout: creating one moves no money, and it marks the referenced payable settled. It carries the payable and payee ids, the amount it settles and the amount actually sent (which may be a different asset), a type of eth, wire or other, the transaction hash or wire reference, when it was paid and who recorded it; amounts are exact decimal strings with an asset, not cents. It is admin-gated because writing one settles money we owe, and nothing enforces uniqueness on the reference — so posting the same transfer twice settles the payable twice. Answers a pagination envelope — the page and display echoed back, the rows under models, a total count and a facets array — read from the caller org's own namespaced store, so one tenant can never list another's. Sorting defaults to the last-updated time and is overridable with sort. display is the page size and page applies only alongside it; either one that is not a positive integer is refused with 500 rather than silently ignored, and the limit query overrides the reported COUNT only, never the rows returned. No search backend is wired, so the datastore is the one and only list path and facets is always empty. A request resolving no org namespace is served an EMPTY page rather than an unscoped scan: the namespace IS the tenant filter, so without one there is nothing safe to return. The token must carry the ADMIN permission; an ordinary access token is refused. The per-kind permission table has no entry for transfer, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceTransfer(
|
|
) const;
|
|
/// <summary>
|
|
/// Fetch one transfer
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A transfer records that a payable WAS PAID — the annotation a human writes after paying out of band. Commerce executes no payout: creating one moves no money, and it marks the referenced payable settled. It carries the payable and payee ids, the amount it settles and the amount actually sent (which may be a different asset), a type of eth, wire or other, the transaction hash or wire reference, when it was paid and who recorded it; amounts are exact decimal strings with an asset, not cents. It is admin-gated because writing one settles money we owe, and nothing enforces uniqueness on the reference — so posting the same transfer twice settles the payable twice. Reads the addressed row from the caller org's own namespaced store. An id that is not there is 404 — and another tenant's id is not there by construction, so it reads exactly like a typo instead of confirming the row exists somewhere else. The token must carry the ADMIN permission; an ordinary access token is refused. The per-kind permission table has no entry for transfer, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="transferid"></param>
|
|
pplx::task<void> getCommerceTransferByTransferid(
|
|
utility::string_t transferid
|
|
) const;
|
|
/// <summary>
|
|
/// List your org's variants, as a page
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A variant is one purchasable SKU of a product — its product id, SKU and UPC, name, media, availability, the option name and value pairs that distinguish it, a sold counter, and its own money and stock: currency, price, MSRP, inventory cost, inventory count and taxability. Inventory and sold are plain writable numbers with no decrement logic behind them here. The same variant also exists as a JSON copy inside its product, and writing one does not update the other. Answers a pagination envelope — the page and display echoed back, the rows under models, a total count and a facets array — read from the caller org's own namespaced store, so one tenant can never list another's. Sorting defaults to the SKU and is overridable with sort. display is the page size and page applies only alongside it; either one that is not a positive integer is refused with 500 rather than silently ignored, and the limit query overrides the reported COUNT only, never the rows returned. No search backend is wired, so the datastore is the one and only list path and facets is always empty. A request resolving no org namespace is served an EMPTY page rather than an unscoped scan: the namespace IS the tenant filter, so without one there is nothing safe to return. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The token must also carry Admin or the Variant list scope.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceVariant(
|
|
) const;
|
|
/// <summary>
|
|
/// Fetch one variant
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A variant is one purchasable SKU of a product — its product id, SKU and UPC, name, media, availability, the option name and value pairs that distinguish it, a sold counter, and its own money and stock: currency, price, MSRP, inventory cost, inventory count and taxability. Inventory and sold are plain writable numbers with no decrement logic behind them here. The same variant also exists as a JSON copy inside its product, and writing one does not update the other. Reads the addressed row from the caller org's own namespaced store. An id that is not there is 404 — and another tenant's id is not there by construction, so it reads exactly like a typo instead of confirming the row exists somewhere else. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The token must also carry Admin or ReadVariant.
|
|
/// </remarks>
|
|
/// <param name="variantid"></param>
|
|
pplx::task<void> getCommerceVariantByVariantid(
|
|
utility::string_t variantid
|
|
) const;
|
|
/// <summary>
|
|
/// List your org's wallets, as a page
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A wallet is a container of custodial blockchain accounts, and its only field is that account list — each account carrying a name, an address, a chain type, and the ENCRYPTED private key with its salt. Creating a wallet through this table generates NO KEYS: key generation lives on the account routes, so a wallet made here is an empty shell and an account posted into one is stored exactly as sent, with no key generation and no validation behind it. Know what a read renders: the plaintext private key is never marshalled and never stored, but the encrypted blob and its salt ARE returned, so whoever can read a wallet can attack it offline down to the strength of the owner's passphrase. That is why this kind is admin-gated. Answers a pagination envelope — the page and display echoed back, the rows under models, a total count and a facets array — read from the caller org's own namespaced store, so one tenant can never list another's. Sorting defaults to the last-updated time and is overridable with sort. display is the page size and page applies only alongside it; either one that is not a positive integer is refused with 500 rather than silently ignored, and the limit query overrides the reported COUNT only, never the rows returned. No search backend is wired, so the datastore is the one and only list path and facets is always empty. A request resolving no org namespace is served an EMPTY page rather than an unscoped scan: the namespace IS the tenant filter, so without one there is nothing safe to return. The token must carry the ADMIN permission; an ordinary access token is refused. The per-kind permission table has no entry for wallet, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceWallet(
|
|
) const;
|
|
/// <summary>
|
|
/// Fetch one wallet
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A wallet is a container of custodial blockchain accounts, and its only field is that account list — each account carrying a name, an address, a chain type, and the ENCRYPTED private key with its salt. Creating a wallet through this table generates NO KEYS: key generation lives on the account routes, so a wallet made here is an empty shell and an account posted into one is stored exactly as sent, with no key generation and no validation behind it. Know what a read renders: the plaintext private key is never marshalled and never stored, but the encrypted blob and its salt ARE returned, so whoever can read a wallet can attack it offline down to the strength of the owner's passphrase. That is why this kind is admin-gated. Reads the addressed row from the caller org's own namespaced store. An id that is not there is 404 — and another tenant's id is not there by construction, so it reads exactly like a typo instead of confirming the row exists somewhere else. The token must carry the ADMIN permission; an ordinary access token is refused. The per-kind permission table has no entry for wallet, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="walletid"></param>
|
|
pplx::task<void> getCommerceWalletByWalletid(
|
|
utility::string_t walletid
|
|
) const;
|
|
/// <summary>
|
|
/// List your org's watchlists, as a page
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A watchlist is a viewer's saved list of movies — a user id, an email, and the movies themselves. It stores WHOLE MOVIE SNAPSHOTS rather than movie ids, so a list goes stale the moment a film record changes and grows without bound as it fills. Answers a pagination envelope — the page and display echoed back, the rows under models, a total count and a facets array — read from the caller org's own namespaced store, so one tenant can never list another's. Sorting defaults to the last-updated time and is overridable with sort. display is the page size and page applies only alongside it; either one that is not a positive integer is refused with 500 rather than silently ignored, and the limit query overrides the reported COUNT only, never the rows returned. No search backend is wired, so the datastore is the one and only list path and facets is always empty. A request resolving no org namespace is served an EMPTY page rather than an unscoped scan: the namespace IS the tenant filter, so without one there is nothing safe to return. Any valid access token reaches it. The per-kind permission table has no entry for watchlist, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceWatchlist(
|
|
) const;
|
|
/// <summary>
|
|
/// Fetch one watchlist
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A watchlist is a viewer's saved list of movies — a user id, an email, and the movies themselves. It stores WHOLE MOVIE SNAPSHOTS rather than movie ids, so a list goes stale the moment a film record changes and grows without bound as it fills. Reads the addressed row from the caller org's own namespaced store. An id that is not there is 404 — and another tenant's id is not there by construction, so it reads exactly like a typo instead of confirming the row exists somewhere else. Any valid access token reaches it. The per-kind permission table has no entry for watchlist, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="watchlistid"></param>
|
|
pplx::task<void> getCommerceWatchlistByWatchlistid(
|
|
utility::string_t watchlistid
|
|
) const;
|
|
/// <summary>
|
|
/// List your org's webhooks, as a page
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A webhook is a merchant-registered endpoint that receives commerce event callbacks — a name, a URL, live and all flags, a per-event map, an enabled flag, and the shared access token each delivery posts IN THE BODY. Two things to know before registering one: that token is a plainly readable field, so anyone who may read webhooks reads every endpoint's secret, and delivery consults only the all flag and the event map — it does NOT consult enabled or live, so setting enabled false does not stop delivery and deleting the row is the only thing that does. Delivery is a single POST with a twenty-second timeout and no retry. Answers a pagination envelope — the page and display echoed back, the rows under models, a total count and a facets array — read from the caller org's own namespaced store, so one tenant can never list another's. Sorting defaults to the last-updated time and is overridable with sort. display is the page size and page applies only alongside it; either one that is not a positive integer is refused with 500 rather than silently ignored, and the limit query overrides the reported COUNT only, never the rows returned. No search backend is wired, so the datastore is the one and only list path and facets is always empty. A request resolving no org namespace is served an EMPTY page rather than an unscoped scan: the namespace IS the tenant filter, so without one there is nothing safe to return. The token must carry the ADMIN permission; an ordinary access token is refused. The per-kind permission table has no entry for webhook, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
pplx::task<void> getCommerceWebhook(
|
|
) const;
|
|
/// <summary>
|
|
/// Fetch one webhook
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A webhook is a merchant-registered endpoint that receives commerce event callbacks — a name, a URL, live and all flags, a per-event map, an enabled flag, and the shared access token each delivery posts IN THE BODY. Two things to know before registering one: that token is a plainly readable field, so anyone who may read webhooks reads every endpoint's secret, and delivery consults only the all flag and the event map — it does NOT consult enabled or live, so setting enabled false does not stop delivery and deleting the row is the only thing that does. Delivery is a single POST with a twenty-second timeout and no retry. Reads the addressed row from the caller org's own namespaced store. An id that is not there is 404 — and another tenant's id is not there by construction, so it reads exactly like a typo instead of confirming the row exists somewhere else. The token must carry the ADMIN permission; an ordinary access token is refused. The per-kind permission table has no entry for webhook, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="webhookid"></param>
|
|
pplx::task<void> getCommerceWebhookByWebhookid(
|
|
utility::string_t webhookid
|
|
) const;
|
|
/// <summary>
|
|
/// Open a cart for a shopper to fill
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Opens an empty cart for a shopper to fill, and answers it with its new id. This is the first step of a sale: hold the id, add items to it with setCartItem, then hand it to checkout. Every field of the request is optional — an empty body opens a perfectly good anonymous cart — and the fields exist only to pre-fill what is already known about the shopper. The STORE defaults to the org's own default storefront, so a merchant selling through one storefront never has to name it. The CURRENCY defaults to usd; note that checkout overrides it with the store's own currency when the sale is authorized, so a currency set here is a hint rather than a commitment. The cart is created in the CALLER'S OWN org namespace, taken from the validated principal and never from the body, so a cart can never be opened on another tenant's books. A named handler, not a closure, so zipdoc can lift this prose into the registry.
|
|
/// </remarks>
|
|
/// <param name="cartOpen"></param>
|
|
pplx::task<std::shared_ptr<Cart>> openCart(
|
|
std::shared_ptr<CartOpen> cartOpen
|
|
) const;
|
|
/// <summary>
|
|
/// Change part of a collection
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A collection is a merchandising group a storefront renders — a slug and name, copy and media, flat lists of the product and variant ids it holds, published, preorder and out-of-stock flags, and an availability window. Membership lives on the collection as those id lists rather than as a join, so putting a product into a collection is a write here and not on the product. Loads the stored row and decodes the body OVER it, so only the fields the body names change and everything else keeps its stored value — the difference from the full replace, which clears what it is not told. Answers the merged row. An id absent from the caller org's namespace is 404 and a body that fails to decode is 400. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The token must also carry Admin, or ReadCollection and WriteCollection together.
|
|
/// </remarks>
|
|
/// <param name="collectionid"></param>
|
|
pplx::task<void> patchCommerceCollectionByCollectionid(
|
|
utility::string_t collectionid
|
|
) const;
|
|
/// <summary>
|
|
/// Change part of a disclosure
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A disclosure is a published-document record — a publication body, a content hash, a type and a named receiver. The hash LOOKS like a field you set and is in fact derived, but only on update: a freshly created disclosure keeps whatever hash the caller sent until the first replace or patch recomputes it, so a new row's hash attests to nothing. This kind lives in commerce's demo tree — a live writable resource in your tenant's real store that nothing else in commerce reads. Loads the stored row and decodes the body OVER it, so only the fields the body names change and everything else keeps its stored value — the difference from the full replace, which clears what it is not told. Answers the merged row. An id absent from the caller org's namespace is 404 and a body that fails to decode is 400. Any valid access token reaches it. The per-kind permission table has no entry for disclosure, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="disclosureid"></param>
|
|
pplx::task<void> patchCommerceDisclosureByDisclosureid(
|
|
utility::string_t disclosureid
|
|
) const;
|
|
/// <summary>
|
|
/// Change part of a discount
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A discount is a price rule: a type (flat, percent, free-shipping, free-item or bulk), a window, a scope naming the store, collection, product or variant it applies to, a target, and rules pairing a trigger — a price or quantity threshold — with an action, an amount off or a percentage. It is ENABLED BY DEFAULT, so a bare create makes a live discount rather than a draft. The rule engine caches per replica for about thirty seconds, so a discount switched off here can keep applying briefly on other replicas. Loads the stored row and decodes the body OVER it, so only the fields the body names change and everything else keeps its stored value — the difference from the full replace, which clears what it is not told. Answers the merged row. An id absent from the caller org's namespace is 404 and a body that fails to decode is 400. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The per-kind permission table has no entry for discount, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="discountid"></param>
|
|
pplx::task<void> patchCommerceDiscountByDiscountid(
|
|
utility::string_t discountid
|
|
) const;
|
|
/// <summary>
|
|
/// Change part of a movie
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A movie is a film catalog record — a slug plus EIDR and IMDB ids, all three required, with title and synopsis copy, artwork, screenshots, trailers, cast and crew, and available and hidden flags. It carries NO price: the money for a film lives on the product that sells it. Loads the stored row and decodes the body OVER it, so only the fields the body names change and everything else keeps its stored value — the difference from the full replace, which clears what it is not told. Answers the merged row. An id absent from the caller org's namespace is 404 and a body that fails to decode is 400. Any valid access token reaches it. The per-kind permission table has no entry for movie, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="movieid"></param>
|
|
pplx::task<void> patchCommerceMovieByMovieid(
|
|
utility::string_t movieid
|
|
) const;
|
|
/// <summary>
|
|
/// Change part of a note
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A note is a timestamped free-text log line — a caller-supplied time, a source, a message and an enabled flag. That time is the caller's own field and is distinct from the row's creation stamp; the note search filters on it, so a note written without one is a zero-time note the ops log will never surface. Loads the stored row and decodes the body OVER it, so only the fields the body names change and everything else keeps its stored value — the difference from the full replace, which clears what it is not told. Answers the merged row. An id absent from the caller org's namespace is 404 and a body that fails to decode is 400. Any valid access token reaches it. The per-kind permission table has no entry for note, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="noteid"></param>
|
|
pplx::task<void> patchCommerceNoteByNoteid(
|
|
utility::string_t noteid
|
|
) const;
|
|
/// <summary>
|
|
/// Change part of a product
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A product is a sellable catalog item: slug, SKU and UPC, name and copy, media, availability and preorder flags, a reservation block, and its money — currency, price, MSRP, list price and inventory cost in minor units, inventory count, taxability, and the subscription interval when it is subscribeable. Its variants and options are carried as a denormalized JSON snapshot inside the product, separate from the standalone variant rows, and nothing keeps the two in step for you. Loads the stored row and decodes the body OVER it, so only the fields the body names change and everything else keeps its stored value — the difference from the full replace, which clears what it is not told. Answers the merged row. An id absent from the caller org's namespace is 404 and a body that fails to decode is 400. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The token must also carry Admin, or ReadProduct and WriteProduct together.
|
|
/// </remarks>
|
|
/// <param name="productid"></param>
|
|
pplx::task<void> patchCommerceProductByProductid(
|
|
utility::string_t productid
|
|
) const;
|
|
/// <summary>
|
|
/// Change part of a return
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A return is an RMA — the store, user and order it belongs to, the line items coming back, a fulfillment block carrying its own type, status and pricing, a summary, and eight lifecycle timestamps from submitted through delivered and processed. Its status is a FREE STRING with no enumeration behind it, and there is no refund amount on the return itself: the money sits inside the line items and the fulfillment pricing. Loads the stored row and decodes the body OVER it, so only the fields the body names change and everything else keeps its stored value — the difference from the full replace, which clears what it is not told. Answers the merged row. An id absent from the caller org's namespace is 404 and a body that fails to decode is 400. Any valid access token reaches it. The token must also carry Admin, or ReadReturn and WriteReturn together.
|
|
/// </remarks>
|
|
/// <param name="returnid"></param>
|
|
pplx::task<void> patchCommerceReturnByReturnid(
|
|
utility::string_t returnid
|
|
) const;
|
|
/// <summary>
|
|
/// Change part of a sales channel
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A sales channel is a named selling surface — a name, a description, a disabled flag and metadata. The flag is NEGATIVE, so a channel created from an empty body is enabled. Nothing on this row links products, prices or stock to the channel; here it is a label other surfaces scope themselves by. Loads the stored row and decodes the body OVER it, so only the fields the body names change and everything else keeps its stored value — the difference from the full replace, which clears what it is not told. Answers the merged row. An id absent from the caller org's namespace is 404 and a body that fails to decode is 400. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The per-kind permission table has no entry for saleschannel, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="saleschannelid"></param>
|
|
pplx::task<void> patchCommerceSaleschannelBySaleschannelid(
|
|
utility::string_t saleschannelid
|
|
) const;
|
|
/// <summary>
|
|
/// Change part of a stock location
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A stock location is a physical address inventory can be held at — a name, street lines, city, province, country, postal code and a phone. None of it is validated, there are no coordinates, and the row carries no enabled flag and no inventory link, so deleting it is the only way to retire one. Loads the stored row and decodes the body OVER it, so only the fields the body names change and everything else keeps its stored value — the difference from the full replace, which clears what it is not told. Answers the merged row. An id absent from the caller org's namespace is 404 and a body that fails to decode is 400. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The per-kind permission table has no entry for stocklocation, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="stocklocationid"></param>
|
|
pplx::task<void> patchCommerceStocklocationByStocklocationid(
|
|
utility::string_t stocklocationid
|
|
) const;
|
|
/// <summary>
|
|
/// Change part of a storefront
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Loads the stored store and decodes the body over it, so only the fields the body names change and everything else keeps its stored value — the difference from the full replace, which clears what it is not told. Answers the merged entity. The id is resolved inside the caller org's own namespace, so an unknown or foreign id is 404. Requires an admin token, or one holding both store read and store write.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
pplx::task<void> patchCommerceStoreByStoreid(
|
|
utility::string_t storeid
|
|
) const;
|
|
/// <summary>
|
|
/// Confirm a listing override exists and re-save the store
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Requires the key to already be present — an absent one is 404 — and answers the store's listing map at 200. Read the behaviour before relying on it: the decoded body is applied to a COPY taken out of the map and is never assigned back, so the stored listing is unchanged and the map returned is exactly the map that was already there. An actual edit to an existing listing has to go through the upsert, which does write its result back into the store. A body that fails to decode is still 400. Admin-gated and namespaced to the caller's org.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
/// <param name="key"></param>
|
|
pplx::task<void> patchCommerceStoreByStoreidListingByKey(
|
|
utility::string_t storeid,
|
|
utility::string_t key
|
|
) const;
|
|
/// <summary>
|
|
/// Change part of a submission
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A submission is one filled-in form from a site visitor — an email, an optional user id, the client details the server observed (user agent, referer, geography) and the form's own fields as free metadata. It carries no form id, so the link back to the form that produced it is not stored on the row. Loads the stored row and decodes the body OVER it, so only the fields the body names change and everything else keeps its stored value — the difference from the full replace, which clears what it is not told. Answers the merged row. An id absent from the caller org's namespace is 404 and a body that fails to decode is 400. Any valid access token reaches it. The per-kind permission table has no entry for submission, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="submissionid"></param>
|
|
pplx::task<void> patchCommerceSubmissionBySubmissionid(
|
|
utility::string_t submissionid
|
|
) const;
|
|
/// <summary>
|
|
/// Change part of a subscriber
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A subscriber is a mailing-list member — name, email, the form id that captured them, unsubscribed state and date, client details, tags and metadata. Writing one FIRES A WEBHOOK: subscriber.created on create and subscriber.updated on replace or patch, emitted BEFORE the write is known to have succeeded and carrying the row as sent, so the payload holds the raw email rather than the normalized one that gets stored. Loads the stored row and decodes the body OVER it, so only the fields the body names change and everything else keeps its stored value — the difference from the full replace, which clears what it is not told. Answers the merged row. An id absent from the caller org's namespace is 404 and a body that fails to decode is 400. Any valid access token reaches it. The token must also carry Admin, or ReadSubscriber and WriteSubscriber together.
|
|
/// </remarks>
|
|
/// <param name="subscriberid"></param>
|
|
pplx::task<void> patchCommerceSubscriberBySubscriberid(
|
|
utility::string_t subscriberid
|
|
) const;
|
|
/// <summary>
|
|
/// Change part of a token transaction
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A token transaction records a transfer between two identified parties — amount and fees, a timestamp, sending and receiving addresses, names, user ids, states and countries, a flag per side, a protocol name and a transaction hash. Nothing here touches a chain: the hash is an unvalidated string and the flags are plain writable booleans with no screening behind them. Amounts are floating-point rather than the exact minor units every real money field in commerce uses, and there is no currency field at all — this kind lives in commerce's demo tree, so it is a live writable resource in your tenant's store that nothing else in commerce reads, and it must never carry real money. Loads the stored row and decodes the body OVER it, so only the fields the body names change and everything else keeps its stored value — the difference from the full replace, which clears what it is not told. Answers the merged row. An id absent from the caller org's namespace is 404 and a body that fails to decode is 400. Any valid access token reaches it. The per-kind permission table has no entry for tokentransaction, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="tokentransactionid"></param>
|
|
pplx::task<void> patchCommerceTokentransactionByTokentransactionid(
|
|
utility::string_t tokentransactionid
|
|
) const;
|
|
/// <summary>
|
|
/// Change part of a transfer
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A transfer records that a payable WAS PAID — the annotation a human writes after paying out of band. Commerce executes no payout: creating one moves no money, and it marks the referenced payable settled. It carries the payable and payee ids, the amount it settles and the amount actually sent (which may be a different asset), a type of eth, wire or other, the transaction hash or wire reference, when it was paid and who recorded it; amounts are exact decimal strings with an asset, not cents. It is admin-gated because writing one settles money we owe, and nothing enforces uniqueness on the reference — so posting the same transfer twice settles the payable twice. Loads the stored row and decodes the body OVER it, so only the fields the body names change and everything else keeps its stored value — the difference from the full replace, which clears what it is not told. Answers the merged row. An id absent from the caller org's namespace is 404 and a body that fails to decode is 400. The token must carry the ADMIN permission; an ordinary access token is refused. The per-kind permission table has no entry for transfer, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="transferid"></param>
|
|
pplx::task<void> patchCommerceTransferByTransferid(
|
|
utility::string_t transferid
|
|
) const;
|
|
/// <summary>
|
|
/// Change part of a variant
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A variant is one purchasable SKU of a product — its product id, SKU and UPC, name, media, availability, the option name and value pairs that distinguish it, a sold counter, and its own money and stock: currency, price, MSRP, inventory cost, inventory count and taxability. Inventory and sold are plain writable numbers with no decrement logic behind them here. The same variant also exists as a JSON copy inside its product, and writing one does not update the other. Loads the stored row and decodes the body OVER it, so only the fields the body names change and everything else keeps its stored value — the difference from the full replace, which clears what it is not told. Answers the merged row. An id absent from the caller org's namespace is 404 and a body that fails to decode is 400. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The token must also carry Admin, or ReadVariant and WriteVariant together.
|
|
/// </remarks>
|
|
/// <param name="variantid"></param>
|
|
pplx::task<void> patchCommerceVariantByVariantid(
|
|
utility::string_t variantid
|
|
) const;
|
|
/// <summary>
|
|
/// Change part of a wallet
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A wallet is a container of custodial blockchain accounts, and its only field is that account list — each account carrying a name, an address, a chain type, and the ENCRYPTED private key with its salt. Creating a wallet through this table generates NO KEYS: key generation lives on the account routes, so a wallet made here is an empty shell and an account posted into one is stored exactly as sent, with no key generation and no validation behind it. Know what a read renders: the plaintext private key is never marshalled and never stored, but the encrypted blob and its salt ARE returned, so whoever can read a wallet can attack it offline down to the strength of the owner's passphrase. That is why this kind is admin-gated. Loads the stored row and decodes the body OVER it, so only the fields the body names change and everything else keeps its stored value — the difference from the full replace, which clears what it is not told. Answers the merged row. An id absent from the caller org's namespace is 404 and a body that fails to decode is 400. The token must carry the ADMIN permission; an ordinary access token is refused. The per-kind permission table has no entry for wallet, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="walletid"></param>
|
|
pplx::task<void> patchCommerceWalletByWalletid(
|
|
utility::string_t walletid
|
|
) const;
|
|
/// <summary>
|
|
/// Change part of a watchlist
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A watchlist is a viewer's saved list of movies — a user id, an email, and the movies themselves. It stores WHOLE MOVIE SNAPSHOTS rather than movie ids, so a list goes stale the moment a film record changes and grows without bound as it fills. Loads the stored row and decodes the body OVER it, so only the fields the body names change and everything else keeps its stored value — the difference from the full replace, which clears what it is not told. Answers the merged row. An id absent from the caller org's namespace is 404 and a body that fails to decode is 400. Any valid access token reaches it. The per-kind permission table has no entry for watchlist, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="watchlistid"></param>
|
|
pplx::task<void> patchCommerceWatchlistByWatchlistid(
|
|
utility::string_t watchlistid
|
|
) const;
|
|
/// <summary>
|
|
/// Change part of a webhook
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A webhook is a merchant-registered endpoint that receives commerce event callbacks — a name, a URL, live and all flags, a per-event map, an enabled flag, and the shared access token each delivery posts IN THE BODY. Two things to know before registering one: that token is a plainly readable field, so anyone who may read webhooks reads every endpoint's secret, and delivery consults only the all flag and the event map — it does NOT consult enabled or live, so setting enabled false does not stop delivery and deleting the row is the only thing that does. Delivery is a single POST with a twenty-second timeout and no retry. Loads the stored row and decodes the body OVER it, so only the fields the body names change and everything else keeps its stored value — the difference from the full replace, which clears what it is not told. Answers the merged row. An id absent from the caller org's namespace is 404 and a body that fails to decode is 400. The token must carry the ADMIN permission; an ordinary access token is refused. The per-kind permission table has no entry for webhook, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="webhookid"></param>
|
|
pplx::task<void> patchCommerceWebhookByWebhookid(
|
|
utility::string_t webhookid
|
|
) const;
|
|
/// <summary>
|
|
/// Add a catalog entry
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Creates a catalog row from the body and answers it at 201. The slug is required and is the globally-unique catalog key, so a second entry claiming a slug already in use is refused 409 rather than shadowing the first. PLATFORM admin only — this is cross-tenant pricing and packaging data, and an org-level admin is refused 403.
|
|
/// </remarks>
|
|
pplx::task<void> postCommerceCatalogEntries(
|
|
) const;
|
|
/// <summary>
|
|
/// Land a syncer's view of the model catalog: upstream costs and machine facts
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Takes a batch of model rows and upserts each one's upstream COST and machine-observable facts, answering what was created and changed. It deliberately touches nothing a human owns — not the retail price, not the markup, not the entitlement tier — so a sync can never overwrite an administrator's pricing decision. The gate is a PLATFORM principal rather than a platform ADMIN, because the caller is normally a scheduled job holding the internal service token, which carries platform scope but no admin claim.
|
|
/// </remarks>
|
|
pplx::task<void> postCommerceCatalogModels(
|
|
) const;
|
|
/// <summary>
|
|
/// Refresh the model catalog by reading the upstream provider
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Pulls the upstream model list and lands it through the same upsert the push endpoint uses, so the rule that a sync owns cost and an administrator owns price holds no matter which endpoint a row came through. It takes no body — the upstream is READ rather than told. If that upstream cannot be read the call answers 502 and writes NOTHING: a sync that cannot see its source must never conclude the source is empty, because that conclusion would withdraw every model on sale. The gate is a PLATFORM principal so the scheduled job's service token qualifies.
|
|
/// </remarks>
|
|
pplx::task<void> postCommerceCatalogModelsRefresh(
|
|
) const;
|
|
/// <summary>
|
|
/// Seed the embedded catalog, without disturbing edits already made
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Upserts the shipped catalog seed and answers how many entries it created. It is idempotent and non-destructive — an entry an administrator has since edited is left alone — so it is safe to run against a live catalog to fill in what is missing. PLATFORM admin only; an org-level admin is refused 403.
|
|
/// </remarks>
|
|
pplx::task<void> postCommerceCatalogSeed(
|
|
) const;
|
|
/// <summary>
|
|
/// Create a collection
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A collection is a merchandising group a storefront renders — a slug and name, copy and media, flat lists of the product and variant ids it holds, published, preorder and out-of-stock flags, and an availability window. Membership lives on the collection as those id lists rather than as a join, so putting a product into a collection is a write here and not on the product. Decodes the body into a new row in the caller org's own namespaced store — isolated to that tenant from its first write — and answers the stored row at 201 with a Location header naming its id. The id is assigned by the store, not taken from the body. A body that fails to decode is 400 and a store that refuses the write is 500. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The token must also carry Admin or WriteCollection.
|
|
/// </remarks>
|
|
pplx::task<void> postCommerceCollection(
|
|
) const;
|
|
/// <summary>
|
|
/// Method-override tunnel for a collection — for clients that cannot send PUT, PATCH or DELETE
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A collection is a merchandising group a storefront renders — a slug and name, copy and media, flat lists of the product and variant ids it holds, published, preorder and out-of-stock flags, and an availability window. Membership lives on the collection as those id lists rather than as a join, so putting a product into a collection is a write here and not on the product. Re-dispatches the request into the handler the intended verb would have reached, taking that verb from a _method form value or query parameter and then from the X-HTTP-Method-Override header. PUT replaces the row, PATCH changes part of it, DELETE removes it, and anything else is 405. The trap is the DEFAULT: naming no override at all leaves the method POST, which this tunnel maps to the PARTIAL UPDATE — it is never a create, and creating is the collection root's job. Behaviour and authorization are the underlying operation's, since the real handler runs. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through.
|
|
/// </remarks>
|
|
/// <param name="collectionid"></param>
|
|
pplx::task<void> postCommerceCollectionByCollectionid(
|
|
utility::string_t collectionid
|
|
) const;
|
|
/// <summary>
|
|
/// Create a disclosure
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A disclosure is a published-document record — a publication body, a content hash, a type and a named receiver. The hash LOOKS like a field you set and is in fact derived, but only on update: a freshly created disclosure keeps whatever hash the caller sent until the first replace or patch recomputes it, so a new row's hash attests to nothing. This kind lives in commerce's demo tree — a live writable resource in your tenant's real store that nothing else in commerce reads. Decodes the body into a new row in the caller org's own namespaced store — isolated to that tenant from its first write — and answers the stored row at 201 with a Location header naming its id. The id is assigned by the store, not taken from the body. A body that fails to decode is 400 and a store that refuses the write is 500. Any valid access token reaches it. The per-kind permission table has no entry for disclosure, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
pplx::task<void> postCommerceDisclosure(
|
|
) const;
|
|
/// <summary>
|
|
/// Method-override tunnel for a disclosure — for clients that cannot send PUT, PATCH or DELETE
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A disclosure is a published-document record — a publication body, a content hash, a type and a named receiver. The hash LOOKS like a field you set and is in fact derived, but only on update: a freshly created disclosure keeps whatever hash the caller sent until the first replace or patch recomputes it, so a new row's hash attests to nothing. This kind lives in commerce's demo tree — a live writable resource in your tenant's real store that nothing else in commerce reads. Re-dispatches the request into the handler the intended verb would have reached, taking that verb from a _method form value or query parameter and then from the X-HTTP-Method-Override header. PUT replaces the row, PATCH changes part of it, DELETE removes it, and anything else is 405. The trap is the DEFAULT: naming no override at all leaves the method POST, which this tunnel maps to the PARTIAL UPDATE — it is never a create, and creating is the collection root's job. Behaviour and authorization are the underlying operation's, since the real handler runs. Any valid access token reaches it.
|
|
/// </remarks>
|
|
/// <param name="disclosureid"></param>
|
|
pplx::task<void> postCommerceDisclosureByDisclosureid(
|
|
utility::string_t disclosureid
|
|
) const;
|
|
/// <summary>
|
|
/// Create a discount
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A discount is a price rule: a type (flat, percent, free-shipping, free-item or bulk), a window, a scope naming the store, collection, product or variant it applies to, a target, and rules pairing a trigger — a price or quantity threshold — with an action, an amount off or a percentage. It is ENABLED BY DEFAULT, so a bare create makes a live discount rather than a draft. The rule engine caches per replica for about thirty seconds, so a discount switched off here can keep applying briefly on other replicas. Decodes the body into a new row in the caller org's own namespaced store — isolated to that tenant from its first write — and answers the stored row at 201 with a Location header naming its id. The id is assigned by the store, not taken from the body. A body that fails to decode is 400 and a store that refuses the write is 500. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The per-kind permission table has no entry for discount, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
pplx::task<void> postCommerceDiscount(
|
|
) const;
|
|
/// <summary>
|
|
/// Method-override tunnel for a discount — for clients that cannot send PUT, PATCH or DELETE
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A discount is a price rule: a type (flat, percent, free-shipping, free-item or bulk), a window, a scope naming the store, collection, product or variant it applies to, a target, and rules pairing a trigger — a price or quantity threshold — with an action, an amount off or a percentage. It is ENABLED BY DEFAULT, so a bare create makes a live discount rather than a draft. The rule engine caches per replica for about thirty seconds, so a discount switched off here can keep applying briefly on other replicas. Re-dispatches the request into the handler the intended verb would have reached, taking that verb from a _method form value or query parameter and then from the X-HTTP-Method-Override header. PUT replaces the row, PATCH changes part of it, DELETE removes it, and anything else is 405. The trap is the DEFAULT: naming no override at all leaves the method POST, which this tunnel maps to the PARTIAL UPDATE — it is never a create, and creating is the collection root's job. Behaviour and authorization are the underlying operation's, since the real handler runs. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through.
|
|
/// </remarks>
|
|
/// <param name="discountid"></param>
|
|
pplx::task<void> postCommerceDiscountByDiscountid(
|
|
utility::string_t discountid
|
|
) const;
|
|
/// <summary>
|
|
/// Create a movie
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A movie is a film catalog record — a slug plus EIDR and IMDB ids, all three required, with title and synopsis copy, artwork, screenshots, trailers, cast and crew, and available and hidden flags. It carries NO price: the money for a film lives on the product that sells it. Decodes the body into a new row in the caller org's own namespaced store — isolated to that tenant from its first write — and answers the stored row at 201 with a Location header naming its id. The id is assigned by the store, not taken from the body. A body that fails to decode is 400 and a store that refuses the write is 500. Any valid access token reaches it. The per-kind permission table has no entry for movie, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
pplx::task<void> postCommerceMovie(
|
|
) const;
|
|
/// <summary>
|
|
/// Method-override tunnel for a movie — for clients that cannot send PUT, PATCH or DELETE
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A movie is a film catalog record — a slug plus EIDR and IMDB ids, all three required, with title and synopsis copy, artwork, screenshots, trailers, cast and crew, and available and hidden flags. It carries NO price: the money for a film lives on the product that sells it. Re-dispatches the request into the handler the intended verb would have reached, taking that verb from a _method form value or query parameter and then from the X-HTTP-Method-Override header. PUT replaces the row, PATCH changes part of it, DELETE removes it, and anything else is 405. The trap is the DEFAULT: naming no override at all leaves the method POST, which this tunnel maps to the PARTIAL UPDATE — it is never a create, and creating is the collection root's job. Behaviour and authorization are the underlying operation's, since the real handler runs. Any valid access token reaches it.
|
|
/// </remarks>
|
|
/// <param name="movieid"></param>
|
|
pplx::task<void> postCommerceMovieByMovieid(
|
|
utility::string_t movieid
|
|
) const;
|
|
/// <summary>
|
|
/// Create a note
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A note is a timestamped free-text log line — a caller-supplied time, a source, a message and an enabled flag. That time is the caller's own field and is distinct from the row's creation stamp; the note search filters on it, so a note written without one is a zero-time note the ops log will never surface. Decodes the body into a new row in the caller org's own namespaced store — isolated to that tenant from its first write — and answers the stored row at 201 with a Location header naming its id. The id is assigned by the store, not taken from the body. A body that fails to decode is 400 and a store that refuses the write is 500. Any valid access token reaches it. The per-kind permission table has no entry for note, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
pplx::task<void> postCommerceNote(
|
|
) const;
|
|
/// <summary>
|
|
/// Method-override tunnel for a note — for clients that cannot send PUT, PATCH or DELETE
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A note is a timestamped free-text log line — a caller-supplied time, a source, a message and an enabled flag. That time is the caller's own field and is distinct from the row's creation stamp; the note search filters on it, so a note written without one is a zero-time note the ops log will never surface. Re-dispatches the request into the handler the intended verb would have reached, taking that verb from a _method form value or query parameter and then from the X-HTTP-Method-Override header. PUT replaces the row, PATCH changes part of it, DELETE removes it, and anything else is 405. The trap is the DEFAULT: naming no override at all leaves the method POST, which this tunnel maps to the PARTIAL UPDATE — it is never a create, and creating is the collection root's job. Behaviour and authorization are the underlying operation's, since the real handler runs. Any valid access token reaches it.
|
|
/// </remarks>
|
|
/// <param name="noteid"></param>
|
|
pplx::task<void> postCommerceNoteByNoteid(
|
|
utility::string_t noteid
|
|
) const;
|
|
/// <summary>
|
|
/// Add a subscription plan
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Creates a plan from the body and answers it at 201. The slug is required and globally unique — a duplicate is 409 — and the row is marked authoritative on creation, so the corrective seed will leave it alone. Price, annual price and the contact-sales flag are stored exactly as sent, never coerced, so the difference between a free plan and a quote-only plan survives. PLATFORM admin only.
|
|
/// </remarks>
|
|
pplx::task<void> postCommercePlansEntries(
|
|
) const;
|
|
/// <summary>
|
|
/// Seed the embedded plan catalog, without overwriting administrative edits
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Upserts the shipped plan rows and answers how many were created and how many corrected. It is idempotent and non-destructive — a row an administrator authored or edited is left as it stands — so it is safe against a live authority and fills only what is missing or has drifted. PLATFORM admin only, and a deployment with no seed source wired answers 500 rather than quietly seeding nothing.
|
|
/// </remarks>
|
|
pplx::task<void> postCommercePlansSeed(
|
|
) const;
|
|
/// <summary>
|
|
/// Create a product
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A product is a sellable catalog item: slug, SKU and UPC, name and copy, media, availability and preorder flags, a reservation block, and its money — currency, price, MSRP, list price and inventory cost in minor units, inventory count, taxability, and the subscription interval when it is subscribeable. Its variants and options are carried as a denormalized JSON snapshot inside the product, separate from the standalone variant rows, and nothing keeps the two in step for you. Decodes the body into a new row in the caller org's own namespaced store — isolated to that tenant from its first write — and answers the stored row at 201 with a Location header naming its id. The id is assigned by the store, not taken from the body. A body that fails to decode is 400 and a store that refuses the write is 500. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The token must also carry Admin or WriteProduct.
|
|
/// </remarks>
|
|
pplx::task<void> postCommerceProduct(
|
|
) const;
|
|
/// <summary>
|
|
/// Method-override tunnel for a product — for clients that cannot send PUT, PATCH or DELETE
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A product is a sellable catalog item: slug, SKU and UPC, name and copy, media, availability and preorder flags, a reservation block, and its money — currency, price, MSRP, list price and inventory cost in minor units, inventory count, taxability, and the subscription interval when it is subscribeable. Its variants and options are carried as a denormalized JSON snapshot inside the product, separate from the standalone variant rows, and nothing keeps the two in step for you. Re-dispatches the request into the handler the intended verb would have reached, taking that verb from a _method form value or query parameter and then from the X-HTTP-Method-Override header. PUT replaces the row, PATCH changes part of it, DELETE removes it, and anything else is 405. The trap is the DEFAULT: naming no override at all leaves the method POST, which this tunnel maps to the PARTIAL UPDATE — it is never a create, and creating is the collection root's job. Behaviour and authorization are the underlying operation's, since the real handler runs. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through.
|
|
/// </remarks>
|
|
/// <param name="productid"></param>
|
|
pplx::task<void> postCommerceProductByProductid(
|
|
utility::string_t productid
|
|
) const;
|
|
/// <summary>
|
|
/// Add a rate
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Creates one rate. Product AND meter are both required, because together they are the identity: a rate keyed on the metered thing alone would let one product's price overwrite another's under the same name. A slug that already exists is refused rather than silently replaced. SuperAdmin only.
|
|
/// </remarks>
|
|
pplx::task<void> postCommerceRatesEntries(
|
|
) const;
|
|
/// <summary>
|
|
/// Load the published price document, reconciling rather than replacing
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Takes an array of rates and seeds the authority from it — the same reconcile the boot catalog runs, driven from admin instead. It RECONCILES: a row that matches is left alone, a row that has drifted is corrected, and a row an operator edited is skipped — so importing the same document twice is a no-op and importing a corrected one moves exactly the rows that changed. Answers what it received, created, corrected and left unchanged, so an import that changes nothing reads as nothing to do rather than as a failure. An empty array is refused 400. SuperAdmin only.
|
|
/// </remarks>
|
|
pplx::task<void> postCommerceRatesImport(
|
|
) const;
|
|
/// <summary>
|
|
/// Create a return
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A return is an RMA — the store, user and order it belongs to, the line items coming back, a fulfillment block carrying its own type, status and pricing, a summary, and eight lifecycle timestamps from submitted through delivered and processed. Its status is a FREE STRING with no enumeration behind it, and there is no refund amount on the return itself: the money sits inside the line items and the fulfillment pricing. Decodes the body into a new row in the caller org's own namespaced store — isolated to that tenant from its first write — and answers the stored row at 201 with a Location header naming its id. The id is assigned by the store, not taken from the body. A body that fails to decode is 400 and a store that refuses the write is 500. Any valid access token reaches it. The token must also carry Admin or WriteReturn.
|
|
/// </remarks>
|
|
pplx::task<void> postCommerceReturn(
|
|
) const;
|
|
/// <summary>
|
|
/// Method-override tunnel for a return — for clients that cannot send PUT, PATCH or DELETE
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A return is an RMA — the store, user and order it belongs to, the line items coming back, a fulfillment block carrying its own type, status and pricing, a summary, and eight lifecycle timestamps from submitted through delivered and processed. Its status is a FREE STRING with no enumeration behind it, and there is no refund amount on the return itself: the money sits inside the line items and the fulfillment pricing. Re-dispatches the request into the handler the intended verb would have reached, taking that verb from a _method form value or query parameter and then from the X-HTTP-Method-Override header. PUT replaces the row, PATCH changes part of it, DELETE removes it, and anything else is 405. The trap is the DEFAULT: naming no override at all leaves the method POST, which this tunnel maps to the PARTIAL UPDATE — it is never a create, and creating is the collection root's job. Behaviour and authorization are the underlying operation's, since the real handler runs. Any valid access token reaches it.
|
|
/// </remarks>
|
|
/// <param name="returnid"></param>
|
|
pplx::task<void> postCommerceReturnByReturnid(
|
|
utility::string_t returnid
|
|
) const;
|
|
/// <summary>
|
|
/// Create a sales channel
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A sales channel is a named selling surface — a name, a description, a disabled flag and metadata. The flag is NEGATIVE, so a channel created from an empty body is enabled. Nothing on this row links products, prices or stock to the channel; here it is a label other surfaces scope themselves by. Decodes the body into a new row in the caller org's own namespaced store — isolated to that tenant from its first write — and answers the stored row at 201 with a Location header naming its id. The id is assigned by the store, not taken from the body. A body that fails to decode is 400 and a store that refuses the write is 500. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The per-kind permission table has no entry for saleschannel, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
pplx::task<void> postCommerceSaleschannel(
|
|
) const;
|
|
/// <summary>
|
|
/// Method-override tunnel for a sales channel — for clients that cannot send PUT, PATCH or DELETE
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A sales channel is a named selling surface — a name, a description, a disabled flag and metadata. The flag is NEGATIVE, so a channel created from an empty body is enabled. Nothing on this row links products, prices or stock to the channel; here it is a label other surfaces scope themselves by. Re-dispatches the request into the handler the intended verb would have reached, taking that verb from a _method form value or query parameter and then from the X-HTTP-Method-Override header. PUT replaces the row, PATCH changes part of it, DELETE removes it, and anything else is 405. The trap is the DEFAULT: naming no override at all leaves the method POST, which this tunnel maps to the PARTIAL UPDATE — it is never a create, and creating is the collection root's job. Behaviour and authorization are the underlying operation's, since the real handler runs. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through.
|
|
/// </remarks>
|
|
/// <param name="saleschannelid"></param>
|
|
pplx::task<void> postCommerceSaleschannelBySaleschannelid(
|
|
utility::string_t saleschannelid
|
|
) const;
|
|
/// <summary>
|
|
/// Create a stock location
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A stock location is a physical address inventory can be held at — a name, street lines, city, province, country, postal code and a phone. None of it is validated, there are no coordinates, and the row carries no enabled flag and no inventory link, so deleting it is the only way to retire one. Decodes the body into a new row in the caller org's own namespaced store — isolated to that tenant from its first write — and answers the stored row at 201 with a Location header naming its id. The id is assigned by the store, not taken from the body. A body that fails to decode is 400 and a store that refuses the write is 500. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The per-kind permission table has no entry for stocklocation, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
pplx::task<void> postCommerceStocklocation(
|
|
) const;
|
|
/// <summary>
|
|
/// Method-override tunnel for a stock location — for clients that cannot send PUT, PATCH or DELETE
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A stock location is a physical address inventory can be held at — a name, street lines, city, province, country, postal code and a phone. None of it is validated, there are no coordinates, and the row carries no enabled flag and no inventory link, so deleting it is the only way to retire one. Re-dispatches the request into the handler the intended verb would have reached, taking that verb from a _method form value or query parameter and then from the X-HTTP-Method-Override header. PUT replaces the row, PATCH changes part of it, DELETE removes it, and anything else is 405. The trap is the DEFAULT: naming no override at all leaves the method POST, which this tunnel maps to the PARTIAL UPDATE — it is never a create, and creating is the collection root's job. Behaviour and authorization are the underlying operation's, since the real handler runs. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through.
|
|
/// </remarks>
|
|
/// <param name="stocklocationid"></param>
|
|
pplx::task<void> postCommerceStocklocationByStocklocationid(
|
|
utility::string_t stocklocationid
|
|
) const;
|
|
/// <summary>
|
|
/// Create a storefront
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Creates a store from the body inside the caller org's own namespaced database, so the row is physically isolated to that tenant from its first write, and answers it at 201 with a Location header naming its id. Requires an admin or store-write token: the anonymous published storefront key may READ stores but never create one. A body that fails to decode is 400.
|
|
/// </remarks>
|
|
pplx::task<void> postCommerceStore(
|
|
) const;
|
|
/// <summary>
|
|
/// Method-override tunnel for clients that cannot send PUT, PATCH or DELETE
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Re-dispatches the request into the handler the intended verb would have reached, taking that verb from a _method form value or query parameter and then from the X-HTTP-Method-Override header, the header winning when both are present. Only PUT, PATCH and DELETE are accepted; anything else resolves to 405. The trap is the default: naming NO override at all is treated as a partial update, never as a create. Authorization is whatever the underlying operation requires, since the real handler runs.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
pplx::task<void> postCommerceStoreByStoreid(
|
|
utility::string_t storeid
|
|
) const;
|
|
/// <summary>
|
|
/// Authorize a new order against a storefront, holding the funds without settling them
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Tallies a new order for the addressed store from the user, payment and order body, reserves its items, runs the processor authorization and answers the saved order with a Location header pointing at it. The gate is a token carrying admin or published scope, so a published storefront key is enough; no token is 401 and a token with neither bit is 403. The store is loaded BEFORE any payment work and its currency OVERRIDES whatever the body asked for, so a store that will not load ends the call with 500 and nothing is charged. On any authorization failure the reservations are released and the order and payment are persisted as cancelled, so a failed attempt still leaves a durable record. Capture is a separate call.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
pplx::task<void> postCommerceStoreByStoreidAuthorize(
|
|
utility::string_t storeid
|
|
) const;
|
|
/// <summary>
|
|
/// Authorize an order that already exists, holding the funds without settling them
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Continues the order named in the path rather than minting a new one, holding funds for it. The order is loaded from the caller org's own store, so an id belonging to another tenant is a 404. The rule most callers get wrong is that the body's order object is MERGED onto the loaded order before the tally — this is not a read-only reference, and a field sent here overwrites what is stored. The gate, the store resolution and the currency override behave exactly as on the bodiless-id sibling, and settling is still the capture call's job.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
/// <param name="orderid"></param>
|
|
pplx::task<void> postCommerceStoreByStoreidAuthorizeByOrderid(
|
|
utility::string_t storeid,
|
|
utility::string_t orderid
|
|
) const;
|
|
/// <summary>
|
|
/// Capture a previously authorized order and settle the payment
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Settles the order named in the path — the second half of the two-step flow — and answers the updated order with a Location header. Dispatch follows the order's STORED payment type, and a successful capture is the moment the rest of the system learns about the sale: order and payment rows are updated, coupon redemptions, referral, cart and stats are written, the confirmation email goes out, and the paid and completed events are emitted. A capture failure releases the order's inventory reservations and answers 400, so a failed settlement never leaves items held.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
/// <param name="orderid"></param>
|
|
pplx::task<void> postCommerceStoreByStoreidCaptureByOrderid(
|
|
utility::string_t storeid,
|
|
utility::string_t orderid
|
|
) const;
|
|
/// <summary>
|
|
/// Authorize and capture a new order in one call
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Runs authorization and capture back to back against a freshly created order — the one-step flow for callers with no reason to hold funds. It takes the authorize body and inherits every authorize rule: the store's currency wins over the body, the items are reserved before the processor is called, and the amount bounds the processor enforces still apply. There is no order id on this address, so it can never continue an existing order. Either half failing answers 400, and the capture side effects — confirmation email, redemptions, stats, the paid and completed events — run only when both halves succeed.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
pplx::task<void> postCommerceStoreByStoreidCharge(
|
|
utility::string_t storeid
|
|
) const;
|
|
/// <summary>
|
|
/// Authorize a new order against a storefront, holding the funds — the checkout spelling
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Authorizes a new order for the addressed store and holds the funds, answering the saved order with a Location header. It binds the identical handler as the shorter authorize address, so the two are ONE operation at two spellings and not two behaviours; the checkout prefix is the newer one. Every rule carries over: admin or published scope on the token, the store loaded first with its currency overriding the body, items reserved before the processor call, and reservations released with the order persisted cancelled on failure. Nothing is settled here.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
pplx::task<void> postCommerceStoreByStoreidCheckoutAuthorize(
|
|
utility::string_t storeid
|
|
) const;
|
|
/// <summary>
|
|
/// Authorize an existing order, holding the funds — the checkout spelling
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Continues the order named in the path rather than minting one, and shares its handler byte for byte with the unprefixed authorize-by-id address. The order is loaded from the caller org's own store, so another tenant's id is a 404, and the body's order object is merged onto the loaded row before the tally — a field sent here overwrites what is stored. Store resolution, the token gate and the currency override behave as on every other authorize address; settle with the capture address and the same order id.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
/// <param name="orderid"></param>
|
|
pplx::task<void> postCommerceStoreByStoreidCheckoutAuthorizeByOrderid(
|
|
utility::string_t storeid,
|
|
utility::string_t orderid
|
|
) const;
|
|
/// <summary>
|
|
/// Capture a previously authorized order and settle it — the checkout spelling
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Settles the authorized order named in the path and answers the updated order with a Location header, running the same handler as the unprefixed capture address. Dispatch follows the order's stored payment type. Success is what triggers the downstream work — order and payment updates, redemptions, referral, cart and stats, the confirmation email, and the paid and completed events — while a failure releases the order's inventory reservations and answers 400.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
/// <param name="orderid"></param>
|
|
pplx::task<void> postCommerceStoreByStoreidCheckoutCaptureByOrderid(
|
|
utility::string_t storeid,
|
|
utility::string_t orderid
|
|
) const;
|
|
/// <summary>
|
|
/// Authorize and capture a new order in one call — the checkout spelling
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Performs authorization and capture back to back against a newly created order for the addressed store, on the same handler as the unprefixed charge address. It takes the authorize body and inherits every authorize rule, including the store's currency winning over the body and the items being reserved before the processor is called. There is no order id on this address, so it can never continue an existing order. Either half failing answers 400, and the capture side effects run only when both succeed.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
pplx::task<void> postCommerceStoreByStoreidCheckoutCharge(
|
|
utility::string_t storeid
|
|
) const;
|
|
/// <summary>
|
|
/// PayPal cancel by pay key — refuses, exactly as the unprefixed address does
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Meant to void the payments carrying the given pay key, stamp them cancelled and cancel the order, but the shared checkout handler resolves its order from an ORDER ID path parameter this route does not carry. The result is an untyped order and a cancel dispatch that refuses with 400 before the pay key lookup ever runs. Token gate, namespacing and store resolution happen first, so a missing token is still 401 and an unloadable store still 500. It is the same handler as the unprefixed cancel address, with the same outcome.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
/// <param name="payKey"></param>
|
|
pplx::task<void> postCommerceStoreByStoreidCheckoutPaypalCancelByPaykey(
|
|
utility::string_t storeid,
|
|
utility::string_t payKey
|
|
) const;
|
|
/// <summary>
|
|
/// PayPal confirm by pay key — refuses, exactly as the unprefixed address does
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Meant to mark the payments carrying the given pay key as paid and set the order to paid, it cannot reach that work from this address: the shared checkout handler takes its order from an ORDER ID path parameter this route does not carry, so the order is always fresh and untyped and the confirm dispatch refuses with 400 before the pay key is queried. The token gate, the namespace middleware and the store lookup all run ahead of that, so authentication and store failures surface first. Behaviour is identical to the unprefixed confirm address; the checkout prefix changes nothing here.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
/// <param name="payKey"></param>
|
|
pplx::task<void> postCommerceStoreByStoreidCheckoutPaypalConfirmByPaykey(
|
|
utility::string_t storeid,
|
|
utility::string_t payKey
|
|
) const;
|
|
/// <summary>
|
|
/// Start a PayPal authorization for a new order — the checkout spelling
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Begins a PayPal authorization by running the ordinary store authorize flow, since the route binds that exact handler — body, store resolution, tally, reservations and failure behaviour are the authorize address's, unchanged. The processor is chosen from the body's payment type, so this path reaches PayPal only when that type says so. A successful PayPal authorization stamps a pay key onto the payment, which is the key the confirm and cancel addresses filter on. Build against the plain authorize address instead.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
pplx::task<void> postCommerceStoreByStoreidCheckoutPaypalPay(
|
|
utility::string_t storeid
|
|
) const;
|
|
/// <summary>
|
|
/// Add a listing override under a new key
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Creates the override and answers the store's ENTIRE listing map at 201 with a Location header — not just the entry that was added. A key already present is refused 400: creation never silently overwrites, so changing an existing listing has to be an explicit replace. The stored listing has its currency stamped from the store's own, which the replace path does not do. The key is matched exactly here, with none of the slug or SKU fallback the read allows. Admin-gated and resolved inside the caller org's namespace.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
/// <param name="key"></param>
|
|
pplx::task<void> postCommerceStoreByStoreidListingByKey(
|
|
utility::string_t storeid,
|
|
utility::string_t key
|
|
) const;
|
|
/// <summary>
|
|
/// PayPal cancel by pay key — refuses, because a pay key alone does not identify the order
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Intended to void the payments carrying the given pay key, stamp them cancelled and cancel the order, it never reaches that work: the shared checkout handler reads its order from an ORDER ID path parameter this route does not carry, leaving an untyped order that the cancel dispatch refuses with 400 before the pay key lookup runs. Authentication, namespacing and store resolution happen ahead of the refusal, so a missing token is 401 and an unloadable store 500. Cancelling a real PayPal authorization needs an address that carries the order id.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
/// <param name="payKey"></param>
|
|
pplx::task<void> postCommerceStoreByStoreidPaypalCancelByPaykey(
|
|
utility::string_t storeid,
|
|
utility::string_t payKey
|
|
) const;
|
|
/// <summary>
|
|
/// PayPal confirm by pay key — refuses, because a pay key alone does not identify the order
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Intended to mark every payment carrying the given pay key as paid and flip the order to paid, it cannot do that from this address and does not pretend to: the shared checkout handler resolves its order from an ORDER ID path parameter that this route does not carry, so it always works against a fresh untyped order and the confirm dispatch refuses it with 400 before the pay key is ever queried. The token gate, the namespace and the store lookup all run ahead of that, so a missing token is still 401 and an unloadable store still 500. Drive a PayPal return through an address that carries the order id.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
/// <param name="payKey"></param>
|
|
pplx::task<void> postCommerceStoreByStoreidPaypalConfirmByPaykey(
|
|
utility::string_t storeid,
|
|
utility::string_t payKey
|
|
) const;
|
|
/// <summary>
|
|
/// Start a PayPal authorization for a new order
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Runs the ordinary store authorize flow — the route binds that very handler, so the body, the store resolution, the tally, the reservations and the failure behaviour are the authorize address's, unchanged. It reaches PayPal only when the body's payment type says so; nothing about this path forces the processor, so a card-typed payment posted here authorizes on the card processor instead. A successful PayPal authorization stamps a pay key onto the payment, which is the key the confirm and cancel addresses filter on. It is the older entry point; the plain authorize address is the one to build against.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
pplx::task<void> postCommerceStoreByStoreidPaypalPay(
|
|
utility::string_t storeid
|
|
) const;
|
|
/// <summary>
|
|
/// Start this store's no-card trial on the entry plan
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Creates a trialing subscription for the addressed store on the entry plan and grants that plan's trial credit, answering 201 when this call actually started one and 200 with a reason otherwise — not_new when the store already has billing history, trial_not_configured when no entry plan is wired. The window is always the SEVEN-DAY no-card trial, because this address never presents a card; the longer card-present window is reached only by adding a card afterwards. Entitlement is per store while the billing subject is the org, so every store an org owns takes its own trial. Admin-gated and namespaced to the caller's org: no resolvable store is 404 with store_required, and a backing-store failure is 503.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
pplx::task<void> postCommerceStoreByStoreidTrial(
|
|
utility::string_t storeid
|
|
) const;
|
|
/// <summary>
|
|
/// Mint your org's least-privilege storefront read key
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Answers a freshly minted token carrying ONLY the published-read permission — enough for a logged-out shopper's storefront to read your published catalog and nothing more, with no write and no admin scope. It is org-bound, signed with the org's own secret and subject to the org id, so unlike a shared service token it can never act on another tenant. Minting ROTATES rather than accumulates: the previous storefront token is dropped first and is invalid immediately, so re-minting is how you revoke. Admin is enforced by the handler as well as the route, because the route's token gate does not apply on the identity path and a plain member must not be able to mint their org's key.
|
|
/// </remarks>
|
|
pplx::task<void> postCommerceStoreToken(
|
|
) const;
|
|
/// <summary>
|
|
/// Create a submission
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A submission is one filled-in form from a site visitor — an email, an optional user id, the client details the server observed (user agent, referer, geography) and the form's own fields as free metadata. It carries no form id, so the link back to the form that produced it is not stored on the row. Decodes the body into a new row in the caller org's own namespaced store — isolated to that tenant from its first write — and answers the stored row at 201 with a Location header naming its id. The id is assigned by the store, not taken from the body. A body that fails to decode is 400 and a store that refuses the write is 500. Any valid access token reaches it. The per-kind permission table has no entry for submission, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
pplx::task<void> postCommerceSubmission(
|
|
) const;
|
|
/// <summary>
|
|
/// Method-override tunnel for a submission — for clients that cannot send PUT, PATCH or DELETE
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A submission is one filled-in form from a site visitor — an email, an optional user id, the client details the server observed (user agent, referer, geography) and the form's own fields as free metadata. It carries no form id, so the link back to the form that produced it is not stored on the row. Re-dispatches the request into the handler the intended verb would have reached, taking that verb from a _method form value or query parameter and then from the X-HTTP-Method-Override header. PUT replaces the row, PATCH changes part of it, DELETE removes it, and anything else is 405. The trap is the DEFAULT: naming no override at all leaves the method POST, which this tunnel maps to the PARTIAL UPDATE — it is never a create, and creating is the collection root's job. Behaviour and authorization are the underlying operation's, since the real handler runs. Any valid access token reaches it.
|
|
/// </remarks>
|
|
/// <param name="submissionid"></param>
|
|
pplx::task<void> postCommerceSubmissionBySubmissionid(
|
|
utility::string_t submissionid
|
|
) const;
|
|
/// <summary>
|
|
/// Create a subscriber
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A subscriber is a mailing-list member — name, email, the form id that captured them, unsubscribed state and date, client details, tags and metadata. Writing one FIRES A WEBHOOK: subscriber.created on create and subscriber.updated on replace or patch, emitted BEFORE the write is known to have succeeded and carrying the row as sent, so the payload holds the raw email rather than the normalized one that gets stored. Decodes the body into a new row in the caller org's own namespaced store — isolated to that tenant from its first write — and answers the stored row at 201 with a Location header naming its id. The id is assigned by the store, not taken from the body. A body that fails to decode is 400 and a store that refuses the write is 500. Any valid access token reaches it. The token must also carry Admin or WriteSubscriber.
|
|
/// </remarks>
|
|
pplx::task<void> postCommerceSubscriber(
|
|
) const;
|
|
/// <summary>
|
|
/// Method-override tunnel for a subscriber — for clients that cannot send PUT, PATCH or DELETE
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A subscriber is a mailing-list member — name, email, the form id that captured them, unsubscribed state and date, client details, tags and metadata. Writing one FIRES A WEBHOOK: subscriber.created on create and subscriber.updated on replace or patch, emitted BEFORE the write is known to have succeeded and carrying the row as sent, so the payload holds the raw email rather than the normalized one that gets stored. Re-dispatches the request into the handler the intended verb would have reached, taking that verb from a _method form value or query parameter and then from the X-HTTP-Method-Override header. PUT replaces the row, PATCH changes part of it, DELETE removes it, and anything else is 405. The trap is the DEFAULT: naming no override at all leaves the method POST, which this tunnel maps to the PARTIAL UPDATE — it is never a create, and creating is the collection root's job. Behaviour and authorization are the underlying operation's, since the real handler runs. Any valid access token reaches it.
|
|
/// </remarks>
|
|
/// <param name="subscriberid"></param>
|
|
pplx::task<void> postCommerceSubscriberBySubscriberid(
|
|
utility::string_t subscriberid
|
|
) const;
|
|
/// <summary>
|
|
/// Create a token transaction
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A token transaction records a transfer between two identified parties — amount and fees, a timestamp, sending and receiving addresses, names, user ids, states and countries, a flag per side, a protocol name and a transaction hash. Nothing here touches a chain: the hash is an unvalidated string and the flags are plain writable booleans with no screening behind them. Amounts are floating-point rather than the exact minor units every real money field in commerce uses, and there is no currency field at all — this kind lives in commerce's demo tree, so it is a live writable resource in your tenant's store that nothing else in commerce reads, and it must never carry real money. Decodes the body into a new row in the caller org's own namespaced store — isolated to that tenant from its first write — and answers the stored row at 201 with a Location header naming its id. The id is assigned by the store, not taken from the body. A body that fails to decode is 400 and a store that refuses the write is 500. Any valid access token reaches it. The per-kind permission table has no entry for tokentransaction, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
pplx::task<void> postCommerceTokentransaction(
|
|
) const;
|
|
/// <summary>
|
|
/// Method-override tunnel for a token transaction — for clients that cannot send PUT, PATCH or DELETE
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A token transaction records a transfer between two identified parties — amount and fees, a timestamp, sending and receiving addresses, names, user ids, states and countries, a flag per side, a protocol name and a transaction hash. Nothing here touches a chain: the hash is an unvalidated string and the flags are plain writable booleans with no screening behind them. Amounts are floating-point rather than the exact minor units every real money field in commerce uses, and there is no currency field at all — this kind lives in commerce's demo tree, so it is a live writable resource in your tenant's store that nothing else in commerce reads, and it must never carry real money. Re-dispatches the request into the handler the intended verb would have reached, taking that verb from a _method form value or query parameter and then from the X-HTTP-Method-Override header. PUT replaces the row, PATCH changes part of it, DELETE removes it, and anything else is 405. The trap is the DEFAULT: naming no override at all leaves the method POST, which this tunnel maps to the PARTIAL UPDATE — it is never a create, and creating is the collection root's job. Behaviour and authorization are the underlying operation's, since the real handler runs. Any valid access token reaches it.
|
|
/// </remarks>
|
|
/// <param name="tokentransactionid"></param>
|
|
pplx::task<void> postCommerceTokentransactionByTokentransactionid(
|
|
utility::string_t tokentransactionid
|
|
) const;
|
|
/// <summary>
|
|
/// Create a transfer
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A transfer records that a payable WAS PAID — the annotation a human writes after paying out of band. Commerce executes no payout: creating one moves no money, and it marks the referenced payable settled. It carries the payable and payee ids, the amount it settles and the amount actually sent (which may be a different asset), a type of eth, wire or other, the transaction hash or wire reference, when it was paid and who recorded it; amounts are exact decimal strings with an asset, not cents. It is admin-gated because writing one settles money we owe, and nothing enforces uniqueness on the reference — so posting the same transfer twice settles the payable twice. Decodes the body into a new row in the caller org's own namespaced store — isolated to that tenant from its first write — and answers the stored row at 201 with a Location header naming its id. The id is assigned by the store, not taken from the body. A body that fails to decode is 400 and a store that refuses the write is 500. The token must carry the ADMIN permission; an ordinary access token is refused. The per-kind permission table has no entry for transfer, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
pplx::task<void> postCommerceTransfer(
|
|
) const;
|
|
/// <summary>
|
|
/// Method-override tunnel for a transfer — for clients that cannot send PUT, PATCH or DELETE
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A transfer records that a payable WAS PAID — the annotation a human writes after paying out of band. Commerce executes no payout: creating one moves no money, and it marks the referenced payable settled. It carries the payable and payee ids, the amount it settles and the amount actually sent (which may be a different asset), a type of eth, wire or other, the transaction hash or wire reference, when it was paid and who recorded it; amounts are exact decimal strings with an asset, not cents. It is admin-gated because writing one settles money we owe, and nothing enforces uniqueness on the reference — so posting the same transfer twice settles the payable twice. Re-dispatches the request into the handler the intended verb would have reached, taking that verb from a _method form value or query parameter and then from the X-HTTP-Method-Override header. PUT replaces the row, PATCH changes part of it, DELETE removes it, and anything else is 405. The trap is the DEFAULT: naming no override at all leaves the method POST, which this tunnel maps to the PARTIAL UPDATE — it is never a create, and creating is the collection root's job. Behaviour and authorization are the underlying operation's, since the real handler runs. The token must carry the ADMIN permission; an ordinary access token is refused.
|
|
/// </remarks>
|
|
/// <param name="transferid"></param>
|
|
pplx::task<void> postCommerceTransferByTransferid(
|
|
utility::string_t transferid
|
|
) const;
|
|
/// <summary>
|
|
/// Create a variant
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A variant is one purchasable SKU of a product — its product id, SKU and UPC, name, media, availability, the option name and value pairs that distinguish it, a sold counter, and its own money and stock: currency, price, MSRP, inventory cost, inventory count and taxability. Inventory and sold are plain writable numbers with no decrement logic behind them here. The same variant also exists as a JSON copy inside its product, and writing one does not update the other. Decodes the body into a new row in the caller org's own namespaced store — isolated to that tenant from its first write — and answers the stored row at 201 with a Location header naming its id. The id is assigned by the store, not taken from the body. A body that fails to decode is 400 and a store that refuses the write is 500. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The token must also carry Admin or WriteVariant.
|
|
/// </remarks>
|
|
pplx::task<void> postCommerceVariant(
|
|
) const;
|
|
/// <summary>
|
|
/// Method-override tunnel for a variant — for clients that cannot send PUT, PATCH or DELETE
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A variant is one purchasable SKU of a product — its product id, SKU and UPC, name, media, availability, the option name and value pairs that distinguish it, a sold counter, and its own money and stock: currency, price, MSRP, inventory cost, inventory count and taxability. Inventory and sold are plain writable numbers with no decrement logic behind them here. The same variant also exists as a JSON copy inside its product, and writing one does not update the other. Re-dispatches the request into the handler the intended verb would have reached, taking that verb from a _method form value or query parameter and then from the X-HTTP-Method-Override header. PUT replaces the row, PATCH changes part of it, DELETE removes it, and anything else is 405. The trap is the DEFAULT: naming no override at all leaves the method POST, which this tunnel maps to the PARTIAL UPDATE — it is never a create, and creating is the collection root's job. Behaviour and authorization are the underlying operation's, since the real handler runs. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through.
|
|
/// </remarks>
|
|
/// <param name="variantid"></param>
|
|
pplx::task<void> postCommerceVariantByVariantid(
|
|
utility::string_t variantid
|
|
) const;
|
|
/// <summary>
|
|
/// Create a wallet
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A wallet is a container of custodial blockchain accounts, and its only field is that account list — each account carrying a name, an address, a chain type, and the ENCRYPTED private key with its salt. Creating a wallet through this table generates NO KEYS: key generation lives on the account routes, so a wallet made here is an empty shell and an account posted into one is stored exactly as sent, with no key generation and no validation behind it. Know what a read renders: the plaintext private key is never marshalled and never stored, but the encrypted blob and its salt ARE returned, so whoever can read a wallet can attack it offline down to the strength of the owner's passphrase. That is why this kind is admin-gated. Decodes the body into a new row in the caller org's own namespaced store — isolated to that tenant from its first write — and answers the stored row at 201 with a Location header naming its id. The id is assigned by the store, not taken from the body. A body that fails to decode is 400 and a store that refuses the write is 500. The token must carry the ADMIN permission; an ordinary access token is refused. The per-kind permission table has no entry for wallet, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
pplx::task<void> postCommerceWallet(
|
|
) const;
|
|
/// <summary>
|
|
/// Method-override tunnel for a wallet — for clients that cannot send PUT, PATCH or DELETE
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A wallet is a container of custodial blockchain accounts, and its only field is that account list — each account carrying a name, an address, a chain type, and the ENCRYPTED private key with its salt. Creating a wallet through this table generates NO KEYS: key generation lives on the account routes, so a wallet made here is an empty shell and an account posted into one is stored exactly as sent, with no key generation and no validation behind it. Know what a read renders: the plaintext private key is never marshalled and never stored, but the encrypted blob and its salt ARE returned, so whoever can read a wallet can attack it offline down to the strength of the owner's passphrase. That is why this kind is admin-gated. Re-dispatches the request into the handler the intended verb would have reached, taking that verb from a _method form value or query parameter and then from the X-HTTP-Method-Override header. PUT replaces the row, PATCH changes part of it, DELETE removes it, and anything else is 405. The trap is the DEFAULT: naming no override at all leaves the method POST, which this tunnel maps to the PARTIAL UPDATE — it is never a create, and creating is the collection root's job. Behaviour and authorization are the underlying operation's, since the real handler runs. The token must carry the ADMIN permission; an ordinary access token is refused.
|
|
/// </remarks>
|
|
/// <param name="walletid"></param>
|
|
pplx::task<void> postCommerceWalletByWalletid(
|
|
utility::string_t walletid
|
|
) const;
|
|
/// <summary>
|
|
/// Create a watchlist
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A watchlist is a viewer's saved list of movies — a user id, an email, and the movies themselves. It stores WHOLE MOVIE SNAPSHOTS rather than movie ids, so a list goes stale the moment a film record changes and grows without bound as it fills. Decodes the body into a new row in the caller org's own namespaced store — isolated to that tenant from its first write — and answers the stored row at 201 with a Location header naming its id. The id is assigned by the store, not taken from the body. A body that fails to decode is 400 and a store that refuses the write is 500. Any valid access token reaches it. The per-kind permission table has no entry for watchlist, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
pplx::task<void> postCommerceWatchlist(
|
|
) const;
|
|
/// <summary>
|
|
/// Method-override tunnel for a watchlist — for clients that cannot send PUT, PATCH or DELETE
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A watchlist is a viewer's saved list of movies — a user id, an email, and the movies themselves. It stores WHOLE MOVIE SNAPSHOTS rather than movie ids, so a list goes stale the moment a film record changes and grows without bound as it fills. Re-dispatches the request into the handler the intended verb would have reached, taking that verb from a _method form value or query parameter and then from the X-HTTP-Method-Override header. PUT replaces the row, PATCH changes part of it, DELETE removes it, and anything else is 405. The trap is the DEFAULT: naming no override at all leaves the method POST, which this tunnel maps to the PARTIAL UPDATE — it is never a create, and creating is the collection root's job. Behaviour and authorization are the underlying operation's, since the real handler runs. Any valid access token reaches it.
|
|
/// </remarks>
|
|
/// <param name="watchlistid"></param>
|
|
pplx::task<void> postCommerceWatchlistByWatchlistid(
|
|
utility::string_t watchlistid
|
|
) const;
|
|
/// <summary>
|
|
/// Create a webhook
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A webhook is a merchant-registered endpoint that receives commerce event callbacks — a name, a URL, live and all flags, a per-event map, an enabled flag, and the shared access token each delivery posts IN THE BODY. Two things to know before registering one: that token is a plainly readable field, so anyone who may read webhooks reads every endpoint's secret, and delivery consults only the all flag and the event map — it does NOT consult enabled or live, so setting enabled false does not stop delivery and deleting the row is the only thing that does. Delivery is a single POST with a twenty-second timeout and no retry. Decodes the body into a new row in the caller org's own namespaced store — isolated to that tenant from its first write — and answers the stored row at 201 with a Location header naming its id. The id is assigned by the store, not taken from the body. A body that fails to decode is 400 and a store that refuses the write is 500. The token must carry the ADMIN permission; an ordinary access token is refused. The per-kind permission table has no entry for webhook, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
pplx::task<void> postCommerceWebhook(
|
|
) const;
|
|
/// <summary>
|
|
/// Method-override tunnel for a webhook — for clients that cannot send PUT, PATCH or DELETE
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A webhook is a merchant-registered endpoint that receives commerce event callbacks — a name, a URL, live and all flags, a per-event map, an enabled flag, and the shared access token each delivery posts IN THE BODY. Two things to know before registering one: that token is a plainly readable field, so anyone who may read webhooks reads every endpoint's secret, and delivery consults only the all flag and the event map — it does NOT consult enabled or live, so setting enabled false does not stop delivery and deleting the row is the only thing that does. Delivery is a single POST with a twenty-second timeout and no retry. Re-dispatches the request into the handler the intended verb would have reached, taking that verb from a _method form value or query parameter and then from the X-HTTP-Method-Override header. PUT replaces the row, PATCH changes part of it, DELETE removes it, and anything else is 405. The trap is the DEFAULT: naming no override at all leaves the method POST, which this tunnel maps to the PARTIAL UPDATE — it is never a create, and creating is the collection root's job. Behaviour and authorization are the underlying operation's, since the real handler runs. The token must carry the ADMIN permission; an ordinary access token is refused.
|
|
/// </remarks>
|
|
/// <param name="webhookid"></param>
|
|
pplx::task<void> postCommerceWebhookByWebhookid(
|
|
utility::string_t webhookid
|
|
) const;
|
|
/// <summary>
|
|
/// Payment-provider webhook intake for settlement and subscription lifecycle events
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Accepts a payment provider's event, verifies it, records it for audit, and applies subscription lifecycle changes to the matching local row. There is no bearer here and there cannot be: the provider's SIGNATURE over the body IS the authentication, so a request with no recognized signature header is 400 and one whose signature does not verify is 401. The provider path segment is only a hint for dashboard configuration — verification picks the processor regardless of what the URL says. Redelivery is safe: an event id already recorded is acknowledged as a duplicate without re-applying any side effect, which matters because providers retry for days until they see a 2xx.
|
|
/// </remarks>
|
|
/// <param name="provider"></param>
|
|
pplx::task<void> postCommerceWebhooksByProvider(
|
|
utility::string_t provider
|
|
) const;
|
|
/// <summary>
|
|
/// Replace a collection outright
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A collection is a merchandising group a storefront renders — a slug and name, copy and media, flat lists of the product and variant ids it holds, published, preorder and out-of-stock flags, and an availability window. Membership lives on the collection as those id lists rather than as a join, so putting a product into a collection is a write here and not on the product. This is a true REPLACEMENT, not a merge: the stored row's key is preserved, but the body is decoded onto a FRESH entity, so every field the body omits is written back as its ZERO value. Patch is the verb for changing part of a row. The id is resolved inside the caller org's own namespace and an absent one is 404 before anything is written; a body that fails to decode is 400. Answers the stored result. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The token must also carry Admin, or ReadCollection and WriteCollection together.
|
|
/// </remarks>
|
|
/// <param name="collectionid"></param>
|
|
pplx::task<void> putCommerceCollectionByCollectionid(
|
|
utility::string_t collectionid
|
|
) const;
|
|
/// <summary>
|
|
/// Replace a disclosure outright
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A disclosure is a published-document record — a publication body, a content hash, a type and a named receiver. The hash LOOKS like a field you set and is in fact derived, but only on update: a freshly created disclosure keeps whatever hash the caller sent until the first replace or patch recomputes it, so a new row's hash attests to nothing. This kind lives in commerce's demo tree — a live writable resource in your tenant's real store that nothing else in commerce reads. This is a true REPLACEMENT, not a merge: the stored row's key is preserved, but the body is decoded onto a FRESH entity, so every field the body omits is written back as its ZERO value. Patch is the verb for changing part of a row. The id is resolved inside the caller org's own namespace and an absent one is 404 before anything is written; a body that fails to decode is 400. Answers the stored result. Any valid access token reaches it. The per-kind permission table has no entry for disclosure, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="disclosureid"></param>
|
|
pplx::task<void> putCommerceDisclosureByDisclosureid(
|
|
utility::string_t disclosureid
|
|
) const;
|
|
/// <summary>
|
|
/// Replace a discount outright
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A discount is a price rule: a type (flat, percent, free-shipping, free-item or bulk), a window, a scope naming the store, collection, product or variant it applies to, a target, and rules pairing a trigger — a price or quantity threshold — with an action, an amount off or a percentage. It is ENABLED BY DEFAULT, so a bare create makes a live discount rather than a draft. The rule engine caches per replica for about thirty seconds, so a discount switched off here can keep applying briefly on other replicas. This is a true REPLACEMENT, not a merge: the stored row's key is preserved, but the body is decoded onto a FRESH entity, so every field the body omits is written back as its ZERO value. Patch is the verb for changing part of a row. The id is resolved inside the caller org's own namespace and an absent one is 404 before anything is written; a body that fails to decode is 400. Answers the stored result. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The per-kind permission table has no entry for discount, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="discountid"></param>
|
|
pplx::task<void> putCommerceDiscountByDiscountid(
|
|
utility::string_t discountid
|
|
) const;
|
|
/// <summary>
|
|
/// Replace a movie outright
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A movie is a film catalog record — a slug plus EIDR and IMDB ids, all three required, with title and synopsis copy, artwork, screenshots, trailers, cast and crew, and available and hidden flags. It carries NO price: the money for a film lives on the product that sells it. This is a true REPLACEMENT, not a merge: the stored row's key is preserved, but the body is decoded onto a FRESH entity, so every field the body omits is written back as its ZERO value. Patch is the verb for changing part of a row. The id is resolved inside the caller org's own namespace and an absent one is 404 before anything is written; a body that fails to decode is 400. Answers the stored result. Any valid access token reaches it. The per-kind permission table has no entry for movie, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="movieid"></param>
|
|
pplx::task<void> putCommerceMovieByMovieid(
|
|
utility::string_t movieid
|
|
) const;
|
|
/// <summary>
|
|
/// Replace a note outright
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A note is a timestamped free-text log line — a caller-supplied time, a source, a message and an enabled flag. That time is the caller's own field and is distinct from the row's creation stamp; the note search filters on it, so a note written without one is a zero-time note the ops log will never surface. This is a true REPLACEMENT, not a merge: the stored row's key is preserved, but the body is decoded onto a FRESH entity, so every field the body omits is written back as its ZERO value. Patch is the verb for changing part of a row. The id is resolved inside the caller org's own namespace and an absent one is 404 before anything is written; a body that fails to decode is 400. Answers the stored result. Any valid access token reaches it. The per-kind permission table has no entry for note, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="noteid"></param>
|
|
pplx::task<void> putCommerceNoteByNoteid(
|
|
utility::string_t noteid
|
|
) const;
|
|
/// <summary>
|
|
/// Edit a plan, leaving the fields you omit alone
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Loads the addressed plan, applies the body over it and answers the stored result, so a partial edit never silently zeroes a price or the contact-sales flag. The slug is IMMUTABLE: a body naming a different slug is rejected outright before anything is written, because a rename would orphan every subscription that stored the old id — deprecate and create instead. An admin edit marks the row authoritative so the seed stops correcting it. PLATFORM admin only; an unknown slug is 404.
|
|
/// </remarks>
|
|
/// <param name="slug"></param>
|
|
pplx::task<void> putCommercePlansEntriesBySlug(
|
|
utility::string_t slug
|
|
) const;
|
|
/// <summary>
|
|
/// Replace a product outright
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A product is a sellable catalog item: slug, SKU and UPC, name and copy, media, availability and preorder flags, a reservation block, and its money — currency, price, MSRP, list price and inventory cost in minor units, inventory count, taxability, and the subscription interval when it is subscribeable. Its variants and options are carried as a denormalized JSON snapshot inside the product, separate from the standalone variant rows, and nothing keeps the two in step for you. This is a true REPLACEMENT, not a merge: the stored row's key is preserved, but the body is decoded onto a FRESH entity, so every field the body omits is written back as its ZERO value. Patch is the verb for changing part of a row. The id is resolved inside the caller org's own namespace and an absent one is 404 before anything is written; a body that fails to decode is 400. Answers the stored result. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The token must also carry Admin, or ReadProduct and WriteProduct together.
|
|
/// </remarks>
|
|
/// <param name="productid"></param>
|
|
pplx::task<void> putCommerceProductByProductid(
|
|
utility::string_t productid
|
|
) const;
|
|
/// <summary>
|
|
/// Edit a rate, and mark it as operator-set
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Edits one rate and MARKS it edited, which is the whole contract with the importer: an operator's price outranks the document it came from, so a later import leaves this row alone. Without that mark a price set here would apply, work, and silently revert on the next import. Only the editable fields move; identity and bookkeeping are not writable from the body. SuperAdmin only.
|
|
/// </remarks>
|
|
/// <param name="product"></param>
|
|
/// <param name="meter"></param>
|
|
pplx::task<void> putCommerceRatesEntriesByProductByMeter(
|
|
utility::string_t product,
|
|
utility::string_t meter
|
|
) const;
|
|
/// <summary>
|
|
/// Replace a return outright
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A return is an RMA — the store, user and order it belongs to, the line items coming back, a fulfillment block carrying its own type, status and pricing, a summary, and eight lifecycle timestamps from submitted through delivered and processed. Its status is a FREE STRING with no enumeration behind it, and there is no refund amount on the return itself: the money sits inside the line items and the fulfillment pricing. This is a true REPLACEMENT, not a merge: the stored row's key is preserved, but the body is decoded onto a FRESH entity, so every field the body omits is written back as its ZERO value. Patch is the verb for changing part of a row. The id is resolved inside the caller org's own namespace and an absent one is 404 before anything is written; a body that fails to decode is 400. Answers the stored result. Any valid access token reaches it. The token must also carry Admin, or ReadReturn and WriteReturn together.
|
|
/// </remarks>
|
|
/// <param name="returnid"></param>
|
|
pplx::task<void> putCommerceReturnByReturnid(
|
|
utility::string_t returnid
|
|
) const;
|
|
/// <summary>
|
|
/// Replace a sales channel outright
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A sales channel is a named selling surface — a name, a description, a disabled flag and metadata. The flag is NEGATIVE, so a channel created from an empty body is enabled. Nothing on this row links products, prices or stock to the channel; here it is a label other surfaces scope themselves by. This is a true REPLACEMENT, not a merge: the stored row's key is preserved, but the body is decoded onto a FRESH entity, so every field the body omits is written back as its ZERO value. Patch is the verb for changing part of a row. The id is resolved inside the caller org's own namespace and an absent one is 404 before anything is written; a body that fails to decode is 400. Answers the stored result. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The per-kind permission table has no entry for saleschannel, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="saleschannelid"></param>
|
|
pplx::task<void> putCommerceSaleschannelBySaleschannelid(
|
|
utility::string_t saleschannelid
|
|
) const;
|
|
/// <summary>
|
|
/// Replace a stock location outright
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A stock location is a physical address inventory can be held at — a name, street lines, city, province, country, postal code and a phone. None of it is validated, there are no coordinates, and the row carries no enabled flag and no inventory link, so deleting it is the only way to retire one. This is a true REPLACEMENT, not a merge: the stored row's key is preserved, but the body is decoded onto a FRESH entity, so every field the body omits is written back as its ZERO value. Patch is the verb for changing part of a row. The id is resolved inside the caller org's own namespace and an absent one is 404 before anything is written; a body that fails to decode is 400. Answers the stored result. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The per-kind permission table has no entry for stocklocation, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="stocklocationid"></param>
|
|
pplx::task<void> putCommerceStocklocationByStocklocationid(
|
|
utility::string_t stocklocationid
|
|
) const;
|
|
/// <summary>
|
|
/// Replace a storefront outright
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// This is a true REPLACEMENT, not a merge: the stored key is preserved but the body is decoded onto a fresh entity, so every field the body omits is written back as its zero value. Use the partial update when you mean to change part of a store. The id is resolved inside the caller org's own namespace, so an unknown or foreign id is a 404 before anything is written. Requires an admin token, or one holding both store read and store write.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
pplx::task<void> putCommerceStoreByStoreid(
|
|
utility::string_t storeid
|
|
) const;
|
|
/// <summary>
|
|
/// Upsert a listing override
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Decodes the body over the existing listing when the key is present, so fields it omits keep their stored values, and builds the listing from the body alone when the key is new. Answers 200 when it replaced something and 201 with a Location header when it created it; either way the body is the store's entire listing map, not the single entry. Unlike creation, this path does NOT restamp the listing's currency from the store. Admin-gated, with the store resolved inside the caller org's namespace.
|
|
/// </remarks>
|
|
/// <param name="storeid"></param>
|
|
/// <param name="key"></param>
|
|
pplx::task<void> putCommerceStoreByStoreidListingByKey(
|
|
utility::string_t storeid,
|
|
utility::string_t key
|
|
) const;
|
|
/// <summary>
|
|
/// Replace a submission outright
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A submission is one filled-in form from a site visitor — an email, an optional user id, the client details the server observed (user agent, referer, geography) and the form's own fields as free metadata. It carries no form id, so the link back to the form that produced it is not stored on the row. This is a true REPLACEMENT, not a merge: the stored row's key is preserved, but the body is decoded onto a FRESH entity, so every field the body omits is written back as its ZERO value. Patch is the verb for changing part of a row. The id is resolved inside the caller org's own namespace and an absent one is 404 before anything is written; a body that fails to decode is 400. Answers the stored result. Any valid access token reaches it. The per-kind permission table has no entry for submission, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="submissionid"></param>
|
|
pplx::task<void> putCommerceSubmissionBySubmissionid(
|
|
utility::string_t submissionid
|
|
) const;
|
|
/// <summary>
|
|
/// Replace a subscriber outright
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A subscriber is a mailing-list member — name, email, the form id that captured them, unsubscribed state and date, client details, tags and metadata. Writing one FIRES A WEBHOOK: subscriber.created on create and subscriber.updated on replace or patch, emitted BEFORE the write is known to have succeeded and carrying the row as sent, so the payload holds the raw email rather than the normalized one that gets stored. This is a true REPLACEMENT, not a merge: the stored row's key is preserved, but the body is decoded onto a FRESH entity, so every field the body omits is written back as its ZERO value. Patch is the verb for changing part of a row. The id is resolved inside the caller org's own namespace and an absent one is 404 before anything is written; a body that fails to decode is 400. Answers the stored result. Any valid access token reaches it. The token must also carry Admin, or ReadSubscriber and WriteSubscriber together.
|
|
/// </remarks>
|
|
/// <param name="subscriberid"></param>
|
|
pplx::task<void> putCommerceSubscriberBySubscriberid(
|
|
utility::string_t subscriberid
|
|
) const;
|
|
/// <summary>
|
|
/// Replace a token transaction outright
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A token transaction records a transfer between two identified parties — amount and fees, a timestamp, sending and receiving addresses, names, user ids, states and countries, a flag per side, a protocol name and a transaction hash. Nothing here touches a chain: the hash is an unvalidated string and the flags are plain writable booleans with no screening behind them. Amounts are floating-point rather than the exact minor units every real money field in commerce uses, and there is no currency field at all — this kind lives in commerce's demo tree, so it is a live writable resource in your tenant's store that nothing else in commerce reads, and it must never carry real money. This is a true REPLACEMENT, not a merge: the stored row's key is preserved, but the body is decoded onto a FRESH entity, so every field the body omits is written back as its ZERO value. Patch is the verb for changing part of a row. The id is resolved inside the caller org's own namespace and an absent one is 404 before anything is written; a body that fails to decode is 400. Answers the stored result. Any valid access token reaches it. The per-kind permission table has no entry for tokentransaction, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="tokentransactionid"></param>
|
|
pplx::task<void> putCommerceTokentransactionByTokentransactionid(
|
|
utility::string_t tokentransactionid
|
|
) const;
|
|
/// <summary>
|
|
/// Replace a transfer outright
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A transfer records that a payable WAS PAID — the annotation a human writes after paying out of band. Commerce executes no payout: creating one moves no money, and it marks the referenced payable settled. It carries the payable and payee ids, the amount it settles and the amount actually sent (which may be a different asset), a type of eth, wire or other, the transaction hash or wire reference, when it was paid and who recorded it; amounts are exact decimal strings with an asset, not cents. It is admin-gated because writing one settles money we owe, and nothing enforces uniqueness on the reference — so posting the same transfer twice settles the payable twice. This is a true REPLACEMENT, not a merge: the stored row's key is preserved, but the body is decoded onto a FRESH entity, so every field the body omits is written back as its ZERO value. Patch is the verb for changing part of a row. The id is resolved inside the caller org's own namespace and an absent one is 404 before anything is written; a body that fails to decode is 400. Answers the stored result. The token must carry the ADMIN permission; an ordinary access token is refused. The per-kind permission table has no entry for transfer, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="transferid"></param>
|
|
pplx::task<void> putCommerceTransferByTransferid(
|
|
utility::string_t transferid
|
|
) const;
|
|
/// <summary>
|
|
/// Replace a variant outright
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A variant is one purchasable SKU of a product — its product id, SKU and UPC, name, media, availability, the option name and value pairs that distinguish it, a sold counter, and its own money and stock: currency, price, MSRP, inventory cost, inventory count and taxability. Inventory and sold are plain writable numbers with no decrement logic behind them here. The same variant also exists as a JSON copy inside its product, and writing one does not update the other. This is a true REPLACEMENT, not a merge: the stored row's key is preserved, but the body is decoded onto a FRESH entity, so every field the body omits is written back as its ZERO value. Patch is the verb for changing part of a row. The id is resolved inside the caller org's own namespace and an absent one is 404 before anything is written; a body that fails to decode is 400. Answers the stored result. Any valid access token reaches it. The org must also be entitled to the commerce admin: the paywall answers 402 subscription_required unless the org holds an active or trialing pro subscription, a live trial credit or a redeemed invite, and 503 when that entitlement cannot be read rather than admitting on an unknown. The internal service token and a platform superadmin pass straight through. The token must also carry Admin, or ReadVariant and WriteVariant together.
|
|
/// </remarks>
|
|
/// <param name="variantid"></param>
|
|
pplx::task<void> putCommerceVariantByVariantid(
|
|
utility::string_t variantid
|
|
) const;
|
|
/// <summary>
|
|
/// Replace a wallet outright
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A wallet is a container of custodial blockchain accounts, and its only field is that account list — each account carrying a name, an address, a chain type, and the ENCRYPTED private key with its salt. Creating a wallet through this table generates NO KEYS: key generation lives on the account routes, so a wallet made here is an empty shell and an account posted into one is stored exactly as sent, with no key generation and no validation behind it. Know what a read renders: the plaintext private key is never marshalled and never stored, but the encrypted blob and its salt ARE returned, so whoever can read a wallet can attack it offline down to the strength of the owner's passphrase. That is why this kind is admin-gated. This is a true REPLACEMENT, not a merge: the stored row's key is preserved, but the body is decoded onto a FRESH entity, so every field the body omits is written back as its ZERO value. Patch is the verb for changing part of a row. The id is resolved inside the caller org's own namespace and an absent one is 404 before anything is written; a body that fails to decode is 400. Answers the stored result. The token must carry the ADMIN permission; an ordinary access token is refused. The per-kind permission table has no entry for wallet, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="walletid"></param>
|
|
pplx::task<void> putCommerceWalletByWalletid(
|
|
utility::string_t walletid
|
|
) const;
|
|
/// <summary>
|
|
/// Replace a watchlist outright
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A watchlist is a viewer's saved list of movies — a user id, an email, and the movies themselves. It stores WHOLE MOVIE SNAPSHOTS rather than movie ids, so a list goes stale the moment a film record changes and grows without bound as it fills. This is a true REPLACEMENT, not a merge: the stored row's key is preserved, but the body is decoded onto a FRESH entity, so every field the body omits is written back as its ZERO value. Patch is the verb for changing part of a row. The id is resolved inside the caller org's own namespace and an absent one is 404 before anything is written; a body that fails to decode is 400. Answers the stored result. Any valid access token reaches it. The per-kind permission table has no entry for watchlist, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="watchlistid"></param>
|
|
pplx::task<void> putCommerceWatchlistByWatchlistid(
|
|
utility::string_t watchlistid
|
|
) const;
|
|
/// <summary>
|
|
/// Replace a webhook outright
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A webhook is a merchant-registered endpoint that receives commerce event callbacks — a name, a URL, live and all flags, a per-event map, an enabled flag, and the shared access token each delivery posts IN THE BODY. Two things to know before registering one: that token is a plainly readable field, so anyone who may read webhooks reads every endpoint's secret, and delivery consults only the all flag and the event map — it does NOT consult enabled or live, so setting enabled false does not stop delivery and deleting the row is the only thing that does. Delivery is a single POST with a twenty-second timeout and no retry. This is a true REPLACEMENT, not a merge: the stored row's key is preserved, but the body is decoded onto a FRESH entity, so every field the body omits is written back as its ZERO value. Patch is the verb for changing part of a row. The id is resolved inside the caller org's own namespace and an absent one is 404 before anything is written; a body that fails to decode is 400. Answers the stored result. The token must carry the ADMIN permission; an ordinary access token is refused. The per-kind permission table has no entry for webhook, so the scaffold skips that second check with a warning and the gate above is the whole authorization story.
|
|
/// </remarks>
|
|
/// <param name="webhookid"></param>
|
|
pplx::task<void> putCommerceWebhookByWebhookid(
|
|
utility::string_t webhookid
|
|
) const;
|
|
/// <summary>
|
|
/// Set one item's quantity in a cart; zero removes it
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Sets how many of one item a cart holds, and answers the whole updated cart. This is the ONE way a cart's contents change. The quantity is the RESULT, not a delta: sending 3 leaves 3 however many were there before, so a retry is safe and a double-submit cannot double an order. ZERO REMOVES the line — there is deliberately no separate delete, because removal is the same act at the boundary value and a second spelling would be a second set of edge cases. Name the item with EITHER product OR variant, never both. Prefer variant for anything sold in sizes, colours or tiers: the price and the stock belong to the variant, so a product-level line on a varianted product prices the wrong thing. Either may be given as an id or as the human key — a product's URL slug, a variant's SKU — which is what lets a storefront add to cart straight from a product page URL without a lookup first. The item's price and name are CACHED onto the line as it is added, so the cart keeps the price the shopper was shown even if the catalog moves underneath it. An item that resolves to nothing in the catalog is refused 400 and the cart is left exactly as it was; nothing is partially applied. A named handler, not a closure, so zipdoc can lift this prose into the registry.
|
|
/// </remarks>
|
|
/// <param name="id">ID is the cart to amend, from the path.</param>
|
|
/// <param name="cartItemSet"></param>
|
|
pplx::task<std::shared_ptr<Cart>> setCartItem(
|
|
utility::string_t id,
|
|
std::shared_ptr<CartItemSet> cartItemSet
|
|
) const;
|
|
|
|
protected:
|
|
std::shared_ptr<const ApiClient> m_ApiClient;
|
|
};
|
|
|
|
}
|
|
}
|
|
|
|
#endif /* HANZO_API_CommerceApi_H_ */
|
|
|