Set a gift voucher's redemption rules

PUT/v2/experiences/{experienceId}/retail-voucher-config

Requires your API key in the X-API-Key header.

Creates or replaces the redemption rules of your gift voucher product: how many uses one voucher grants, which experiences it can be redeemed against, and whether a redemption may include one add-on. Organizer only (403 otherwise). Every id in scopeExperienceIds must be one of your own active, bookable experiences (400, VOUCHER_SCOPE_EXPERIENCE_INVALID). Rules are read live, so a change also applies to vouchers already sold. A voucher product can't be set ACTIVE until its rules cover at least one experience.

Requestbash
curl -X PUT "https://api.turneo.co/v2/experiences/8e7d6c5b-4a39-4281-90ef-1a2b3c4d5e6f/retail-voucher-config" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "redemptionsPerUnit": 5,
    "scopeExperienceIds": [
      "0d4dbb2e-8a51-4a4b-9d3e-6f2b7c1a9e55",
      "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
    ],
    "includesAddon": false
  }'

Path parameters

  • experienceIdstring (uuid)required

    UUID of the gift voucher product (an experience with experienceType VOUCHER).

    Example:
    8e7d6c5b-4a39-4281-90ef-1a2b3c4d5e6f

Request bodyapplication/json, required

  • redemptionsPerUnitinteger

    How many uses one voucher grants. Defaults to 1.

    Limits:
    minimum 1
    Example:
    5
  • scopeExperienceIdsstring (uuid)[]required

    Experiences the voucher can be redeemed against. Each must be one of your own active, bookable experiences. An empty list is accepted, but the voucher can't be activated without one.

  • includesAddonboolean

    Whether a redeemed booking may include one add-on of its option. Defaults to false.

    Example:
    false
Example: Five uses across two experiences
Five uses across two experiencesjson
{
  "redemptionsPerUnit": 5,
  "scopeExperienceIds": [
    "0d4dbb2e-8a51-4a4b-9d3e-6f2b7c1a9e55",
    "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  ],
  "includesAddon": false
}

Responses

200object

The stored redemption rules.

  • redemptionsPerUnitinteger

    How many uses one voucher grants. One use covers one booking.

    Limits:
    minimum 1
    Example:
    5
  • scopeExperienceIdsstring (uuid)[]

    The experiences the voucher can be redeemed against.

  • includesAddonboolean

    Whether a redeemed booking may include one add-on of its option at no charge.

    Example:
    false
Response 200json
{
  "redemptionsPerUnit": 5,
  "scopeExperienceIds": [
    "0d4dbb2e-8a51-4a4b-9d3e-6f2b7c1a9e55"
  ],
  "includesAddon": false
}

Errors

400

Validation failed. Inspect errors[].field and errors[].code.

401

Missing or invalid X-API-Key header.

403

The API key is valid but not allowed to perform this action on this resource.

404

The resource does not exist or belongs to another partner (existence is not leaked across partners).

Error body
  • typestring

    Error class.

    Allowed values:
    validation_errorclient_errorserver_error
    Example:
    validation_error
  • errorsobject[]
    Child fields
    • codestring

      Machine-readable error code.

      Example:
      required
    • fieldstringnullable

      Offending field, or null/'general' for non-field errors.

      Example:
      startTime
    • messagestring

      Human-readable message.

      Example:
      This field is required.
Response 400json
{
  "type": "validation_error",
  "errors": [
    {
      "code": "required",
      "field": "startTime",
      "message": "This field is required."
    }
  ]
}