Orders API

Once you've taken payment from the customer, you need to convert your checkout into an order.

Create an Order

POST /orders

{
    "checkoutId": "bb0f2c30-9770-410a-a680-a5363a395eab",
    "meta": {
        // Any internal data you may need when receiving webhooks
        "anything": "anything"
    },

    // An optional reference you can use in the future for reconciliation.
    "paymentReference": null,

    "webhookUrls": [
        "http://your-webhook-url.com"
    ],

    "idempotencyKey": "any-key-you-want"
}

Property	Description	Example
checkoutId	The ID of the checkout.	bb0f2c30-9770-410a-a680-a5363a395eab
meta	optional An object of properties that will be given back to you in all webhook calls that we initiate.	json { "internal_user_id": 18729, "source": "app", "language": "ar" }
paymentReference	optional Any reference you use internally to track payments, this will be part of all your reconciliation reports.	WS94820oPws
webhookUrls	optional An array of webhook URLs passed as strings, each will be called for each webhook events that occur.	json [ "https://my-webhook-1.com/callback", "https://my-webhook-2.com/callback" ]
idempotencyKey	optional A unique idempotency key from you.	any-key-you-want

Response (200)

{
    "id": "9f74936e-f91e-4cf9-a4de-7efc3b263604"
}

Make sure to store this order ID as you will likely need it in the future.

When an order is successfully created, you can safely delete the cart from the UI as well as the cart reference.

Query Orders

You can use this endpoint to query both relevant orders to the current user or to build a back-end admin section to your application.

GET /orders

Property	Description	Example
filter.userId	Returns only orders created by this user.	?filter.userId=any-unique-id-from-your-system
filter.idempotencyKey	Filters by idempotency key.	&filter.idempotencyKey=$in:key1,key2
filter.status	Filters by the status of the order. See Orders Lifecycle.	&filter.status=$in:success,pending
filter.id	Filter by order ID, useful if you want to display the order page for a specific order.	&filter.id=9f74936e-f91e-4cf9-a4de-7efc3b263604
filter.amount	Filters by order amount	&filter.amount=$gt:10000

Response (200)

{
    "id": "9f74936e-f91e-4cf9-a4de-7efc3b263604",
    "userId": "7e81c14b-893d-4c98-b92a-da0f7ccf732b",
    "idempotencyKey": "anything-you-want",
    "amount": 200000,
    "currency": "EGP",
    "status": "pending.confirmed",
    "products": [
        // An array of Product Objects
    ],
    "cartId": "7e81c14b-893d-4c98-b92a-da0f7ccf732b",
    "createdAt": "2014-11-12T15:30:06+00:00",
    "deliveredAt": null,
    "delivery": {
        "trackingReference": null,
        "trackingURL": null,
        "address": {
            // ... an Address Object for the customer
        }
    },

    "pagination": {
        "totalItems": 12,
        "currentPage": 1,
        "pageSize": 25,
        "totalPages": 1
    },
    // Note: returns are only returned if a filter.id or filter.idempotencyKey is provided
    "returns": {
        "returnableProducts": [
            {
                "returnableQuantity": 4,
                "returnableReasons": [
                    {
                        "code": "changed_mind",
                        "label": "I changed my mind"
                    },
                    {
                        "code": "stopped_working",
                        "label": "Item stopped working well after usage"
                    },
                ],
                // ... the rest of a Product Object
            },
            // ... rest of the Product Objects with returnableQuantity
        ],
        "returns": [
            {
                "id": "",
                "status": "pending.pickup",
                "createdAt": "2014-11-12T19:30:06+00:00",
                "pickedUpAt": null,
                "succeededAt": "2014-11-15T19:30:06+00:00",
                "products":[
                    // ... an array of Product Objects
                ]
            }
        ]
    }
}