Newstore reservations API

openapi: 3.2.0
info:
  version: '1.0'
  title: NewStore Reservations API
  description: NewStore public APIs
  contact:
    email: support@newstore.com
    name: NewStore API Support
    url: https://developer.newstore.com
servers:
- url: https://dodici-demo.p.newstore.net/
security: []
tags:
- name: reservations
  description: Reservations
  externalDocs:
    url: https://docs.newstore.com/docs/reservations-1
    description: 'With NewStore Reservations, store associates can reserve items for customers who intend to buy but want to finalize their transaction later, whether the products are temporarily out of stock or the customer plans to return to the store. This creates a premium, personalized shopper experience where high-value or limited items are held exclusively for a set timeframe (example, 24 to 48 hours), shielded from other in-store or omnichannel demand.


      Once a reservation is created, the specified products are moved from sellable inventory to the Customer Reservations stock location. When the customer returns to purchase, the items are automatically returned to sellable inventory to complete the sale. If the customer is no longer interested in the reserved items, the store associates can unreserve the items, which also moves the items to sellable inventory. For more information, see the [setup guide](https://docs.newstore.com/v1/docs/set-up-reservations-product-holds-in-the-store).


      '
paths:
  /inventory/config/reservations:
    get:
      description: Gets the reservation configuration of the retailer.
      summary: showReservationConfig
      tags:
      - reservations
      operationId: showReservationConfig
      deprecated: false
      responses:
        default:
          description: Default response
          headers: {}
        '200':
          description: Successful Response
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservationConfigResponse'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ReservationConfigResponse'
        '400':
          description: Validation Error
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - newstore:configuration:read
    patch:
      description: Updates the reservations configuration for the retailer.
      summary: updateReservationConfig
      tags:
      - reservations
      operationId: updateReservationConfig
      deprecated: false
      parameters:
      - name: Content-Type
        in: header
        required: false
        description: ''
        schema:
          type: string
          enum:
          - application/json
      responses:
        default:
          description: Default response
          headers: {}
        '204':
          description: Successful Response
          headers: {}
        '400':
          description: Validation Error
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - newstore:configuration:write
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReservationConfigUpdate'
        required: true
  /inventory/reservations:
    get:
      description: Lists all reservations, supporting various filters.
      summary: listReservations
      tags:
      - reservations
      operationId: listReservations
      deprecated: false
      parameters:
      - name: location_id
        in: query
        required: false
        description: ID of the fulfillment location in which the reservations are being listed.
        schema:
          type: string
      - name: status
        in: query
        required: false
        description: Status(es) of the reservations to list. If omitted, all reservation statuses are listed.
        schema:
          type: array
          items:
            type: string
            enum:
            - PENDING
            - REJECTED
            - RESERVED
            - CONVERTED
            - UNRESERVED
          maxItems: 5
          uniqueItems: false
      - name: external_id
        in: query
        required: false
        description: If using V1 of the API, allows filtering on the user facing ID, and a partial match is also considered a match. If using V2, allows filtering on the external ID that was provided when the reservation was created, and only an exact match is considered a match.
        schema:
          type: string
      - name: display_id
        in: query
        required: false
        description: Allows filtering the reservations by 'display_id'. A partial match is also considered a match. Only usable in V2 of the API.
        schema:
          type: string
      - name: customer_profile_id
        in: query
        required: false
        description: Allows filtering the reservations by customer profile id
        schema:
          type: string
      - name: associate_id
        in: query
        required: false
        description: Allows filtering the reservations by associate id
        schema:
          type: string
      - name: offset
        in: query
        required: false
        description: Page number to return
        schema:
          type: integer
          format: int32
          default: 0
          minimum: 0.0
      - name: count
        in: query
        required: false
        description: Number of results to return in each page
        schema:
          type: integer
          format: int32
          default: 10
          maximum: 100.0
          minimum: 1.0
      - name: sort
        in: query
        required: false
        description: Field(s) to sort by. Supported values are 'created_at|asc' or 'status|asc' to list in ascending order and 'created_at|desc' or 'status|desc' to list in descending order.
        schema:
          type: array
          items:
            type: string
            enum:
            - created_at|asc
            - created_at|desc
            - status|asc
            - status|desc
          maxItems: 2
          uniqueItems: false
      - name: expired
        in: query
        required: false
        description: Filter for expired reservations
        schema:
          type: boolean
      - name: accept
        in: header
        required: false
        description: Use this to specify the version of the API to use. Possible values are `application/vnd.com.newstore.reservations+json; version=2` and `application/vnd.com.newstore.reservations+json; version=1`
        schema:
          type: string
          default: application/vnd.com.newstore.reservations+json; version=1
      responses:
        default:
          description: Default response
          headers: {}
        '200':
          description: Successful response
          headers: {}
          content:
            application/vnd.com.newstore.reservations+json; version=1:
              schema:
                $ref: '#/components/schemas/ListReservationsResponseV1'
            application/vnd.com.newstore.reservations+json; version=2:
              schema:
                $ref: '#/components/schemas/ListReservationsResponseV1'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ListReservationsResponseV1'
        '400':
          description: Validation Error
          headers: {}
          content:
            application/vnd.com.newstore.reservations+json; version=1:
              schema:
                $ref: '#/components/schemas/Problem'
            application/vnd.com.newstore.reservations+json; version=2:
              schema:
                $ref: '#/components/schemas/Problem'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/vnd.com.newstore.reservations+json; version=1:
              schema:
                $ref: '#/components/schemas/Problem'
            application/vnd.com.newstore.reservations+json; version=2:
              schema:
                $ref: '#/components/schemas/Problem'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/vnd.com.newstore.reservations+json; version=1:
              schema:
                $ref: '#/components/schemas/Problem'
            application/vnd.com.newstore.reservations+json; version=2:
              schema:
                $ref: '#/components/schemas/Problem'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/vnd.com.newstore.reservations+json; version=1:
              schema:
                $ref: '#/components/schemas/Problem'
            application/vnd.com.newstore.reservations+json; version=2:
              schema:
                $ref: '#/components/schemas/Problem'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/vnd.com.newstore.reservations+json; version=1:
              schema:
                $ref: '#/components/schemas/Problem'
            application/vnd.com.newstore.reservations+json; version=2:
              schema:
                $ref: '#/components/schemas/Problem'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - inventory:reservations:read
    post:
      description: 'Creates a new reservation. For each of the items in the reservation, 1 unit of the corresponding product will be moved from the ''main'' stock location to the ''_customer_reservations'' stock location at the specified fulfillment location.


        Reservations are created in the ''RESERVED'' status by default, with an expiry date of 24 hours from when they have been created. The default duration of a reservation can by configured using the [Update Reservation Config](#/http/inventory/reservations/update-reservation-config) endpoint.


        **Important**: No stock is moved when a reservation expires. Stock is only moved back into the ''main'' stock location when the reservation is converted to a sale or the item is unreserved. See [Update Reservation Items](#/http/inventory/reservations/update-reservation-items).


        If you specify the reservation status to be ''PENDING'', no stock movements will occur, and the reservation will be shown as Pending in the Associate App. If a pending reservation is accepted, its status will change to ''RESERVED'' and the stock will be moved. If a pending reservation is declined, its status will change to ''REJECTED'' and no stock is moved.


        You can specify an external ID for a reservation (identifier of the reservation in an external system) by setting the Content-Type header of your request to `application/vnd.com.newstore.reservations+json; version=2` and including an `external_id` field in the body. If provided, `external_id` must be a string between 1 and 255 characters.'
      summary: createReservation
      tags:
      - reservations
      operationId: createReservation
      deprecated: false
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        description: A unique value that should be the same between retries of the request. If a request has previously been received with the same idempotency key, the ID of the existing reservation will be returned instead of creating a new one. We recommend using a UUID for this value.
        schema:
          type: string
          minLength: 1
      - name: Content-Type
        in: header
        required: false
        description: Use this to specify the version of the API to use. Possible values are `application/vnd.com.newstore.reservations+json; version=2` and `application/vnd.com.newstore.reservations+json; version=1`
        schema:
          type: string
          enum:
          - application/vnd.com.newstore.reservations+json; version=1
      responses:
        default:
          description: Default response
          headers: {}
        '201':
          description: Successful Response
          headers:
            Location:
              description: The ID of the created reservation.
              schema:
                type: string
          content:
            application/json:
              schema: {}
            application/problem+json:
              schema: {}
        '400':
          description: Validation Error
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - inventory:reservations:write
      requestBody:
        content:
          application/vnd.com.newstore.reservations+json; version=1:
            schema:
              $ref: '#/components/schemas/CreateReservationRequestV1'
  /inventory/reservations/{reservation_id}:
    get:
      description: 'Retrieves a single reservation by ID.


        The reservation status is derived from the status of its items as follows:

        - Any item is RESERVED => Reservation is RESERVED

        - Some items are CONVERTED to a sale or UNRESERVED => Reservation is CONVERTED

        - All items are UNRESERVED => Reservation is UNRESERVED, meaning the reservation has been cancelled'
      summary: showReservation
      tags:
      - reservations
      operationId: showReservation
      deprecated: false
      parameters:
      - name: reservation_id
        in: path
        required: true
        description: Reservation identifier.
        schema:
          type: string
          format: uuid
      - name: accept
        in: header
        required: false
        description: Use this to specify the version of the API to use. Possible values are `application/vnd.com.newstore.reservations+json; version=2` and `application/vnd.com.newstore.reservations+json; version=1`
        schema:
          type: string
          default: application/vnd.com.newstore.reservations+json; version=1
      responses:
        default:
          description: Default response
          headers: {}
        '200':
          description: Successful response
          headers: {}
          content:
            application/vnd.com.newstore.reservations+json; version=1:
              schema:
                $ref: '#/components/schemas/ReservationDetailsResponseV1'
            application/vnd.com.newstore.reservations+json; version=2:
              schema:
                $ref: '#/components/schemas/ReservationDetailsResponseV1'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ReservationDetailsResponseV1'
        '400':
          description: Validation Error
          headers: {}
          content:
            application/vnd.com.newstore.reservations+json; version=1:
              schema:
                $ref: '#/components/schemas/Problem'
            application/vnd.com.newstore.reservations+json; version=2:
              schema:
                $ref: '#/components/schemas/Problem'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/vnd.com.newstore.reservations+json; version=1:
              schema:
                $ref: '#/components/schemas/Problem'
            application/vnd.com.newstore.reservations+json; version=2:
              schema:
                $ref: '#/components/schemas/Problem'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/vnd.com.newstore.reservations+json; version=1:
              schema:
                $ref: '#/components/schemas/Problem'
            application/vnd.com.newstore.reservations+json; version=2:
              schema:
                $ref: '#/components/schemas/Problem'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/vnd.com.newstore.reservations+json; version=1:
              schema:
                $ref: '#/components/schemas/Problem'
            application/vnd.com.newstore.reservations+json; version=2:
              schema:
                $ref: '#/components/schemas/Problem'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/vnd.com.newstore.reservations+json; version=1:
              schema:
                $ref: '#/components/schemas/Problem'
            application/vnd.com.newstore.reservations+json; version=2:
              schema:
                $ref: '#/components/schemas/Problem'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - inventory:reservations:read
    patch:
      description: 'Updates the status of a ''PENDING'' reservation to either ''REJECTED'' or ''RESERVED''.


        If the status is changed to ''RESERVED'', stock for each item in the reservation will be moved from the ''main'' stock location to the ''_customer_reservations'' stock location and the expiry date will be reset. An email will be sent to the customer using the ''reservation_accepted_email'' template if the ''send_accepted_email'' [config](#/http/inventory/reservations/update-reservation-config) is enabled.


        If the status is changed to ''RESERVED'', no stock will be moved, and an email will be sent to the customer using the ''reservation_rejected_email'' template if the ''send_rejected_email'' [config](#/http/inventory/reservations/update-reservation-config) is enabled.


        **Important**: This endpoint can only be used to update the status of reservations in the ''PENDING'' status. All other status updates must be made at the item-level using the [Update Reservation Items](#/http/inventory/reservations/update-reservation-items) endpoint.'
      summary: updateReservation
      tags:
      - reservations
      operationId: updateReservation
      deprecated: false
      parameters:
      - name: reservation_id
        in: path
        required: true
        description: Unique identifier of the reservation
        schema:
          type: string
          format: uuid
      - name: Content-Type
        in: header
        required: false
        description: ''
        schema:
          type: string
          enum:
          - application/json
      responses:
        default:
          description: Default response
          headers: {}
        '204':
          description: Successful Response
          headers: {}
        '400':
          description: Validation Error
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: The reservation was not found.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: An attempt was made to perform an invalid status update.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - inventory:reservations:write
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReservationUpdate'
        required: true
  /inventory/reservations/{reservation_id}/items:
    patch:
      description: 'Updates the status of a reservation''s items.


        Items start in the ''RESERVED'' status, and can only be updated to ''CONVERTED'' or ''UNRESERVED''. ''CONVERTED'' and ''UNRESERVED'' are both terminal states; You cannot change or update the status of items with these statuses.


        Updating the status of a RESERVED item will cause 1 unit of the corresponding product to be moved from the ''_customer_reservations'' stock location to the ''main'' stock location at the fulfillment location associated with the reservation.


        When setting an item''s status to ''CONVERTED'', you can provide an optional ''cart_id'' which indicates  cart that the reserved products were added to. If this cart results in a purchase, a link to the corresponding order will be displayed alongside the item in the reservation details page in Omnichannel Manager. See [this guide](https://docs.newstore.com/v1/docs/monitoring-reservations).


        **Important**: This endpoint cannot be used to update the status of items currently in a ''PENDING'' reservation. To do this, use the [Update Reservation](#/http/inventory/reservations/update-reservation) endpoint instead.'
      summary: updateReservationItems
      tags:
      - reservations
      operationId: updateReservationItems
      deprecated: false
      parameters:
      - name: reservation_id
        in: path
        required: true
        description: Unique identifier of the reservation
        schema:
          type: string
          format: uuid
      - name: Content-Type
        in: header
        required: false
        description: ''
        schema:
          type: string
          enum:
          - application/json
      responses:
        default:
          description: Default response
          headers: {}
        '204':
          description: Successful Response
          headers: {}
        '400':
          description: Validation Error
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: The reservation or one or more of the reservation items was not found.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: An attempt was made to update the status of an item in a terminal state.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - inventory:reservations:write
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/ReservationItemUpdate'
              maxItems: 500
        required: true
components:
  schemas:
    ReservationConfigUpdate:
      title: ReservationConfigUpdate
      type: object
      properties:
        expires_in_min:
          description: Default duration for reservations, in minutes.
          type: integer
          minimum: 1.0
          format: int32
        send_accepted_emails:
          description: Whether to send emails to customers when a pending reservation is accepted by a store.
          type: boolean
        send_rejected_emails:
          description: Whether to send emails to customers when a pending reservation is rejected by a store.
          type: boolean
    ReservationStatus:
      title: ReservationStatus
      description: The status of a reservation.
      type: string
      enum:
      - PENDING
      - REJECTED
      - RESERVED
      - CONVERTED
      - UNRESERVED
    ReservationDetailsResponseV1:
      title: ReservationDetailsResponseV1
      type: object
      properties:
        associate_id:
          description: ID of the associate assigned to the reservation
          type: string
        created_at:
          description: Date and time the reservation was created
          type: string
          format: date-time
        customer_profile_id:
          description: Profile ID of the customer the reservation is for
          type: string
        expires_at:
          description: Date and time the reservation expires
          type: string
          format: date-time
        external_id:
          description: Short, human-readable identifier for the reservation
          type: string
        id:
          description: Unique identifier for the reservation
          type: string
          format: uuid
        items:
          description: Items associated with the reservation
          type: array
          items:
            $ref: '#/components/schemas/ReservationItemDetailsResponse'
          maxItems: 500
        location_id:
          description: ID of the fulfillment location the reservation is for
          type: string
        status:
          type: object
          allOf:
          - $ref: '#/components/schemas/ReservationStatus'
          - description: The status of a reservation.
        updated_at:
          description: Date and time the reservation was updated
          type: string
          format: date-time
      required:
      - associate_id
      - created_at
      - customer_profile_id
      - expires_at
      - external_id
      - id
      - items
      - location_id
      - status
      - updated_at
    InitialReservationStatus:
      title: InitialReservationStatus
      description: 'Initial status of the reservation. If PENDING then the reservation will need to be confirmed by a store

        associate before the stock is reserved.'
      type: string
      enum:
      - PENDING
      - RESERVED
    ReservationSummaryResponseV1:
      title: ReservationSummaryResponseV1
      type: object
      properties:
        associate_id:
          description: ID of the associate that created the reservation
          type: string
        created_at:
          description: Date and time the reservation was created
          type: string
          format: date-time
        customer_profile_id:
          description: Pr

# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/newstore/refs/heads/main/openapi/newstore-reservations-api-openapi.yml