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

# Convert a hold into confirmed bookings (the idempotent purchase hook)

> Turns the held supplier time into real bookings, drawing credits from the given order item. The order item's skuType decides what is booked: a PACKAGE item books every held interval as package sessions; a SINGLE_SESSION item books the ONE held interval as an ordinary single booking — no package, and no 1-credit "reservation vehicle" package needed. (A SINGLE_SESSION item against a hold covering more than one interval returns 409 RESERVATION_MULTI_INTERVAL; any other skuType returns 400.) Call it once your checkout has confirmed payment (poll `GET /orders/{orderId}` for `PAID`, or convert first: convert does not require a paid order). The open API sends no webhooks. It is idempotent on the reservationId (the package booking write uses the deterministic key convert:<reservationId>), so a retried call replays the same bookings rather than double-booking, and a reservation already CONVERTED replays its stored result. The bookings are rebuilt from the RESERVATION and the ORDER ITEM — never by re-resolving a suggestion that may have expired — so the booked service and the credit it draws down cannot disagree. Returns 409 HOLD_EXPIRED if you converted too late (the hold no longer blocks anyone), or SLOT_HELD/SLOT_BOOKED if someone else took the time in the meantime. The order need not be paid, but a CANCELLED order converts nothing (409 ORDER_CANCELLED), not even as a replay: its cascade has released its credits and cancelled what it had booked. This response is NOT wrapped in a { data } envelope, and created[].sessionIndex is 0-based.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/projects/{projectId}/holds/{reservationId}/convert
openapi: 3.0.0
info:
  title: MarketBox 2.0 Open API
  version: 1.0.0
  description: >-
    The MarketBox public API for building booking experiences. Core model:
    create an order, then draw its order items down into bookings. Single
    bookings reference an order item per service line; package bookings draw one
    PACKAGE item down across N sessions. To schedule a package, build a slate
    (POST /availability/package-slate) and book it by slateId (POST
    /orders/{orderId}/package-bookings). See the guides for end-to-end
    walkthroughs.
  contact:
    name: MarketBox support
servers:
  - url: https://apiv2.gomarketbox.com
    description: MarketBox Open API
security:
  - ApiKeyAuth: []
