API Integration

API integration is only available under the Platinum Plan

The Product Expiration Dates app provides an API that allows one to manage inventory batches programmatically.

API requests are authenticated using your shop's API key. You can find your API key on the General tab of the settings page. Include your API key in the X-API-Key header with each request.

Requests require you to specificy a product or variant identifer. This can be: sku, barcode, variant_id, or Product Expiration Date app ID.

Base URL

All API endpoints are relative to: https://apps.screenstaring.com/ed

GET /api/inventories/expiration_dates

Retrieve inventory batches for a product or variant. You can query by SKU, barcode, or Shopify variant ID

Query Parameters:

• sku - The variant's SKU (optional)
• barcode - The variant's barcode (optional)
• variant_id - Shopify variant ID; if a product has no variants use the default variant's ID (optional)
• external_location_id - Filter results by Shopify location ID (optional)

Example using curl:

curl -H "X-API-Key: YOUR_API_KEY" https://apps.screenstaring.com/ed/api/inventories/expiration_dates?sku=PRODUCT-SKU

Response (200 OK):

[
  {
    "id": 1,
    "expires": "2026-12-31",
    "quantity": 10,
    "batch_number": "BATCH-001",
    "location": {
      "id": 10,
      "external_id": "123456",
      "name": "Main Warehouse"
    },
    "inventory": {
      "id": 789,
      "sku": "PRODUCT-SKU",
      "variant_id": "456789",
      "product_id": "123456"
    }
  },
  {
    "id": 2,
    "expires": "2027-01-15",
    "quantity": 20,
    "batch_number": "BATCH-002",
    "location": {
      "id": 10,
      "external_id": "123456",
      "name": "Main Warehouse"
    },
    "inventory": {
      "id": 789,
      "sku": "PRODUCT-SKU",
      "variant_id": "456789",
      "product_id": "123456"
    }
  }
]

POST /api/inventories/expiration_dates

Create or update an inventory batch. Updates are based on the SKU/barcode combined with either: a) expiration date and location or b) batch number and location. Otherwise, a new batch is created.

Request Parameters:

• sku - The variant's SKU (optional)
• barcode - The variant's barcode (optional)
• variant_id - Shopify variant ID; if a product has no variants use the default variant's ID (optional)
• expires - Expiration date, must be in YYYY-MM-DD format (required)
• quantity - Quantity available (required)
• batch_number - Batch number (optional)
• external_location_id - The Shopify location ID (required if location_id not provided)
• location_id - Product Expiration Dates app ID (required if external_location_id not provided)
• inventory_batch_assignment_event - When to assign inventory batches to orders. Only valid when creating a product. Either "order_placed" or "order_item_fulfilled". If you're using Inventory Push this will always be "order_placed".
• invoice_number - Invoice number (optional)
• lot_number - Lot number (optional)
• manufactured_at - Manufacture date, must be in YYYY-MM-DD format (optional)
• received_at - Date received, must be in YYYY-MM-DD format (optional)
• comments - Free-form notes (optional)
• batch_unit_cost - Unit cost for the batch (optional)

Example using curl:

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" -d '{
    "sku": "PRODUCT-SKU",
    "expires": "2026-12-31",
    "quantity": 10,
    "batch_number": "BATCH-001",
    "id": "9876",
    "external_location_id": "123456"
  }' "https://apps.screenstaring.com/ed/api/inventories/expiration_dates"

Response (200 OK):

{
  "id": 1,
  "expires": "2026-12-31",
  "quantity": 10,
  "batch_number": "BATCH-001",
  "location": {
    "id": "9876",
    "external_id": "123456",
    "name": "Main Warehouse"
  },
  "inventory": {
    "id": 789,
    "sku": "PRODUCT-SKU",
    "variant_id": "456789",
    "product_id": "123456"
  }
}

PATCH /api/inventories/expiration_dates/:id

Update an existing inventory batch

URL Parameters:

• :id - The Product Expiration Dates app ID for the inventory batch (required)

Request Parameters:

• expires - Expiration date, must be in YYYY-MM-DD format (optional)
• quantity - Quantity available (optional)
• external_location_id - The Shopify location ID (optional)
• location_id - Product Expiration Dates app Location ID (optional)
• batch_number - Batch number (optional)
• invoice_number - Invoice number (optional)
• lot_number - Lot number (optional)
• manufactured_at - Manufacture date, must be in YYYY-MM-DD format (optional)
• received_at - Date received, must be in YYYY-MM-DD format (optional)
• comments - Free-form notes (optional)
• batch_unit_cost - Unit cost for the batch (optional)

Example using curl:

curl -X PATCH -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" -d '{
  "expires": "2027-01-15",
  "quantity": 20,
  "batch_number": "BATCH-002"
}' "https://apps.screenstaring.com/ed/api/inventories/expiration_dates/1"

Response (200 OK):

{
  "id": 1,
  "expires": "2027-01-15",
  "quantity": 20,
  "batch_number": "BATCH-002",
  "location": {
    "id": 10,
    "external_id": "123456",
    "name": "Main Warehouse"
  },
  "inventory": {
    "id": 789,
    "sku": "PRODUCT-SKU",
    "variant_id": "456789",
    "product_id": "123456"
  }
}

DELETE /api/inventories/expiration_dates/:id

Delete an inventory batch by its ID.

URL Parameters:

• :id - The Product Expiration Dates app ID for the inventory batch

Example using curl:

curl -X DELETE -H "X-API-Key: YOUR_API_KEY" https://apps.screenstaring.com/ed/api/inventories/expiration_dates/1

Response (200 OK):

{
  "id": 1,
  "expires": "2026-12-31",
  "quantity": 10,
  "batch_number": "BATCH-001",
  "location": {
    "id": 10,
    "external_id": "123456",
    "name": "Main Warehouse"
  },
  "inventory": {
    "id": 789,
    "sku": "PRODUCT-SKU",
    "variant_id": "456789",
    "product_id": "123456"
  }
}

Error Responses

The API returns appropriate HTTP status codes and error messages:

Status Code	Description	Example Response
400	Bad Request - Missing or invalid parameters	{"errors": ["param is missing or the value is empty: id"]}
401	Unauthorized - Invalid or missing API key	{"errors": ["Shop not found"]}
403	Forbidden - Plan does not allow API access	{"errors": ["API access not available for your subscription"]}
404	Not Found - Product, variant, or location not found	{"errors": ["Record not found"]}
422	Unprocessable Entity - Validation errors	{"errors": ["Quantity must be greater than 0"]}