Update Template Modifications

Update the content of text and image layers in a studio template. This endpoint allows you to modify parameterized elements directly without re-saving the entire template structure. Supports updating multiple parameters across multiple pages in a single request.

For detailed information about the template data structure, see Anatomy of a Template.

Endpoint#

https://api.orshot.com/v1/studio/templates/:templateId/update-modifications

Query Parameters#

Request Examples#

// Update text and image on a single page
await fetch("https://api.orshot.com/v1/studio/templates/12345/update-modifications", {
  method: "PATCH",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
  body: JSON.stringify({
    data: [
      {
        page: 1,
        modifications: {
          headline: "Flash Sale: 24 Hours Only!",
          subtitle: "Don't miss out on amazing deals",
          product_image: "https://cdn.example.com/sale-banner.png",
          price: "$49.99"
        }
      }
    ],
    embed_user_id: "your-external-user-id" // Optional
  }),
});

Rate Limits#

URL Parameters#

Request Body Structure#

The request body uses a data array format, where each item specifies the page number and modifications to apply:

{
  "data": [
    {
      "page": 1,
      "modifications": {
        "headline": "New Headline Text",
        "product_image": "https://cdn.example.com/new-image.png",
        "price": "$99.99"
      }
    }
  ]
}

Request Body Parameters#

Data Object Structure#

Each object in the data array should include:

Supported Modification Types#

Text Content#

Update text element content by its parameterId:

{
  "page": 1,
  "modifications": {
    "headline": "Summer Sale 2026!",
    "subtitle": "Up to 50% off all items",
    "cta_text": "Shop Now"
  }
}

Image URLs#

Update image sources by providing a URL:

{
  "page": 1,
  "modifications": {
    "product_image": "https://cdn.example.com/product.png",
    "logo": "https://cdn.example.com/logo.svg",
    "background": "https://cdn.example.com/bg.jpg"
  }
}

Style Properties#

Update style properties using dot notation:

{
  "page": 1,
  "modifications": {
    "headline.fontSize": 48,
    "headline.color": "#ff0000",
    "cta_button.backgroundColor": "#007bff",
    "subtitle.fontFamily": "Inter"
  }
}

Response Fields#

Which array a key lands in#

failed and skipped are omitted from the response when they are empty, so a clean patch returns applied only. Check data.failed before treating a patch as fully successful.

Applied/Failed Object Structure#

Keys you need to act on come back in failed with a reason code:

Keys that are legitimate for a render but have no home on a stored template come back in skipped with a reason and a human-readable message. They are informational: send them to a render call instead.

Thumbnails Object Structure#

When ?includeThumbnails=true is passed, a PNG thumbnail is regenerated for only the pages that had modifications applied (not all pages). The thumbnails object in the response has this shape:

When ?includeThumbnails is not passed, thumbnails regenerate in the background for the modified pages and appear on the template shortly after the response.

Supported Style Properties#

When using dot notation for style updates, the following properties are commonly supported:

Error Responses#

Invalid per-item input (a non-positive page, or modifications that isn't an object) does not fail the request: the item is reported in the failed array and the response still returns 200. | 500 | Internal server error | Server-side error |

Cache Invalidation#

When modifications are applied:

1. Template render cache is automatically invalidated
2. Dynamic URL cache for the template is cleared
3. Subsequent render requests will use the updated content

Best Practices#

1. Use Parameter IDs: Ensure your template has parameterId set on elements you want to update
2. Batch Updates: Combine multiple page modifications in a single request to reduce API calls
3. Validate URLs: Ensure image URLs are accessible and return valid images
4. Error Handling: Always check the failed array in responses for partial failures. It is omitted when every key landed, so test data.failed before reading its length. Keys in skipped need no action
5. Style Consistency: When updating styles, ensure values are compatible with the element type