Variant Groups

Server

Download schema

Product options and modifiers

List variant groups

GET

https://common-api.karma.life

/api/v1/variant-groups

List variant groups with optional filtering

Permissions: 🔵 variant_groups.read

List variant groups › query Parameters

locationId

number

Filter by location ID

type

string · enum

Filter by group type

Enum values:

EXTRA

VARIANT

includeVariants

boolean

Include variants in response

Default: true

page

number · min: 1

Page number

Default: 1

limit

number · min: 1 · max: 100

Items per page

Default: 20

List variant groups › Responses

Default Response

status

string · enum · required

Enum values:

success

object · required

Create variant group

POST

https://common-api.karma.life

/api/v1/variant-groups

Create a new variant group with variants

Permissions: 🟢 variant_groups.create

Create variant group › Request Body

locationId

number · required

Location ID

name

string · minLength: 1 · required

Group name

type

string · enum · required

Enum values:

EXTRA

VARIANT

object[] · required

Initial variants for this group

description

string | null

min

number · min: 0

Default: 0

max

number | null · min: 1

isVisible

boolean

Default: true

useChildCoursing

boolean

When true, item-based variant children commit with their own coursing_order

Default: false

Create variant group › Responses

Default Response

status

string · enum · required

Enum values:

success

object · required

POST/api/v1/variant-groups

curl --request POST \
  --url https://common-api.karma.life/api/v1/variant-groups \
  --header 'Content-Type: application/json' \
  --data '
{
  "locationId": 0,
  "name": "name",
  "type": "EXTRA",
  "description": "description",
  "min": 0,
  "max": 1,
  "isVisible": true,
  "useChildCoursing": false,
  "variants": [
    {
      "name": "name",
      "price": 0,
      "defaultSelection": false,
      "description": "description",
      "rank": 0,
      "itemId": 0,
      "quantity": 1,
      "allowQuantityChange": false,
      "quantityCents": 100,
      "minQuantityCents": 0,
      "maxQuantityCents": 0
    }
  ]
}
'

Example Request Body

{
  "locationId": 0,
  "name": "name",
  "type": "EXTRA",
  "description": "description",
  "min": 0,
  "max": 1,
  "isVisible": true,
  "useChildCoursing": false,
  "variants": [
    {
      "name": "name",
      "price": 0,
      "defaultSelection": false,
      "description": "description",
      "rank": 0,
      "itemId": 0,
      "quantity": 1,
      "allowQuantityChange": false,
      "quantityCents": 100,
      "minQuantityCents": 0,
      "maxQuantityCents": 0
    }
  ]
}

json

Example Responses

No example specified for this content type

application/json

Get variant group

GET

https://common-api.karma.life

/api/v1/variant-groups/{id}

Get a single variant group by ID with its variants

Permissions: 🔵 variant_groups.read

Get variant group › path Parameters

id

string · pattern: ^[0-9]+$ · required

Variant group ID

Get variant group › Responses

Default Response

status

string · enum · required

Enum values:

success

object · required

Update variant group

PUT

https://common-api.karma.life

/api/v1/variant-groups/{id}

Update an existing variant group

Permissions: 🟠 variant_groups.update

Update variant group › path Parameters

id

string · pattern: ^[0-9]+$ · required

Variant group ID

Update variant group › Request Body

name

string · minLength: 1

description

string | null

min

number · min: 0

max

number | null · min: 1

isVisible

boolean

useChildCoursing

boolean

When true, item-based variant children commit with their own coursing_order

Update variant group › Responses

Default Response

status

string · enum · required

Enum values:

success

object · required

Delete variant group

DELETE

https://common-api.karma.life

/api/v1/variant-groups/{id}

Delete a variant group and its variants

Permissions: 🔴 variant_groups.delete

Delete variant group › path Parameters

id

string · pattern: ^[0-9]+$ · required

Variant group ID

Delete variant group › Responses

Variant group successfully deleted

status

string · enum

Enum values:

success

object

Webhook: Variant group created

POST

https://common-api.karma.life

/webhook/variant-group.created

Fired when a new variant group is created. The full group object is spread into data.

This is an outbound webhook event. Karma POSTs this payload to the URL you registered via POST /api/v1/webhooks/subscriptions. Your endpoint should respond 2xx within 30 seconds to acknowledge delivery.

Webhook: Variant group created › Request Body

Standard envelope wrapping every outbound webhook event.

id

string · required

Unique webhook delivery ID

event

string · enum · required

Enum values:

variant-group.created

resource

string · enum · required

Enum values:

variant-group

resourceId

string · required

String ID of the affected resource

timestamp

string · date-time · required

ISO 8601 timestamp when the event was emitted

apiVersion

string · enum · required

Enum values:

object

Webhook: Variant group created › Responses

200

Acknowledged. Karma considers any 2xx response a successful delivery; non-2xx triggers retry with exponential backoff.

No data returned

Webhook: Variant group updated

POST

https://common-api.karma.life

/webhook/variant-group.updated

changes contains only the fields that were modified.

Webhook: Variant group updated › Request Body

Standard envelope wrapping every outbound webhook event.

id

string · required

Unique webhook delivery ID

