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:

get

Authorizations

Path parameters

companyIdstringrequired

Query parameters

createdAtstringoptionalExample: 2022-01-30T10:30:40-03:00

sortBystring[]optional

orderBystring · enumoptionalAvailable options:

pagenumberoptionalDefault: 1Example: 1

limitnumberoptionalDefault: 10Example: 10

searchstringoptional

statusstring · enum[]optionalExample: ["pending"]

Responses

application/json

get

curl -L \
  --url 'https://commerce.w3block.io/companies/{companyId}/orders' \
  --header 'Authorization: Bearer JWT'

200

401

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "createdAt": "2025-04-10T15:30:02.722Z",
      "updatedAt": "2025-04-10T15:30:02.722Z",
      "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-04-10T15:30:02.722Z",
      "expiresIn": "2025-04-10T15:30:02.722Z",
      "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"
  }
}

get

Authorizations

Path parameters

companyIdstringrequired

orderIdstringrequired

Query parameters

fetchNewestStatusbooleanoptional

Use this attribute to force fetching the newest status available based on payment driver used.

Default: falseExample: false

Responses

application/json

get

curl -L \
  --url 'https://commerce.w3block.io/companies/{companyId}/orders/{orderId}' \
  --header 'Authorization: Bearer JWT'

200

401

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2025-04-10T15:30:02.722Z",
  "updatedAt": "2025-04-10T15:30:02.722Z",
  "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-04-10T15:30:02.722Z",
  "expiresIn": "2025-04-10T15:30:02.722Z",
  "deliverId": "B61JHC",
  "products": [
    {}
  ],
  "payments": [
    {}
  ]
}

post

Authorizations

Path parameters

companyIdstringrequired

Body

orderProductsobject[]required

acceptIncompleteCartobjectoptionalDefault: trueExample: true

couponCodestringoptionalExample: coupon-code

destinationWalletAddressstringoptionalExample: 0xd3304183ec1fa687e380b67419875f97f1db05f5

destinationUserIdstring · uuidoptional

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

paymentMethodstring · enumoptionalDeprecatedExample: pixAvailable options:

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

paymentsobject[]required

Responses

post

curl -L \
  --request POST \
  --url 'https://commerce.w3block.io/companies/{companyId}/orders/preview' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "orderProducts": [
      {
        "productId": "3db843f4-1ee6-4f6e-a86d-b0aee938bdde",
        "productTokenId": "3062cdc2-2bd8-4143-8a04-90fc1e607794",
        "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"
      }
    ]
  }'

201

401

No Content

post

Authorizations

Path parameters

companyIdstringrequired

Body

orderProductsobject[]required

addressIdstring · uuidoptional

destinationWalletAddressstringoptionalExample: 0xd3304183ec1fa687e380b67419875f97f1db05f5

destinationUserIdstring · uuidoptional

signedGasFeestringoptionalDeprecatedExample: ===812hgsahbncva

signedGasFeesobject[]required

successUrlstringoptionalExample: https://domain.com

utmParamsobjectoptional

couponCodestringoptionalExample: coupon-code

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

paymentMethodstring · enumoptionalDeprecatedExample: pixAvailable options:

paymentProviderstring · enumoptionalDeprecatedExample: stripeAvailable options:

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

paymentsobject[]required

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

application/json

post

curl -L \
  --request POST \
  --url 'https://commerce.w3block.io/companies/{companyId}/orders' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "orderProducts": [
      {
        "productId": "3db843f4-1ee6-4f6e-a86d-b0aee938bdde",
        "productTokenId": "3062cdc2-2bd8-4143-8a04-90fc1e607794",
        "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": {}
  }'

201

401

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2025-04-10T15:30:02.722Z",
  "updatedAt": "2025-04-10T15:30:02.722Z",
  "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-04-10T15:30:02.722Z",
  "expiresIn": "2025-04-10T15:30:02.722Z",
  "deliverId": "B61JHC",
  "products": [
    {}
  ],
  "payments": [
    {}
  ]
}

Service Methods

List logged-in user orders

Get logged-in user order by id

Creates an order preview

Creates an order

Service Methods

List logged-in user orders

Get logged-in user order by id

Creates an order preview

Creates an order

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Show child attributes