paths:
  /v1/projects/{projectId}/holds/{reservationId}/convert:
    post:
      tags:
        - Holds
      summary: Convert a hold into confirmed bookings (the idempotent purchase hook)
      description: >-
        Turns the held supplier time into real bookings, drawing credits from
        the given order item. The order item's skuType decides what is booked: a
        PACKAGE item books every held interval as package sessions; a
        SINGLE_SESSION item books the ONE held interval as an ordinary single
        booking — no package, and no 1-credit "reservation vehicle" package
        needed. (A SINGLE_SESSION item against a hold covering more than one
        interval returns 409 RESERVATION_MULTI_INTERVAL; any other skuType
        returns 400.) Call it once your checkout has confirmed payment (poll
        `GET /orders/{orderId}` for `PAID`, or convert first: convert does not
        require a paid order). The open API sends no webhooks. It is idempotent
        on the reservationId (the package booking write uses the deterministic
        key convert:<reservationId>), so a retried call replays the same
        bookings rather than double-booking, and a reservation already CONVERTED
        replays its stored result. The bookings are rebuilt from the RESERVATION
        and the ORDER ITEM — never by re-resolving a suggestion that may have
        expired — so the booked service and the credit it draws down cannot
        disagree. Returns 409 HOLD_EXPIRED if you converted too late (the hold
        no longer blocks anyone), or SLOT_HELD/SLOT_BOOKED if someone else took
        the time in the meantime. The order need not be paid, but a CANCELLED
        order converts nothing (409 ORDER_CANCELLED), not even as a replay: its
        cascade has released its credits and cancelled what it had booked. This
        response is NOT wrapped in a { data } envelope, and
        created[].sessionIndex is 0-based.
      parameters:
        - schema:
            type: string
            minLength: 1
            description: The project the hold belongs to.
            example: prj_01kv60qgnef2kt3pvqgwmkbzfr
          required: true
          description: The project the hold belongs to.
          name: projectId
          in: path
        - schema:
            type: string
            minLength: 1
            description: The reservationId returned by POST /holds.
            example: resv_01kv8p20m1gnqvxl92xln6awk8
          required: true
          description: The reservationId returned by POST /holds.
          name: reservationId
          in: path
      requestBody:
        description: orderId + orderItemId (+ optional heldBy, atomicity)
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                orderId:
                  type: string
                  minLength: 1
                  description: The order whose item the bookings draw credits from.
                  example: ord_01kv7n10k0fnptwk81wkm59vj7
                orderItemId:
                  type: string
                  minLength: 1
                  description: >-
                    The order item to draw down. For a multi-session hold this
                    must be a PACKAGE item with enough quantityRemaining.
                  example: oi_01kv7n10k0fnptwk81wkm59vj7
                heldBy:
                  type: string
                  minLength: 1
                  description: Required to match if the hold was created with a heldBy.
                atomicity:
                  type: string
                  enum:
                    - all_or_nothing
                    - best_effort
                  default: all_or_nothing
                  description: >-
                    all_or_nothing (default) books every session in one
                    transaction. best_effort requires
                    suggestionConfig.allowPartialPackages.
              required:
                - orderId
                - orderItemId
      responses:
        '201':
          description: Hold converted to confirmed bookings
          content:
            application/json:
              schema:
                type: object
                properties:
                  orderId:
                    type: string
                  orderItemId:
                    type: string
                  packageOrderItemId:
                    type: string
                  atomicity:
                    type: string
                    enum:
                      - all_or_nothing
                      - best_effort
                  created:
                    type: array
                    items:
                      type: object
                      properties:
                        sessionIndex:
                          type: integer
                          minimum: 0
                        bookingId:
                          type: string
                        allocationId:
                          type: string
                      required:
                        - sessionIndex
                        - bookingId
                        - allocationId
                    description: >-
                      Bookings created, each with a 0-based sessionIndex,
                      bookingId and allocationId.
                  failed:
                    type: array
                    items:
                      type: object
                      properties:
                        sessionIndex:
                          type: integer
                          minimum: 0
                        reason:
                          type: string
                      required:
                        - sessionIndex
                        - reason
                    description: Per-session failures (best_effort only).
                  quantityRemaining:
                    type: integer
                    minimum: 0
                    description: Credits left on the order item after this call.
                required:
                  - orderId
                  - orderItemId
                  - packageOrderItemId
                  - atomicity
                  - created
                  - failed
                  - quantityRemaining
        '400':
          description: >-
            Validation error, or a location of the wrong type / another
            supplier’s, or with invalid fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: API key cannot access this project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Order / order item / offering / location not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '409':
          description: >-
            Hold expired / not yours / already released, the time is now taken
            (SLOT_HELD / SLOT_BOOKED), the calendar is under contention
            (OCCUPANCY_CONTENTION), the order is cancelled (code:
            ORDER_CANCELLED), the package has expired (PACKAGE_EXPIRED), or the
            order item has fewer sessions left than the hold has intervals
            (ORDER_ITEM_QUANTITY_UNAVAILABLE)
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ErrorMessage'
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - SLOT_HELD
                          - SLOT_BOOKED
                        description: Which kind of claim is blocking the requested time.
                        example: SLOT_HELD
                      message:
                        type: string
                        description: Human-readable summary of the conflict.
                        example: >-
                          Supplier time is not available: HOLD
                          resv_01kv8p20m1gnqvxl92xln6awk8
                          (2026-08-01T10:00:00Z–2026-08-01T11:00:00Z)
                      statusCode:
                        type: number
                        enum:
                          - 409
                        description: >-
                          The HTTP status, repeated in the body — every
                          MarketBox error carries it, so you can branch on the
                          body alone.
                        example: 409
                      requestId:
                        type: string
                        description: >-
                          The id of this request (also returned as the
                          X-Request-Id header). Quote it in a support ticket.
                        example: a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10
                      conflicts:
                        type: array
                        items:
                          type: object
                          properties:
                            claimType:
                              type: string
                              enum:
                                - BOOKING
                                - HOLD
                              description: >-
                                Whether the blocking claim is a HOLD or a
                                confirmed BOOKING.
                            supplierId:
                              type: string
                              nullable: true
                              description: >-
                                The supplier whose calendar is blocked, when
                                known.
                            startUtc:
                              type: string
                              format: date-time
                              description: Start of the blocking claim, UTC ISO 8601.
                              example: '2026-08-01T10:00:00Z'
                            endUtc:
                              type: string
                              format: date-time
                              description: End of the blocking claim, UTC ISO 8601.
                              example: '2026-08-01T11:00:00Z'
                            reservationId:
                              type: string
                              nullable: true
                              description: >-
                                Present when claimType is HOLD — the
                                reservationId to convert or release. Null for a
                                BOOKING conflict.
                              example: resv_01kv8p20m1gnqvxl92xln6awk8
                            bookingId:
                              type: string
                              nullable: true
                              description: >-
                                Present when claimType is BOOKING — the id of
                                the confirmed booking occupying this time. Null
                                for a HOLD conflict.
                              example: null
                            heldUntil:
                              type: string
                              nullable: true
                              format: date-time
                              description: >-
                                HOLD only: when the blocking hold lazily
                                expires. Null for a BOOKING conflict.
                              example: '2026-08-01T10:05:00Z'
                          required:
                            - claimType
                            - startUtc
                            - endUtc
                        description: >-
                          Every live claim that overlaps the requested time —
                          usually one, but can be more.
                      hint:
                        type: string
                        description: >-
                          What to do next: for SLOT_HELD, convert or release the
                          named reservationId (POST
                          .../holds/{reservationId}/convert or /release); for
                          SLOT_BOOKED, search availability again.
                        example: >-
                          This time is held (reservation
                          resv_01kv8p20m1gnqvxl92xln6awk8). Convert the hold via
                          POST
                          /v1/projects/{projectId}/holds/{reservationId}/convert,
                          or release it with POST
                          /v1/projects/{projectId}/holds/{reservationId}/release.
                          Direct booking routes will not consume a hold — if you
                          hold, you convert.
                    required:
                      - code
                      - message
                      - statusCode
                      - requestId
                      - conflicts
                      - hint
                  - type: object
                    properties:
                      code:
                        type: string
                        description: >-
                          Why the hold could not be used: HOLD_EXPIRED,
                          RESERVATION_NOT_FOUND, RESERVATION_NOT_HELD,
                          RESERVATION_FORBIDDEN, RESERVATION_MULTI_INTERVAL (a
                          SINGLE_SESSION order item converts exactly one held
                          interval), SLOT_NOT_FOUND, SLATE_NOT_FOUND,
                          EMPTY_SLATE, SUGGESTION_EXPIRED (placing or extending
                          a hold from a slate or slot past its resolvableUntil:
                          plan a fresh slate).
                        example: HOLD_EXPIRED
                      message:
                        type: string
                        description: Human-readable explanation.
                        example: >-
                          Reservation resv_01kv8 expired at
                          2026-07-10T12:05:00.000Z
                      statusCode:
                        type: number
                        enum:
                          - 409
                        description: >-
                          The HTTP status, repeated in the body — every
                          MarketBox error carries it, so you can branch on the
                          body alone.
                        example: 409
                      requestId:
                        type: string
                        description: >-
                          The id of this request (also returned as the
                          X-Request-Id header). Quote it in a support ticket.
                        example: a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10
                    required:
                      - code
                      - message
                      - statusCode
                      - requestId
        '422':
          description: >-
            The hold has more intervals than an all_or_nothing booking can write
            at once (PACKAGE_SLATE_TOO_LARGE_FOR_ATOMIC), best_effort is not
            enabled for this project (BEST_EFFORT_NOT_ENABLED), the held
            location is a PHYSICAL Location without coordinates
            (UNPROCESSABLE_ENTITY), or the order item names an offering that is
            not ACTIVE (NOT_SELLABLE): the hold draws down an order item already
            bought, so only the offering is checked, and a service retired since
            stays bookable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
components:
  schemas:
    ErrorMessage:
      type: object
      properties:
        code:
          type: string
          description: Stable machine-readable error code, e.g. NOT_FOUND.
        message:
          type: string
          description: Human-readable description of what went wrong.
        statusCode:
          type: integer
          description: The HTTP status code of this response.
        requestId:
          type: string
          description: >-
            The id of this request, also returned as the X-Request-Id header.
            Quote it in a support ticket.
      required:
        - code
        - message
        - statusCode
        - requestId
      example:
        code: NOT_FOUND
        message: Booking not found
        statusCode: 404
        requestId: a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key minted in the MarketBox dashboard. Scope is restricted to the
        projects you select at creation time. Every route needs the key's
        standard API access (`*`) except `POST /v1/projects/{projectId}/events`,
        which needs `events:write`; a key without `*` is refused with 403
        `CAPABILITY_NOT_GRANTED`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.