Skip to main content
POST
/
v1
/
orders
/
earning
/
product-rating
Create a product-rating earning order
curl --request POST \
  --url https://business.papp.sa/api/v1/orders/earning/product-rating \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "phone_number": "512345678",
  "review_reference": "PRODUCT-REVIEW-2026-0001",
  "product_id": "SKU-CAPPUCCINO-250G",
  "product_name": "Cappuccino 250g",
  "rating": 4,
  "comment": "Good aroma, smooth taste.",
  "metadata": {
    "channel": "mobile_app"
  }
}
'
{
  "status": true,
  "message": "",
  "appended_data": {},
  "data": {
    "id": 42,
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "reference_number": "REF-2024-001234",
    "order_status": "approved",
    "status_label": "خرج للتوصيل",
    "custom_status": {
      "ar": "خرج للتوصيل",
      "en": "Out for delivery"
    },
    "order_number": "ORD-2024-001234",
    "type": 1,
    "total_price": 150.5,
    "total_points": 1505,
    "metadata": {
      "source": "mobile_app"
    },
    "date": "2024-12-23T00:00:00.000Z",
    "time": "10:00:00",
    "since": "2 hours ago",
    "settlement_status": "settled",
    "status": 1,
    "created_at": "2024-12-23T10:00:00.000Z",
    "updated_at": "2024-12-23T15:30:00.000Z",
    "items": [
      {
        "product_name": "Cappuccino",
        "product_price": 18.5,
        "quantity": 2
      }
    ]
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.papp.sa/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
phone_number
string
required

Customer phone number. Accepted formats: +966XXXXXXXXX, 00966XXXXXXXXX, 966XXXXXXXXX, 0XXXXXXXXX, or bare 5XXXXXXXX. Normalised server-side to 5\d{8}.

Example:

"512345678"

​
review_reference
string
required

Merchant-side unique identifier for this rating. Used as the idempotency key — sending the same value twice for the same merchant is rejected as a duplicate.

Example:

"PRODUCT-REVIEW-2026-0001"

​
product_id
string
required

Merchant-side product identifier (SKU or internal ID) that the rating belongs to.

Example:

"SKU-CAPPUCCINO-250G"

​
product_name
string | null

Human-readable product name. Stored for audit.

Example:

"Cappuccino 250g"

​
rating
integer | null

Star value submitted by the customer. Stored for audit only; does not change the points awarded.

Required range: 1 <= x <= 5
Example:

4

​
comment
string | null

Free-text review body. Stored for audit only.

Example:

"Good aroma, smooth taste."

​
metadata
object

Optional metadata stored on the earning order.

Example:
{ "channel": "mobile_app" }

Response

Points awarded successfully. When the customer's account is not yet activated, a pending_client_activation payload is returned instead of a full order resource.

​
status
boolean
required
Example:

true

​
message
string | null
required
Example:

""

​
appended_data
object
required
Example:
{}
​
data
object
required