# Handling Orders

#### Creating Orders

## Create Order

<mark style="color:green;">`POST`</mark> `https://api.cryptum.io/plugins/orders/checkout`

This endpoint is used to create new orders

#### Request Body

| Name                                                     | Type   | Description                                                                                                         |
| -------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| ecommerceOrderId<mark style="color:red;">\*</mark>       | string | The id of the order according to your application. This number is arbitrary and may follow your own business logic. |
| ecommerceType<mark style="color:red;">\*</mark>          | enum   | For the checkout API, this parameter should be "api". Our wordpress plugin uses "wordpress".                        |
| orderTotal<mark style="color:red;">\*</mark>             | string | Numerical value of the order                                                                                        |
| orderCurrency<mark style="color:red;">\*</mark>          | string | Which currency the order is based on.                                                                               |
| paymentStatus                                            | enum   | Either "pending" or "on-hold"                                                                                       |
| callbackUrl<mark style="color:red;">\*</mark>            | string | The address that will receive notifications regarding the order.                                                    |
| store<mark style="color:red;">\*</mark>                  | string | The store ID that can be found in our dashboard, under your project.                                                |
| deliveryInfo<mark style="color:red;">\*</mark>           | object | Specified bellow.                                                                                                   |
| deliveryInfo.firstName<mark style="color:red;">\*</mark> | string | First name of the customer.                                                                                         |
| deliveryInfo.lastName<mark style="color:red;">\*</mark>  | string | Last name of the customer                                                                                           |
| deliveryInfo.email<mark style="color:red;">\*</mark>     | string | Email of the customer                                                                                               |
| deliveryInfo.country<mark style="color:red;">\*</mark>   | string | Country of the customer                                                                                             |

{% tabs %}
{% tab title="200: OK Sucessfully created order" %}

```javascript
{
  "message": "Payment was successful",
  "status": "confirmed",
  "orderId": "0da30...f53b37",
  "ecommerceOrderId": "2",
  "storeId": "3ac0...ad4e9e",
  "transactions": [
    {
      "protocol": "CELO",
      "hash": "0x7a9c9...39517d3d"
    }
  ],
  "updatedProducts": null
}
```

{% endtab %}

{% tab title="400: Bad Request Failed attempt to create order" %}

```javascript
{
  "message": "Invalid transaction: received amount is less than order total",
  "status": "failed",
  "orderId": "dba...b23",
  "ecommerceOrderId": "3",
  "storeId": "3ac0...4e9e",
  "transactions": [],
  "updatedProducts": null
}
```

{% endtab %}
{% endtabs %}

#### Updating Orders

## Update Orders

<mark style="color:orange;">`PUT`</mark> `https://api.cryptum.io/plugins/checkout/{orderId}`

This endpoint is used to update existing orders.

#### Path Parameters

| Name                                      | Type   | Description                               |
| ----------------------------------------- | ------ | ----------------------------------------- |
| orderId<mark style="color:red;">\*</mark> | string | The id of the order that will be updated. |

#### Request Body

| Name            | Type   | Description                                                           |
| --------------- | ------ | --------------------------------------------------------------------- |
| transactionHash | string | Hash of the transaction that represented the order in the blockchain. |
| paymentMethod   | string | Payment method used for the transaction. e.g. "CELO"                  |
| paymentStatus   | enum   | "pending", "on-hold", "failed" or "cancelled".                        |
| blockchain      | string | Which blockchain is being used.                                       |
| convertedTotal  | string | Converted order total.                                                |

{% tabs %}
{% tab title="200: OK " %}

{% endtab %}

{% tab title="400: Bad Request " %}

{% endtab %}
{% endtabs %}

#### Get Order

## Get Order

<mark style="color:blue;">`GET`</mark> `https://api.cryptum.io/plugins/orders/{orderId}`

Use this endpoint to fetch information of an individual order.

#### Path Parameters

| Name                                      | Type   | Description                               |
| ----------------------------------------- | ------ | ----------------------------------------- |
| orderId<mark style="color:red;">\*</mark> | string | The id of the order that will be fetched. |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
  "callbackUrl": "http://...",
  "sessionToken": "eyJhbG...5m4",
  "id": "f701...672e",
  "ecommerceOrderId": "103",
  "ecommerce": "api",
  "orderTotal": "25.40",
  "orderCurrency": "USD",
  "storeMarkupPercentage": "0",
  "storeDiscountPercentage": "0",
  "cancelReturnUrl": "http://...",
  "successReturnUrl": "http://...",
  "deliveryInfo": {
    "firstName": "...",
    "lastName": "...",
    "email": "email@mail.com",
    "country": "AR"
  },
  "store": {
    "id": "a8f9...9f32",
    "name": "...",
    "email": "email@mail.com",
    "apiKeyId": "",
    "segment": "",
    "userId": "",
    "wallets": [],
    "storeUrl": "",
    "storeDiscountPercentage": "0",
    "storeMarkupPercentage": "0",
    "createdAt": "202...Z"
  },
  "marketRates": {
    "BRL": "1.00",
    "USD": "0.19",
    "EUR": "0.17",
    "JPY": "25.19",
    "BTC": "0.00000791",
    "ETH": "0.00011354",
    "XLM": "2.4025",
    "XRP": "0.519459",
    "BNB": "0.00061351",
    "MDA": "3.844",
    "CELO": "0.32033333",
    "HTR": "2.74",
    "ADA": "0.549142",
    "AVAX": "0.01150898",
    "MATIC": "0.16016667",
    "SOL": "0.009048964"
  }
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

{% endtab %}
{% endtabs %}

#### Get Orders

## Get Multiple Orders

<mark style="color:blue;">`GET`</mark> `https://api.cryptum.io/plugins/orders/`

#### Query Parameters

| Name                                      | Type    | Description                                               |
| ----------------------------------------- | ------- | --------------------------------------------------------- |
| limit                                     | number  | Default: 100                                              |
| offset                                    | number  | Default: 0                                                |
| storeId<mark style="color:red;">\*</mark> | string  |                                                           |
| paymentStatus                             | enum    | "pending", "on-hold", "failed" "cancelled" or "confirmed" |
| startDate                                 | string  |                                                           |
| endDate                                   | string  |                                                           |
| withCount                                 | boolean |                                                           |
| withTotal                                 | boolean |                                                           |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
  "total": 1,
  "orders": [
    {
      "id": "f70...1672e",
      "store": "a8f9...9f32",
      "sessionToken": "eyJhbG..uP5m4",
      "ecommerceOrderId": "103",
      "ecommerce": "api",
      "orderTotal": "25.40",
      "orderCurrency": "USD",
      "storeMarkupPercentage": "0",
      "storeDiscountPercentage": "0",
      "cancelReturnUrl": "http://...",
      "successReturnUrl": "http://...",
      "deliveryInfo": {
        "firstName": "...",
        "lastName": "...",
        "email": "email@gmail.com",
        "city": "...",
        "country": "...",
        "zip": "...",
        "address": "...",
        "complement": "...",
        "state": "..."
      },
      "callbackUrl": "http://...",
      "marketRates": {
        ...
      }
    }
  ]
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cryptum.io/english/products/crypto-checkout/checkout-api/orders/handling-orders.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.