Ενημέρωση παραγγελίας

Η κλήση PATCH /orders/{id} αλλάζει μια παραγγελία που δεν έχει ακόμα voucher. Στέλνετε μόνο τα πεδία που θέλετε να αλλάξουν.

WARNING

Θα πρέπει να συμπεριλάβετε το API Token σας σε κάθε αίτημα ως Bearer Token. Αντικαταστήστε το YOUR_TOKEN με το API Token του καταστήματος (chub_...). Δείτε το Overview.

Method	URI	Headers
PATCH	/api/v2/orders/{id}	Authorization: Bearer YOUR_TOKEN Content-Type: application/json

Κανόνες

• Μόνο ό,τι στέλνετε. Τα πεδία που δεν στέλνετε μένουν όπως είναι. Στο recipient στέλνετε μόνο τα υπο-πεδία που αλλάζουν (π.χ. μόνο recipient.address).
• Τα πεδία που στέλνετε δεν μπορούν να αδειάσουν. Τα υποχρεωτικά πεδία της δημιουργίας (order_number, recipient.*, payment_method) δεν δέχονται null ή κενό. Τα προαιρετικά courier_id, services, locker_id, cod_cost, shipping_cost, weight, notes δέχονται null για να καθαρίσουν (το courier_id: null γίνεται δεκτό μόνο μαζί με παραλαβή από κατάστημα).
• Ίδιοι κανόνες με τη δημιουργία. Κάθε πεδίο ελέγχεται όπως στο POST /orders, και οι κανόνες που συνδυάζουν πεδία ελέγχονται πάνω στην παραγγελία όπως θα γίνει (αποθηκευμένες τιμές μαζί με τις αλλαγές). Π.χ. ταχυδρομικός κώδικας 1010 απορρίπτεται για παραγγελία με αποθηκευμένη χώρα GR, και cod_cost απορρίπτεται αν η παραγγελία δεν είναι cod.
• Παραγγελίες από όλα τα καταστήματα. Μπορείτε να αλλάξετε κάθε παραγγελία του λογαριασμού σας (και παραγγελίες που ήρθαν από e-shop), με το token οποιουδήποτε καταστήματος. Η παραγγελία παραμένει στο κατάστημά της. Οι αλλαγές δεν στέλνονται πίσω στο e-shop.
• Παραγγελία με voucher. Αν η παραγγελία έχει voucher, η απάντηση είναι 409 order_has_shipment και δεν αλλάζει τίποτα.

Ομάδες πεδίων

Ξαναγράφονται μόνο οι ομάδες πεδίων που στείλατε. Έτσι, π.χ. μια αλλαγή στις notes μιας παραγγελίας από e-shop δεν ξαναϋπολογίζει τα ποσά της (που μπορεί να περιέχουν εκπτώσεις ή φόρους), ούτε αλλάζει την κατάσταση ή την courier της.

Ομάδα	Πεδία που την ενεργοποιούν	Τι γίνεται
Αποστολή	courier_id, receive_from_reception, services, locker_id	Ελέγχονται ξανά courier, Box Now locker_id και services με τις τελικές τιμές.
Ποσά	products, subtotal, shipping_cost, cod_cost, payment_method	Το total_amount ξαναϋπολογίζεται ως subtotal + shipping_cost + cod_cost.
Κατάσταση	status, receive_from_reception	receive_from_reception: true δίνει store_pickup. Με receive_from_reception: false μια παραγγελία παραλαβής από κατάστημα επιστρέφει σε pending.
Ταχυδρομικός κώδικας	recipient.postal_code, recipient.country	Ο κώδικας ελέγχεται ξανά με βάση τη χώρα.

Όταν στέλνετε οποιοδήποτε πεδίο της ομάδας Αποστολή, οι αποθηκευμένες τιμές που δεν ταιριάζουν πια με τη νέα κατάσταση της ομάδας καθαρίζονται σιωπηλά, χωρίς σφάλμα:

• receive_from_reception: true (παραλαβή από κατάστημα): το courier γίνεται null και καθαρίζονται τα αποθηκευμένα services και locker_id.
• Courier Box Now: καθαρίζονται τα αποθηκευμένα services (το αποθηκευμένο locker_id διατηρείται, αν δεν στείλετε νέο).
• Οποιαδήποτε άλλη courier (π.χ. αλλαγή από Box Now σε ACS): καθαρίζεται το αποθηκευμένο locker_id (τα αποθηκευμένα services διατηρούνται, αν δεν στείλετε νέα).

Σφάλμα 422 παίρνετε μόνο για τιμές που στέλνετε στο ίδιο αίτημα και δεν ταιριάζουν (π.χ. services μαζί με receive_from_reception: true ή με Box Now, locker_id με courier εκτός Box Now), ή αν λείπει κάτι υποχρεωτικό (π.χ. locker_id για Box Now, courier_id με receive_from_reception: false σε παραγγελία χωρίς courier).

Ειδικά για τα ποσά:

