Create order

curl --request POST \
  --url https://staging-v2.sparqle.tech/orders \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "locationId": "ABC123",
  "orderRef": "PADE3JWEA",
  "deliveryName": "Jane Doe",
  "deliveryAddress": {
    "street": "Gustav Mahlerlaan",
    "houseNumber": "320",
    "postalCode": "1082 ME",
    "countryCode": "NL",
    "suffix": "",
    "city": "Amsterdam"
  },
  "name": "iPod",
  "description": "ABC",
  "deliveryEmail": "[email protected]",
  "deliveryPhone": "+31612345678",
  "deliveryNote": "Please leave the package at the door when I am not home.",
  "isBusiness": false,
  "height": 120.5,
  "length": 200,
  "width": 75.5,
  "weight": 22.5,
  "pudoId": "9f83c1b0a4",
  "orderBundleId": "VNN1UY7TMSY81P8Q4A2C7"
}
'

import requests

url = "https://staging-v2.sparqle.tech/orders"

payload = {
    "locationId": "ABC123",
    "orderRef": "PADE3JWEA",
    "deliveryName": "Jane Doe",
    "deliveryAddress": {
        "street": "Gustav Mahlerlaan",
        "houseNumber": "320",
        "postalCode": "1082 ME",
        "countryCode": "NL",
        "suffix": "",
        "city": "Amsterdam"
    },
    "name": "iPod",
    "description": "ABC",
    "deliveryEmail": "[email protected]",
    "deliveryPhone": "+31612345678",
    "deliveryNote": "Please leave the package at the door when I am not home.",
    "isBusiness": False,
    "height": 120.5,
    "length": 200,
    "width": 75.5,
    "weight": 22.5,
    "pudoId": "9f83c1b0a4",
    "orderBundleId": "VNN1UY7TMSY81P8Q4A2C7"
}
headers = {
    "api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    locationId: 'ABC123',
    orderRef: 'PADE3JWEA',
    deliveryName: 'Jane Doe',
    deliveryAddress: {
      street: 'Gustav Mahlerlaan',
      houseNumber: '320',
      postalCode: '1082 ME',
      countryCode: 'NL',
      suffix: '',
      city: 'Amsterdam'
    },
    name: 'iPod',
    description: 'ABC',
    deliveryEmail: '[email protected]',
    deliveryPhone: '+31612345678',
    deliveryNote: 'Please leave the package at the door when I am not home.',
    isBusiness: false,
    height: 120.5,
    length: 200,
    width: 75.5,
    weight: 22.5,
    pudoId: '9f83c1b0a4',
    orderBundleId: 'VNN1UY7TMSY81P8Q4A2C7'
  })
};

