> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrip.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Fail a pending redemption

> Release the reservation backing a pending redemption and mark fulfillment failed. Replaying an already-failed redemption returns the same record.

Marks a `PENDING` redemption as `FAILED` and releases its live reserved value from `HELD` to `AVAILABLE`. Include an optional `reason` to retain the fulfillment outcome on the redemption.

Reserved LOT value can expire before failure. The endpoint releases only the live remainder and never recreates expired value. Repeating failure returns the stored redemption; a different terminal outcome returns `409 redemption_already_resolved`.

<Note>
  For expiration and terminal state behavior, see the [Redemption lifecycle guide](/guides/redemption-lifecycle).
</Note>


## OpenAPI

````yaml POST /v1/redemptions/{id}/fail
openapi: 3.0.3
info:
  contact:
    email: support@scrip.dev
    name: Scrip Support
  description: >-
    Scrip is the operating system for rewards programs. Use this REST API to
    define earn and redemption rules, issue and redeem assets, and track every
    movement in a double-entry ledger. Full guides and reference:
    https://docs.scrip.dev


    Core concepts:

    - **Programs**: Containers for incentive logic (e.g., "Q1 Sales Bonus",
    "Customer Loyalty")

    - **Assets**: The currency or points being tracked (e.g., "Bonus Points",
    "Cash Rewards")

    - **Participants**: Users who earn and spend assets (identified by
    external_id)

    - **Groups**: Collections of participants for team-based incentives

    - **Rules**: Automated reward logic triggered by events

    - **Events**: Actions that trigger rule evaluation (e.g., "purchase",
    "referral")


    Response formats:

    - **Collection endpoints** return: {"data": [...], "pagination":
    {"has_more": true, "next_cursor": "..."}}

    - **Single-resource endpoints** return the resource directly

    - **Errors** return: {"code": "...", "message": "...", "details": {...}} —
    `details` is an optional object, present on input errors only
  license:
    name: Proprietary
  termsOfService: https://scrip.dev/terms
  title: Scrip API
  version: '1.0'
servers:
  - url: https://api.scrip.dev
security: []
tags:
  - description: >-
      Manage incentive programs. Programs are the top-level container for all
      incentive logic.
    name: Programs
  - description: >-
      Manage asset types (currencies, points). Assets define what participants
      can earn and spend.
    name: Assets
  - description: >-
      Manage participants and their balances. Participants are identified by
      external_id from your system.
    name: Participants
  - description: Manage participant groups for team-based incentives.
    name: Groups
  - description: >-
      Manage automated reward rules. Rules define conditions and actions
      triggered by events.
    name: Rules
  - description: Ingest events that trigger rule evaluation and reward distribution.
    name: Events
  - description: Transfer assets between participants.
    name: Transfers
  - description: Access ledger summaries and program activity reports.
    name: Reporting
  - description: >-
      Redeem participant balances for rewards. Supports raw amount redemptions
      and catalog item redemptions.
    name: Redemptions
  - description: >-
      Manage the reward catalog. Create and manage redeemable items with
      inventory tracking.
    name: Rewards
  - description: >-
      Schedule and manage automated event dispatching. Automations generate
      events on cron schedules, at specific times, or by evaluating participant
      state.
    name: Automations
  - description: >-
      Manage tier types and levels within programs. Tiers define status
      hierarchies that participants progress through based on qualification
      rules.
    name: Tiers
  - description: Inspect double-entry ledger records for auditing and reconciliation.
    name: Journal Entries
  - description: >-
      Manage webhook endpoints and delivery logs. Webhooks notify your
      application of real-time events via HTTP POST with HMAC-SHA256 signatures.
    name: Webhooks
