# Orders

Orders are the entities which indicates a purchase into commerce service. A order can be made with a single product token or a set of product tokens. You can also use the automatic distribution type that will define the product token to be delivered to the user, or you can specify into the order creation request a specific product token to be purchased.

{% hint style="warning" %}
*If the specified product token could not be purchased for any reason, the request will fail*

***example of fail reasons**: token has fixed user match, token is not on for\_sale status, etc.*
{% endhint %}

The order will automatically identify the payment gateway and create the payment transaction depending on the currency which you want to use to pay. For example: if you have Paypal configured to receive in USD and Pagar.me to receive in BRL and you product is enabled for both currencies, you must specify into the order creation request what is the currency that your user want to use for paying. After that, the commerce service will use the right gateway.

By default, all orders have only 9 minutes to be finalised, i.e, paid in the payment gateway. If user delay more than that, the order will be automatically expired.

{% hint style="info" %}
*You can also change that expiration time in the* [*payment providers configurations*](/w3block-eng/dev-docs/api/commerce-api-services/company-administration/companies-admin.md)*.*
{% endhint %}

<details>

<summary>Order Model (Example)</summary>

```json
{
  "id": "string",
  "createdAt": "2022-11-04T12:56:48.255Z",
  "updatedAt": "2022-11-04T12:56:48.255Z",
  "companyId": "string",
  "userId": "string",
  "destinationWalletAddress": "string",
  "addressId": "string",
  "address": null,
  "currencyId": "string",
  "currencyAmount": "string",
  "products": [
    ...
  ],
  "status": "pending",
  "paymentProvider": "pagar_me",
  "providerTransactionId": "za_1012skak1",
  "paymentMethod": "credit_card",
  "paymentInfo": {
    "paymentUrl": "https://example.com/order/1/pay"
  },
  "deliverDate": "2022-11-04T12:56:48.255Z",
  "expiresIn": "2022-11-04T12:56:48.255Z",
  "gasFee": "string",
  "clientServiceFee": "string",
  "companyServiceFee": "string",
}
```

</details>

## Service Methods

### List logged-in user orders

<details>

<summary>Using SDK</summary>

{% code lineNumbers="true" %}

```typescript
// init your sdk as defined in main page of Commerce service
import { W3blockCommerceSDK } from '@w3block/sdk-commerce';
const sdk: W3blockCommerceSDK;
...

const tenantId = '<your tenant id>';
const orders = await sdk.api.companies.listUserOrders(tenantId, {page: 1, limit: 100});
console.log('user orders', orders);
```

{% endcode %}

</details>

Rest API reference:

{% openapi src="<https://commerce.pixway.io/sdk-json>" path="/companies/{companyId}/orders" method="get" %}
<https://commerce.pixway.io/sdk-json>
{% endopenapi %}

### Get logged-in user order by id

<details>

<summary>Using SDK</summary>

{% code lineNumbers="true" %}

```typescript
// init your sdk as defined in main page of Commerce service
import { W3blockCommerceSDK } from '@w3block/sdk-commerce';
const sdk: W3blockCommerceSDK;
...

const tenantId = '<your tenant id>';
const orderId = '<orderId>';
const order = await sdk.api.companies.getUserOrder(tenantId, orderId);
console.log('user order', order);
```

{% endcode %}

</details>

Rest API reference:

{% openapi src="<https://commerce.pixway.io/sdk-json>" path="/companies/{companyId}/orders/{orderId}" method="get" %}
<https://commerce.pixway.io/sdk-json>
{% endopenapi %}

### Creates an order preview

This endpoint must be used to get the gas price signature that must be informed to create the order. Basically, this endpoint checks if the informed state of order could be created and returns the preview of final values, including gas price, and its signature.

{% hint style="warning" %}
The signature is valid only for 40 seconds as blockchain gas price is volatile. So, you need to keep refreshing data using this endpoint for each 40 seconds until user confirm the order creation.
{% endhint %}

<details>

<summary>Using SDK</summary>

{% code lineNumbers="true" %}

```typescript
// init your sdk as defined in main page of Commerce service
import { W3blockCommerceSDK } from '@w3block/sdk-commerce';
const sdk: W3blockCommerceSDK;
...

const tenantId = '<your tenant id>';
const preview = await sdk.api.companies.computeOrderPreview(tenantId, {
  orderProducts: [
    {
      productId: "3db843f4-1ee6-4f6e-a86d-b0aee938bdde",
      productTokenId: "3062cdc2-2bd8-4143-8a04-90fc1e607794" // This can be specified or not
    }
  ],
  currencyId: "65fe1119-6ec0-4b78-8d30-cb989914bdcb"
});
console.log('order preview', preview);
```

{% endcode %}

</details>

Rest API reference:

{% openapi src="<https://commerce.pixway.io/sdk-json>" path="/companies/{companyId}/orders/preview" method="post" %}
<https://commerce.pixway.io/sdk-json>
{% endopenapi %}

### Creates an order

{% hint style="info" %}
If you don't specify **destinationWalletAddress**, commerce service will automatically get the user main wallet address. This input also just accept addresses owned by the user which is creating the order.
{% endhint %}

<details>

<summary>Using SDK</summary>

{% code lineNumbers="true" %}

```typescript
// init your sdk as defined in main page of Commerce service
import { W3blockCommerceSDK } from '@w3block/sdk-commerce';
const sdk: W3blockCommerceSDK;
...

const tenantId = '<your tenant id>';
const order = await sdk.api.companies.createOrder(tenantId, {
  orderProducts: [
    {
      productId: "3db843f4-1ee6-4f6e-a86d-b0aee938bdde",
      productTokenId: "3062cdc2-2bd8-4143-8a04-90fc1e607794", // This can be specified or not
      expectedPrice: '100', // This is used to check inconsistency between front-end and backend prices
    }
  ],
  currencyId: "65fe1119-6ec0-4b78-8d30-cb989914bdcb",
  destinationWalletAddress: '0xd3304183ec1fa687e380b67419875f97f1db05f5',
  signedGasFee: '===812hgsahbncva',
  successUrl: 'https://domain.com'
});
console.log('order', order);
```

{% endcode %}

</details>

Rest API reference:

{% openapi src="<https://commerce.pixway.io/sdk-json>" path="/companies/{companyId}/orders" method="post" %}
<https://commerce.pixway.io/sdk-json>
{% endopenapi %}


---

# 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://w3block.gitbook.io/w3block-eng/dev-docs/api/commerce-api-services/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.