Error

A valid request URL is required to generate request examples

{
  "id": "<string>",
  "name": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "object": "<string>",
  "stock": {
    "limited": {
      "quantity": 4503599627370495
    }
  },
  "points": {
    "value": 4503599627370495,
    "card_definition_id": "<string>"
  },
  "points_proportional": {
    "card_definition_id": "<string>",
    "order": {
      "amount": {
        "every": 4503599627370496,
        "value": 4503599627370495.5
      },
      "total_amount": {
        "every": 4503599627370496,
        "value": 4503599627370495.5
      },
      "metadata": {
        "every": 4503599627370496,
        "value": 4503599627370495.5,
        "property": "<string>"
      }
    },
    "customer": {
      "metadata": {
        "every": 4503599627370496,
        "value": 4503599627370495.5,
        "property": "<string>"
      }
    },
    "custom_event": {
      "metadata": {
        "every": 4503599627370496,
        "value": 4503599627370495.5,
        "property": "<string>"
      }
    },
    "order_items": {
      "amount": {
        "every": 4503599627370496,
        "value": 4503599627370495.5,
        "applicable_to": [
          {
            "product": {
              "id": "<string>"
            },
            "sku": {
              "id": "<string>"
            },
            "products_collection": {
              "id": "<string>"
            }
          }
        ]
      },
      "subtotal_amount": {
        "every": 4503599627370496,
        "value": 4503599627370495.5,
        "applicable_to": [
          {
            "product": {
              "id": "<string>"
            },
            "sku": {
              "id": "<string>"
            },
            "products_collection": {
              "id": "<string>"
            }
          }
        ]
      },
      "quantity": {
        "every": 4503599627370496,
        "value": 4503599627370495.5,
        "applicable_to": [
          {
            "product": {
              "id": "<string>"
            },
            "sku": {
              "id": "<string>"
            },
            "products_collection": {
              "id": "<string>"
            }
          }
        ]
      }
    }
  },
  "material": {
    "product": {
      "id": "<string>"
    },
    "sku": {
      "product_id": "<string>",
      "id": "<string>"
    }
  },
  "digital": {
    "gift_vouchers": {
      "campaign_id": "<string>",
      "balance": 4503599627370495.5
    },
    "discount_coupons": {
      "campaign_id": "<string>"
    }
  },
  "updated_at": "2023-11-07T05:31:56Z"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

Create benefit

⚠️ BETA endpoint

This is a work-in-progress documentation of a BETA endpoint. The parameters, fields, request and response bodies, and other data may subject to change. If you want to share feedback or improvements, contact Voucherify support or your Technical Account Manager.

Creates a new benefit. Exactly one type-specific configuration object (points, points_proportional, material, or digital) is required, matching the type. When status is omitted the benefit is created in DRAFT status. When stock is omitted it defaults to { "type": "UNLIMITED" }.

Referenced resources are validated: the card definition (for points-based types) must exist and - when creating with status: ACTIVE - must be ACTIVE (423 resource_locked otherwise); the product/SKU (for MATERIAL) and campaign (for DIGITAL) must exist, and the campaign type must match the digital benefit type (DISCOUNT_COUPONS or GIFT_VOUCHERS). The benefit name must be unique per project (409 duplicate_found).

POST

loyalties

benefits

Error

A valid request URL is required to generate request examples

{
  "id": "<string>",
  "name": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "object": "<string>",
  "stock": {
    "limited": {
      "quantity": 4503599627370495
    }
  },
  "points": {
    "value": 4503599627370495,
    "card_definition_id": "<string>"
  },
  "points_proportional": {
    "card_definition_id": "<string>",
    "order": {
      "amount": {
        "every": 4503599627370496,
        "value": 4503599627370495.5
      },
      "total_amount": {
        "every": 4503599627370496,
        "value": 4503599627370495.5
      },
      "metadata": {
        "every": 4503599627370496,
        "value": 4503599627370495.5,
        "property": "<string>"
      }
    },
    "customer": {
      "metadata": {
        "every": 4503599627370496,
        "value": 4503599627370495.5,
        "property": "<string>"
      }
    },
    "custom_event": {
      "metadata": {
        "every": 4503599627370496,
        "value": 4503599627370495.5,
        "property": "<string>"
      }
    },
    "order_items": {
      "amount": {
        "every": 4503599627370496,
        "value": 4503599627370495.5,
        "applicable_to": [
          {
            "product": {
              "id": "<string>"
            },
            "sku": {
              "id": "<string>"
            },
            "products_collection": {
              "id": "<string>"
            }
          }
        ]
      },
      "subtotal_amount": {
        "every": 4503599627370496,
        "value": 4503599627370495.5,
        "applicable_to": [
          {
            "product": {
              "id": "<string>"
            },
            "sku": {
              "id": "<string>"
            },
            "products_collection": {
              "id": "<string>"
            }
          }
        ]
      },
      "quantity": {
        "every": 4503599627370496,
        "value": 4503599627370495.5,
        "applicable_to": [
          {
            "product": {
              "id": "<string>"
            },
            "sku": {
              "id": "<string>"
            },
            "products_collection": {
              "id": "<string>"
            }
          }
        ]
      }
    }
  },
  "material": {
    "product": {
      "id": "<string>"
    },
    "sku": {
      "product_id": "<string>",
      "id": "<string>"
    }
  },
  "digital": {
    "gift_vouchers": {
      "campaign_id": "<string>",
      "balance": 4503599627370495.5
    },
    "discount_coupons": {
      "campaign_id": "<string>"
    }
  },
  "updated_at": "2023-11-07T05:31:56Z"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

X-App-Id

string

header

required

X-App-Token

string

header

required

Body

application/json

Request body for creating a benefit. Exactly one type-specific configuration object is required, matching the type; the remaining type-specific properties must be omitted or null.

name

string

required

Benefit name. Must be unique within the project.

Required string length: 1 - 200

type

enum<string>

required

Benefit type. Determines which configuration object is required.

Available options:

POINTS,

POINTS_PROPORTIONAL,

MATERIAL,

DIGITAL

status

enum<string>

Initial status of the benefit. Defaults to DRAFT when omitted.

Available options:

DRAFT,

ACTIVE

points

object | null

Fixed points configuration. Required when type is POINTS, must be null otherwise.

Show child attributes

points_proportional

object | null

Proportional points configuration. Required when type is POINTS_PROPORTIONAL, must be null otherwise.

Show child attributes

material

object | null

Material (physical product/SKU) configuration. Required when type is MATERIAL, must be null otherwise.

Show child attributes

digital

object | null

Digital (campaign-based) configuration. Required when type is DIGITAL, must be null otherwise.

Show child attributes

stock

object | null

Stock configuration. Defaults to { "type": "UNLIMITED" } when omitted.

Show child attributes

Response

The created benefit

A benefit object. Exactly one type-specific configuration object (points, points_proportional, material, or digital) is present, matching the type; the others are omitted.

string

required

Unique benefit ID, prefixed with lben_.

Pattern: ^lben_[a-f0-9]+$

name

string

required

Benefit name, unique within the project.

type

enum<string>

required

Benefit type.

Available options:

POINTS,

POINTS_PROPORTIONAL,

MATERIAL,

DIGITAL

status

enum<string>

required

Current benefit status. DELETED appears only in the response of the delete endpoint and in activity snapshots.

Available options:

DRAFT,

ACTIVE,

DELETED

created_at

string<date-time>

required

Timestamp of when the benefit was created, in ISO 8601 format.

object

string

required

Type of the object. Always benefit.

Allowed value: "benefit"

stock

object

Stock configuration. Omitted when not set.

Show child attributes

points

object

Fixed points configuration. Present only when type is POINTS.

Show child attributes

points_proportional

object

Proportional points configuration. Present only when type is POINTS_PROPORTIONAL.

Show child attributes

material

object

Material configuration. Present only when type is MATERIAL.

Show child attributes

digital

object

Digital configuration. Present only when type is DIGITAL.

Show child attributes

updated_at

string<date-time> | null

Timestamp of the last update, in ISO 8601 format. Null when the benefit was never updated.

Last modified on July 9, 2026

List benefits Get benefit

⌘I