Update Product

Update a one-time product’s content with automatic immutable versioning

Update a one-time product’s content. If the content has changed, a new immutable version is created automatically. If the content is identical to the current version, no new version is created.

POST /v1/actions/onetime-product/update-product

Authentication: API Key

Use the Update Status endpoint to change a product’s status (active/inactive). This endpoint is for content updates only.

Request Body

Field	Type	Required	Description
id	string	Yes	Product ID (Short ID format PROD_xxx)
name	string	No	Updated product name (max 64 chars)
description	string | null	No	Updated description (pass null or "" to clear)
prices	object	No	Updated multi-currency pricing map
media	array	No	Updated media items
successUrl	string | null	No	Updated redirect URL (max 512 chars, must be a valid http(s) URL; pass null or "" to clear)
metadata	object	No	Updated custom metadata

For the prices and media object formats, see Create Product.

Example Request

SDK

const { product } = await client.onetimeProducts.update({
  id: "PROD_3kF9mNpQrStUvWxYz1A2bC",
  name: "Premium Template Pack v2",
  description: "75 premium design templates — expanded collection.",
  prices: {
    USD: { amount: "59.00", taxIncluded: false, taxCategory: TaxCategory.DigitalGoods },
    EUR: { amount: "55.00", taxIncluded: true, taxCategory: TaxCategory.DigitalGoods },
  },
  successUrl: "https://example.com/thank-you",
});

Success Response (200)

{
  "data": {
    "product": {
      "id": "PROD_3kF9mNpQrStUvWxYz1A2bC",
      "storeId": "STO_2aUyqjCzEIiEcYMKj7TZtw",
      "name": "Premium Template Pack v2",
      "description": "75 premium design templates — expanded collection.",
      "prices": {
        "USD": { "amount": "59.00", "taxCategory": "digital_goods" },
        "EUR": { "amount": "55.00", "taxCategory": "digital_goods" }
      },
      "media": [],
      "successUrl": "https://example.com/thank-you",
      "metadata": {},
      "status": "active",
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-01-15T11:00:00.000Z"
    }
  }
}

Response Fields

Same as Create Product response.

Product versions are immutable. Existing orders retain their original version. New purchases always use the latest version. If the submitted content is identical to the current version, no new version is created and the existing version is returned.

Errors

Retry policy: Never retry 4xx — fix the request and resubmit. Retry 5xx with exponential backoff (start 5s, max 3 attempts).

Status	errors[0].message	What it means	Recommended handling
400	Missing required field: id	id not provided	Fix the body, resubmit
400	Invalid ID format	The provided Short ID could not be decoded	Fix the id format, resubmit
400	Invalid currency code	Currency code must be exactly 3 uppercase letters (ISO 4217, e.g. USD, EUR, JPY)	Use a valid ISO 4217 code, resubmit
400	Invalid amount	Amount must be a positive number string (e.g. "9.99", "100")	Use a positive number string, resubmit
400	Product X has no version in environment Y	The product has no version in the targeted environment (e.g. attempting to update prod before publishing)	Publish the product to the target environment first via Publish Product
404	Product not found	Product does not exist or is not accessible	Verify the id belongs to your merchant account
500	Internal server error	Unexpected server-side failure	Retry with exponential backoff (start 5s, max 3 attempts)