v2.catalog

Create a central subaccount price

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. product must belong to the same subaccount and environment (sandbox: a product created through this API for the same platform and subaccount; live: any product of the subaccount store, drafts included), otherwise 404 resource_missing. currency is the subaccount currency in lower case (brl, usd, eur, gbp, chf or ars, the currency returned by GET /v2/subaccounts/{id} in upper case); a valid currency different from the subaccount currency answers 400 currency_mismatch_subaccount (param: currency) before the idempotency key is reserved. Prices are immutable: create another price to change an offer. In live, is_primary of the new price is null; later reads show the catalog value (true for the product's first price); sandbox always returns false. 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); price currency against the subaccount currency (400 currency_mismatch_subaccount); 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/prices

Request

  • Base URL: https://api.cooud.com/v2
  • URL: https://api.cooud.com/v2/prices
  • 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

thanks_page_url, when present, must be an absolute http(s) URL. An explicit {} differs from an omitted field for idempotency.

productstring required

prod_ id of a product in the same subaccount and environment.

currency'brl' | 'usd' | 'eur' | 'gbp' | 'chf' | 'ars' required

Lower-case ISO 4217 currency; must equal the subaccount currency (GET /v2/subaccounts/{id}.currency, upper case). Upper case (USD) is rejected with 400 parameter_invalid; a valid currency different from the subaccount currency with 400 currency_mismatch_subaccount (param currency), and nothing is reserved.

unit_amountinteger required

Amount in cents.

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
course_slugstring

Product slug. Only in GET /v2/prices/{id} of the live catalog; absent from lists and from a central subaccount's sandbox catalog.

createdinteger required
currencystring required
descriptionstring nullable required
idstring required
is_primaryboolean nullable required

Primary price of the product. Null in the product prices list and in the live 201 of POST /v2/prices; later reads show the catalog value (true for the product's first price). Always false in a central subaccount's sandbox catalog.

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'price' required
productstring required
request_idstring required
trial_intervalstring nullable required
trial_interval_countinteger nullable required
unit_amountinteger required

Changes

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