Skip to main content
Publish a product from the test environment to production. This is a one-way, first-publish-only operation that copies the current test version to production. 
POST /v1/actions/onetime-product/publish-product
Authentication: API Key
Do not include the X-Environment header for this endpoint. Publishing is always one-way from test to production.

​
Request Body

FieldTypeRequiredDescription
idstringYesProduct ID (Short ID format PROD_xxx)

​
Example Request

const { product } = await client.onetimeProducts.publish({
  id: "PROD_3kF9mNpQrStUvWxYz1A2bC",
});

​
Success Response (200)

{
  "data": {
    "product": {
      "id": "PROD_3kF9mNpQrStUvWxYz1A2bC",
      "storeId": "STO_2aUyqjCzEIiEcYMKj7TZtw",
      "name": "Premium Template Pack",
      "description": "50 premium design templates for your next project.",
      "prices": {
        "USD": { "amount": "49.00", "taxCategory": "digital_goods" },
        "EUR": { "amount": "45.00", "taxCategory": "digital_goods" }
      },
      "media": [
        { "type": "image", "url": "https://example.com/templates-preview.png", "alt": "Template preview" }
      ],
      "successUrl": "https://example.com/thank-you",
      "metadata": { "category": "design", "fileCount": "50" },
      "status": "active",
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-01-15T12:00:00.000Z"
    }
  }
}

​
Response Fields

Same as Create Product response.
Only the first publish is supported. Once a product has a production version, this endpoint cannot be used again for the same product. To update the production version after initial publish, use the Update Product endpoint with the X-Environment: prod header.

​
Errors

Retry policy: Never retry 4xx — fix the request and resubmit. Retry 5xx with exponential backoff (start 5s, max 3 attempts).
Statuserrors[0].messageWhat it meansRecommended handling
400Missing required field: idid not providedFix the body, resubmit
400Invalid ID formatThe provided Short ID could not be decodedFix the id format, resubmit
400No test version foundThe product has no version in the test environment yetCreate the product first via Create Product
400Test version is not activeThe current test version’s status is inactiveActivate the test version via Update Status first
400Already published to productionThe product already has a production versionUse Update Product with X-Environment: prod to make further changes
404Product not foundProduct does not exist or is not accessibleVerify the id belongs to your merchant account
500Internal server errorUnexpected server-side failureRetry with exponential backoff (start 5s, max 3 attempts)