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#

Applied/Failed Object Structure#

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#

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
5. Style Consistency: When updating styles, ensure values are compatible with the element type