fetch('https://staging-v2.sparqle.tech/orders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://staging-v2.sparqle.tech/orders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'locationId' => 'ABC123',
    'orderRef' => 'PADE3JWEA',
    'deliveryName' => 'Jane Doe',
    'deliveryAddress' => [
        'street' => 'Gustav Mahlerlaan',
        'houseNumber' => '320',
        'postalCode' => '1082 ME',
        'countryCode' => 'NL',
        'suffix' => '',
        'city' => 'Amsterdam'
    ],
    'name' => 'iPod',
    'description' => 'ABC',
    'deliveryEmail' => '[email protected]',
    'deliveryPhone' => '+31612345678',
    'deliveryNote' => 'Please leave the package at the door when I am not home.',
    'isBusiness' => false,
    'height' => 120.5,
    'length' => 200,
    'width' => 75.5,
    'weight' => 22.5,
    'pudoId' => '9f83c1b0a4',
    'orderBundleId' => 'VNN1UY7TMSY81P8Q4A2C7'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://staging-v2.sparqle.tech/orders"

	payload := strings.NewReader("{\n  \"locationId\": \"ABC123\",\n  \"orderRef\": \"PADE3JWEA\",\n  \"deliveryName\": \"Jane Doe\",\n  \"deliveryAddress\": {\n    \"street\": \"Gustav Mahlerlaan\",\n    \"houseNumber\": \"320\",\n    \"postalCode\": \"1082 ME\",\n    \"countryCode\": \"NL\",\n    \"suffix\": \"\",\n    \"city\": \"Amsterdam\"\n  },\n  \"name\": \"iPod\",\n  \"description\": \"ABC\",\n  \"deliveryEmail\": \"[email protected]\",\n  \"deliveryPhone\": \"+31612345678\",\n  \"deliveryNote\": \"Please leave the package at the door when I am not home.\",\n  \"isBusiness\": false,\n  \"height\": 120.5,\n  \"length\": 200,\n  \"width\": 75.5,\n  \"weight\": 22.5,\n  \"pudoId\": \"9f83c1b0a4\",\n  \"orderBundleId\": \"VNN1UY7TMSY81P8Q4A2C7\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://staging-v2.sparqle.tech/orders")
  .header("api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"locationId\": \"ABC123\",\n  \"orderRef\": \"PADE3JWEA\",\n  \"deliveryName\": \"Jane Doe\",\n  \"deliveryAddress\": {\n    \"street\": \"Gustav Mahlerlaan\",\n    \"houseNumber\": \"320\",\n    \"postalCode\": \"1082 ME\",\n    \"countryCode\": \"NL\",\n    \"suffix\": \"\",\n    \"city\": \"Amsterdam\"\n  },\n  \"name\": \"iPod\",\n  \"description\": \"ABC\",\n  \"deliveryEmail\": \"[email protected]\",\n  \"deliveryPhone\": \"+31612345678\",\n  \"deliveryNote\": \"Please leave the package at the door when I am not home.\",\n  \"isBusiness\": false,\n  \"height\": 120.5,\n  \"length\": 200,\n  \"width\": 75.5,\n  \"weight\": 22.5,\n  \"pudoId\": \"9f83c1b0a4\",\n  \"orderBundleId\": \"VNN1UY7TMSY81P8Q4A2C7\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://staging-v2.sparqle.tech/orders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"locationId\": \"ABC123\",\n  \"orderRef\": \"PADE3JWEA\",\n  \"deliveryName\": \"Jane Doe\",\n  \"deliveryAddress\": {\n    \"street\": \"Gustav Mahlerlaan\",\n    \"houseNumber\": \"320\",\n    \"postalCode\": \"1082 ME\",\n    \"countryCode\": \"NL\",\n    \"suffix\": \"\",\n    \"city\": \"Amsterdam\"\n  },\n  \"name\": \"iPod\",\n  \"description\": \"ABC\",\n  \"deliveryEmail\": \"[email protected]\",\n  \"deliveryPhone\": \"+31612345678\",\n  \"deliveryNote\": \"Please leave the package at the door when I am not home.\",\n  \"isBusiness\": false,\n  \"height\": 120.5,\n  \"length\": 200,\n  \"width\": 75.5,\n  \"weight\": 22.5,\n  \"pudoId\": \"9f83c1b0a4\",\n  \"orderBundleId\": \"VNN1UY7TMSY81P8Q4A2C7\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": 1,
  "orderId": "SPQ-10293",
  "orderRef": "PADE3JWEA",
  "status": "draft",
  "name": "iPod",
  "barcode": "3STBXX123456789",
  "pudoId": "9f83c1b0a4",
  "trackingUrl": "https://tracking.sparqle.com/barcode/3STBXX123456789",
  "deliveryName": "Jane Doe",
  "deliveryEmail": "[email protected]",
  "deliveryAddress": "Gustav Mahlerlaan 320, 1082 ME Amsterdam",
  "deliveryEta": "12:40 - 13:00",
  "deliveryEtaDate": "2026-08-13",
  "deliveryDate": "2026-08-13",
  "locationId": 1,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

{
  "statusCode": 400,
  "message": [
    "deliveryName should not be empty"
  ],
  "error": "Bad Request"
}

POST

orders

Create order

curl --request POST \
  --url https://staging-v2.sparqle.tech/orders \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "locationId": "ABC123",
  "orderRef": "PADE3JWEA",
  "deliveryName": "Jane Doe",
  "deliveryAddress": {
    "street": "Gustav Mahlerlaan",
    "houseNumber": "320",
    "postalCode": "1082 ME",
    "countryCode": "NL",
    "suffix": "",
    "city": "Amsterdam"
  },
  "name": "iPod",
  "description": "ABC",
  "deliveryEmail": "[email protected]",
  "deliveryPhone": "+31612345678",
  "deliveryNote": "Please leave the package at the door when I am not home.",
  "isBusiness": false,
  "height": 120.5,
  "length": 200,
  "width": 75.5,
  "weight": 22.5,
  "pudoId": "9f83c1b0a4",
  "orderBundleId": "VNN1UY7TMSY81P8Q4A2C7"
}
'

import requests

url = "https://staging-v2.sparqle.tech/orders"

payload = {
    "locationId": "ABC123",
    "orderRef": "PADE3JWEA",
    "deliveryName": "Jane Doe",
    "deliveryAddress": {
        "street": "Gustav Mahlerlaan",
        "houseNumber": "320",
        "postalCode": "1082 ME",
        "countryCode": "NL",
        "suffix": "",
        "city": "Amsterdam"
    },
    "name": "iPod",
    "description": "ABC",
    "deliveryEmail": "[email protected]",
    "deliveryPhone": "+31612345678",
    "deliveryNote": "Please leave the package at the door when I am not home.",
    "isBusiness": False,
    "height": 120.5,
    "length": 200,
    "width": 75.5,
    "weight": 22.5,
    "pudoId": "9f83c1b0a4",
    "orderBundleId": "VNN1UY7TMSY81P8Q4A2C7"
}
headers = {
    "api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    locationId: 'ABC123',
    orderRef: 'PADE3JWEA',
    deliveryName: 'Jane Doe',
    deliveryAddress: {
      street: 'Gustav Mahlerlaan',
      houseNumber: '320',
      postalCode: '1082 ME',
      countryCode: 'NL',
      suffix: '',
      city: 'Amsterdam'
    },
    name: 'iPod',
    description: 'ABC',
    deliveryEmail: '[email protected]',
    deliveryPhone: '+31612345678',
    deliveryNote: 'Please leave the package at the door when I am not home.',
    isBusiness: false,
    height: 120.5,
    length: 200,
    width: 75.5,
    weight: 22.5,
    pudoId: '9f83c1b0a4',
    orderBundleId: 'VNN1UY7TMSY81P8Q4A2C7'
  })
};

