> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suprsend.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create or Update Variant
> Create a new variant or update an existing one for a specific channel. Pass the variant content, conditions, locale, and optionally vendor approval details.
The `content` JSON structure is channel-specific. Refer to the [variant content schema](https://schema.suprsend.com/template/v2/variant_schema.json) for each channel's structure.
## OpenAPI
````yaml POST /v2/{workspace}/template/{template_slug}/channel/{channel}/variant/{variant_id}/
openapi: 3.1.1
info:
title: SuprSend API
description: APIs supported on suprsend platform
version: 1.2.2
servers:
- url: https://hub.suprsend.com
security:
- sec0: []
- BearerAuth: []
paths:
/v2/{workspace}/template/{template_slug}/channel/{channel}/variant/{variant_id}/:
post:
summary: Create or Update Variant
description: >
Create a new variant or update an existing one for a specific channel.
Pass the variant content, conditions, locale, and optionally vendor
approval details.
The `content` JSON structure is channel-specific. Refer to the [variant
content
schema](https://schema.suprsend.com/template/v2/variant_schema.json) for
each channel's structure.
operationId: upsert-variant-v2
parameters:
- in: path
name: workspace
required: true
schema:
type: string
- in: path
name: template_slug
required: true
schema:
type: string
- in: path
name: channel
required: true
schema:
type: string
enum:
- email
- sms
- whatsapp
- inbox
- androidpush
- iospush
- webpush
- slack
- ms_teams
- in: path
name: variant_id
required: true
schema:
type: string
description: >-
Variant identifier. If a variant with this ID doesn't exist, a new
one is created.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- locale
- content
properties:
locale:
type: string
description: Locale code for the variant (e.g., `en`, `es`, `fr`).
example: en
tenant_id:
type: string
nullable: true
description: >-
Tenant ID this variant is scoped to. `null` for the default
variant.
conditions:
type: array
description: >-
Conditions for variant selection. Structure follows the
[expression
format](https://schema.suprsend.com/template/v2/variant_schema.json).
items:
type: object
properties:
type:
type: string
enum:
- expression_v1
expression_v1:
type: object
properties:
op:
type: string
enum:
- AND
args:
type: array
items:
type: object
properties:
op:
type: string
enum:
- '=='
variable_ns:
type: string
variable:
type: string
value:
type: string
content:
type: object
description: >-
Channel-specific content. See [variant content
schema](https://schema.suprsend.com/template/v2/variant_schema.json)
for the structure of each channel.
needs_vendor_approval:
type: boolean
description: >-
*(SMS only)* Whether this variant requires vendor (DLT)
approval.
seq_no:
type: integer
description: >-
Ordering of the variant within the same channel + tenant +
locale combination.
vendor_approvals:
type: array
description: >-
Vendor approval entries for WhatsApp/SMS variants. See
[approval
schema](https://schema.suprsend.com/template/v2/variant_schema.json).
items:
type: object
responses:
'200':
description: >-
Variant created or updated successfully. Returns the full variant
including rendered content.
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateVariant'
example:
$schema: https://schema.suprsend.com/template/v2/variant_schema.json
channel: email
id: default
tenant_id: null
locale: en
conditions: []
hash: >-
97f031b56ba642d137758652ce21dda6962ecee81d544fcf245661898107bcb9
needs_vendor_approval: false
sysgen_template_name: null
approval_status: auto_approved
discard_comment: null
approval_at: '2026-04-07T10:39:28.502737Z'
content:
$schema: >-
https://schema.suprsend.com/template/v2/channel/email_schema.json
templating_language: handlebars
from_name: Acme Store
from_address: noreply@acme-store.com
extra_to: ''
cc: ''
bcc: ''
reply_to: ''
subject: 'Your order has been shipped - #{{order.number}}'
body:
type: raw
raw:
html: >-
Order Shipped!
Hi
{{customer.name}},
Your order
#{{order.number}} has been shipped and
is on its way.
Expected delivery:
{{order.delivery_date}}
Track your
order
text: >-
Hi {{customer.name}}, Your order #{{order.number}} has
been shipped. Expected delivery:
{{order.delivery_date}}. Track: {{{order.tracking_url}}}
designer:
html: ...
text: ...
design_json: {}
merge_tags: []
display_conditions: []
preheader: 'Your order #{{order.number}} is on its way'
plain_text: null
email_markup: ''
errors: {}
vendor_approvals: []
has_error: false
seq_no: 1
action: null
created_at: '2026-04-07T10:39:28.510000Z'
'401':
$ref: '#/components/responses/AuthenticationError'
'404':
$ref: '#/components/responses/NotFoundError'
security:
- ServiceTokenAuth: []
servers:
- url: https://management-api.suprsend.com
x-codeSamples:
- lang: cURL
label: Upsert Variant
source: >
curl -X POST
"https://management-api.suprsend.com/v2/{workspace}/template/{template_slug}/channel/{channel}/variant/{variant_id}/"
\
--header 'Authorization: ServiceToken ' \
--header 'Content-Type: application/json' \
--data '{
"locale": "en",
"tenant_id": null,
"conditions": [],
"content": { ... }
}'
components:
schemas:
TemplateVariant:
type: object
properties:
$schema:
type: string
description: Schema URL for variant validation.
example: https://schema.suprsend.com/template/v2/variant_schema.json
channel:
type: string
description: Channel this variant belongs to.
example: email
id:
type: string
description: Variant identifier.
example: default
tenant_id:
type: string
nullable: true
description: Tenant this variant is scoped to, or null for default.
locale:
type: string
description: Locale code.
example: en
conditions:
type: array
description: Conditions for variant selection at send time.
items:
type: object
hash:
type: string
description: Content hash for change detection.
needs_vendor_approval:
type: boolean
description: Whether this variant requires vendor approval (SMS DLT, WhatsApp).
sysgen_template_name:
type: string
nullable: true
description: System-generated template name for vendor approval.
approval_status:
type: string
enum:
- auto_approved
- pending
- sent_for_approval
- approved
- rejected
description: Current approval status of the variant.
discard_comment:
type: string
nullable: true
description: Reason provided when a variant is discarded.
approval_at:
type: string
format: date-time
nullable: true
description: Timestamp when the variant was approved.
has_error:
type: boolean
description: Whether the variant has validation errors.
seq_no:
type: integer
description: Ordering within the channel + tenant + locale combination.
action:
type: string
nullable: true
description: >-
Action taken in the latest commit (Updated, Added, Unchanged, or
null).
created_at:
type: string
format: date-time
description: Timestamp when the variant was created.
content:
type: object
description: >-
Channel-specific content. Structure varies by channel. Only returned
in variant detail endpoint.
vendor_approvals:
type: array
description: >-
Vendor approval entries (WhatsApp/SMS only). Only returned in
variant detail endpoint.
items:
type: object
ErrorResponse:
type: object
properties:
code:
type: integer
description: HTTP status code
error_code:
type: string
description: Specific error code identifier
type:
type: string
description: Error type classification
message:
type: string
description: Human-readable error message
detail:
type: string
description: Additional error details
responses:
AuthenticationError:
description: Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: 401
error_code: authentication_failed
type: AuthenticationFailed
message: Invalid service token.
detail: Invalid service token.
NotFoundError:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: 404
error_code: not_found
type: NotFound
message: workspace 'demo' not found
detail: workspace 'demo' not found
securitySchemes:
sec0:
type: apiKey
in: header
name: Authorization
x-bearer-format: bearer
description: >-
Bearer authentication header of the form `Bearer `, where
is your auth token.
BearerAuth:
type: http
scheme: bearer
bearerFormat: API_Key
description: >-
Pass as `Bearer `. Get API Key from SuprSend dashboard
Developers -> API Keys section.
ServiceTokenAuth:
type: apiKey
in: header
name: ServiceToken
description: >-
You can get Service Token from [SuprSend dashboard -> Account Settings
-> Service
Tokens](https://app.suprsend.com/en/account-settings/service-tokens)
section.
````