Order API

# --- Change feed: first call starts at the beginning of time ---
curl "https://api.scoperly.com/connect/v1/supplier/orders?updatedAfter=1970-01-01T00:00:00Z&limit=50" \
  -H "Authorization: Bearer $TOKEN"

# Response (sanitized OrderSummaryResponse — branch / full address stripped):
# {
#   "items": [
#     {
#       "id": 42,
#       "uuid": "e3f5a2c1-...-...-...-...",
#       "orderNumber": "SCP-2025-000042",
#       "status": "PLACED",
#       "customerKind": "BUYER_TENANT",        # or INTERNAL_PARTNER - see "Three kinds of order"
#       "customerName": "Café Araks",
#       "buyerId": 7,                           # absent on an INTERNAL_PARTNER order
#       "buyerName": "Café Araks",
#       "saleChannel": "ORDER",                 # or DIRECT_SALE - a counter sale, born DELIVERED
#       "supplierName": "Avan Dairy",
#       "totalAmount": 1250.00,                 # net of VAT
#       "grossTotal": 1500.00,                  # what the customer owes
#       "amountPaid": 0.00,
#       "currency": "AMD",
#       "paymentStatus": "UNPAID",              # UNPAID | PARTIAL | PAID | REFUNDED
#       "createdAt": "2025-03-20T09:15:00Z",
#       "updatedAt": "2025-03-20T09:15:00Z",
#       "version": "1742461200000000"           # changes with every change - dedupe on (id, version)
#     }
#   ],
#   "nextCursor": "1742461200000000_42",
#   "hasMore": true
# }
#
# A field with no value is left out, not sent as null - treat a missing key as null.
# An order for a client-book partner carries customerInternalPartnerId and
# customerInternalPartnerExternalId (your own id) instead of buyerId; an order your
# operator keyed carries placedOnBehalfByUserId; deliveredAt, cancelledAt,
# rejectedAt, cancelReason and voidReason appear once they happen.

# --- Subsequent calls: pass nextCursor back, unchanged ---
curl "https://api.scoperly.com/connect/v1/supplier/orders?cursor=1742461200000000_42&limit=50" \
  -H "Authorization: Bearer $TOKEN"

# nextCursor is ALWAYS returned, including on an empty page (it echoes your own
# position back). Persist it after you have durably stored the page — never before.
# hasMore=false means "you are caught up", not "the feed ended": keep polling with
# the same cursor and new changes will arrive.

# --- Browse mode (newest first, NOT resumable) ---
curl "https://api.scoperly.com/connect/v1/supplier/orders?status=PLACED&limit=10" \
  -H "Authorization: Bearer $TOKEN"

curl "https://api.scoperly.com/connect/v1/supplier/orders/12345" \
  -H "Authorization: Bearer $TOKEN"

