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.

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.

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.

You can also change that expiration time in the payment providers configurations.

Order Model (Example)

{
  "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",
}

Service Methods

List logged-in user orders

Using SDK

// 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);

Rest API reference:

Error while loading OpenAPI operation — Failed to fetch OpenAPI file

Get logged-in user order by id

Using SDK

// 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);

Rest API reference:

Error while loading OpenAPI operation — Failed to fetch OpenAPI file

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.

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.

Using SDK

// 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);

Rest API reference:

Error while loading OpenAPI operation — Failed to fetch OpenAPI file

Creates an order

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.

Using SDK

// 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);

Rest API reference:

Error while loading OpenAPI operation — Failed to fetch OpenAPI file