Create Draft Consignment

This API is used to create a draft consignment. Draft consignments are used when all information is not yet ready or when you want to save it for processing later.

Endpoint Information

What is a Draft Consignment?

Draft consignments differ from regular consignments in the following ways:

When to Use?

• When package information is not yet known
• When bulk consignment entry will be made
• When consignment information needs to be completed later
• When you want to create a consignment record when an order is received and process it after packaging

Request Parameters

Basic Parameters

Sender Information

Recipient Information

Package Information (Optional)

Package information is optional for draft consignments. It can be added later in the Update Draft or Process stage.

Package Content Information (Optional)

Document Information (Optional)

Special Services Information (Optional)

Example Usage

Minimal Draft Creation (Address Information Only)

curl -X POST "{{BASE_URL}}/api/v1/consignments/draft" \
  -H "Content-Type: application/json" \
  -H "APIKEY: {{APIKEY}}" \
  -d '{
    "provider_id": 7,
    "preference": 0,
    "consignor": {
        "name": "Sender Company Inc.",
        "country": "TR",
        "state": "İstanbul",
        "city": "Kadıköy",
        "postal_code": "34758",
        "address": "Moda Caddesi No:1",
        "phone_number": "+902161234567",
        "email": "info@company.com"
    },
    "consignee": {
        "name": "Hans Mueller",
        "country": "DE",
        "state": "Hamburg",
        "city": "Altona",
        "postal_code": "22765",
        "address": "Beispielstraße 123",
        "phone_number": "+4940123456",
        "email": "hans@example.de"
    }
}'

<?php
$client = new \GuzzleHttp\Client();

$response = $client->request('POST', '{{BASE_URL}}/api/v1/consignments/draft', [
    'headers' => [
        'Content-Type' => 'application/json',
        'APIKEY' => '{{APIKEY}}'
    ],
    'json' => [
        'provider_id' => 7,
        'preference' => 0,
        'consignor' => [
            'name' => 'Sender Company Inc.',
            'country' => 'TR',
            'state' => 'İstanbul',
            'city' => 'Kadıköy',
            'postal_code' => '34758',
            'address' => 'Moda Caddesi No:1',
            'phone_number' => '+902161234567',
            'email' => 'info@company.com'
        ],
        'consignee' => [
            'name' => 'Hans Mueller',
            'country' => 'DE',
            'state' => 'Hamburg',
            'city' => 'Altona',
            'postal_code' => '22765',
            'address' => 'Beispielstraße 123',
            'phone_number' => '+4940123456',
            'email' => 'hans@example.de'
        ]
    ]
]);

$body = json_decode($response->getBody(), true);

// Store the draft ID - will be used for processing later
$draftId = $body['data']['id'];
$draftUuid = $body['data']['uuid'];

print_r($body);

<?php
$payload = [
    'provider_id' => 7,
    'preference' => 0,
    'consignor' => [
        'name' => 'Sender Company Inc.',
        'country' => 'TR',
        'state' => 'İstanbul',
        'city' => 'Kadıköy',
        'postal_code' => '34758',
        'address' => 'Moda Caddesi No:1',
        'phone_number' => '+902161234567',
        'email' => 'info@company.com'
    ],
    'consignee' => [
        'name' => 'Hans Mueller',
        'country' => 'DE',
        'state' => 'Hamburg',
        'city' => 'Altona',
        'postal_code' => '22765',
        'address' => 'Beispielstraße 123',
        'phone_number' => '+4940123456',
        'email' => 'hans@example.de'
    ]
];

$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => '{{BASE_URL}}/api/v1/consignments/draft',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'APIKEY: {{APIKEY}}'
    ]
]);

$response = curl_exec($ch);
$result = json_decode($response, true);

// Store the draft ID
$draftId = $result['data']['id'];

curl_close($ch);

Full Draft Creation (Including Package Information)

{
    "provider_id": 7,
    "preference": 0,
    "incoterms_type": 2,
    "reference_no": "ORDER-2024-001",
    "consignor": {
        "name": "Sender Company Inc.",
        "country": "TR",
        "state": "İstanbul",
        "city": "Kadıköy",
        "postal_code": "34758",
        "address": "Moda Caddesi No:1",
        "phone_number": "+902161234567",
        "tax_number": "1234567890"
    },
    "consignee": {
        "name": "Hans Mueller",
        "country": "DE",
        "state": "Hamburg",
        "city": "Altona",
        "postal_code": "22765",
        "address": "Beispielstraße 123",
        "phone_number": "+4940123456"
    },
    "packages": [
        {
            "package_type": 1,
            "post_type": 4,
            "weight": 1.5,
            "length": 30,
            "width": 20,
            "height": 15,
            "dangerous_goods": false,
            "items": [
                {
                    "description": "Electronic Device",
                    "gtip": "854370900000",
                    "origin": "TR",
                    "currency_code": "EUR",
                    "unit_price": 150.00,
                    "quantity": 1
                }
            ]
        }
    ]
}

API Response

Successful Response

{
    "status": true,
    "message": "Draft consignment created",
    "data": {
        "id": 242,
        "uuid": "aa203bc1-c2f0-46c3-a635-f59abccd1c4a",
        "provider_id": 7,
        "preference": 0,
        "barcode": null,
        "reference_no": null,
        "invoice_number": null,
        "status": 24,
        "status_message": "New draft",
        "weight": 0,
        "desi": 0,
        "consignor": {
            "name": "Sender Company Inc.",
            "attention_name": null,
            "country": "Turkey",
            "country_iso3": "TUR",
            "state": "İstanbul",
            "city": "Kadıköy",
            "address": "Moda Caddesi No:1",
            "postal_code": "34758",
            "phone": "+902161234567",
            "email": "info@company.com"
        },
        "consignee": {
            "name": "Hans Mueller",
            "attention_name": null,
            "country": "Germany",
            "country_iso3": "DEU",
            "state": "Hamburg",
            "city": "Altona",
            "address": "Beispielstraße 123",
            "postal_code": "22765",
            "phone": "+4940123456",
            "email": "hans@example.de"
        },
        "packages": [],
        "documents": [],
        "special_services": [],
        "consignment_type": 2,
        "incoterms_type": 2,
        "specific_shipping_method": null,
        "specific_provider_barcode": null,
        "created_at": "2025-05-07 18:14:45",
        "updated_at": "2025-05-07 18:14:45"
    }
}

Response Fields

Error Responses

{
    "status": false,
    "errors": [
        {
            "message": "reference_no: Reference number \"ORDER-2024-001\" has already been used. Please provide a unique reference number."
        }
    ]
}

Common Error Scenarios

Next Steps

After creating a draft consignment:

1. Update: Complete missing information with Update Draft
2. Process: When all information is complete, activate the consignment with Process Draft
3. Delete: You can delete the draft if needed