fetch('https://staging-v2.sparqle.tech/orders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://staging-v2.sparqle.tech/orders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'locationId' => 'ABC123',
    'orderRef' => 'PADE3JWEA',
    'deliveryName' => 'Jane Doe',
    'deliveryAddress' => [
        'street' => 'Gustav Mahlerlaan',
        'houseNumber' => '320',
        'postalCode' => '1082 ME',
        'countryCode' => 'NL',
        'suffix' => '',
        'city' => 'Amsterdam'
    ],
    'name' => 'iPod',
    'description' => 'ABC',
    'deliveryEmail' => '[email protected]',
    'deliveryPhone' => '+31612345678',
    'deliveryNote' => 'Please leave the package at the door when I am not home.',
    'isBusiness' => false,
    'height' => 120.5,
    'length' => 200,
    'width' => 75.5,
    'weight' => 22.5,
    'pudoId' => '9f83c1b0a4',
    'orderBundleId' => 'VNN1UY7TMSY81P8Q4A2C7'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://staging-v2.sparqle.tech/orders"

	payload := strings.NewReader("{\n  \"locationId\": \"ABC123\",\n  \"orderRef\": \"PADE3JWEA\",\n  \"deliveryName\": \"Jane Doe\",\n  \"deliveryAddress\": {\n    \"street\": \"Gustav Mahlerlaan\",\n    \"houseNumber\": \"320\",\n    \"postalCode\": \"1082 ME\",\n    \"countryCode\": \"NL\",\n    \"suffix\": \"\",\n    \"city\": \"Amsterdam\"\n  },\n  \"name\": \"iPod\",\n  \"description\": \"ABC\",\n  \"deliveryEmail\": \"[email protected]\",\n  \"deliveryPhone\": \"+31612345678\",\n  \"deliveryNote\": \"Please leave the package at the door when I am not home.\",\n  \"isBusiness\": false,\n  \"height\": 120.5,\n  \"length\": 200,\n  \"width\": 75.5,\n  \"weight\": 22.5,\n  \"pudoId\": \"9f83c1b0a4\",\n  \"orderBundleId\": \"VNN1UY7TMSY81P8Q4A2C7\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://staging-v2.sparqle.tech/orders")
  .header("api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"locationId\": \"ABC123\",\n  \"orderRef\": \"PADE3JWEA\",\n  \"deliveryName\": \"Jane Doe\",\n  \"deliveryAddress\": {\n    \"street\": \"Gustav Mahlerlaan\",\n    \"houseNumber\": \"320\",\n    \"postalCode\": \"1082 ME\",\n    \"countryCode\": \"NL\",\n    \"suffix\": \"\",\n    \"city\": \"Amsterdam\"\n  },\n  \"name\": \"iPod\",\n  \"description\": \"ABC\",\n  \"deliveryEmail\": \"[email protected]\",\n  \"deliveryPhone\": \"+31612345678\",\n  \"deliveryNote\": \"Please leave the package at the door when I am not home.\",\n  \"isBusiness\": false,\n  \"height\": 120.5,\n  \"length\": 200,\n  \"width\": 75.5,\n  \"weight\": 22.5,\n  \"pudoId\": \"9f83c1b0a4\",\n  \"orderBundleId\": \"VNN1UY7TMSY81P8Q4A2C7\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://staging-v2.sparqle.tech/orders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"locationId\": \"ABC123\",\n  \"orderRef\": \"PADE3JWEA\",\n  \"deliveryName\": \"Jane Doe\",\n  \"deliveryAddress\": {\n    \"street\": \"Gustav Mahlerlaan\",\n    \"houseNumber\": \"320\",\n    \"postalCode\": \"1082 ME\",\n    \"countryCode\": \"NL\",\n    \"suffix\": \"\",\n    \"city\": \"Amsterdam\"\n  },\n  \"name\": \"iPod\",\n  \"description\": \"ABC\",\n  \"deliveryEmail\": \"[email protected]\",\n  \"deliveryPhone\": \"+31612345678\",\n  \"deliveryNote\": \"Please leave the package at the door when I am not home.\",\n  \"isBusiness\": false,\n  \"height\": 120.5,\n  \"length\": 200,\n  \"width\": 75.5,\n  \"weight\": 22.5,\n  \"pudoId\": \"9f83c1b0a4\",\n  \"orderBundleId\": \"VNN1UY7TMSY81P8Q4A2C7\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": 1,
  "orderId": "SPQ-10293",
  "orderRef": "PADE3JWEA",
  "status": "draft",
  "name": "iPod",
  "barcode": "3STBXX123456789",
  "pudoId": "9f83c1b0a4",
  "trackingUrl": "https://tracking.sparqle.com/barcode/3STBXX123456789",
  "deliveryName": "Jane Doe",
  "deliveryEmail": "[email protected]",
  "deliveryAddress": "Gustav Mahlerlaan 320, 1082 ME Amsterdam",
  "deliveryEta": "12:40 - 13:00",
  "deliveryEtaDate": "2026-08-13",
  "deliveryDate": "2026-08-13",
  "locationId": 1,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

{
  "statusCode": 400,
  "message": [
    "deliveryName should not be empty"
  ],
  "error": "Bad Request"
}

Authorizations

api-key

string

header

required

Body

application/json

locationId

string

required

Pickup location the order is dispatched from.

Maximum string length: 20

Example:

"ABC123"

orderRef

string

required

Your own reference for the order. Keep it unique.

Maximum string length: 100

Example:

"PADE3JWEA"

deliveryName

string

required

Maximum string length: 100

Example:

"Jane Doe"

deliveryAddress

object

required

Show child attributes

name

string

Example:

"iPod"

description

string

Maximum string length: 100

Example:

"ABC"

deliveryEmail

string<email>

Example:

"[email protected]"

deliveryPhone

string

Maximum string length: 30

Example:

"+31612345678"

deliveryNote

string

Maximum string length: 100

Example:

"Please leave the package at the door when I am not home."

isBusiness

boolean

Example:

false

height

number

Height of the collo (mm).

Required range: x <= 1000

Example:

120.5

length

number

Length of the collo (mm).

Required range: x <= 1000

Example:

200

width

number

Width of the collo (mm).

Required range: x <= 1000

Example:

75.5

weight

number

Weight of the collo (g).

Required range: x <= 20000

Example:

22.5

pudoId

string

Deliver to this pickup point. Use the pudoId of a point returned by GET /pickup-points. The order is created with the carrier that serves that point, and is rejected when no pickup point delivery is available for the address.

Maximum string length: 100

Example:

"9f83c1b0a4"

orderBundleId

string

Attach this order to an existing delivery bundle. Omit it on the first order; the create response returns an orderBundle object whose bundleId you pass here on subsequent orders to group them as one multi-parcel shipment.

Maximum string length: 100

Example:

"VNN1UY7TMSY81P8Q4A2C7"

Response

Order created

integer

Example:

1

orderId

string

Example:

"SPQ-10293"

orderRef

string

Example:

"PADE3JWEA"

status

enum<string>

Available options:

draft,

expected,

in_transit,

out_for_delivery,

awaiting_next_attempt,

at_pickup_point,

completed,

failed,

in_return_transit,

returned,

cancelled,

rejected,

address_not_found,

inactive,

missing,

lost,

error

Example:

"draft"

name

string

Example:

"iPod"

barcode

string

Example:

"3STBXX123456789"

pudoId

string

Pickup point this order is delivered to, when there is one.

Example:

"9f83c1b0a4"

trackingUrl

string

Example:

"https://tracking.sparqle.com/barcode/3STBXX123456789"

deliveryName

string

Example:

"Jane Doe"

deliveryEmail

string

Example:

"[email protected]"

deliveryAddress

string

Example:

"Gustav Mahlerlaan 320, 1082 ME Amsterdam"

deliveryEta

string

Example:

"12:40 - 13:00"

deliveryEtaDate

string<date>

Example:

"2026-08-13"

deliveryDate

string

Example:

"2026-08-13"

locationId

integer

Example:

1

createdAt

string<date-time>

updatedAt

string<date-time>