Allocations & Reservations

Order Allocation Item Model

Properties

  • Name
    id
    Type
    string
    Required
    required
    Restrictions
    Description

    The inventory item ID.

  • Name
    quantity
    Type
    integer
    Required
    required
    Restrictions
    Description

    The quantity of the item in the allocation.

{
  "id": "inv_2MNiSi4jiDJMglxrFf0akgGFdj6",
  "quantity": 3
}

Order Allocation Model

Properties

  • Name
    id
    Type
    string,null
    Restrictions
    Description

    The ID for the allocation.

  • Name
    location
    Type
    object,null
    Restrictions
    Description
  • Name
    » id
    Type
    string
    Restrictions
    Description

    The ID of the location that the allocation is assigned to.

  • Name
    order
    Type
    object,null
    Restrictions
    Description
  • Name
    » id
    Type
    string
    Restrictions
    Description

    The ID of the order that this allocation relates to.

  • Name
    items
    Type
    array,null
    Restrictions
    Description
  • Name
    completed_at
    Type
    string(date-time)
    Restrictions
    Description

    A timestamp representing the time at which this allocation was marked as completed.

{
  "id": "alloc_2NiMwhLAPms2qhvq9sGhpaqShgZ",
  "location": {
    "id": "loc_2N8nMje6GOtjc7ce9AjkQHmkGJ0"
  },
  "order": {
    "id": "ord_2MnGzhX20IfDmIOSHb4JVY1XBRS"
  },
  "items": [
    {
      "id": "inv_2MNiSi4jiDJMglxrFf0akgGFdj6",
      "quantity": 3
    }
  ],
  "completed_at": "2023-02-28T20:00:42.815574Z"
}

Order Reservation Item Model

Properties

  • Name
    id
    Type
    string
    Restrictions
    Description

    The ID of the item.

  • Name
    quantity
    Type
    integer
    Restrictions
    Description

    The quantity of the item with this ID found in the specified order.

  • Name
    allocated_quantity
    Type
    integer
    Restrictions
    Description

    The quantity of the item with this ID found in the specified order that have been allocated to a location.

    This number will not exceed the quantity variable above.

{
  "id": "inv_2UtgnpHBpjcA1E1QE5THSJDoa6l",
  "quantity": 4,
  "allocated_quantity": 2
}

Order Reservation Model

