Inventory_batches

>>>

GET /api/shopify/inventory_batches
List of inventory batches based on pagination, search, and filter (by variant ID or location ID or both).

In the response, the custom fields batch_name, batch_number, barcode, invoice_number and description are returned nested under the metadata object of each batch, not as top-level attributes.

Errors

Code Description
401 The provided token is invalid

Examples

// invalid token
GET /api/shopify/inventory_batches?location_id=1000&variant_id=2000&page=1&search=Inventory+Batch
401
HTTP Token: Access denied.

// valid token
GET /api/shopify/inventory_batches?location_id=1000&variant_id=2000&page=1&search=Inventory+Batch
200
[
  {
    "id": 4037,
    "quantity": 55,
    "expired_at": null,
    "expiry_date": "2023-07-13 05:48:06 UTC",
    "received_date": "2023-07-03 05:48:06 UTC",
    "metadata": {
      "batch_name": "Inventory Batch"
    },
    "created_at": "2023-07-03 05:48:06 UTC",
    "updated_at": "2023-07-03 05:48:06 UTC",
    "notified_at": null,
    "discounted": false,
    "location_id": 1000,
    "variant_id": 2000
  }
]

Params

Param name Description
location_id
optional

Shopify location ID

Validations:

  • Must be a Integer
variant_id
optional

Shopify variant ID

Validations:

  • Must be a Integer
page
optional

Page number

Validations:

  • Must be a Integer
search
optional

Search by inventory batch batch_name, batch_number, barcode, invoice_number description or product title or variant title or barcode

Validations:

  • Must be a String

Headers

Header name Description
Authorization
required 		Bearer token
>>>

GET /api/shopify/inventory_batches/:id
Show inventory batch

In the response, the custom fields batch_name, batch_number, barcode, invoice_number and description are returned nested under the metadata object of the batch, not as top-level attributes.

Errors

Code Description
401 The provided token is invalid
404 Record not found

Examples

// valid token
GET /api/shopify/inventory_batches/4029
200
{
  "id": 4029,
  "quantity": 55,
  "expired_at": null,
  "expiry_date": "2023-07-13 05:48:05 UTC",
  "received_date": "2023-07-03 05:48:05 UTC",
  "metadata": {
    "batch_name": "Inventory Batch"
  },
  "created_at": "2023-07-03 05:48:05 UTC",
  "updated_at": "2023-07-03 05:48:05 UTC",
  "notified_at": null,
  "discounted": false,
  "location_id": 1000,
  "variant_id": 2000
}
// invalid id
GET /api/shopify/inventory_batches/4031
404
Record not found
// invalid token
GET /api/shopify/inventory_batches/4032
401
HTTP Token: Access denied.

Params

Param name Description
id
required

Inventory batch ID

Validations:

  • Must be a Integer

Headers

Header name Description
Authorization
required 		Bearer token
>>>

POST /api/shopify/inventory_batches
Create inventory batch

In the response, the custom fields batch_name, batch_number, barcode, invoice_number and description are returned nested under the metadata object of the batch, not as top-level attributes (see the example below).

Errors

Code Description
401 The provided token is invalid
422 Could not process parameters

Examples

Request:

POST /api/shopify/inventory_batches
{
  "enable_shopify_sync": true,
  "inventory_batch": {
    "location_id": 63066407088,
    "variant_id": 44519466369200,
    "quantity": 55,
    "batch_name": "Strawberry Jam March",
    "batch_number": "SJ-2024-03",
    "barcode": "0123456789012",
    "invoice_number": "INV-1042",
    "description": "March restock",
    "received_date": "2024-03-01",
    "expiry_date": "2024-09-01"
  }
}

Response (201) - batch_name, batch_number, barcode, invoice_number and
description are returned under the "metadata" object, not at the top level:

{
  "id": 4041,
  "quantity": 55,
  "expired_at": null,
  "expiry_date": "2024-09-01 00:00:00 UTC",
  "received_date": "2024-03-01 00:00:00 UTC",
  "metadata": {
    "batch_name": "Strawberry Jam March",
    "batch_number": "SJ-2024-03",
    "barcode": "0123456789012",
    "invoice_number": "INV-1042",
    "description": "March restock"
  },
  "created_at": "2024-03-01 05:48:06 UTC",
  "updated_at": "2024-03-01 05:48:06 UTC",
  "notified_at": null,
  "discounted": false,
  "location_id": 63066407088,
  "variant_id": 44519466369200
}