event

string · enum · required

Enum values:

variant-group.updated

resource

string · enum · required

Enum values:

variant-group

resourceId

string · required

String ID of the affected resource

timestamp

string · date-time · required

ISO 8601 timestamp when the event was emitted

apiVersion

string · enum · required

Enum values:

object

Webhook: Variant group updated › Responses

200

Acknowledged. Karma considers any 2xx response a successful delivery; non-2xx triggers retry with exponential backoff.

No data returned

POST/webhook/variant-group.updated

curl --request POST \
  --url https://common-api.karma.life/webhook/variant-group.updated \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "evt_01HZK3...",
  "event": "variant-group.updated",
  "resource": "variant-group",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "variantGroupId": 0,
    "changes": {},
    "locationId": 0,
    "updatedAt": "2024-08-25T15:00:00Z"
  }
}
'

Example Request Body

{
  "id": "evt_01HZK3...",
  "event": "variant-group.updated",
  "resource": "variant-group",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "variantGroupId": 0,
    "changes": {},
    "locationId": 0,
    "updatedAt": "2024-08-25T15:00:00Z"
  }
}

json

Example Responses

No example specified for this content type

Webhook: Variant group deleted

POST

https://common-api.karma.life

/webhook/variant-group.deleted

Soft delete.

Webhook: Variant group deleted › Request Body

Standard envelope wrapping every outbound webhook event.

id

string · required

Unique webhook delivery ID

event

string · enum · required

Enum values:

variant-group.deleted

resource

string · enum · required

Enum values:

variant-group

resourceId

string · required

String ID of the affected resource

timestamp

string · date-time · required

ISO 8601 timestamp when the event was emitted

apiVersion

string · enum · required

Enum values:

object

Webhook: Variant group deleted › Responses

200

Acknowledged. Karma considers any 2xx response a successful delivery; non-2xx triggers retry with exponential backoff.

No data returned

POST/webhook/variant-group.deleted

curl --request POST \
  --url https://common-api.karma.life/webhook/variant-group.deleted \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "evt_01HZK3...",
  "event": "variant-group.deleted",
  "resource": "variant-group",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "variantGroupId": 0,
    "locationId": 0,
    "deletedAt": "2024-08-25T15:00:00Z"
  }
}
'

Example Request Body

{
  "id": "evt_01HZK3...",
  "event": "variant-group.deleted",
  "resource": "variant-group",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "variantGroupId": 0,
    "locationId": 0,
    "deletedAt": "2024-08-25T15:00:00Z"
  }
}

json

Example Responses

No example specified for this content type

Webhook: Variant created

POST

https://common-api.karma.life

/webhook/variant.created

Fired when a variant is created within a variant group. The full variant object is spread into data.

Webhook: Variant created › Request Body

Standard envelope wrapping every outbound webhook event.

id

string · required

Unique webhook delivery ID

event

string · enum · required

Enum values:

variant.created

resource

string · enum · required

Enum values:

variant

resourceId

string · required

String ID of the affected resource

timestamp

string · date-time · required

ISO 8601 timestamp when the event was emitted

apiVersion

string · enum · required

Enum values:

object · required

Webhook: Variant created › Responses

200

Acknowledged. Karma considers any 2xx response a successful delivery; non-2xx triggers retry with exponential backoff.

No data returned

POST/webhook/variant.created

curl --request POST \
  --url https://common-api.karma.life/webhook/variant.created \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "evt_01HZK3...",
  "event": "variant.created",
  "resource": "variant",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "id": 0,
    "variantGroupId": 0,
    "name": "name",
    "price": 0,
    "defaultSelection": true,
    "description": "description",
    "rank": 0,
    "itemId": 0,
    "quantity": 0,
    "allowQuantityChange": true,
    "minQuantity": 0,
    "maxQuantity": 0,
    "quantityCents": 0,
    "minQuantityCents": 0,
    "maxQuantityCents": 0
  }
}
'

Example Request Body

{
  "id": "evt_01HZK3...",
  "event": "variant.created",
  "resource": "variant",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "id": 0,
    "variantGroupId": 0,
    "name": "name",
    "price": 0,
    "defaultSelection": true,
    "description": "description",
    "rank": 0,
    "itemId": 0,
    "quantity": 0,
    "allowQuantityChange": true,
    "minQuantity": 0,
    "maxQuantity": 0,
    "quantityCents": 0,
    "minQuantityCents": 0,
    "maxQuantityCents": 0
  }
}

json

Example Responses

No example specified for this content type

Webhook: Variant updated

POST

https://common-api.karma.life

/webhook/variant.updated

changes contains only the modified fields.

Webhook: Variant updated › Request Body

Standard envelope wrapping every outbound webhook event.

id

string · required

Unique webhook delivery ID

event

string · enum · required

Enum values:

variant.updated

resource

string · enum · required

Enum values:

variant

resourceId

string · required

String ID of the affected resource

timestamp

string · date-time · required

ISO 8601 timestamp when the event was emitted

apiVersion

string · enum · required

Enum values:

object

Webhook: Variant updated › Responses

200

Acknowledged. Karma considers any 2xx response a successful delivery; non-2xx triggers retry with exponential backoff.

