Courier company integration

How the point-of-sale software reports the courier details and location of a courier company contracted by the business.

The platform does not operate couriers; the business delivers with its own courier or with a company it has contracted. If a contracted courier company makes the delivery, the courier details and location are written by the business's point-of-sale software. The business's key is not given to the courier company, and the company does not call these endpoints with its own credentials. The commercial relationship is between the business and the company; the platform only relays the information.

Endpoints on this page

Each row links to the full definition in the API reference — fields, response codes and the try-it console.

Flow

Read the order that is ready for delivery: on a restaurant, GET /orders?status=ready; on a Çarşı business, an order whose picking is closed (picking.completed: true). With webhooks, the order.updated event reports the change.
Report the courier: PUT /orders/{id}/courier. Resending updates the record; the assignedAt of the first write is kept.
When the courier departs, advance the status: POST /orders/{id}/status with dispatch. Status transitions are not made through the courier endpoints. On a Çarşı business, dispatch cannot be written before picking is closed.
While in transit, write the location: PUT /orders/{id}/courier/location. The recommended interval is 10 seconds.
On delivery, write deliver.

Reporting the courier

curl -X PUT "https://api.supergelsin.com/api/partner/v1/orders/cm_ornek_siparis/courier" \
  -H "Authorization: Basic $(printf '%s:%s' "$API_KEY" "$API_SECRET" | base64)" \
  -H "X-Integrator: Ornek POS" \
  -H "X-Operator: kasiyer_01" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Örnek Kurye", "phone": "+905000000000", "externalId": "K-17", "company": "Örnek Kurye Firması", "arrivedAtStore": true }'

Location

curl -X PUT "https://api.supergelsin.com/api/partner/v1/orders/cm_ornek_siparis/courier/location" \
  -H "Authorization: Basic $(printf '%s:%s' "$API_KEY" "$API_SECRET" | base64)" \
  -H "X-Integrator: Ornek POS" \
  -H "X-Operator: kasiyer_01" \
  -H "Content-Type: application/json" \
  -d '{ "latitude": 40.9127, "longitude": 38.3895, "heading": 135, "recordedAt": "2026-01-31T10:41:05Z" }'

Start in the test environment: the restaurant and the Çarşı business of a test account accept the courier endpoints too.

Fields

Courier request

Alan	Tip	Açıklama
`name`zorunlu	string	Courier name, 2–80 characters.
`phone`	string	Optional; 10–15 digits, may start with +.
`externalId`	string	The courier company's own courier identifier, at most 64 characters.
`company`	string	The courier company's name, 1–64 characters. Send it on every request: a `PUT` without `company` removes the previous company name.
`arrivedAtStore`	boolean	If true, the moment the courier reached the business is recorded; the first record is kept.

Location request

Alan	Tip	Açıklama
`latitude`zorunlu	number	Between -90 and 90.
`longitude`zorunlu	number	Between -180 and 180.
`heading`	number	Heading, between 0 and 359.
`recordedAt`	ISO 8601	When the position was captured. A value in the future or older than 10 minutes is not rejected; it is replaced with the request time.

The courier is a motorcycle courier; there is no vehicle field. The courier's name and phone are returned only to the business and the integrator; they are never shown to the customer. On the order object this information is returned in the courier block: name, phone, externalId, firm (the X-Integrator value of the request that wrote it), company (the courier company's name; null if never sent), assignedAt, arrivedAtStoreAt and location. The courier response also carries id (the order identifier); on a restaurant, deliveryProvider gives the provider code derived from the X-Integrator value.

The location is personal data. Only the last position per order is stored; no trail is kept. Location writes are in their own rate-limit group (konum) and do not consume the order-reading quota; see Service limits.

Rules and errors

Alan	Tip	Açıklama
`409 order_closed`	closed order	No courier or location can be written to a delivered or cancelled order; `current` gives the order status.
`409 courier_not_set`	ordering	`PUT /orders/{id}/courier` must precede the location.
`400 invalid_body`	field	The `field` in the response names the rejected field (`name`, `phone`, `externalId`, `company`, `latitude`, `longitude`, `heading`, `recordedAt`).
`404 not_found`	order	The order does not exist or does not belong to this business.

Customer contact data is narrowed on the order object 2 hours after the order is delivered or cancelled: the name is shortened, the phone and coordinates are removed, the address is reduced to District / Province and the customer note is removed. Do not keep customer contact data in your own records beyond that period; indefinite retention conflicts with the KVKK proportionality principle.

Flow

Read the order that is ready for delivery: on a restaurant, GET /orders?status=ready; on a Çarşı business, an order whose picking is closed (picking.completed: true). With webhooks, the order.updated event reports the change.

Report the courier: PUT /orders/{id}/courier. Resending updates the record; the assignedAt of the first write is kept.

When the courier departs, advance the status: POST /orders/{id}/status with dispatch. Status transitions are not made through the courier endpoints. On a Çarşı business, dispatch cannot be written before picking is closed.

While in transit, write the location: PUT /orders/{id}/courier/location. The recommended interval is 10 seconds.

On delivery, write deliver.