• Το products αντικαθιστά όλα τα προϊόντα της παραγγελίας. Αν δεν στείλετε και subtotal, το subtotal γίνεται το άθροισμα των νέων προϊόντων. Το products: [] αφαιρεί όλα τα προϊόντα (και μηδενίζει το subtotal, εκτός αν στείλετε subtotal).
• Αν αλλάξετε το payment_method από cod σε άλλο τρόπο πληρωμής, το cod_cost γίνεται 0.00 και το total_amount μειώνεται αντίστοιχα.
• Αν αλλάξετε ποσά σε παραγγελία e-shop, το total_amount υπολογίζεται με τον τύπο του CourierHub και χάνεται το σύνολο που είχε στείλει το e-shop. Στείλτε τότε και το subtotal που θέλετε.

Αλλαγή order_number

Μπορείτε να αλλάξετε το order_number, αρκεί να μην το χρησιμοποιεί άλλη (μη διαγραμμένη) παραγγελία του ίδιου καταστήματος, αλλιώς η απάντηση είναι 409 order_number_taken. Ο αριθμός της ίδιας της παραγγελίας δεν μετράει: π.χ. η 1001 μπορεί να γίνει #1001. Το order_id δεν αλλάζει ποτέ.

Μεταβλητές αποστολής

Variable Name	Type	Usage	Required
id	Integer	Το id της παραγγελίας, μέσα στο path του URL.	*
Πεδία παραγγελίας		Οποιοδήποτε από τα πεδία του POST /orders (order_number, status, order_date, recipient.*, receive_from_reception, courier_id, services, locker_id, payment_method, cod_cost, shipping_cost, subtotal, weight, notes, products), με τους ίδιους κανόνες. Όλα προαιρετικά.

Απάντηση αιτήματος

Επιτυχής ενημέρωση: HTTP 200 με την ενημερωμένη παραγγελία μέσα στο κλειδί data, με τα πεδία του GET /orders/{id} (μαζί με products και shipments).

Variable Name	Type	Description
data	Object	Η παραγγελία μετά την αλλαγή (order).
data.updated_at	String	Η στιγμή της αλλαγής (ISO 8601, UTC).

Παράδειγμα επιτυχημένης ενημέρωσης (διεύθυνση, τηλέφωνο και σημειώσεις).

Αίτημα:

{
    "recipient": {
        "address": "Ερμού 27",
        "phone": "+30 694 765 4321"
    },
    "notes": "Παράδοση μετά τις 17:00"
}

Απάντηση: τα υπόλοιπα στοιχεία του παραλήπτη, τα ποσά και τα προϊόντα δεν άλλαξαν.

{
    "data": {
        "id": 1,
        "order_id": "20261015101200482",
        "order_number": "#1001",
        "status": "pending",
        "status_label": "Εκκρεμής",
        "order_date": "2026-10-15T07:05:00Z",
        "recipient": {
            "name": "Μαρία Παπαδοπούλου",
            "phone": "+306947654321",
            "email": "maria@example.com",
            "address": "Ερμού 27",
            "city": "Αθήνα",
            "postal_code": "10563",
            "country": "GR"
        },
        "receive_from_reception": false,
        "courier": {
            "id": 8,
            "name": "ACS"
        },
        "services": [],
        "locker_id": null,
        "payment_method": "cod",
        "subtotal": "31.80",
        "shipping_cost": "3.50",
        "cod_cost": "1.50",
        "total_amount": "36.80",
        "weight": "1.200",
        "notes": "Παράδοση μετά τις 17:00",
        "has_shipment": false,
        "store": {
            "id": 1,
            "name": "Το Κατάστημά μου"
        },
        "products": [
            {
                "name": "Κούπα κεραμική",
                "sku": "MUG-01",
                "unit_price": "12.90",
                "quantity": 2,
                "total_price": "25.80"
            },
            {
                "name": "Σουβέρ (σετ 4)",
                "sku": null,
                "unit_price": "6.00",
                "quantity": 1,
                "total_price": "6.00"
            }
        ],
        "shipments": [],
        "created_at": "2026-10-15T07:12:00Z",
        "updated_at": "2026-10-15T08:12:00Z"
    }
}

Παράδειγμα: νέα προϊόντα και αλλαγή τρόπου πληρωμής.

Πρώτα αντικαθίστανται τα προϊόντα:

{
    "products": [
        { "name": "Κούπα κεραμική", "sku": "MUG-01", "unit_price": "12.90", "quantity": 3 }
    ]
}

Το subtotal γίνεται 38.70 και το total_amount 43.70 (38.70 + 3.50 + 1.50). Μετά η πληρωμή αλλάζει από αντικαταβολή σε τραπεζική κατάθεση:

{
    "payment_method": "bank_transfer"
}

Απάντηση: το cod_cost μηδενίζεται και το total_amount γίνεται 38.70 + 3.50.

