Inventory

Overview of the Inventory resource and associated endpoints.

3 minute read

IMPORTANT

Sellers building integrations into Marketplacer should only use the current GraphQL-based Seller API, and not this (REST-based) API.

All future developments, including new features will be added to the the GraphQL-based Seller API only, more details on this API can be found here

Inventory represents the stock holding that a specific seller has for a multi-store advert variant. For instance, a parent seller might have an advert with two variants: “Blue / Small” and “Red / Large”; Seller A might hold 2 of the “Blue / Small” variant while Seller B holds 3 of the “Red / Large” variant. This would be represented by 2 inventory items:

Seller A, “Blue / Small”, 2 on hand
Seller B, “Red / Large”, 3 on hand

You can retrieve the seller IDs related to the multi-store using multi_store_memberships.

An inventory item can have a different price/sale price from the parent variant. It can also be configured to have infinite stock which never sells out.

This endpoint only deals with multi-store adverts. For single seller adverts, stock levels are set directly on the variant.

List a variant’s inventory items

Request

GET /api/v2/client/variants/1/inventories

Response

Status: 200 OK

{
  "data": [
    {
      "id": 1,
      "type": "inventories",
      "attributes": {
        "count_on_hand": 10,
        "price": "500",
        "sale_price": "450",
        "infinite": false,
        "seller_id": 1,
        "fulfilment_provider": "fulfilment_provider"
      }
    }
  ]
}

Updating a variant’s inventory

This route can be used by:

The multi-store parent to update or create multiple inventories
Members of the multi-store to update or create a single inventory record associated with their multi-store membership.

Request

PUT /api/v2/client/variants/1/inventories

Multi Store Owner / Parent Example

If you do not send a record for a seller who already has stock in the system, that seller’s stock will remain unchanged. To set a seller as having no stock, you must explicitly send a 0 value.

{
  "data": [
    {
      "type": "inventories",
      "attributes": {
        "count_on_hand": 10,
        "price": 500,
        "sale_price": 450,
        "seller_id": 1,
        "fulfilment_provider": "fulfilio"
      }
    },
    {
      "type": "inventories",
      "attributes": {
        "count_on_hand": 15,
        "seller_id": 2
      }
    },
    {
      "type": "inventories",
      "attributes": {
        "infinite": true,
        "seller_id": 3
      }
    }
  ]
}

Multi Store Owner / Parent Response

Status: 200 OK

{
  "data": [
    {
      "id": 1,
      "type": "inventories",
      "attributes": {
        "count_on_hand": 10,
        "price": "500",
        "sale_price": "450",
        "infinite": false,
        "seller_id": 1,
        "fulfilment_provider": "fulfilment_provider"
      }
    },
    {
      "id": 2,
      "type": "inventories",
      "attributes": {
        "count_on_hand": 15,
        "price": null,
        "sale_price": null,
        "infinite": false,
        "seller_id": 2,
        "fulfilment_provider": ""
      }
    },
    {
      "id": 3,
      "type": "inventories",
      "attributes": {
        "infinite": true,
        "seller_id": 3,
        "fulfilment_provider": ""
      }
    }
  ]
}

Multi Store Member / Child Example

This request will either update or create an Inventory associated with the member’s API key in the request. The owner of the API key will need to already be a member of the multi-store. The attributes must be submitted in an array, and the last element will be used to update the multi-store member’s inventory. All inventories will be returned.

{
  "data": [
    {
      "attributes": {
        "count_on_hand": 22,
        "price": 27.38,
        "sale_price": 21.99,
        "infinite": false,
        "fulfilment_provider": "fulfilment_provider"
      }
    }
  ]
}

Multi Store Member / Child Response

Status: 200 OK

{
  "data": [
    {
      "id": 1,
      "type": "inventories",
      "attributes": {
        "count_on_hand": 22,
        "price": "27.38",
        "sale_price": "21.99",
        "infinite": false,
        "seller_id": 1,
        "fulfilment_provider": "fulfilment_provider"
      }
    },
    {
      "id": 2,
      "type": "inventories",
      "attributes": {
        "count_on_hand": 15,
        "price": null,
        "sale_price": null,
        "infinite": false,
        "seller_id": 2,
        "fulfilment_provider": ""
      }
    },
    {
      "id": 3,
      "type": "inventories",
      "attributes": {
        "infinite": true,
        "seller_id": 3,
        "fulfilment_provider": ""
      }
    }
  ]
}

Deleting an inventory record

An inventory record with a 0 count_on_hand value is handled differently to a non-existent inventory record. The 0 value will show the seller in the store selector but disabled; a non-existent record means the seller won’t be shown at all in the store selector.

Request

DELETE /api/v2/client/variants/1/inventories/1

Reponse

Status: 204 No Content