v2.catalog

Create a central subaccount product

Requires a platform key with scope * or catalog:write and Cooud-Account: cooud_subacct_… of a platform_central subaccount; Cooud-Account, Idempotency-Key and Cooud-Compat-Date are mandatory. Standard Connect accounts (cooud_acct_…) and store keys receive 403 catalog_write_not_supported. Sandbox stores the object in the subaccount's persistent test catalog, isolated by platform and subaccount; live uses the native catalog. Does not charge customers or change existing subscriptions. Live creates and publishes the product (live: true). Server-set fields: slug api-<lowercase ULID>, domain entrepreneurship, product_type digital, thumbnail_url null. Check order: request JSON (400 before authentication); Authorization, Cooud-Compat-Date, Cooud-Account and rate limit; body and Idempotency-Key (400 parameter_invalid); write permission (403); idempotency (201 replay or 409); creation (404, 503). A store key or Connect account without Idempotency-Key therefore gets 400, not 403. Idempotency: the key is scoped by platform, environment, subaccount and operation, not by credential, and is reserved before any effect. The same key with the same validated body replays the original 201, including the original request_id (the Request-Id header identifies the new request); there is no Idempotency-Replayed header and successful receipts do not expire. The comparison ignores property order and leading or trailing spaces in name; an explicit null or {} differs from an omitted field. A failure without effect releases the key, so the same key runs the creation again. An uncertain result answers 409 catalog_operation_pending for 15 minutes from the start of that attempt; afterwards the same key and body send the creation again, without reusing what the uncertain attempt may have left.

post/products

Request

  • Base URL: https://api.cooud.com/v2
  • URL: https://api.cooud.com/v2/products
  • Auth: HTTP bearer

Headers

Cooud-Compat-Datestring date required

Required per-request compat-date. Format: ISO calendar date YYYY-MM-DD. Merchants pinned to an older date have their request and response transformed by every gate whose appliesAfter is strictly greater than this date.

Cooud-Accountstring required

Required: cooud_subacct_… of a platform_central subaccount. A platform key without it receives 400 cooud_account_required; an id that is neither cooud_subacct_… nor cooud_acct_… receives 400 cooud_account_invalid; a subaccount missing in this environment, disabled, or whose live central receiving is off receives 403 account_not_connected.

Idempotency-Keystring required

Required. Missing, empty, whitespace-only or longer than 255 characters: 400 parameter_invalid with param: Idempotency-Key (not idempotency_key_invalid). Scoped by platform, environment, subaccount and operation.

Request body

namestring required

Leading and trailing spaces are removed, also for the idempotency comparison.

descriptionstring nullable

An explicit null differs from an omitted field for idempotency.

metadataobject

An explicit {} differs from an omitted field for idempotency.

Response

Created resource, or replay of the original successful creation with the same body and the original request_id. livemode and request_id are always present.

archivedboolean required
createdinteger required
descriptionstring nullable required
domainstring required
idstring required
liveboolean required
livemodeboolean required

Present in the 201 of central catalog creation (true in live, false in sandbox) and in reads of a central subaccount's sandbox catalog (false). Other reads omit it.

metadataobject required
namestring required
object'product' required
product_type'digital' | 'physical' required
request_idstring required
slugstring required
thumbnail_urlstring nullable required

Changes

No recorded changes to this operation across all 1 revision of this API.