paths:
  /v1/redemptions/{id}/fail:
    post:
      tags:
        - Redemptions
      summary: Fail a pending redemption
      description: >-
        Release the reservation backing a pending redemption and mark
        fulfillment failed. Replaying an already-failed redemption returns the
        same record.
      operationId: failRedemption
      parameters:
        - description: Redemption ID
          in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handlers.ReleaseRedemptionRequest'
        description: Failure details
        x-originalParamName: request
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.RedemptionResponse'
          description: Redemption failed or same-outcome replay
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrBadRequestResponse'
          description: 'Validation failed (code: validation_error | bad_request)'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrUnauthorizedResponse'
          description: 'Missing or invalid credentials (code: unauthorized)'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrNotFoundResponse'
          description: 'Redemption not found (code: redemption_not_found)'
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrConflictResponse'
          description: 'Redemption already resolved (code: redemption_already_resolved)'
        '415':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrUnsupportedMediaTypeResponse'
          description: 'Content-Type must be application/json (code: unsupported_media_type)'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrInternalResponse'
          description: 'Internal server error (code: internal_error)'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
components:
  schemas:
    handlers.ReleaseRedemptionRequest:
      additionalProperties: false
      properties:
        idempotency_key:
          description: Reconciled with the Idempotency-Key header when both are supplied
          example: fail-12345
          type: string
        reason:
          description: Optional fulfillment failure or cancellation reason (1-500 chars)
          example: provider_rejected
          maxLength: 500
          minLength: 1
          type: string
      type: object
    handlers.RedemptionResponse:
      properties:
        amount:
          description: Total amount debited from the participant's balance (decimal string)
          example: '1000.00'
          type: string
        asset_id:
          description: The asset that was debited
          example: 550e8400-e29b-41d4-a716-446655440003
          format: uuid
          type: string
        capture_journal_entry_id:
          description: Ledger entry that captured a pending redemption
          example: 550e8400-e29b-41d4-a716-446655440007
          format: uuid
          type: string
        captured_at:
          description: When the pending redemption was captured
          example: '2024-01-15T10:45:00Z'
          format: date-time
          type: string
        created_at:
          description: When this redemption was created
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
        description:
          description: Context for this redemption, used in journal entries
          example: 'Redeemed: Gift Card'
          type: string
        expires_at:
          description: >-
            Effective deadline of the backing reservation. Always present for
            pending redemptions; defaults to 90 days and may be configured up to
            one year.
          example: '2024-01-15T11:30:00Z'
          format: date-time
          type: string
        failure_reason:
          description: Machine-readable or operator-supplied terminal failure detail
          example: fulfillment_failed
          type: string
        id:
          description: Unique identifier for this redemption
          example: 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        journal_entry_id:
          description: >-
            Immutable ledger anchor: the hold entry for pending redemptions,
            otherwise the instant redemption entry
          example: 550e8400-e29b-41d4-a716-446655440005
          format: uuid
          type: string
        participant_id:
          description: The participant who redeemed
          example: 550e8400-e29b-41d4-a716-446655440002
          format: uuid
          type: string
        program_id:
          description: The program this redemption belongs to
          example: 550e8400-e29b-41d4-a716-446655440001
          format: uuid
          type: string
        quantity:
          description: Number of units redeemed (catalog redemptions only)
          example: 2
          type: integer
        reservation_id:
          description: Reservation backing a pending redemption
          example: 550e8400-e29b-41d4-a716-446655440006
          format: uuid
          type: string
        resolved_at:
          description: When the pending redemption reached a terminal state
          example: '2024-01-15T10:45:00Z'
          format: date-time
          type: string
        reversed_amount:
          description: Cumulative amount reversed so far (decimal string)
          example: '0.00'
          type: string
        reversed_quantity:
          description: >-
            Cumulative units reversed so far (UNIT_BASED catalog redemptions
            only)
          example: 0
          type: integer
        reward_id:
          description: The reward catalog item that was redeemed (catalog redemptions only)
          example: 550e8400-e29b-41d4-a716-446655440004
          format: uuid
          type: string
        status:
          description: Current lifecycle and reversal state
          enum:
            - PENDING
            - COMPLETED
            - FAILED
            - CANCELLED
            - PARTIALLY_REVERSED
            - FULLY_REVERSED
          example: COMPLETED
          type: string
        unit_cost:
          description: >-
            Cost per unit at the time of redemption (catalog redemptions only,
            decimal string)
          example: '500.00'
          type: string
        updated_at:
          description: When this redemption was last updated (e.g., after a reversal)
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
      type: object
    handlers.ErrBadRequestResponse:
      additionalProperties: false
      properties:
        code:
          description: Code is the machine-readable error code
          example: bad_request
          type: string
        details:
          allOf:
            - $ref: '#/components/schemas/handlers.ErrorDetails'
          description: >-
            Details provides optional structured error context (field errors,
            etc.)
        message:
          description: Message is the human-readable error description
          example: Invalid request parameters
          type: string
      type: object
    handlers.ErrUnauthorizedResponse:
      properties:
        code:
          description: Code is the machine-readable error code
          example: unauthorized
          type: string
        details:
          allOf:
            - $ref: '#/components/schemas/handlers.ErrorDetails'
          description: Details provides optional structured error context
        message:
          description: Message is the human-readable error description
          example: Missing or invalid credentials
          type: string
      type: object
    handlers.ErrNotFoundResponse:
      properties:
        code:
          description: Code is the machine-readable error code
          example: not_found
          type: string
        details:
          allOf:
            - $ref: '#/components/schemas/handlers.ErrorDetails'
          description: Details provides optional structured error context
        message:
          description: Message is the human-readable error description
          example: Resource not found
          type: string
      type: object
    handlers.ErrConflictResponse:
      properties:
        code:
          description: Code is the machine-readable error code
          example: conflict
          type: string
        details:
          allOf:
            - $ref: '#/components/schemas/handlers.ErrorDetails'
          description: Details provides optional structured error context
        message:
          description: Message is the human-readable error description
          example: Resource already exists or state conflict
          type: string
      type: object
    handlers.ErrUnsupportedMediaTypeResponse:
      properties:
        code:
          description: Code is the machine-readable error code
          example: unsupported_media_type
          type: string
        details:
          allOf:
            - $ref: '#/components/schemas/handlers.ErrorDetails'
          description: Details provides optional structured error context
        message:
          description: Message is the human-readable error description
          example: Content-Type must be application/json
          type: string
      type: object
    handlers.ErrInternalResponse:
      properties:
        code:
          description: Code is the machine-readable error code
          example: internal_error
          type: string
        message:
          description: Message is the human-readable error description
          example: An internal error occurred
          type: string
      type: object
    handlers.ErrorDetails:
      description: >-
        Optional structured details about the error. Always a JSON object: a
        `fields` array for validation errors, or flat
        field/reason/expected/received properties for other input errors.
      properties:
        expected:
          description: Expected value or format (non-validation input errors)
          example: uuid
          type: string
        field:
          description: Field name that caused the error (non-validation input errors)
          example: asset_id
          type: string
        fields:
          description: >-
            Fields lists each offending input field on validation_error
            responses.
          items:
            $ref: '#/components/schemas/handlers.ErrorFieldDetail'
          type: array
        reason:
          description: Machine-readable reason code (non-validation input errors)
          example: invalid
          type: string
        received:
          description: Value that was received (non-validation input errors)
          example: not-a-uuid
          type: string
      type: object
    handlers.ErrorFieldDetail:
      description: >-
        A single field-level error: which input field failed, why, and (where
        known) the expected and received values.
      properties:
        expected:
          description: >-
            Expected value or format. Usually a string; for "one of" constraints
            it

            is an array of the allowed values.
        field:
          description: Field name that caused the error
          example: amount
          type: string
        message:
          description: Human-readable explanation (validation errors only)
          example: This field is required
          type: string
        reason:
          description: Machine-readable reason code
          example: required
          type: string
        received:
          description: Value that was received
          example: '-10.00'
          type: string
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: API key passed in the X-API-Key header.
      in: header
      name: X-API-Key
      type: apiKey
    BearerAuth:
      description: Bearer token passed in the Authorization header (e.g. "Bearer sk_...").
      in: header
      name: Authorization
      type: apiKey

````