Create an earning order
curl --request POST \
--url https://business.papp.sa/api/v1/orders/earning \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"phone_number": "512345678",
"total_price": 115,
"products": [
{
"product_name": "Cappuccino",
"product_price": 18.5,
"quantity": 2
}
],
"order_number": "SALE-2024-0021",
"name": "Ahmed Al-Saud",
"shipping_amount": 15,
"tax_amount": 22.5,
"discount_amount": 10,
"shipping_address": {
"city": "Riyadh",
"line1": "1234 King Fahd Rd, Al Olaya"
},
"metadata": {}
}
'import requests
url = "https://business.papp.sa/api/v1/orders/earning"
payload = {
"phone_number": "512345678",
"total_price": 115,
"products": [
{
"product_name": "Cappuccino",
"product_price": 18.5,
"quantity": 2
}
],
"order_number": "SALE-2024-0021",
"name": "Ahmed Al-Saud",
"shipping_amount": 15,
"tax_amount": 22.5,
"discount_amount": 10,
"shipping_address": {
"city": "Riyadh",
"line1": "1234 King Fahd Rd, Al Olaya"
},
"metadata": {}
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
phone_number: '512345678',
total_price: 115,
products: [{product_name: 'Cappuccino', product_price: 18.5, quantity: 2}],
order_number: 'SALE-2024-0021',
name: 'Ahmed Al-Saud',
shipping_amount: 15,
tax_amount: 22.5,
discount_amount: 10,
shipping_address: {city: 'Riyadh', line1: '1234 King Fahd Rd, Al Olaya'},
metadata: {}
})
};
fetch('https://business.papp.sa/api/v1/orders/earning', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://business.papp.sa/api/v1/orders/earning",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'phone_number' => '512345678',
'total_price' => 115,
'products' => [
[
'product_name' => 'Cappuccino',
'product_price' => 18.5,
'quantity' => 2
]
],
'order_number' => 'SALE-2024-0021',
'name' => 'Ahmed Al-Saud',
'shipping_amount' => 15,
'tax_amount' => 22.5,
'discount_amount' => 10,
'shipping_address' => [
'city' => 'Riyadh',
'line1' => '1234 King Fahd Rd, Al Olaya'
],
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://business.papp.sa/api/v1/orders/earning"
payload := strings.NewReader("{\n \"phone_number\": \"512345678\",\n \"total_price\": 115,\n \"products\": [\n {\n \"product_name\": \"Cappuccino\",\n \"product_price\": 18.5,\n \"quantity\": 2\n }\n ],\n \"order_number\": \"SALE-2024-0021\",\n \"name\": \"Ahmed Al-Saud\",\n \"shipping_amount\": 15,\n \"tax_amount\": 22.5,\n \"discount_amount\": 10,\n \"shipping_address\": {\n \"city\": \"Riyadh\",\n \"line1\": \"1234 King Fahd Rd, Al Olaya\"\n },\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://business.papp.sa/api/v1/orders/earning")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"phone_number\": \"512345678\",\n \"total_price\": 115,\n \"products\": [\n {\n \"product_name\": \"Cappuccino\",\n \"product_price\": 18.5,\n \"quantity\": 2\n }\n ],\n \"order_number\": \"SALE-2024-0021\",\n \"name\": \"Ahmed Al-Saud\",\n \"shipping_amount\": 15,\n \"tax_amount\": 22.5,\n \"discount_amount\": 10,\n \"shipping_address\": {\n \"city\": \"Riyadh\",\n \"line1\": \"1234 King Fahd Rd, Al Olaya\"\n },\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://business.papp.sa/api/v1/orders/earning")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"phone_number\": \"512345678\",\n \"total_price\": 115,\n \"products\": [\n {\n \"product_name\": \"Cappuccino\",\n \"product_price\": 18.5,\n \"quantity\": 2\n }\n ],\n \"order_number\": \"SALE-2024-0021\",\n \"name\": \"Ahmed Al-Saud\",\n \"shipping_amount\": 15,\n \"tax_amount\": 22.5,\n \"discount_amount\": 10,\n \"shipping_address\": {\n \"city\": \"Riyadh\",\n \"line1\": \"1234 King Fahd Rd, Al Olaya\"\n },\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"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
}
]
}
}{
"status": false,
"message": "Invalid or inactive API key",
"appended_data": {}
}{
"status": false,
"message": "Invalid or inactive API key",
"appended_data": {}
}{
"status": false,
"message": "The given data was invalid.",
"appended_data": {},
"errors": {
"total_price": [
"The total price field is required."
],
"products.0.quantity": [
"The quantity must be at least 1."
]
}
}{
"status": false,
"message": "Invalid or inactive API key",
"appended_data": {}
}Orders
Create an earning order
Creates an earning order (points awarded on a completed off-platform purchase). The request is serialized inside a distributed lock scoped to the authenticated merchant to reduce concurrent processing conflicts.
POST
/
v1
/
orders
/
earning
Create an earning order
curl --request POST \
--url https://business.papp.sa/api/v1/orders/earning \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"phone_number": "512345678",
"total_price": 115,
"products": [
{
"product_name": "Cappuccino",
"product_price": 18.5,
"quantity": 2
}
],
"order_number": "SALE-2024-0021",
"name": "Ahmed Al-Saud",
"shipping_amount": 15,
"tax_amount": 22.5,
"discount_amount": 10,
"shipping_address": {
"city": "Riyadh",
"line1": "1234 King Fahd Rd, Al Olaya"
},
"metadata": {}
}
'import requests
url = "https://business.papp.sa/api/v1/orders/earning"
payload = {
"phone_number": "512345678",
"total_price": 115,
"products": [
{
"product_name": "Cappuccino",
"product_price": 18.5,
"quantity": 2
}
],
"order_number": "SALE-2024-0021",
"name": "Ahmed Al-Saud",
"shipping_amount": 15,
"tax_amount": 22.5,
"discount_amount": 10,
"shipping_address": {
"city": "Riyadh",
"line1": "1234 King Fahd Rd, Al Olaya"
},
"metadata": {}
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
phone_number: '512345678',
total_price: 115,
products: [{product_name: 'Cappuccino', product_price: 18.5, quantity: 2}],
order_number: 'SALE-2024-0021',
name: 'Ahmed Al-Saud',
shipping_amount: 15,
tax_amount: 22.5,
discount_amount: 10,
shipping_address: {city: 'Riyadh', line1: '1234 King Fahd Rd, Al Olaya'},
metadata: {}
})
};
fetch('https://business.papp.sa/api/v1/orders/earning', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://business.papp.sa/api/v1/orders/earning",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'phone_number' => '512345678',
'total_price' => 115,
'products' => [
[
'product_name' => 'Cappuccino',
'product_price' => 18.5,
'quantity' => 2
]
],
'order_number' => 'SALE-2024-0021',
'name' => 'Ahmed Al-Saud',
'shipping_amount' => 15,
'tax_amount' => 22.5,
'discount_amount' => 10,
'shipping_address' => [
'city' => 'Riyadh',
'line1' => '1234 King Fahd Rd, Al Olaya'
],
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://business.papp.sa/api/v1/orders/earning"
payload := strings.NewReader("{\n \"phone_number\": \"512345678\",\n \"total_price\": 115,\n \"products\": [\n {\n \"product_name\": \"Cappuccino\",\n \"product_price\": 18.5,\n \"quantity\": 2\n }\n ],\n \"order_number\": \"SALE-2024-0021\",\n \"name\": \"Ahmed Al-Saud\",\n \"shipping_amount\": 15,\n \"tax_amount\": 22.5,\n \"discount_amount\": 10,\n \"shipping_address\": {\n \"city\": \"Riyadh\",\n \"line1\": \"1234 King Fahd Rd, Al Olaya\"\n },\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://business.papp.sa/api/v1/orders/earning")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"phone_number\": \"512345678\",\n \"total_price\": 115,\n \"products\": [\n {\n \"product_name\": \"Cappuccino\",\n \"product_price\": 18.5,\n \"quantity\": 2\n }\n ],\n \"order_number\": \"SALE-2024-0021\",\n \"name\": \"Ahmed Al-Saud\",\n \"shipping_amount\": 15,\n \"tax_amount\": 22.5,\n \"discount_amount\": 10,\n \"shipping_address\": {\n \"city\": \"Riyadh\",\n \"line1\": \"1234 King Fahd Rd, Al Olaya\"\n },\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://business.papp.sa/api/v1/orders/earning")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"phone_number\": \"512345678\",\n \"total_price\": 115,\n \"products\": [\n {\n \"product_name\": \"Cappuccino\",\n \"product_price\": 18.5,\n \"quantity\": 2\n }\n ],\n \"order_number\": \"SALE-2024-0021\",\n \"name\": \"Ahmed Al-Saud\",\n \"shipping_amount\": 15,\n \"tax_amount\": 22.5,\n \"discount_amount\": 10,\n \"shipping_address\": {\n \"city\": \"Riyadh\",\n \"line1\": \"1234 King Fahd Rd, Al Olaya\"\n },\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"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
}
]
}
}{
"status": false,
"message": "Invalid or inactive API key",
"appended_data": {}
}{
"status": false,
"message": "Invalid or inactive API key",
"appended_data": {}
}{
"status": false,
"message": "The given data was invalid.",
"appended_data": {},
"errors": {
"total_price": [
"The total price field is required."
],
"products.0.quantity": [
"The quantity must be at least 1."
]
}
}{
"status": false,
"message": "Invalid or inactive API key",
"appended_data": {}
}Authorizations
Body
application/json
Customer phone number. Accepted formats: +966XXXXXXXXX, 00966XXXXXXXXX, 966XXXXXXXXX, 0XXXXXXXXX, or bare 5XXXXXXXX. Normalised server-side to 5\d{8}.
Example:
"512345678"
Purchase amount (SAR).
Required range:
x >= 0Example:
115
Minimum array length:
1Show child attributes
Show child attributes
Merchant order reference.
Example:
"SALE-2024-0021"
Maximum string length:
255Example:
"Ahmed Al-Saud"
Required range:
x >= 0Example:
15
Required range:
x >= 0Example:
22.5
Required range:
x >= 0Example:
10
Optional shipping address. All fields are individually optional.
Show child attributes
Show child attributes
Optional metadata stored on the order.
Response
Order created successfully. When the customer's account is not yet activated, a pending_client_activation payload is returned instead of a full order resource.
⌘I