OpenAPI Specification
swagger: '2.0'
info:
version: '1.0'
title: NewStore address reservations API
description: NewStore public APIs
contact:
email: support@newstore.com
name: NewStore API Support
url: https://developer.newstore.com
host: dodici-demo.p.newstore.net
basePath: /
schemes:
- https
consumes:
- application/json
produces:
- application/json
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
produces:
- application/json
- application/problem+json
parameters: []
responses:
default:
description: Default response
headers: {}
'200':
description: Successful Response
schema:
$ref: '#/definitions/ReservationConfigResponse'
headers: {}
'400':
description: Validation Error
schema:
$ref: '#/definitions/Problem'
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Problem'
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/Problem'
headers: {}
security:
- oauth:
- newstore:configuration:read
patch:
description: Updates the reservations configuration for the retailer.
summary: updateReservationConfig
tags:
- reservations
operationId: updateReservationConfig
deprecated: false
produces:
- application/problem+json
consumes:
- application/json
parameters:
- name: Content-Type
in: header
required: false
enum:
- application/json
type: string
description: ''
- name: body
in: body
required: true
description: ''
schema:
$ref: '#/definitions/ReservationConfigUpdate'
responses:
default:
description: Default response
headers: {}
'204':
description: Successful Response
headers: {}
'400':
description: Validation Error
schema:
$ref: '#/definitions/Problem'
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Problem'
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/Problem'
headers: {}
security:
- oauth:
- newstore:configuration:write
/inventory/reservations:
get:
description: Lists all reservations, supporting various filters.
summary: listReservations
tags:
- reservations
operationId: listReservations
deprecated: false
produces:
- application/vnd.com.newstore.reservations+json; version=1
- application/vnd.com.newstore.reservations+json; version=2
- application/problem+json
parameters:
- name: location_id
in: query
required: false
type: string
description: ID of the fulfillment location in which the reservations are being listed.
- name: status
in: query
required: false
type: array
maxItems: 5
uniqueItems: false
items:
type: string
enum:
- PENDING
- REJECTED
- RESERVED
- CONVERTED
- UNRESERVED
description: Status(es) of the reservations to list. If omitted, all reservation statuses are listed.
- name: external_id
in: query
required: false
type: string
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.
- name: display_id
in: query
required: false
type: string
description: Allows filtering the reservations by 'display_id'. A partial match is also considered a match. Only usable in V2 of the API.
- name: customer_profile_id
in: query
required: false
type: string
description: Allows filtering the reservations by customer profile id
- name: associate_id
in: query
required: false
type: string
description: Allows filtering the reservations by associate id
- name: offset
in: query
required: false
default: 0
type: integer
format: int32
minimum: 0.0
exclusiveMinimum: false
description: Page number to return
- name: count
in: query
required: false
default: 10
type: integer
format: int32
minimum: 1.0
maximum: 100.0
exclusiveMaximum: false
exclusiveMinimum: false
description: Number of results to return in each page
- name: sort
in: query
required: false
type: array
maxItems: 2
uniqueItems: false
items:
type: string
enum:
- created_at|asc
- created_at|desc
- status|asc
- status|desc
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.
- name: expired
in: query
required: false
type: boolean
description: Filter for expired reservations
- name: accept
in: header
required: false
default: application/vnd.com.newstore.reservations+json; version=1
type: string
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`
responses:
default:
description: Default response
headers: {}
'200':
description: Successful response
schema:
$ref: '#/definitions/ListReservationsResponseV1'
headers: {}
'400':
description: Validation Error
schema:
$ref: '#/definitions/Problem'
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Problem'
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/Problem'
headers: {}
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
produces:
- application/json
- application/problem+json
consumes:
- application/vnd.com.newstore.reservations+json; version=1
parameters:
- name: Idempotency-Key
in: header
required: true
type: string
minLength: 1
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.
- name: Content-Type
in: header
required: false
enum:
- application/vnd.com.newstore.reservations+json; version=1
type: string
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`
- name: body
in: body
required: false
description: ''
schema:
$ref: '#/definitions/CreateReservationRequestV1'
responses:
default:
description: Default response
headers: {}
'201':
description: Successful Response
schema: {}
headers:
Location:
description: The ID of the created reservation.
type: string
'400':
description: Validation Error
schema:
$ref: '#/definitions/Problem'
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Problem'
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/Problem'
headers: {}
security:
- oauth:
- inventory:reservations:write
/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
produces:
- application/vnd.com.newstore.reservations+json; version=1
- application/vnd.com.newstore.reservations+json; version=2
- application/problem+json
parameters:
- name: reservation_id
in: path
required: true
type: string
format: uuid
description: Reservation identifier.
- name: accept
in: header
required: false
default: application/vnd.com.newstore.reservations+json; version=1
type: string
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`
responses:
default:
description: Default response
headers: {}
'200':
description: Successful response
schema:
$ref: '#/definitions/ReservationDetailsResponseV1'
headers: {}
'400':
description: Validation Error
schema:
$ref: '#/definitions/Problem'
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Problem'
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/Problem'
headers: {}
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
produces:
- application/problem+json
consumes:
- application/json
parameters:
- name: reservation_id
in: path
required: true
type: string
format: uuid
description: Unique identifier of the reservation
- name: Content-Type
in: header
required: false
enum:
- application/json
type: string
description: ''
- name: body
in: body
required: true
description: ''
schema:
$ref: '#/definitions/ReservationUpdate'
responses:
default:
description: Default response
headers: {}
'204':
description: Successful Response
headers: {}
'400':
description: Validation Error
schema:
$ref: '#/definitions/Problem'
headers: {}
'404':
description: The reservation was not found.
schema:
$ref: '#/definitions/Problem'
headers: {}
'409':
description: An attempt was made to perform an invalid status update.
schema:
$ref: '#/definitions/Problem'
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Problem'
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/Problem'
headers: {}
security:
- oauth:
- inventory:reservations:write
/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
produces:
- application/problem+json
consumes:
- application/json
parameters:
- name: reservation_id
in: path
required: true
type: string
format: uuid
description: Unique identifier of the reservation
- name: Content-Type
in: header
required: false
enum:
- application/json
type: string
description: ''
- name: body
in: body
required: true
description: ''
schema:
type: array
items:
$ref: '#/definitions/ReservationItemUpdate'
maxItems: 500
responses:
default:
description: Default response
headers: {}
'204':
description: Successful Response
headers: {}
'400':
description: Validation Error
schema:
$ref: '#/definitions/Problem'
headers: {}
'404':
description: The reservation or one or more of the reservation items was not found.
schema:
$ref: '#/definitions/Problem'
headers: {}
'409':
description: An attempt was made to update the status of an item in a terminal state.
schema:
$ref: '#/definitions/Problem'
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Problem'
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/Problem'
headers: {}
security:
- oauth:
- inventory:reservations:write
definitions:
ReservationItemStatus:
title: ReservationItemStatus
description: The status of a reservation item.
type: string
enum:
- PENDING
- REJECTED
- RESERVED
- CONVERTED
- UNRESERVED
UpdatedReservationStatus:
title: UpdatedReservationStatus
type: string
enum:
- REJECTED
- 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: 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: '#/definitions/ReservationItemSummaryResponse'
maxItems: 500
location_id:
description: ID of the fulfillment location the reservation is for
type: string
reserved_item_count:
description: Number of items in the RESERVED state
type: integer
minimum: 0.0
format: int32
status:
type: object
allOf:
- $ref: '#/definitions/ReservationStatus'
- description: The status of a reservation.
required:
- associate_id
- created_at
- customer_profile_id
- expires_at
- external_id
- id
- items
- location_id
- reserved_item_count
- status
Problem:
title: Problem
type: object
properties:
detail:
description: A human readable explanation specific to this occurrence of the problem that is helpful to locate the problem and give advice on how to proceed. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.
example: some description for the error situation
type: string
error_code:
type: string
instance:
description: A URI reference that identifies the specific occurrence of the problem, e.g. by adding a fragment identifier or sub-path to the problem type. May be used to locate the root of this problem in the source code.
example: /some/uri-reference#specific-occurrence-context
type: string
message:
type: string
messages:
type: array
items:
type: string
request_id:
type: string
status:
description: The HTTP status code generated by the origin server for this occurrence of the problem.
type: integer
minimum: 100.0
maximum: 600.0
exclusiveMaximum: true
format: int32
title:
description: A short summary of the problem type. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.
example: some title for the error situation
type: string
type:
description: A URI reference that uniquely identifies the problem type only in the context of the provided API. Opposed to the specification in RFC-7807, it is neither recommended to be dereferenceable and point to a human-readable documentation nor globally unique for the problem type.
example: /some/uri-reference
type: string
default: about:blank
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
ReservationsPaginationInfo:
title: ReservationsPaginationInfo
type: object
properties:
count:
type: integer
minimum: 0.0
format: int32
offset:
type: integer
minimum: 0.0
format: int32
reserved_item_count:
description: Total number of reserved items.
type: integer
minimum: 0.0
format: int32
total:
description: Total number of items.
type: integer
minimum: 0.0
format: int32
required:
- total
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: '#/definitions/ReservationItemDetailsResponse'
maxItems: 500
location_id:
description: ID of the fulfillment location the reservation is for
type: string
status:
type: object
allOf:
- $ref: '#/definitions/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
ListReservationsResponseV1:
title: ListReservationsResponseV1
type: object
properties:
items:
description: List of reservations.
type: array
items:
$ref: '#/definitions/ReservationSummaryResponseV1'
maxItems: 100
pagination_info:
$ref: '#/definitions/ReservationsPaginationInfo'
required:
- items
- pagination_info
ReservationStatus:
title: ReservationStatus
description: The status of a reservation.
type: string
enum:
- PENDING
- REJECTED
- RESERVED
- CONVERTED
- UNRESERVED
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
UpdatedItemStatus:
title: UpdatedItemStatus
type: string
enum:
- CONVERTED
- UNRESERVED
ReservationConfigResponse:
title: ReservationConfigResponse
type: object
properties:
expires_in_min:
description: Duration of the reservation in minutes
type: integer
minimum: 0.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
required:
- expires_in_min
- send_accepted_emails
- send_rejected_emails
ReservationItemDetailsResponse:
title: ReservationItemDetailsResponse
type: object
properties:
cart_id:
description: ID of the cart in which the item was purchased during conversion
type: string
id:
description: Unique identifier for the reservation item
type: string
format: uuid
product_id:
description: ID of the product the reservation item corresponds to
type: string
status:
type: object
allOf:
- $ref: '#/definitions/ReservationItemStatus'
- description: The status of a reservation item.
updated_at:
description: Date and time the status of the item was updated
type: string
format: date-time
required:
- id
- product_id
- status
- updated_at
ReservationItemRequest:
title: ReservationItemRequest
type: object
properties:
product_id:
type: string
minLength: 1
required:
- product_id
ReservationItemUpdate:
title: ReservationItemUpdate
type: object
properties:
cart_id:
description: ID of the cart in which the item was purchased during conversion
type: string
id:
description: Unique identifier of the reservation item to update
type: string
format: uuid
status:
$ref: '#/definitions/UpdatedItemStatus'
required:
- id
- status
CreateReservationRequestV1:
title: CreateReservationRequestV1
example:
customer_profile_id: 7809c25e-630c-42d1-aa5d-f61388b97d74
items:
- product_id: p1
- product_id: p2
- product_id: p3
location_id: US01
type: object
properties:
associate_id:
description: 'ID of the associate who owns the reservation. If not provided, the associate ID present in the JWT will be used.
**Important**: if this method is called using an API client and the ''associate_id'' value is not provided, it will be set to null and the reservation won''t be linked to any associate.'
type: string
minLength: 1
customer_profile_id:
description: Profile ID of the customer the reservation is for
type: string
minLength: 1
expires_in_min:
description: "Duration of the reservation in minutes. If not provided, the default value is the [configured](#/http/inventory/reservations/replace-reservation-config) one \nor 1440 minutes (if there's no default configured)."
type: integer
minimum: 0.0
format: int32
items:
description: Items to reserve
type: array
items:
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/newstore/refs/heads/main/openapi/newstore-reservations-api-openapi.yml