Skip to content
ShopentlyLearn

Create an inventory delivery

Create an inventory delivery using Shopently API. Check required JSON fields, permissions and write requirements. Examples in cURL, PHP and Python.

POST/api/v1/inventory/deliveries

Authentication
Bearer
Available from
STANDARD
Required permissions
inventory.stock_delivery:create

Code examples

Request example

cURL

: "${SHOPENTLY_SHOP_URL:?}"

curl --disable --globoff --fail-with-body --silent --show-error \
  --proto '=https' --connect-timeout 5 --max-time 30 \
  --request POST \
  --header "Authorization: Bearer ${SHOPENTLY_ACCESS_TOKEN:?}" \
  --header 'Idempotency-Key: example-create_delivery_api_v1_inventory_deliveries_post' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "delivered_at": "2026-01-01T00:00:00Z",
  "location_id": "example",
  "quantity": 1,
  "status": "planned",
  "target_id": "example",
  "target_type": "product",
  "warehouse_id": "example"
}' \
  --url "${SHOPENTLY_SHOP_URL%/}"/api/v1/inventory/deliveries

PHP

<?php
declare(strict_types=1);

$baseUrl = rtrim(getenv('SHOPENTLY_SHOP_URL') ?: '', '/');
$origin = parse_url($baseUrl);
if (!$origin || ($origin['scheme'] ?? '') !== 'https' || empty($origin['host']) ||
    isset($origin['user'], $origin['pass']) || isset($origin['user']) || isset($origin['path']) ||
    isset($origin['query']) || isset($origin['fragment'])) {
    throw new RuntimeException('SHOPENTLY_SHOP_URL must be an HTTPS origin');
}
$credential = getenv('SHOPENTLY_ACCESS_TOKEN') ?: '';
if ($credential === '' || strpbrk($credential, "\r\n") !== false) {
    throw new RuntimeException('Invalid credential');
}
$headers = ['Idempotency-Key: example-create_delivery_api_v1_inventory_deliveries_post', 'Content-Type: application/json'];
$headers[] = 'Authorization: Bearer ' . $credential;
$responseHeaders = [];
$handle = curl_init($baseUrl . '/api/v1/inventory/deliveries');
curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_PROTOCOLS => CURLPROTO_HTTPS,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_SSL_VERIFYHOST => 2,
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HEADERFUNCTION => static function ($handle, string $line) use (&$responseHeaders): int {
        if (str_contains($line, ':')) {
            [$name, $value] = explode(':', $line, 2);
            $responseHeaders[strtolower(trim($name))] = trim($value);
        }
        return strlen($line);
    },
]);
curl_setopt($handle, CURLOPT_POSTFIELDS, '{
  "delivered_at": "2026-01-01T00:00:00Z",
  "location_id": "example",
  "quantity": 1,
  "status": "planned",
  "target_id": "example",
  "target_type": "product",
  "warehouse_id": "example"
}');
$raw = curl_exec($handle);
$status = curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
$error = curl_error($handle);
curl_close($handle);
if ($raw === false) {
    throw new RuntimeException('Transport error: ' . $error);
}
if ($status < 200 || $status >= 300) {
    throw new RuntimeException('HTTP ' . $status . '; request_id=' .
        ($responseHeaders['x-request-id'] ?? '') . '; retry_after=' . ($responseHeaders['retry-after'] ?? ''));
}
$result = $raw === '' ? null : json_decode($raw, true, 512, JSON_THROW_ON_ERROR | JSON_BIGINT_AS_STRING);
echo json_encode($result, JSON_THROW_ON_ERROR | JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE), PHP_EOL;

Python

from contextlib import ExitStack
import json
import os
from urllib.parse import urlsplit

import requests  # python -m pip install requests

base_url = os.environ["SHOPENTLY_SHOP_URL"].rstrip("/")
origin = urlsplit(base_url)
if origin.scheme != "https" or not origin.hostname or origin.username or origin.password or origin.path or origin.query or origin.fragment:
    raise ValueError("SHOPENTLY_SHOP_URL must be an HTTPS origin")
credential = os.environ['SHOPENTLY_ACCESS_TOKEN']
if not credential or "\r" in credential or "\n" in credential:
    raise ValueError("Invalid credential")
headers = {'Idempotency-Key': 'example-create_delivery_api_v1_inventory_deliveries_post'}
headers["Authorization"] = 'Bearer' + " " + credential
body = '{\n  "delivered_at": "2026-01-01T00:00:00Z",\n  "location_id": "example",\n  "quantity": 1,\n  "status": "planned",\n  "target_id": "example",\n  "target_type": "product",\n  "warehouse_id": "example"\n}'
if body is not None:
    headers["Content-Type"] = "application/json"

