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 .

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:

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:

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:

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:

PreviousProducts NextWebhooks

Last updated 2 years ago

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.

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 .

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:

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:

Creates an order preview

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:

Creates an 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:

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "createdAt": "2025-06-01T16:35:57.802Z",
      "updatedAt": "2025-06-01T16:35:57.802Z",
      "companyId": "123e4567-e89b-12d3-a456-426614174000",
      "company": {},
      "userId": "123e4567-e89b-12d3-a456-426614174000",
      "user": {},
      "destinationWalletAddress": "text",
      "addressId": "123e4567-e89b-12d3-a456-426614174000",
      "address": {},
      "status": "pending",
      "deliverDate": "2025-06-01T16:35:57.802Z",
      "expiresIn": "2025-06-01T16:35:57.802Z",
      "deliverId": "B61JHC",
      "products": [
        {}
      ],
      "payments": [
        {}
      ]
    }
  ],
  "meta": {
    "itemCount": 1,
    "totalItems": 1,
    "itemsPerPage": 1,
    "totalPages": 1,
    "currentPage": 1
  },
  "links": {
    "first": "http://example.com?page=1",
    "prev": "http://example.com?page=1",
    "next": "http://example.com?page=2",
    "last": "http://example.com?page=3"
  }
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2025-06-01T16:35:57.802Z",
  "updatedAt": "2025-06-01T16:35:57.802Z",
  "companyId": "123e4567-e89b-12d3-a456-426614174000",
  "company": {},
  "userId": "123e4567-e89b-12d3-a456-426614174000",
  "user": {},
  "destinationWalletAddress": "text",
  "addressId": "123e4567-e89b-12d3-a456-426614174000",
  "address": {},
  "status": "pending",
  "deliverDate": "2025-06-01T16:35:57.802Z",
  "expiresIn": "2025-06-01T16:35:57.802Z",
  "deliverId": "B61JHC",
  "products": [
    {}
  ],
  "payments": [
    {}
  ]
}

post

Authorizations

Path parameters

companyIdstringRequired

Body

acceptIncompleteCartobjectOptionalDefault: trueExample: true

couponCodestringOptionalExample: coupon-code

destinationWalletAddressstringOptionalExample: 0xd3304183ec1fa687e380b67419875f97f1db05f5

destinationUserIdstring · uuidOptional

currencyIdstringOptionalDeprecatedExample: 65fe1119-6ec0-4b78-8d30-cb989914bdcb

paymentMethodstring · enumOptionalDeprecatedExample: pixPossible values:

anchorPaymentsCurrencyIdstring · uuidOptionalDefault: nullExample: 65fe1119-6ec0-4b78-8d30-cb989914bdcb

Responses

201Success

401

User doesn't have any of the expected roles: user, superAdmin, integration

post

POST /companies/{companyId}/orders/preview HTTP/1.1
Host: commerce.w3block.io
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 616

{
  "orderProducts": [
    {
      "productId": "3db843f4-1ee6-4f6e-a86d-b0aee938bdde",
      "productTokenId": "3062cdc2-2bd8-4143-8a04-90fc1e607794",
      "resellerId": "123e4567-e89b-12d3-a456-426614174000",
      "selectBestPrice": true,
      "variantIds": [],
      "quantity": "1"
    }
  ],
  "acceptIncompleteCart": true,
  "couponCode": "coupon-code",
  "destinationWalletAddress": "0xd3304183ec1fa687e380b67419875f97f1db05f5",
  "destinationUserId": "123e4567-e89b-12d3-a456-426614174000",
  "anchorPaymentsCurrencyId": "65fe1119-6ec0-4b78-8d30-cb989914bdcb",
  "payments": [
    {
      "currencyId": "65fe1119-6ec0-4b78-8d30-cb989914bdcb",
      "amountType": "percentage",
      "amount": "100",
      "paymentMethod": "pix"
    }
  ]
}

No content

post

Authorizations

Path parameters

companyIdstringRequired

Body

addressIdstring · uuidOptional

destinationWalletAddressstringOptionalExample: 0xd3304183ec1fa687e380b67419875f97f1db05f5

destinationUserIdstring · uuidOptional

signedGasFeestringOptionalDeprecatedExample: ===812hgsahbncva

successUrlstringOptionalExample: https://domain.com

couponCodestringOptionalExample: coupon-code

currencyIdstringOptionalDeprecatedExample: 65fe1119-6ec0-4b78-8d30-cb989914bdcb

paymentMethodstring · enumOptionalDeprecatedExample: pixPossible values:

paymentProviderstring · enumOptionalDeprecatedExample: stripePossible values:

providerInputsobjectOptionalDeprecatedExample: {"ssn":"659.315.680-93","save_credit_card":true,"save_credit_card_name":"My Credit Card"}

acceptSimilarOrderInShortPeriodobjectOptional

When some user tries to create two similar orders in a short period of time, we consider it as an interaction error. Sending this value as true will skip this check and proceed with order creation

Default: falseExample: false

passShareCodeDataobjectOptional

Responses

201Success

application/json

401

User doesn't have any of the expected roles: user, superAdmin, integration

post

POST /companies/{companyId}/orders HTTP/1.1
Host: commerce.w3block.io
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 1107

{
  "orderProducts": [
    {
      "productId": "3db843f4-1ee6-4f6e-a86d-b0aee938bdde",
      "productTokenId": "3062cdc2-2bd8-4143-8a04-90fc1e607794",
      "resellerId": "123e4567-e89b-12d3-a456-426614174000",
      "selectBestPrice": true,
      "variantIds": [],
      "quantity": "1",
      "expectedPrices": [
        {
          "currencyId": "65fe1119-6ec0-4b78-8d30-cb989914bdcb",
          "expectedPrice": "100"
        }
      ]
    }
  ],
  "addressId": null,
  "destinationWalletAddress": "0xd3304183ec1fa687e380b67419875f97f1db05f5",
  "destinationUserId": "123e4567-e89b-12d3-a456-426614174000",
  "signedGasFees": [
    {
      "currencyId": "65fe1119-6ec0-4b78-8d30-cb989914bdcb",
      "signedGasFee": "===812hgsahbncva"
    }
  ],
  "successUrl": "https://domain.com",
  "utmParams": {
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "super_sales",
    "utm_term": "nft",
    "utm_content": "header_banner_link"
  },
  "couponCode": "coupon-code",
  "payments": [
    {
      "currencyId": "65fe1119-6ec0-4b78-8d30-cb989914bdcb",
      "amountType": "percentage",
      "amount": "100",
      "paymentMethod": "pix",
      "paymentProvider": "stripe",
      "providerInputs": {
        "ssn": "659.315.680-93",
        "save_credit_card": true,
        "save_credit_card_name": "My Credit Card"
      }
    }
  ],
  "acceptSimilarOrderInShortPeriod": false,
  "passShareCodeData": {}
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2025-06-01T16:35:57.802Z",
  "updatedAt": "2025-06-01T16:35:57.802Z",
  "companyId": "123e4567-e89b-12d3-a456-426614174000",
  "company": {},
  "userId": "123e4567-e89b-12d3-a456-426614174000",
  "user": {},
  "destinationWalletAddress": "text",
  "addressId": "123e4567-e89b-12d3-a456-426614174000",
  "address": {},
  "status": "pending",
  "deliverDate": "2025-06-01T16:35:57.802Z",
  "expiresIn": "2025-06-01T16:35:57.802Z",
  "deliverId": "B61JHC",
  "products": [
    {}
  ],
  "payments": [
    {}
  ]
}