Orshot Logo
OrshotDocs

PATCH: Update Template Modifications

Update text and image content in template layers

Enterprise Only

This is an Enterprise only private endpoint. Checkout the Enterprise Pricing to get access.

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

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"
        }
      }
    ]
  }),
});
// Update multiple pages in a carousel template
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: "Welcome to Our Store",
          hero_image: "https://cdn.example.com/hero.png"
        }
      },
      {
        page: 2,
        modifications: {
          headline: "Featured Products",
          product_1: "https://cdn.example.com/product1.png",
          product_2: "https://cdn.example.com/product2.png"
        }
      },
      {
        page: 3,
        modifications: {
          headline: "Contact Us",
          email: "hello@example.com",
          phone: "+1 234 567 8900"
        }
      }
    ]
  }),
});
// Update content and styles together
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: {
          // Content updates
          headline: "Black Friday Sale",
          discount: "70% OFF",
          
          // Style updates using dot notation
          "headline.fontSize": 72,
          "headline.color": "#ffffff",
          "discount.backgroundColor": "#ff0000",
          "discount.color": "#ffffff"
        }
      }
    ]
  }),
});
{
  "success": true,
  "template_id": 12345,
  "applied": [
    { "page": 1, "key": "headline", "type": "text" },
    { "page": 1, "key": "subtitle", "type": "text" },
    { "page": 1, "key": "product_image", "type": "image" },
    { "page": 1, "key": "price", "type": "text" },
    { "page": 2, "key": "headline", "type": "text" }
  ]
}
{
  "success": true,
  "template_id": 12345,
  "applied": [
    { "page": 1, "key": "headline", "type": "text" },
    { "page": 1, "key": "product_image", "type": "image" }
  ],
  "failed": [
    { 
      "page": 1, 
      "key": "nonexistent_param", 
      "error": "Element with parameterId 'nonexistent_param' not found" 
    },
    { 
      "page": 5, 
      "error": "Page 5 does not exist. Template has 3 page(s)." 
    }
  ]
}

Rate Limits

LimitValue
Requests per minute30
Max modifications per request50

URL Parameters

ParameterTypeRequiredDescription
templateIdIntegerYesThe ID of the template to update

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

ParameterTypeRequiredDescription
dataArrayYesArray of page modification objects

Data Object Structure

Each object in the data array should include:

FieldTypeRequiredDescription
pageIntegerYesPage number (1-indexed) to apply modifications to
modificationsObjectYesKey-value pairs of parameterId to new value

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

FieldTypeDescription
successBooleanWhether the operation completed
template_idIntegerID of the updated template
appliedArrayList of successfully applied modifications
failedArrayList of failed modifications (only if any failed)

Applied/Failed Object Structure

FieldTypeDescription
pageIntegerPage number where the modification was applied/failed
keyStringThe parameter ID or style path
typeStringType of modification: text, image, or style
errorStringError message (only for failed items)

Supported Style Properties

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

PropertyTypeDescription
fontSizeNumberFont size in pixels
fontFamilyStringFont family name
colorStringText color (hex, rgb, rgba)
backgroundColorStringBackground color
opacityNumberOpacity (0-1)
fontWeightString/NumberFont weight (normal, bold, 100-900)
textAlignStringText alignment (left, center, right)
letterSpacingNumberLetter spacing in pixels
lineHeightNumberLine height multiplier

Error Responses

Status CodeErrorDescription
400data requiredRequest body missing data array
400data array emptyEmpty data array
400page must be positive integerInvalid page number
400modifications must be objectInvalid modifications format
403Access ForbiddenInvalid API key or template not in workspace
404Template not foundTemplate ID doesn't exist
429Rate limit exceededToo many requests (max 30/min)
500Internal server errorServer-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
  5. Style Consistency: When updating styles, ensure values are compatible with the element type

On this page