Picking and return

Substitution preference (per item)

In retail the product is not always on the shelf. The customer states a preference at order time, item by item; it arrives on the order line as substitutionPreference:

This field decides what the picker may do; apply the same constraint in your own screen. If the substitute costs more, the difference is not charged to the customer; if it costs less, the difference is refunded.

Writing the picking result

curl -X POST "https://api.supergelsin.com/api/partner/v1/orders/cm_ornek_siparis/picking" \
  -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 '{ "items": [
    { "clientReferenceId": "POS-1042", "status": "not_found" },
    { "clientReferenceId": "POS-1043", "status": "partial", "pickedQuantity": 2, "note": "Stokta 2 adet kaldı" },
    { "clientReferenceId": "POS-1044", "status": "substituted", "substituteClientReferenceId": "POS-2010", "customerApproved": true }
] }'

{ "orderId": "cm_ornek_siparis", "applied": 3, "failed": 0, "completed": false,
  "results": [ { "clientReferenceId": "POS-1042", "ok": true, "refundAmount": 42.5 } ],
  "adjustmentTotal": 42.5 }

Item results and closing are written in a single request. Items are processed in order; one rejected item does not affect the others, and the result of each item is in results[]. Refund amounts are computed server-side. When the first item result is written, a confirmed order becomes preparing. Picking is written only on a confirmed or preparing order.

Item-level rejection codes (order_not_pickable, picking_closed, invalid_weight, substitution_not_allowed, approval_required and others) are returned in results[].error; the full list is on the Error codes page.

Closing the picking

curl -X POST "https://api.supergelsin.com/api/partner/v1/orders/cm_ornek_siparis/picking" \
  -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 '{ "complete": true, "receiptUrl": "https://ornek-entegrator.example/fis/1044.jpg", "bagCount": 3 }'

complete: true closes the picking; a request that sends only items does not close it. At least one of items and complete: true is required. receiptUrl and bagCount are sent only with complete: true. After picking is closed, dispatch can be written with POST /orders/{id}/status.

• If the closing is rejected, the earlier item results are not rolled back.
• If complete is sent again to a completed order, 200 and completed: true are returned; refund, ledger and notification do not run again. If a completed order later becomes unpickable (for example cancelled), repeating complete returns 409 picking_incomplete.
• The receipt image and bag count are written only if the closing succeeds. The receipt image is downloaded from an external https link and stored in the platform storage (an image, at most 8 MB). If a receipt is already recorded it is not rewritten and a receipt_already_saved warning is returned; on a repeated request that sends only bagCount, the bag count is not written either. If the receipt image cannot be copied, the closing does not stop and a receipt_not_saved warning is returned.
• The picking shortfall is deducted from the amount to be collected at the door: adjustmentTotal is in the response and payment.dueAmount is updated in the order body. Read the order again after picking.

Customer data and test orders

On a Çarşı order the customer's phone number, latitude and longitude are never shared; customer.phone, latitude and longitude are always null. Two hours after the order is delivered or cancelled the customer information is narrowed: the name is shortened (Ayşe Y.), the address is reduced to District / Province and the customer's free-text note is removed from the note field. customer.redacted says the narrowing was done and visibleUntil says when full visibility ends. Narrowed fields are not an error; your integration must not fail on them. Do not store this data indefinitely on your side either (KVKK art. 4/2).

isTest: true shows that the order is a test order created with POST /orders/test. A test order does not reach the picking screen of the business (picking results can still be written through this API) and does not enter revenue, commission or settlement.

Return of an undeliverable order

If the courier cannot reach the customer or the address is wrong, an order on the way can only be cancelled with the code customer_unreachable or invalid_address. On Çarşı, for an online payment, the whole amount is then refunded to the customer (deliveryFailed.completedSale is always false). When the products are back in the store, the return is confirmed item by item.

curl "https://api.supergelsin.com/api/partner/v1/orders?status=return_pending" \
  -H "Authorization: Basic $(printf '%s:%s' "$API_KEY" "$API_SECRET" | base64)" \
  -H "X-Integrator: Ornek POS" \
  -H "X-Operator: kasiyer_01"

curl -X POST "https://api.supergelsin.com/api/partner/v1/orders/cm_ornek_siparis/return" \
  -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 '{ "lines": [{ "lineId": "cm_ornek_satir", "returnedQuantity": 1, "reason": "lost" }] }'

The pending lines are in the returnLines field of the GET /orders/{id} response (lineId, clientReferenceId, sku, barcode, name, quantity). Every line is sent exactly once. Returned quantities are added back to stock; for a quantity that did not return, reason (lost, damaged) is required and the reason is recorded on the order. Of two concurrent confirmations only one is applied. The response has the form { orderId, restockedLines }.