// invalid params
POST /api/shopify/inventory_batches
inventory_batch[quantity]=55
422
Location must exist and Variant must exist
// invalid token
POST /api/shopify/inventory_batches
enable_shopify_sync=true&inventory_batch[location_id]=1000&inventory_batch[variant_id]=2000&inventory_batch[quantity]=55&inventory_batch[batch_name]=batch_name&inventory_batch[batch_number]=batch_number&inventory_batch[barcode]=barcode&inventory_batch[invoice_number]=invoice_number&inventory_batch[description]=description&inventory_batch[received_date]=2023-07-03
401
HTTP Token: Access denied.

// valid token and params
POST /api/shopify/inventory_batches
enable_shopify_sync=true&inventory_batch[location_id]=1000&inventory_batch[variant_id]=2000&inventory_batch[quantity]=55&inventory_batch[batch_name]=batch_name&inventory_batch[batch_number]=batch_number&inventory_batch[barcode]=barcode&inventory_batch[invoice_number]=invoice_number&inventory_batch[description]=description&inventory_batch[received_date]=2023-07-03
201
{
  "id": 4041,
  "quantity": 55,
  "expired_at": null,
  "expiry_date": null,
  "received_date": "2023-07-03 00:00:00 UTC",
  "metadata": {
    "batch_name": "batch_name",
    "batch_number": "batch_number",
    "barcode": "barcode",
    "invoice_number": "invoice_number",
    "description": "description"
  },
  "created_at": "2023-07-03 05:48:06 UTC",
  "updated_at": "2023-07-03 05:48:06 UTC",
  "notified_at": null,
  "discounted": false,
  "location_id": 1000,
  "variant_id": 2000
}

Params

Param name Description
enable_shopify_sync
optional

Whether to apply a Shopify inventory adjustment for this change. Accepted values: true or false. Can be sent at the top level or nested under inventory_batch. Note: the app preference “Batch quantities added or adjusted on Freshly are reflected in Shopify” is a master switch. When that preference is OFF, this parameter has no effect and no Shopify inventory adjustment occurs. When the preference is ON, passing true applies an inventory adjustment at the batch’s location; passing false or omitting the parameter leaves Shopify inventory unchanged.

Validations:

  • Must be one of: true, false, 1, 0.
inventory_batch
optional

Validations:

  • Must be a Hash
inventory_batch[location_id]
required

Shopify location ID

Validations:

  • Must be a Integer
inventory_batch[variant_id]
required

Shopify variant ID

Validations:

  • Must be a Integer
inventory_batch[quantity]
required

Inventory batch quantity

Validations:

  • Must be a Integer
inventory_batch[enable_shopify_sync]
optional

Alternative placement of the top-level enable_shopify_sync parameter (either location is accepted; see enable_shopify_sync above for semantics)

Validations:

  • Must be one of: true, false, 1, 0.
inventory_batch[batch_name]
optional

Inventory batch name (returned under metadata in the response)

Validations:

  • Must be a String
inventory_batch[batch_number]
optional

Inventory batch number (returned under metadata in the response)

Validations:

  • Must be a String
inventory_batch[barcode]
optional

Inventory batch barcode (returned under metadata in the response)

Validations:

  • Must be a String
inventory_batch[invoice_number]
optional

Inventory batch invoice number (returned under metadata in the response)

Validations:

  • Must be a String
inventory_batch[description]
optional

Inventory batch description (returned under metadata in the response)

Validations:

  • Must be a String
inventory_batch[received_date]
optional

Inventory batch received date (YYYY-MM-DD, or any ISO 8601 date/time)

Validations:

  • Must be a String
inventory_batch[expiry_date]
optional

Inventory batch expiry date; same format as received_date (YYYY-MM-DD, or any ISO 8601 date/time)

Validations:

  • Must be a String

Headers

Header name Description
Authorization
required 		Bearer token
>>>

PUT /api/shopify/inventory_batches/:id
Update inventory batch

In the response, the custom fields batch_name, batch_number, barcode, invoice_number and description are returned nested under the metadata object of the batch, not as top-level attributes (see the example below).

Errors

Code Description
401 The provided token is invalid
404 Record not found
422 Could not process parameters

Examples

Request:

PUT /api/shopify/inventory_batches/4025
{
  "inventory_batch": {
    "location_id": 63066407088,
    "variant_id": 44519466369200,
    "quantity": 56,
    "batch_number": "SJ-2024-03",
    "expiry_date": "2024-09-01"
  }
}

Response (200) - batch_name, batch_number, barcode, invoice_number and
description are returned under the "metadata" object, not at the top level:

{
  "id": 4025,
  "quantity": 56,
  "expired_at": null,
  "expiry_date": "2024-09-01 00:00:00 UTC",
  "received_date": "2024-03-01 00:00:00 UTC",
  "metadata": {
    "batch_name": "Strawberry Jam March",
    "batch_number": "SJ-2024-03"
  },
  "created_at": "2024-03-01 05:48:05 UTC",
  "updated_at": "2024-03-05 09:12:44 UTC",
  "notified_at": null,
  "discounted": false,
  "location_id": 63066407088,
  "variant_id": 44519466369200
}