# Response:
# {
#   "order": {
#     "orderNumber": "SCP-2025-000042",
#     "status": "PLACED",
#     "buyerName": "Café Araks",
#     "supplierName": "Avan Dairy",
#     "lines": [
#       {
#         "id": 981,
#         "productId": 5512,
#         "sellerExternalId": "SKU-001",
#         "productName": "Organic Green Tea 500g",
#         "unitOfMeasure": "pcs",
#         "quantity": 50,
#         "unitPrice": 12.50,
#         "vatRate": 20.00,
#         "vatAmount": 125.00,
#         "lineTotal": 625.00,
#         "lineTotalInclVat": 750.00,
#         "currency": "AMD"
#       }
#     ],
#     # sellerExternalId is YOUR catalog id — the exact externalId you sent in the
#     # catalog upsert — snapshotted when the order was placed. Join on this, not on
#     # productId: it survives a later catalog re-import that reassigns external ids.
#     # It is absent for products created directly in the supplier portal.
#     "subtotal": 625.00,
#     "deliveryFee": 0,
#     "deliveryFeeSource": "AUTO_RATE",
#     "vatTotal": 125.00,
#     "totalAmount": 625.00,
#     "amountPaid": 0.00,
#     "amountDue": 750.00,
#     "paymentStatus": "UNPAID",
#     "saleChannel": "ORDER",
#     "currency": "AMD",
#     # Note: totalAmount is the NET total (subtotal + deliveryFee − discount).
#     # VAT is denormalised in vatTotal for the buyer-facing breakdown.
#     # Buyer pays subtotal + deliveryFee + vatTotal − discount = the gross amount.
#     "deliveryCity": "Yerevan",
#     "deliveryCountry": "AM",
#     "requestedDeliveryDate": "2025-03-22",
#     "createdAt": "2025-03-20T09:15:00Z"
#   },
#   "internalPartner": {
#     "externalId": "CLI-0042",
#     "name": "Café Araks",
#     "category": "HORECA",
#     "route": "Yerevan-Center-Mon"
#   },
#   "customer": {
#     "kind": "BUYER_TENANT",
#     "buyerTenantId": 7,
#     "name": "Café Araks"
#   }
# }
#
# "internalPartner" is your own classification of the buyer, matched by tax id
# against your client book; absent when there is no match.
#
# "customer" says who the order is for. For an order your operator keyed for a
# client-book partner it is that partner in full - YOUR data, so it comes back
# whole:
#
#   "customer": {
#     "kind": "INTERNAL_PARTNER",
#     "internalPartnerId": 355,
#     "externalId": "CLI-0042",
#     "name": "Café Araks",
#     "legalName": "Araks LLC",
#     "taxId": "01234567",
#     "address": "...", "deliveryAddress": "...",
#     "contactPhone": "...", "contactEmail": "...",
#     "route": "Yerevan-Center-Mon", "category": "HORECA"
#   }
#
# A buyer tenant is a different party: its block carries the id and display
# name only. Fields that do not apply are omitted, not sent as null.
#
# The sanitized order omits your branch and warehouse ids, the buyer's approval
# state and the full delivery address (city and country only).

# Read the order, keep its version
VERSION=$(curl -s "https://api.scoperly.com/connect/v1/supplier/orders/12345" \
  -H "Authorization: Bearer $TOKEN" | jq -r '.order.version')

# Act on exactly that version
curl -X POST https://api.scoperly.com/connect/v1/supplier/orders/12345/dispatch \
  -H "Authorization: Bearer $TOKEN" \
  -H "If-Match: $VERSION" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "trackingCode": "HP123456789AM" }'

# 409 if it changed:
# {
#   "type": "ORDER_VERSION_CONFLICT",
#   "status": 409,
#   "detail": "The order changed since you read it. Re-read it and decide again — the current version is 1742461200000000."
# }

# Accept an order
curl -X POST https://api.scoperly.com/connect/v1/supplier/orders/12345/accept \
  -H "Authorization: Bearer sck_live_abc123..." \
  -H "Idempotency-Key: $(uuidgen)"

# Reject an order
curl -X POST https://api.scoperly.com/connect/v1/supplier/orders/12345/reject \
  -H "Authorization: Bearer sck_live_abc123..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "reason": "Product temporarily out of stock" }'

curl -X POST https://api.scoperly.com/connect/v1/supplier/orders/12345/dispatch \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "trackingCode": "HP123456789AM",
    "notes": "Handed to HayPost, ETA Mon evening."
  }'

curl -X POST https://api.scoperly.com/connect/v1/supplier/orders/12345/cancel \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "reason": "Warehouse shortage — cannot fulfil" }'

{
  "orderIds": [12345, 12346, 12347]
}

{
  "succeeded": 2,
  "failed": 1,
  "results": [
    { "orderId": 12345, "status": "accepted" },
    { "orderId": 12346, "status": "accepted" },
    { "orderId": 12347, "status": "failed", "errorCode": "ORDER_NOT_FOUND", "error": "Order not found: 12347" }
  ]
}

{
  "orders": [
    { "orderId": 12345, "trackingCode": "HP001", "notes": "Handed to HayPost" },
    { "orderId": 12346, "trackingCode": "HP002" }
  ]
}