Documentation Index
Fetch the complete documentation index at: https://docs.rmz.gg/llms.txt
Use this file to discover all available pages before exploring further.
Create Order
POST/orders
Creates a new order for a customer. If the order total is greater than zero, a checkout link is returned for payment. If the order is free, it is completed immediately.
Authentication
| Header | Value | Required |
|---|
Authorization | Bearer YOUR_API_TOKEN | Yes |
Content-Type | application/json | Yes |
Request Body
| Parameter | Type | Required | Description |
|---|
customer | object | No | Customer identification. Provide either customer.id to reference an existing customer, OR the full customer details below to create/find a customer. |
customer.id | integer | No | Existing customer ID (use this OR the fields below) |
customer.country_code | string | Conditional | Required if customer.id is not provided. One of: 966, 973, 971, 974, 968, 965 |
customer.phone | string | Conditional | Required if customer.id is not provided |
customer.firstName | string | Conditional | Required if customer.id is not provided |
customer.lastName | string | Conditional | Required if customer.id is not provided |
customer.email | string | Conditional | Required if customer.id is not provided |
created_from | string | Yes | Domain name where the order originates (e.g., myapp.com) |
products | array | Yes | Array of products to order (min: 1) |
products[].identifier_type | string | Yes | Either id or slug |
products[].identifier | string/integer | Yes | Product ID or slug |
products[].quantity | integer | Yes | Quantity (min: 1) |
products[].options | object | No | Product field/option selections |
products[].notice | string | No | Customer note for this item (max: 800 chars) |
products[].subscription_plan | integer | No | Subscription variant ID (for subscription products) |
coupon_code | string | No | Coupon code to apply |
Example Request — Existing Customer
curl -X POST "https://merchant-api.rmz.gg/shawarma/orders" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"customer": {
"id": 12345
},
"created_from": "myapp.com",
"products": [
{
"identifier_type": "id",
"identifier": 101,
"quantity": 2
}
],
"coupon_code": "SAVE10"
}'
Example Request — New Customer
curl -X POST "https://merchant-api.rmz.gg/shawarma/orders" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"customer": {
"country_code": "966",
"phone": "501234567",
"firstName": "Ahmed",
"lastName": "Ali",
"email": "ahmed@example.com"
},
"created_from": "myapp.com",
"products": [
{
"identifier_type": "slug",
"identifier": "free-ebook",
"quantity": 1
}
]
}'
Success Response — Paid Order
HTTP 201 Created
{
"message": "Checkout link created successfully",
"data": {
"checkout_id": 123456,
"checkout_url": "https://app.rmz.gg/checkout/abc123def456",
"amount": 299.99,
"status": "pending_payment"
},
"api": "rmz.shawarma",
"timestamp": 1699999999
}
checkout_url to complete payment.
Success Response — Free Order
HTTP 201 Created
{
"message": "Order created successfully",
"data": {
"order_id": 789012,
"status": "completed",
"amount": 0
},
"api": "rmz.shawarma",
"timestamp": 1699999999
}
Idempotency
Duplicate requests within 5 minutes return the existing checkout or order instead of creating a new one. The response includes "duplicate": true:
{
"success": true,
"message": "Checkout already exists",
"data": {
"checkout_id": 123456,
"duplicate": true
}
}
Error Responses
| Code | Description |
|---|
400 | Business logic error (product not found, out of stock, invalid coupon, etc.) |
401 | Unauthorized — invalid or missing token |
422 | Validation error — missing or invalid fields |
Common Error Messages
| Message | Cause |
|---|
Product not found: {identifier} | Product ID or slug does not exist in your store |
Product unavailable: {name} | Product is disabled (status 3) |
Requested quantity not available for product: {name} | Insufficient stock |
Minimum quantity is {n} for product: {name} | Below the minimum order quantity |
Maximum quantity allowed for subscriptions is 1 | Subscription products cannot have quantity > 1 |
Invalid coupon code | Coupon does not exist or is disabled |
Coupon is no longer valid | Coupon has reached its maximum usage |
Failed to create or find customer | Customer ID not found in your store |
