> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mymorabaa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add order

> Create an order for an authenticated app business.

## Endpoint

`POST /orders`

Production URL:

`https://sam.aragon.morabaa.com/api/orders`

## Authentication

This endpoint requires app authentication headers:

* `X-App-Id: <APP_ID>`
* `X-App-Secret: <APP_SECRET>`

### Required headers

<ParamField header="X-App-Id" type="string" required>
  App ID credential.
</ParamField>

<ParamField header="X-App-Secret" type="string" required>
  App secret credential.
</ParamField>

<Note>
  Need credentials? Contact [info@morabaa.com](mailto:info@morabaa.com).
</Note>

If either header is invalid or missing, the response is `401 Unauthorized`.

## Request example

```bash theme={null}
curl -X POST "https://sam.aragon.morabaa.com/api/orders" \
  -H "X-App-Id: <APP_ID>" \
  -H "X-App-Secret: <APP_SECRET>" \
  -H "Content-Type: application/json" \
  -d '{
    "mobile": "07700000000",
    "fullname": "Ahmed Ali",
    "businessId": "9c7f3b9d-0809-4f5e-b8f2-b6e46a4eb3af",
    "externalId": "web-order-1001",
    "note": "Deliver after 5 PM",
    "items": [
      {
        "id": "7f8f6d3b-2b93-4af3-9f65-7ea7d5ab79f1",
        "name": "Paracetamol 500mg",
        "morabaaLocalId": 1024,
        "price": 12.5,
        "quantity": 2,
        "currencyId": 1
      }
    ]
  }'
```

## Body parameters

<ParamField body="mobile" type="string" required>
  Customer mobile number. Must match the Iraqi mobile format `07[4-9]xxxxxxxx`.
</ParamField>

<ParamField body="fullname" type="string" required>
  Customer full name. Maximum length is `64` characters.
</ParamField>

<ParamField body="businessId" type="guid" required>
  Business ID that will receive the order. It must belong to the authenticated app.
</ParamField>

<ParamField body="items" type="array" required>
  Order items. At least one item is required.
</ParamField>

<ParamField body="externalId" type="string">
  Optional external order identifier from your system. The endpoint accepts this field, but the current implementation does not forward it to the upstream order service.
</ParamField>

<ParamField body="note" type="string">
  Optional order note.
</ParamField>

### Item fields

<ParamField body="items[].id" type="guid" required>
  Item ID.
</ParamField>

<ParamField body="items[].name" type="string" required>
  Item name.
</ParamField>

<ParamField body="items[].morabaaLocalId" type="int" required>
  Item local ID in MyMorabaa. Must be greater than `0`.
</ParamField>

<ParamField body="items[].price" type="decimal" required>
  Item price at the time of ordering.
</ParamField>

<ParamField body="items[].quantity" type="decimal" required>
  Ordered quantity. Must be greater than `0`.
</ParamField>

<ParamField body="items[].currencyId" type="int">
  Currency ID for the item price. Defaults to `1` and must be greater than `0`.
</ParamField>

Notes:

* `businessId` must belong to the authenticated app.
* A successful response returns `201 Created`.
* If the upstream order service rejects the order or is unavailable, the response is `502 Bad Gateway`.

## Response

The response contains the created order ID:

<ResponseField name="id" type="guid">
  Created order ID.
</ResponseField>

```json theme={null}
{
  "id": "2d28f0cb-663f-4e58-b984-b99b8b9637dd"
}
```


## OpenAPI

````yaml openapi.json POST /orders
openapi: 3.1.0
info:
  title: MyMorabaa API
  version: 1.0.0
servers:
  - url: https://sam.aragon.morabaa.com/api
security: []
paths:
  /orders:
    post:
      summary: Add order
      description: Create an order for an authenticated app business.
      parameters:
        - $ref: '#/components/parameters/XAppId'
        - $ref: '#/components/parameters/XAppSecret'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddOrderRequest'
            example:
              mobile: '07700000000'
              fullname: Ahmed Ali
              businessId: 9c7f3b9d-0809-4f5e-b8f2-b6e46a4eb3af
              externalId: web-order-1001
              note: Deliver after 5 PM
              items:
                - id: 7f8f6d3b-2b93-4af3-9f65-7ea7d5ab79f1
                  name: Paracetamol 500mg
                  morabaaLocalId: 1024
                  price: 12.5
                  quantity: 2
                  currencyId: 1
      responses:
        '201':
          description: Order created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddOrderResponse'
              example:
                id: 2d28f0cb-663f-4e58-b984-b99b8b9637dd
        '401':
          description: >-
            Missing or invalid app authentication headers, or the business is
            not available to the authenticated app.
        '502':
          description: The upstream order service rejected the order or was unavailable.
components:
  parameters:
    XAppId:
      name: X-App-Id
      in: header
      required: true
      schema:
        type: string
      description: App ID credential.
    XAppSecret:
      name: X-App-Secret
      in: header
      required: true
      schema:
        type: string
      description: App secret credential.
  schemas:
    AddOrderRequest:
      type: object
      required:
        - mobile
        - fullname
        - businessId
        - items
      properties:
        mobile:
          type: string
          pattern: ^07[4-9]\d{8}
          description: Customer mobile number.
        fullname:
          type: string
          maxLength: 64
          description: Customer full name.
        businessId:
          type: string
          format: uuid
          description: Business ID that will receive the order.
        items:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/AddOrderItem'
          description: Order items.
        externalId:
          type: string
          description: >-
            Optional external order identifier from your system. The endpoint
            accepts this field, but the current implementation does not forward
            it to the upstream order service.
        note:
          type: string
          description: Optional order note.
    AddOrderResponse:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          format: uuid
          description: Created order ID.
    AddOrderItem:
      type: object
      required:
        - id
        - name
        - morabaaLocalId
        - price
        - quantity
      properties:
        id:
          type: string
          format: uuid
          description: Item ID.
        name:
          type: string
          description: Item name.
        morabaaLocalId:
          type: integer
          minimum: 1
          description: Item local ID in MyMorabaa.
        price:
          type: number
          format: decimal
          description: Item price at the time of ordering.
        quantity:
          type: number
          format: decimal
          exclusiveMinimum: 0
          description: Ordered quantity.
        currencyId:
          type: integer
          minimum: 1
          default: 1
          description: Currency ID for the item price.

````