Skip to main content

​
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

​
Headers

HeaderValueRequired
AuthorizationBearer YOUR_API_TOKENYes
Content-Typeapplication/jsonYes

​
Request Body

ParameterTypeRequiredDescription
customerobjectNoCustomer identification. Provide either customer.id to reference an existing customer, OR the full customer details below to create/find a customer.
customer.idintegerNoExisting customer ID (use this OR the fields below)
customer.country_codestringConditionalRequired if customer.id is not provided. One of: 966, 973, 971, 974, 968, 965
customer.phonestringConditionalRequired if customer.id is not provided
customer.firstNamestringConditionalRequired if customer.id is not provided
customer.lastNamestringConditionalRequired if customer.id is not provided
customer.emailstringConditionalRequired if customer.id is not provided
created_fromstringYesDomain name where the order originates (e.g., myapp.com)
productsarrayYesArray of products to order (min: 1)
products[].identifier_typestringYesEither id or slug
products[].identifierstring/integerYesProduct ID or slug
products[].quantityintegerYesQuantity (min: 1)
products[].optionsobjectNoProduct field/option selections
products[].noticestringNoCustomer note for this item (max: 800 chars)
products[].subscription_planintegerNoSubscription variant ID (for subscription products)
coupon_codestringNoCoupon 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
}
Redirect the customer to 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
}
Free orders are completed immediately with no checkout step.

​
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

CodeDescription
400Business logic error (product not found, out of stock, invalid coupon, etc.)
401Unauthorized — invalid or missing token
422Validation error — missing or invalid fields

​
Common Error Messages

MessageCause
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 1Subscription products cannot have quantity > 1
Invalid coupon codeCoupon does not exist or is disabled
Coupon is no longer validCoupon has reached its maximum usage
Failed to create or find customerCustomer ID not found in your store