Properties

  • Name
    order
    Type
    object
    Restrictions
    Description
  • Name
    » id
    Type
    string
    Restrictions
    Description

    The ID of the order.

  • Name
    items
    Type
    [[OrderReservationItem](#schemaorderreservationitem)]
    Restrictions
    Description

    [A record representing the ID and quantity of a given item that forms part of an order reservation.]

  • Name
    created_at
    Type
    string(date-time)
    Description
  • Name
    updated_at
    Type
    string(date-time)
    Description
{
  "order": {
    "id": "ord_2P6RjZARWwDuJrJ1Etk4nYf9ivh"
  },
  "items": [
    {
      "id": "inv_2UtgnpHBpjcA1E1QE5THSJDoa6l",
      "quantity": 4,
      "allocated_quantity": 2
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}
GET/allocations

Get Allocations

Retrieves a paginated set of allocations.

Query Parameters

  • Name
    location_id
    Type
    string
    Restrictions
    Description

    The unique ID for a location.

  • Name
    order_id
    Type
    array
    Restrictions
    Description

    One or more order IDs to return allocations for.

Request

GET
/allocations
curl --request GET \
--url https://api.envoy.one/allocations \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

Response

{
  "data": [
    {
      "id": "alloc_2NiMwhLAPms2qhvq9sGhpaqShgZ",
      "location": {
        "id": "loc_2N8nMje6GOtjc7ce9AjkQHmkGJ0"
      },
      "order": {
        "id": "ord_2MnGzhX20IfDmIOSHb4JVY1XBRS"
      },
      "items": [
        {
          "id": "inv_2MNiSi4jiDJMglxrFf0akgGFdj6",
          "quantity": 3
        }
      ],
      "completed_at": "2023-02-28T20:00:42.815574Z"
    }
  ],
  "next_cursor": "WyIyMDIzLTAzLTIxVDAwOjM1OjU5LjczMDYyMVoiXQ==",
  "previous_cursor": "WyIyMDIzLTAzLTE5VDA0OjI4OjAxLjQ4NDg5WiJd",
  "limit": 20
}

undefined

GET/allocations/orders/{order_id}

Get Allocations for Order

Retrieves the allocations associated with an order.

To understand the purpose of order allocations and how they work alongside inventory reservations, it is recommended that one reads the Order Reservations & Allocations article.

Path Parameters

  • Name
    order_id
    Type
    string
    Restrictions
    Description

    The order ID associated with the allocations.

Request

GET
/allocations/orders/{order_id}
curl --request GET \
--url https://api.envoy.one/allocations/orders/string \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

Response

{
  "data": [
    {
      "id": "alloc_2NiMwhLAPms2qhvq9sGhpaqShgZ",
      "location": {
        "id": "loc_2N8nMje6GOtjc7ce9AjkQHmkGJ0"
      },
      "order": {
        "id": "ord_2MnGzhX20IfDmIOSHb4JVY1XBRS"
      },
      "items": [
        {
          "id": "inv_2MNiSi4jiDJMglxrFf0akgGFdj6",
          "quantity": 3
        }
      ],
      "completed_at": "2023-02-28T20:00:42.815574Z"
    }
  ]
}

undefined

POST/allocations/orders/{order_id}

Create Order Allocations

Endpoint for creating order allocations. Each allocation is tied to a location, and contains a set of items that are designated for fulfilment from the specified location.

Each allocation can only contain one allocation item (i.e. an item ID and associated quantity).

In the event that the user has a use case where multiple allocation items referencing the same item is required (eg. the allocation specifies 3 red t-shirts, but only 2 are available for fulfilment), the following should occur:

  • The existing allocation item for the red t-shirts is decreased from 3 to 2, using the update endpoint.

  • A second allocation should be created for the same location, with 1 red t-shirt allocated

  • The first allocation can then be completed using the available stock.

  • The second allocation can be completed at a later date once the third t-shirt is available.

Path Parameters

  • Name
    order_id
    Type
    string
    Restrictions
    Description

    The order ID associated with the allocations.

Request

POST
/allocations/orders/{order_id}
curl --request POST \
--url https://api.envoy.one/allocations/orders/string \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"allocations":[{"location":{"id":"loc_2NDVMYM9Q5itESKOIAfJvx2FH8r"},"items":[{"id":"inv_2MNiSi4jiDJMglxrFf0akgGFdj6","quantity":2},{"id":"inv_2MNP5DWpneqTA8wQ5x9Jocrt4le","quantity":3}]},{"location":{"id":"loc_2N8nMje6GOtjc7ce9AjkQHmkGJ0"},"items":[{"id":"inv_2MNiSi4jiDJMglxrFf0akgGFdj6","quantity":1}]}]}'

Response

{
  "data": [
    {
      "id": "alloc_2NiMwhLAPms2qhvq9sGhpaqShgZ",
      "location": {
        "id": "loc_2N8nMje6GOtjc7ce9AjkQHmkGJ0"
      },
      "order": {
        "id": "ord_2MnGzhX20IfDmIOSHb4JVY1XBRS"
      },
      "items": [
        {
          "id": "inv_2MNiSi4jiDJMglxrFf0akgGFdj6",
          "quantity": 3
        }
      ],
      "completed_at": "2023-02-28T20:00:42.815574Z"
    }
  ]
}

undefined

DELETE/allocations/orders/{order_id}

Delete All Allocations for Order

Deletes all allocations associated with an order.

This will not affect order reservations, other than to reset the allocated quantity to zero.

Path Parameters

  • Name
    order_id
    Type
    string
    Restrictions
    Description

    The order ID associated with the allocations.

Request

DELETE
/allocations/orders/{order_id}
curl --request DELETE \
--url https://api.envoy.one/allocations/orders/string \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

undefined

PATCH/allocations/orders/{order_id}

Update Order Allocations

Update existing order allocations.

This endpoint can be used to modify the items and associated quantities in a given allocation, and to mark the allocation as completed.

Each allocation in the data array must contain the ID of an existing allocation that is to be modified. Attempting to create a new allocation using this endpoint will result in an error.

For more information on how allocations and reservations work, read the Order Reservations & Allocations article.

Path Parameters

  • Name
    order_id
    Type
    string
    Restrictions
    Description

    The order ID associated with the allocations.

Request

PATCH
/allocations/orders/{order_id}
curl --request PATCH \
--url https://api.envoy.one/allocations/orders/string \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"allocations":[{"id":"alloc_2NiMwhLAPms2qhvq9sGhpaqShgZ","items":[{"id":"inv_2MNiSi4jiDJMglxrFf0akgGFdj6","quantity":1},{"id":"inv_2MNP5DWpneqTA8wQ5x9Jocrt4le","quantity":3}]},{"id":"alloc_2NiMwk6JaHDzg5HkjsoSXAAzCui","location":{"id":"loc_2N8nMje6GOtjc7ce9AjkQHmkGJ0"},"items":[{"id":"inv_2MNiSi4jiDJMglxrFf0akgGFdj6","quantity":2}]}]}'

Response

{
  "data": [
    {
      "id": "alloc_2Nkv6rtjPv0HoUYvhV5AnLAG4xl",
      "order": {
        "id": "ord_2MnGzhX20IfDmIOSHb4JVY1XBRS"
      },
      "location": {
        "id": "loc_2NDVMYM9Q5itESKOIAfJvx2FH8r"
      },
      "items": [
        {
          "id": "inv_2MNiSi4jiDJMglxrFf0akgGFdj6",
          "quantity": 1
        },
        {
          "id": "inv_2MNP5DWpneqTA8wQ5x9Jocrt4le",
          "quantity": 3
        }
      ]
    },
    {
      "id": "alloc_2Nkv6kMb4FdGJFL48CIxLP0xWzE",
      "order": {
        "id": "ord_2MnGzhX20IfDmIOSHb4JVY1XBRS"
      },
      "location": {
        "id": "loc_2N8nMje6GOtjc7ce9AjkQHmkGJ0"
      },
      "items": [
        {
          "id": "inv_2MNiSi4jiDJMglxrFf0akgGFdj6",
          "quantity": 2
        }
      ]
    }
  ]
}

undefined

GET/reservations

Get Order Reservations

Retrieve reservations associated with an order.

Order reservations are automatically created when an order is created, or deleted when the order is deleted.

The purpose of an order reservation is to identify inventory that is in principle committed to existing orders. Order reservations are thus only made at the point whereby orders enter the committed state.

For more information, read the Order Reservations & Allocations article.

Request

GET
/reservations
curl --request GET \
--url https://api.envoy.one/reservations \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

Response

{
  "data": [
    {
      "order": {
        "id": "ord_2P6RjZARWwDuJrJ1Etk4nYf9ivh"
      },
      "items": [
        {
          "id": "inv_2UtgnpHBpjcA1E1QE5THSJDoa6l",
          "quantity": 4,
          "allocated_quantity": 2
        }
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ],
  "next_cursor": "string",
  "previous_cursor": "string",
  "limit": 0
}

undefined