No data returned

POST/webhook/variant.updated

curl --request POST \
  --url https://common-api.karma.life/webhook/variant.updated \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "evt_01HZK3...",
  "event": "variant.updated",
  "resource": "variant",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "variantId": 0,
    "changes": {},
    "updatedAt": "2024-08-25T15:00:00Z"
  }
}
'

Example Request Body

{
  "id": "evt_01HZK3...",
  "event": "variant.updated",
  "resource": "variant",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "variantId": 0,
    "changes": {},
    "updatedAt": "2024-08-25T15:00:00Z"
  }
}

json

Example Responses

No example specified for this content type

Webhook: Variant deleted

POST

https://common-api.karma.life

/webhook/variant.deleted

Soft delete.

Webhook: Variant deleted › Request Body

Standard envelope wrapping every outbound webhook event.

id

string · required

Unique webhook delivery ID

event

string · enum · required

Enum values:

variant.deleted

resource

string · enum · required

Enum values:

variant

resourceId

string · required

String ID of the affected resource

timestamp

string · date-time · required

ISO 8601 timestamp when the event was emitted

apiVersion

string · enum · required

Enum values:

object

Webhook: Variant deleted › Responses

200

Acknowledged. Karma considers any 2xx response a successful delivery; non-2xx triggers retry with exponential backoff.

No data returned

POST/webhook/variant.deleted

curl --request POST \
  --url https://common-api.karma.life/webhook/variant.deleted \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "evt_01HZK3...",
  "event": "variant.deleted",
  "resource": "variant",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "variantId": 0,
    "variantGroupId": 0,
    "deletedAt": "2024-08-25T15:00:00Z"
  }
}
'

Example Request Body

{
  "id": "evt_01HZK3...",
  "event": "variant.deleted",
  "resource": "variant",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "variantId": 0,
    "variantGroupId": 0,
    "deletedAt": "2024-08-25T15:00:00Z"
  }
}

json

Example Responses

No example specified for this content type

Webhook: Variant linked to inventory item

POST

https://common-api.karma.life

/webhook/variant.item-linked

Fired when a variant's item_id is set — marks the transition from a legacy variant to an item-based variant.

Webhook: Variant linked to inventory item › Request Body

Standard envelope wrapping every outbound webhook event.

id

string · required

Unique webhook delivery ID

event

string · enum · required

Enum values:

variant.item-linked

resource

string · enum · required

Enum values:

variant

resourceId

string · required

String ID of the affected resource

timestamp

string · date-time · required

ISO 8601 timestamp when the event was emitted

apiVersion

string · enum · required

Enum values:

object

Webhook: Variant linked to inventory item › Responses

200

Acknowledged. Karma considers any 2xx response a successful delivery; non-2xx triggers retry with exponential backoff.

No data returned

POST/webhook/variant.item-linked

curl --request POST \
  --url https://common-api.karma.life/webhook/variant.item-linked \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "evt_01HZK3...",
  "event": "variant.item-linked",
  "resource": "variant",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "variantId": 0,
    "variantGroupId": 0,
    "itemId": 0,
    "item": {},
    "linkedAt": "2024-08-25T15:00:00Z"
  }
}
'

Example Request Body

{
  "id": "evt_01HZK3...",
  "event": "variant.item-linked",
  "resource": "variant",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "variantId": 0,
    "variantGroupId": 0,
    "itemId": 0,
    "item": {},
    "linkedAt": "2024-08-25T15:00:00Z"
  }
}

json

Example Responses

No example specified for this content type

Webhook: Variant unlinked from inventory item

POST

https://common-api.karma.life

/webhook/variant.item-unlinked

Fired when a variant's item_id is cleared — reverts an item-based variant to a legacy variant.

Webhook: Variant unlinked from inventory item › Request Body

Standard envelope wrapping every outbound webhook event.

id

string · required

Unique webhook delivery ID

event

string · enum · required

Enum values:

variant.item-unlinked

resource

string · enum · required

Enum values:

variant

resourceId

string · required

String ID of the affected resource

timestamp

string · date-time · required

ISO 8601 timestamp when the event was emitted

apiVersion

string · enum · required

Enum values:

object

Webhook: Variant unlinked from inventory item › Responses

200

Acknowledged. Karma considers any 2xx response a successful delivery; non-2xx triggers retry with exponential backoff.

No data returned

POST/webhook/variant.item-unlinked

curl --request POST \
  --url https://common-api.karma.life/webhook/variant.item-unlinked \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "evt_01HZK3...",
  "event": "variant.item-unlinked",
  "resource": "variant",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "variantId": 0,
    "variantGroupId": 0,
    "previousItemId": 0,
    "unlinkedAt": "2024-08-25T15:00:00Z"
  }
}
'

Example Request Body

{
  "id": "evt_01HZK3...",
  "event": "variant.item-unlinked",
  "resource": "variant",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "variantId": 0,
    "variantGroupId": 0,
    "previousItemId": 0,
    "unlinkedAt": "2024-08-25T15:00:00Z"
  }
}

json

Example Responses

No example specified for this content type

Translations Vouchers