// valid token and params
PUT /api/shopify/inventory_batches/4025
inventory_batch[quantity]=56&inventory_batch[location_id]=1000&inventory_batch[variant_id]=2000
200
{
  "id": 4025,
  "quantity": 56,
  "expired_at": null,
  "expiry_date": "2023-07-13 05:48:05 UTC",
  "received_date": "2023-07-03 05:48:05 UTC",
  "metadata": {
    "batch_name": "Inventory Batch"
  },
  "created_at": "2023-07-03 05:48:05 UTC",
  "updated_at": "2023-07-03 05:48:05 UTC",
  "notified_at": null,
  "discounted": false,
  "location_id": 1000,
  "variant_id": 2000
}
// invalid params
PUT /api/shopify/inventory_batches/4026
inventory_batch[quantity]=56
422
Location must exist and Variant must exist
// invalid id
PUT /api/shopify/inventory_batches/100
inventory_batch[quantity]=56&inventory_batch[location_id]=1000&inventory_batch[variant_id]=2000
404
Record not found
// invalid token
PUT /api/shopify/inventory_batches/4028
inventory_batch[location_id]=1000&inventory_batch[variant_id]=2000&inventory_batch[quantity]=56&inventory_batch[batch_name]=batch_name&inventory_batch[batch_number]=batch_number&inventory_batch[barcode]=barcode&inventory_batch[invoice_number]=invoice_number&inventory_batch[description]=description&inventory_batch[received_date]=2023-07-03
401
HTTP Token: Access denied.

Params

Param name Description
enable_shopify_sync
optional

Whether to apply a Shopify inventory adjustment for this change. Accepted values: true or false. Can be sent at the top level or nested under inventory_batch. Note: the app preference “Batch quantities added or adjusted on Freshly are reflected in Shopify” is a master switch. When that preference is OFF, this parameter has no effect and no Shopify inventory adjustment occurs. When the preference is ON, passing true applies an inventory adjustment at the batch’s location; passing false or omitting the parameter leaves Shopify inventory unchanged.

Validations:

  • Must be one of: true, false, 1, 0.
inventory_batch
optional

Validations:

  • Must be a Hash
inventory_batch[location_id]
required

Shopify location ID

Validations:

  • Must be a Integer
inventory_batch[variant_id]
required

Shopify variant ID

Validations:

  • Must be a Integer
inventory_batch[quantity]
required

Inventory batch quantity

Validations:

  • Must be a Integer
inventory_batch[enable_shopify_sync]
optional

Alternative placement of the top-level enable_shopify_sync parameter (either location is accepted; see enable_shopify_sync above for semantics)

Validations:

  • Must be one of: true, false, 1, 0.
inventory_batch[batch_name]
optional

Inventory batch name (returned under metadata in the response)

Validations:

  • Must be a String
inventory_batch[batch_number]
optional

Inventory batch number (returned under metadata in the response)

Validations:

  • Must be a String
inventory_batch[barcode]
optional

Inventory batch barcode (returned under metadata in the response)

Validations:

  • Must be a String
inventory_batch[invoice_number]
optional

Inventory batch invoice number (returned under metadata in the response)

Validations:

  • Must be a String
inventory_batch[description]
optional

Inventory batch description (returned under metadata in the response)

Validations:

  • Must be a String
inventory_batch[received_date]
optional

Inventory batch received date (YYYY-MM-DD, or any ISO 8601 date/time)

Validations:

  • Must be a String
inventory_batch[expiry_date]
optional

Inventory batch expiry date; same format as received_date (YYYY-MM-DD, or any ISO 8601 date/time)

Validations:

  • Must be a String

Headers

Header name Description
Authorization
required 		Bearer token
>>>

DELETE /api/shopify/inventory_batches/:id
Delete inventory batch

Responds with a JSON object: {“message”: “Inventory batch deleted”} on success, or {“error”: “…”} with an appropriate HTTP status on failure.

Errors

Code Description
401 The provided token is invalid
404 Record not found

Examples

Response (200):

{ "message": "Inventory batch deleted" }

Response (404):

{ "error": "Record not found" }

// invalid id
DELETE /api/shopify/inventory_batches/100
404
{
  "error": "Record not found"
}
// valid token
DELETE /api/shopify/inventory_batches/4034
200
{
  "message": "Inventory batch deleted"
}
// invalid token
DELETE /api/shopify/inventory_batches/4035
401
HTTP Token: Access denied.

Params

Param name Description
id
required

Inventory batch ID

Validations:

  • Must be a Integer

Headers

Header name Description
Authorization
required 		Bearer token