Menu

Reservations API Routes

A reservation is unavailable quantity of an inventory item in a location.

A reservation is created automatically for variants in an order whose manage_inventory is enabled. Admin users can also create reservations manually.

These API routes allow admin users to manage reservations.

GET /admin/reservations#

List Reservations

Retrieve a list of reservations. The reservations can be filtered by fields such as id. The reservations can also be sorted or paginated.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.
offsetnumberOptional
The number of items to skip when retrieving a list.
limitnumberOptional
Limit the number of items returned in the list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
location_idstring | string[]Optional
Filter by a location's ID to retrieve its associated reservations.
inventory_item_idstring | string[]Optional
Filter by an inventory item's ID to retrieve its associated reservations.
line_item_idstring | string[]Optional
Filter by a line item's ID to retrieve its associated reservations.
created_bystring | string[]Optional
Filter by the ID of a user to retrieve the reservations they created.
descriptionstring | objectOptional
Filter by a reservation's description. This filter applies a full-text match. To search by keywords, use the q query parameter instead. Accepts the filter operators.
created_atobjectOptional
Filter by a reservation's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by a reservation's update date. Accepts the filter operators.
deleted_atobjectOptional
Filter by a reservation's deletion date. Accepts the filter operators.
with_deletedbooleanOptional
Whether to include deleted records in the result.
qstringOptional
Apply a search query on the reservation's searchable properties.
quantityobjectOptional
Filter by the reservation's quantity. Accepts the filter operators.

Request examples

Responses

200 OK

limitnumber
The maximum number of items returned.
offsetnumber
The number of items skipped before retrieving the returned items.
countnumber
The total number of items.
reservationsobject[]
The list of reservations.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/reservations#

Create Reservation

Create a reservation.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

line_item_idstringOptional
The ID of the line item this reservation is created for.
location_idstring
The ID of the location the quantity is reserved from.
inventory_item_idstring
The ID of the inventory item associated with the line item's variant.
quantitynumber
The reserved quantity.
descriptionstringOptional
The reservation's description.
metadataobjectOptional
The reservation's metadata, used to store custom key-value pairs. Learn more in the Manage Metadata section.

Request examples

Responses

200 OK

reservationobject
The reservation's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • reservation-item.created: Emitted when reservations are created.

GET /admin/reservations/{id}#

Get a Reservation

Retrieve a reservation by its ID. You can expand the reservation's relations or select the fields that should be returned.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The reservation's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request examples

Responses

200 OK

reservationobject
The reservation's details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/reservations/{id}#

Update a Reservation

Update a reservation's details.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The reservation's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

location_idstringOptional
The ID of the associated location.
quantitynumberOptional
The reserved quantity.
descriptionstringOptional
The reservation's description.
metadataobjectOptional
The reservation's metadata. Can hold custom key-value pairs. Learn more in the Manage Metadata section.

Request examples

Responses

200 OK

reservationobject
The reservation's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • reservation-item.updated: Emitted when reservations are updated.

DELETE /admin/reservations/{id}#

Delete a Reservation

Delete a reservation.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The reservation's ID.

Request examples

Responses

200 OK

idstring
The reservation's ID.
objectstring
The name of the deleted object.

Default: "reservation"

deletedboolean
Whether the reservation was deleted.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • reservation-item.deleted: Emitted when reservations are deleted.
Found a problem with this page?Report Issue
Edited Nov 14·Edit this page