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:

get
Authorizations
AuthorizationstringRequired

Enter JWT token

Path parameters
companyIdstringRequired
Query parameters
createdAtstringOptionalExample: 2022-01-30T10:30:40-03:00
sortBystring[]Optional
orderBystring · enumOptionalPossible values:
pagenumberOptionalDefault: 1Example: 1
limitnumberOptionalDefault: 10Example: 10
searchstringOptional
Responses
200Success
application/json
get
/companies/{companyId}/orders

Get logged-in user order by id

Using SDK

Rest API reference:

get
Authorizations
AuthorizationstringRequired

Enter JWT token

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
200Success
application/json
get
/companies/{companyId}/orders/{orderId}

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

Rest API reference:

post
Authorizations
AuthorizationstringRequired

Enter JWT token

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
post
/companies/{companyId}/orders/preview
No content

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

Rest API reference:

post
Authorizations
AuthorizationstringRequired

Enter JWT token

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
post
/companies/{companyId}/orders
PreviousProductsNextWebhooks

Last updated