Update benefit

Documentation in progress

This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact Voucherify support or your Technical Account Manager.

Updates a benefit. When the benefit is in DRAFT status all properties can be updated. When the benefit is not in DRAFT status, only name, stock, points, points_proportional, and digital may be updated (400 invalid_payload otherwise). Referenced resources (card definition, product/SKU, campaign) are validated the same way as on create; a points-based benefit can only reference an ACTIVE card definition (423 resource_locked otherwise). The benefit name must remain unique per project (409 duplicate_found).

PUT /v2/loyalties/benefits/{benefitId}

Update benefit

cURL

curl --request PUT \
  --url https://{cluster}.voucherify.io/v2/loyalties/benefits/{benefitId} \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "name": "<string>",
  "points": {
    "value": 4503599627370495,
    "card_definition_id": "<string>"
  },
  "points_proportional": {
    "card_definition_id": "<string>",
    "order": {},
    "customer": {
      "metadata": {
        "every": 4503599627370496,
        "value": 4503599627370495.5,
        "property": "<string>"
      }
    },
    "custom_event": {
      "metadata": {
        "every": 4503599627370496,
        "value": 4503599627370495.5,
        "property": "<string>"
      }
    },
    "order_items": {}
  },
  "material": {
    "product": {
      "id": "<string>"
    },
    "sku": {
      "product_id": "<string>",
      "id": "<string>"
    }
  },
  "digital": {
    "gift_vouchers": {
      "campaign_id": "<string>",
      "balance": 4503599627370495.5
    },
    "discount_coupons": {
      "campaign_id": "<string>"
    }
  },
  "stock": {
    "limited": {
      "quantity": 4503599627370495
    }
  }
}
'

200

{
  "id": "<string>",
  "name": "<string>",
  "type": "POINTS",
  "status": "DRAFT",
  "stock": {
    "type": "UNLIMITED",
    "limited": {
      "quantity": 4503599627370495
    }
  },
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "object": "benefit",
  "points": {
    "value": 4503599627370495,
    "card_definition_id": "<string>"
  },
  "points_proportional": {
    "calculation_type": "PRE_DISCOUNT_ORDER_AMOUNT",
    "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": [
          {
            "type": "product",
            "product": {
              "id": "<string>"
            },
            "sku": {
              "id": "<string>"
            },
            "products_collection": {
              "id": "<string>"
            }
          }
        ]
      },
      "subtotal_amount": {
        "every": 4503599627370496,
        "value": 4503599627370495.5,
        "applicable_to": [
          {
            "type": "product",
            "product": {
              "id": "<string>"
            },
            "sku": {
              "id": "<string>"
            },
            "products_collection": {
              "id": "<string>"
            }
          }
        ]
      },
      "quantity": {
        "every": 4503599627370496,
        "value": 4503599627370495.5,
        "applicable_to": [
          {
            "type": "product",
            "product": {
              "id": "<string>"
            },
            "sku": {
              "id": "<string>"
            },
            "products_collection": {
              "id": "<string>"
            }
          }
        ]
      }
    }
  },
  "material": {
    "type": "PRODUCT",
    "product": {
      "id": "<string>"
    },
    "sku": {
      "product_id": "<string>",
      "id": "<string>"
    }
  },
  "digital": {
    "type": "GIFT_VOUCHERS",
    "gift_vouchers": {
      "campaign_id": "<string>",
      "balance": 4503599627370495.5
    },
    "discount_coupons": {
      "campaign_id": "<string>"
    }
  }
}

Authorizations

X-App-Id & X-App-TokenbearerAuth

X-App-Id · string · header · required

X-App-Token · string · header · required

Path Parameters

benefitId · string · required

Unique benefit ID, prefixed with lben_.

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

Body

application/json

Request body schema for PUT /v2/loyalties/benefits/{benefitId}.

name · string

Benefit name. Must be unique within the project.

Required string length: 1 - 200

type · enum<string>

Benefit type. Determines which configuration object is required.

Available options: POINTS, POINTS_PROPORTIONAL, MATERIAL, DIGITAL

points · object | null

Fixed points configuration (for type POINTS).

Show child attributes

points_proportional · object | null

Proportional points configuration (for type POINTS_PROPORTIONAL).

Show child attributes

material · object | null

Material (physical product/SKU) configuration (for type MATERIAL).

Show child attributes

digital · object | null

Digital (campaign-based) configuration (for type DIGITAL).

Show child attributes

stock · object | null

Stock configuration.

Show child attributes

Response

200

application/json

The updated benefit

Response body schema for PUT /v2/loyalties/benefits/{benefitId}.

id · 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

stock · object · required

Stock configuration. Always present. Null stock is returned as UNLIMITED with limited omitted.

Show child attributes

created_at · string<date-time> · required

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

updated_at · string<date-time> | null · required

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

object · string · required

Type of the object. Always benefit.

Allowed value: "benefit"

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