{
    "data": {
        "id": 1,
        "order_id": "20261015101200482",
        "order_number": "#1001",
        "status": "pending",
        "status_label": "Εκκρεμής",
        "order_date": "2026-10-15T07:05:00Z",
        "recipient": {
            "name": "Μαρία Παπαδοπούλου",
            "phone": "+306947654321",
            "email": "maria@example.com",
            "address": "Ερμού 27",
            "city": "Αθήνα",
            "postal_code": "10563",
            "country": "GR"
        },
        "receive_from_reception": false,
        "courier": {
            "id": 8,
            "name": "ACS"
        },
        "services": [],
        "locker_id": null,
        "payment_method": "bank_transfer",
        "subtotal": "38.70",
        "shipping_cost": "3.50",
        "cod_cost": "0.00",
        "total_amount": "42.20",
        "weight": "1.200",
        "notes": "Παράδοση μετά τις 17:00",
        "has_shipment": false,
        "store": {
            "id": 1,
            "name": "Το Κατάστημά μου"
        },
        "products": [
            {
                "name": "Κούπα κεραμική",
                "sku": "MUG-01",
                "unit_price": "12.90",
                "quantity": 3,
                "total_price": "38.70"
            }
        ],
        "shipments": [],
        "created_at": "2026-10-15T07:12:00Z",
        "updated_at": "2026-10-15T08:12:00Z"
    }
}

Σφάλματα

HTTP	code	Πότε
404	not_found	Άγνωστο id, παραγγελία άλλου λογαριασμού ή διαγραμμένη παραγγελία.
409	order_has_shipment	Η παραγγελία έχει voucher. Δείτε παρακάτω.
409	order_number_taken	Το νέο order_number το χρησιμοποιεί άλλη παραγγελία του ίδιου καταστήματος.
422	validation_failed	Μη έγκυρα πεδία, ή υποχρεωτικό πεδίο με null / κενό.

Παραγγελία με voucher (order_has_shipment)

Μια παραγγελία δεν αλλάζει από τη στιγμή που έχει voucher: η courier έχει ήδη λάβει τη διεύθυνση και τα ποσά. Ως voucher μετράει κάθε μη διαγραμμένο voucher της παραγγελίας, ακόμα κι αν:

• εκδίδεται αυτή τη στιγμή (η έκδοση έχει ξεκινήσει αλλά η courier δεν έχει απαντήσει ακόμα): η παραγγελία εμφανίζεται ακόμα με has_shipment: false, αλλά η αλλαγή απορρίπτεται, γιατί η courier μπορεί να λαμβάνει ήδη τα στοιχεία της.
• η αποστολή φαίνεται ως cancelled στο GET /shipments, εφόσον το voucher δεν έχει διαγραφεί.

Για να αλλάξετε την παραγγελία, πρέπει πρώτα να ακυρωθεί (διαγραφεί) το voucher, με DELETE /shipments/{voucher} ή από το περιβάλλον πελάτη του CourierHub (δείτε Ακύρωση Voucher). Για να δείτε τα vouchers μιας παραγγελίας, χρησιμοποιήστε το shipments του GET /orders/{id} ή το GET /shipments?order_number=....

Η σειρά ελέγχων είναι: πρώτα η μορφή των πεδίων (422), μετά το voucher (409 order_has_shipment), μετά το order_number (409 order_number_taken) και τέλος οι κανόνες που συνδυάζουν πεδία (422).

Παραγγελία με voucher (409 Conflict).

{
    "message": "The order has a shipment (voucher). Cancel or delete the voucher first.",
    "code": "order_has_shipment"
}

Αριθμός παραγγελίας άλλης παραγγελίας (409 Conflict).

Αίτημα {"order_number": "#1003"}, ενώ υπάρχει η παραγγελία 1003 στο ίδιο κατάστημα:

{
    "message": "An order with this order_number already exists in this store.",
    "code": "order_number_taken"
}

Υποχρεωτικά πεδία με null (422).

Αίτημα {"recipient": {"name": null}, "payment_method": null}:

{
    "message": "The given data was invalid.",
    "code": "validation_failed",
    "errors": {
        "recipient.name": [
            "The recipient.name field is required."
        ],
        "payment_method": [
            "The payment method field is required."
        ]
    }
}

Κανόνες πάνω στην αποθηκευμένη παραγγελία (422).

Αίτημα {"recipient": {"postal_code": "1010"}, "cod_cost": "1.00"} σε παραγγελία με χώρα GR και πληρωμή bank_transfer:

{
    "message": "The given data was invalid.",
    "code": "validation_failed",
    "errors": {
        "cod_cost": [
            "The cod_cost field is only allowed when payment_method is cod."
        ],
        "recipient.postal_code": [
            "A Greek postal code has 5 digits."
        ]
    }
}

Άγνωστη παραγγελία (404).

{
    "message": "Resource not found.",
    "code": "not_found"
}

Παράδειγμα κλήσης

curl -X PATCH https://courierhub.gr/api/v2/orders/1 \
  -H "Authorization: Bearer chub_YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": { "address": "Ερμού 27" },
    "notes": "Παράδοση μετά τις 17:00"
  }'