POST orders¶

Create a new order.

Endpoint¶

POST https://dropday.io/api/v1/orders

Parameters¶

Field	Type	Description
external_id	String	The external order number. We recommend that each order should have a unique order number.
source	String	The source of the order. Usually the webshop name.
test `optional`	Boolean	Set this to true to make this order a test order. If not provided, it will not be considered a test order.
total	Number	The total amount of the order.
shipping `optional`	Object	Additional shipping information for the order.
name `optional`	String	The name of the shipping provider (e.g., "UPS").
description `optional`	String	Description of the shipping method (e.g., "Standard delivery").
cost `optional`	Number	The shipping cost.
note `optional`	String	Additional notes or instructions for delivery.
delivery_date `optional`	String	Expected delivery date (format: DD-MM-YYYY).
email `optional`	String	The email address of the receiver.
shipping_address	Object	The shipping address for the order.
first_name	String	The firstname of the shipping address.
last_name	String	The lastname of the shipping address.
company_name `optional`	String	The company name of the shipping address.
address1	String	The street and housenumber of the shipping address.
address2 `optional`	String	Additional information about the shipping address, like apartment number.
postcode	String	The postcode of the shipping address.
city	String	The city of the shipping address.
state `optional`	String	The state of the shipping address.
country `optional`	String	The country of the shipping address (free text). Optional if `country_iso` is provided.
country_iso `optional`	String	ISO 3166-1 alpha-2 country code (e.g. "NL", "US", "GB"). If provided without `country`, the country name is derived from this code.
phone `optional`	Number	The phone of the shipping address.
products	Object[]	Object with information about the products in the order (Array of Objects).
external_id	String	The id of the product bought.
ean13 `optional`	Number	The EAN of the product bought.
name	String	The name or description of the product bought.
reference `optional`	String	The reference or SKU of the product bought.
quantity	Number	The quantity of the product bought.
stock_quantity `optional`	Number	The quantity of the product bought.
price	Number	The price of the product bought.
purchase_price `optional`	Number	The price that you agreed on with your supplier/vendor
height `optional`	Number	The height of the product.
width `optional`	Number	The width of the product.
length `optional`	Number	The length of the product.
weight `optional`	Number	The weight of the product.
image_url `optional`	String	The url of the image of the product bought.
brand `optional`	String	The brand of the product bought.
category `optional`	String	The category of the product bought.
supplier `optional`	String	The supplier of the product bought.
custom `optional`	Object	An object where you can add any key-value pair.
labels `optional`	String[]	An array of free-text labels for this order line (e.g. "fragile", "gift"). Each label max 255 characters.

Provide country, country_iso, or both. If only country_iso is sent, country is derived from it. If both are sent, each is stored as given. Omitting both, or sending an invalid ISO code, returns a validation error.

Request¶

{
    "external_id": "L41223D",
    "source": "Example Shop Dot Org",
    "test": false,
    "total": 435.45,
    "shipping_cost": 4.95,
    "shipping": {
        "name": "DHL Group",
        "description": "Standard delivery",
        "cost": 4.95,
        "note": "Please not at the neighbor, the dogs eat the packages",
        "delivery_date": "07-11-2025"
    },
    "email": "[email protected]",
    "shipping_address":
    {
        "first_name": "John",
        "last_name": "Doe",
        "company_name": "Jeff",
        "address1": "Jumpstreet 23",
        "postcode": "4500",
        "city": "LA",
        "country": "United States",
        "country_iso": "US",
        "phone": "222 222"
    },
    "products": [
    {
        "external_id": "1",
        "ean13": "87235211235464",
        "name": "Pizza margerita",
        "reference": "PZZA00001",
        "quantity": 2,
        "stock_quantity": 424,
        "price": 10.99,
        "purchase_price": 5.95,
        "height": 2.5,
        "width": 30,
        "length": 30,
        "weight": 0.45,
        "image_url": "https://example.org/pizza.jpg",
        "brand": "Italian",
        "category": "Pizzas",
        "supplier": "Mario",
        "custom":
        {
            "toppings": "onions, olives",
            "customer_message": "No ananas/pineapple"
        },
        "labels": ["fragile", "gift"]
    },
    {
        "external_id": "2",
        "ean13": "07235211235464",
        "reference": "COKE",
        "name": "Coca Cola",
        "quantity": 2,
        "stock_quantity": 34,
        "price": 2.50,
        "height": 22,
        "width": 6.5,
        "length": 6.5,
        "weight": 0.35,
        "image_url": "https://example.org/cola.jpg",
        "brand": "Coca Cola",
        "category": "Drinks",
        "supplier": "The Coca Cola Company",
        "custom":
        {
            "customer_message": "No ice"
        }
    }]
}

curl -X POST "https://dropday.io/api/v1/orders" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "api-key: tdh7nNUp3DZAHsMtw3dQYhDsm3wf593hMGbyXP6Y5R8DTF2Rwy4QCvkWFYQb" \
  -H "account-id: 101" \
  -d '{
    "external_id": "L41223D",
    "source": "Example Shop Dot Org",
    "test": false,
    "total": 435.45,
    "shipping_cost": 4.95,
    "shipping": {
        "name": "DHL Group",
        "description": "Standard delivery",
        "cost": 4.95,
        "note": "Please not at the neighbor, the dogs eat the packages",
        "delivery_date": "07-11-2025"
    },
    "email": "[email protected]",
    "shipping_address": {
        "first_name": "John",
        "last_name": "Doe",
        "company_name": "Jeff",
        "address1": "Jumpstreet 23",
        "postcode": "4500",
        "city": "LA",
        "country": "United States",
        "country_iso": "US",
        "phone": "222 222"
    },
    "products": [
        {
            "external_id": "1",
            "ean13": "87235211235464",
            "name": "Pizza margerita",
            "reference": "PZZA00001",
            "quantity": 2,
            "stock_quantity": 424,
            "price": 10.99,
            "purchase_price": 5.95,
            "height": 2.5,
            "width": 30,
            "length": 30,
            "weight": 0.45,
            "image_url": "https://example.org/pizza.jpg",
            "brand": "Italian",
            "category": "Pizzas",
            "supplier": "Mario",
            "custom": {
                "toppings": "onions, olives",
                "customer_message": "No ananas/pineapple"
            },
            "labels": ["fragile", "gift"]
        },
        {
            "external_id": "2",
            "ean13": "07235211235464",
            "reference": "COKE",
            "name": "Coca Cola",
            "quantity": 2,
            "stock_quantity": 34,
            "price": 2.50,
            "height": 22,
            "width": 6.5,
            "length": 6.5,
            "weight": 0.35,
            "image_url": "https://example.org/cola.jpg",
            "brand": "Coca Cola",
            "category": "Drinks",
            "supplier": "The Coca Cola Company",
            "custom": {
                "customer_message": "No ice"
            }
        }
    ]
}'

Response¶

200422401500

{
    "message": "Order created",
    "reference": 98
}

A duplicate external_id for the same user/project is also 422, not a successful create.

{
    "message": "Errors",
    "errors": {
        "external_id": [
            "The external id field is required."
        ],
        "shipping_address.firstname": [
            "The shipping address.firstname field is required."
        ],
        "products.0.external_id": [
            "The products.0.external_id field is required."
        ]
    }
}

{
    "message": "Unauthorized",
    "error": "Invalid or missing api-key or account-id header"
}

{
    "message": "Internal Server Error",
    "error": "An unexpected error occurred. Please try again later."
}