with ExitStack() as stack:
    session = stack.enter_context(requests.Session())
    files = None
    if False:
        image = stack.enter_context(open(os.environ["SHOPENTLY_IMAGE_FILE"], "rb"))
        if os.fstat(image.fileno()).st_size > 5242880:
            raise ValueError("Image exceeds 5 MiB")
        files = {"file": ("article.png", image, "image/png")}
    response = session.request(
        'POST', base_url + '/api/v1/inventory/deliveries', headers=headers,
        data=body.encode("utf-8") if body is not None else None, files=files,
        timeout=(5, 30), allow_redirects=False,
    )
    if not 200 <= response.status_code < 300:
        raise RuntimeError(f"HTTP {response.status_code}; request_id={response.headers.get('X-Request-ID', '')}; retry_after={response.headers.get('Retry-After', '')}")
    if False:
        if response.headers.get("Content-Type") != "image/webp" or len(response.content) > 5242880:
            raise ValueError("Unexpected image response")
        with open(os.environ["SHOPENTLY_OUTPUT_FILE"], "xb") as output:
            output.write(response.content)
    else:
        result = response.json() if response.content else None
        print(json.dumps(result, ensure_ascii=False, indent=2))

Response example 201

JSON
{
  "data": {
    "deleted": false,
    "id": "example",
    "version": 1
  },
  "meta": {
    "request_id": "example"
  }
}

How it works

  • A delivery identifies a product or variant, warehouse, location, quantity, date and status.
  • Choose planned or received explicitly and set increases_stock according to the intended stock effect.
  • Creating a received delivery can change stock, so the required conditional inventory permission must also be granted.
  • Retry the same logical delivery with the original idempotency key to avoid recording it twice.
  • Read stock_applied_at and current stock when reconciling results.

Parameters

Request headers

Idempotency-KeyStringRequired

Unique identifier for one logical write operation.

minLength: 1maxLength: 128
Constraints
pattern
"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
Example: "example-create_delivery_api_v1_inventory_deliveries_post"

Request body

application/json · Required

DeliveryCreate
delivered_atStringRequired

Delivery date and time.

format: "date-time"
Example: "2026-01-01T00:00:00Z"
increases_stockBooleanOptional

Whether receipt of the delivery increases stock.

Default: true
location_idStringRequired

Warehouse location identifier.

Constraints
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
Example: "example"
notesStringOptional

Additional notes.

maxLength: 2000
Default: ""
quantityIntegerRequired

Number of units.

minimum: 1maximum: 2147483647
Example: 1
reasonStringOptional

Reason recorded for the change.

maxLength: 500
Default: ""
statusStringRequired

Status accepted by this specific operation.

Constraints
enum
["planned", "received"]
Example: "planned"
target_idStringRequired

Identifier of the product or variant affected by the operation.

Constraints
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
Example: "example"
target_typeStringRequired

Whether the operation concerns a product or a variant.

Constraints
enum
["product", "variant"]
Example: "product"
warehouse_idStringRequired

Warehouse identifier.

Constraints
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
Example: "example"

Responses

Response 201

dataMutationData Required

Successful response payload.

Fields · data
deletedBooleanRequired

Whether the deletion was applied.

idStringRequired

Resource identifier; preserve it as returned.

versionInteger nullRequired

Resource version used for concurrency control.

metaContextPageMeta ContextMeta PageMeta RequestMeta Required

Response metadata.

Fields · meta

ContextPageMeta

localeStringRequired

Language selected for this request.

market_codeStringRequired

Market code returned by the context endpoint.

market_idStringRequired

Market identifier returned by the context endpoint.

paginationPagination Required

Cursor pagination metadata.

request_idStringRequired

Request identifier; in response metadata this identifies the HTTP request.

minLength: 1maxLength: 100

ContextMeta

localeStringRequired

Language selected for this request.

market_codeStringRequired

Market code returned by the context endpoint.

market_idStringRequired

Market identifier returned by the context endpoint.

request_idStringRequired

Request identifier; in response metadata this identifies the HTTP request.

minLength: 1maxLength: 100

PageMeta

paginationPagination Required

Cursor pagination metadata.

request_idStringRequired

Request identifier; in response metadata this identifies the HTTP request.

minLength: 1maxLength: 100

RequestMeta

request_idStringRequired

Request identifier; in response metadata this identifies the HTTP request.

minLength: 1maxLength: 100
Response example

HTTP status

201
Resource created Schema
400
Invalid request
401
Authentication required
403
Permission denied
404
Resource not found
409
Version conflict
422
Validation failed
429
Rate limit exceeded
Other HTTP statuses (7)
405
Method not allowed
413
Request too large
415
Unsupported media type
500
Server error
502
API gateway error
503
Service unavailable
504
Gateway timeout

Error catalog: ErrorResponse

Headers

201

LocationStringOptional

Relative URL of the created resource.

401

WWW-AuthenticateStringOptional

Authentication scheme required by the server.

405

AllowStringOptional

HTTP methods supported by this resource.

429, 503

Retry-AfterIntegerOptional

Minimum delay before retrying, in seconds.

minimum: 0