NFTs and reward fulfillment

Read web3/NFT data and submit reward fulfillment details. Some requests use a direct JSON body while checkout-reservation calls use body.payload.

Access labels such as Origin + Brand key + Customer are defined in Headers and access. Each endpoint ends in a Try it console; set the host and keys once in its Settings tab or on the overview.

Not collectibles

These endpoints deal with tokens held in a customer's own external wallet and the prize forms tied to them. They are separate from Batch collectibles, which are digital tokens with no chain, minting or wallet.

Submit an NFT reward fulfillment form

Method	URL path	Required access
POST	/api/v1/brand/form/create	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
body	object	yes	—
body.walletAddress	string	yes	—
body.name	string	yes	—
body.email	string	yes	Email address
body.addressId	number	optional	—
body.status	string	optional	Allowed values ("pending" , "completed" , "rejected"); Default ("pending")
body.prize	string	yes	—
body.nftId	string	optional	—
body.rewardTypeApplied	array of string	yes	Minimum (1)

Send fields directly in the JSON body, without a payload wrapper.

Example:

curl -X POST "$BASE_URL/api/v1/brand/form/create" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{"walletAddress":"<WALLET_ADDRESS>","name":"Example","email":"alex@example.com","prize":"example","rewardTypeApplied":["example"]}'

Response: Upstream/service JSON is returned directly, without an extra envelope.

Source: app/v1/controller/nft_controller.ts:18 → createForm; routes: routes/v1/nft_route.ts:10; service: _createForm (app/v1/service/nft_service.ts:14).

Submit NFT reward forms in bulk

Submit a non-empty JSON array of NFT fulfillment forms. This request is a top-level array, without a payload wrapper.

Method	URL path	Required access
POST	/api/v1/brand/form/create-bulk	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
body[]	object	yes	—
body[].walletAddress	string	yes	—
body[].name	string	yes	—
body[].email	string	yes	Email address
body[].addressId	number	optional	—
body[].status	string	optional	Allowed values ("pending" , "completed" , "rejected"); Default ("pending")
body[].prize	string	yes	—
body[].nftId	string	optional	—
body[].rewardTypeApplied	array of string	yes	Minimum (1)

Example:

curl -X POST "$BASE_URL/api/v1/brand/form/create-bulk" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '[{"walletAddress":"<WALLET_ADDRESS>","name":"Example","email":"alex@example.com","prize":"example","rewardTypeApplied":["example"]}]'

Response: Upstream/service JSON is returned directly, without an extra envelope. The local service success response includes success, result, total, created, and failed.

Source: app/v1/controller/nft_controller.ts:60 → createFormBulk; routes: routes/v1/nft_route.ts:19; service: _createFormBulk (app/v1/service/nft_service.ts:161).

Fetch a wallet NFT page

Method	URL path	Required access
POST	/api/v1/brand/user/nfts	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
body	object	yes	—
body.address	string	yes	Whitespace trimmed
body.action	string	yes	Whitespace trimmed; Allowed values ("fetchAll" , "loadMore" , "getKiosks" , "getKioskItems" , "getNftObjects")
body.nftType	string	yes	Whitespace trimmed
body.limit	number	optional	—
body.kioskIds	array of string	optional	—
body.cursors	object	optional	—
body.nextKioskCursor	string	optional	—
body.nftObjectIds	array of string	optional	—

Send fields directly in the JSON body, without a payload wrapper.

Example:

curl -X POST "$BASE_URL/api/v1/brand/user/nfts" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{"address":"<WALLET_ADDRESS>","action":"fetchAll","nftType":"example"}'

Response: Upstream/service JSON is returned directly, without an extra envelope.

Source: app/v1/controller/nft_controller.ts:114 → getUserNfts; routes: routes/v1/nft_route.ts:28; service: _getUserNfts (app/v1/service/nft_service.ts:226).

Sync NFT reward items to an order

Method	URL path	Required access
POST	/api/v1/brand/nfts/syncItem	Origin + Brand key + Hub selected + Customer

Request fields:

Field	Type	Required	Rules / meaning
body	object	yes	—
body.addressId	number	yes	—
body.orderType	string	yes	Allowed values ("delivery" , "pos" , "rapid" , "pickup" , "shipment")

Send fields directly in the JSON body, without a payload wrapper.

Example:

curl -X POST "$BASE_URL/api/v1/brand/nfts/syncItem" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{"addressId":1,"orderType":"delivery"}'

Response: JSON with success: true and result containing the operation’s service data.

Source: app/v1/controller/nft_controller.ts:291 → syncItem; routes: routes/v1/nft_route.ts:37; service: _syncItem (app/v1/service/nft_service.ts:517).

Get web3 brand

Method	URL path	Required access
GET	/api/v1/brand/web3/brand	Origin + Brand key

Request fields: no body, query, or path fields are read by this controller. Context comes from the headers/middleware above.

Example:

curl -X GET "$BASE_URL/api/v1/brand/web3/brand" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY"

Response: Upstream/service JSON is returned directly, without an extra envelope.

Source: app/v1/controller/nft_controller.ts:231 → getWeb3Brand; routes: routes/v1/nft_route.ts:46; service: _getWeb3Brand (app/v1/service/nft_service.ts:480).

Find an NFT by a search field

Search by at least one of nftId, tokenId, name, description, or transactionDigest.

Method	URL path	Required access
GET	/api/v1/brand/brand-nft	Origin + Brand key

Request fields:

Field	Type	Required	Rules / meaning
query.description	string	conditional	Supply at least one search field
query.name	string	conditional	Supply at least one search field
query.nftId	string	conditional	Supply at least one search field
query.tokenId	string	conditional	Supply at least one search field
query.transactionDigest	string	conditional	Supply at least one search field

Example:

curl -X GET "$BASE_URL/api/v1/brand/brand-nft?nftId=%3CNFT_ID%3E" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY"

Response: Upstream/service JSON is returned directly, without an extra envelope.

Source: app/v1/controller/nft_controller.ts:158 → getBrandNFTById; routes: routes/v1/nft_route.ts:55; service: _getBrandNFTById (app/v1/service/nft_service.ts:274).

Get brand nf ts

Method	URL path	Required access
GET	/api/v1/brand/brand-nfts	Origin + Brand key

Request fields:

Field	Type	Required	Rules / meaning
query.customerAddress	string	optional	No controller schema
query.description	string	optional	No controller schema
query.limit	string	optional	No controller schema
query.name	string	optional	No controller schema
query.nftId	string	optional	No controller schema
query.offset	string	optional	No controller schema
query.tokenId	string	optional	No controller schema
query.transactionDigest	string	optional	No controller schema

Example:

curl -X GET "$BASE_URL/api/v1/brand/brand-nfts?limit=example&offset=example" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY"

Response: Upstream/service JSON is returned directly, without an extra envelope.

Source: app/v1/controller/nft_controller.ts:183 → getBrandNFTs; routes: routes/v1/nft_route.ts:64; service: _getBrandNFTs (app/v1/service/nft_service.ts:345).

List NFTs grouped by ownership

Method	URL path	Required access
GET	/api/v1/brand/brand-nfts/grouped	Origin + Brand key

Request fields:

Field	Type	Required	Rules / meaning
query	object	optional	Forwarded to web3 service without local validation

The controller forwards query fields to web3 without local Joi validation. The route describes groupBy (default name) and the same filters as brand-nfts: customerAddress, nftId, tokenId, description, name, transactionDigest, limit, offset. Confirm supported grouping values with that service.

Example:

curl -X GET "$BASE_URL/api/v1/brand/brand-nfts/grouped" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY"

Response: Upstream/service JSON is returned directly, without an extra envelope.

Source: app/v1/controller/nft_controller.ts:217 → getBrandNFTsGrouped; routes: routes/v1/nft_route.ts:73; service: _getBrandNFTsGrouped (app/v1/service/nft_service.ts:413).

Get reward checkout status

Method	URL path	Required access
POST	/api/v1/brand/reward/checkout-status	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
body.payload	object	yes	—
body.payload.nftMarketplaceIds	array of string	yes	Minimum (1)

Send body.payload.nftMarketplaceIds. This only checks eligibility; it does not reserve rewards. Read the upstream canCheckout flag before continuing.

Example:

curl -X POST "$BASE_URL/api/v1/brand/reward/checkout-status" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{"payload":{"nftMarketplaceIds":["<NFTMARKETPLACEIDS>"]}}'

Response: Upstream/service JSON is returned directly, without an extra envelope.

Source: app/v1/controller/nft_controller.ts:251 → getRewardCheckoutStatus; routes: routes/v1/nft_route.ts:82.

Mark reward processing

Method	URL path	Required access
POST	/api/v1/brand/reward/processing	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
body.payload	object	yes	—
body.payload.nftMarketplaceIds	array of string	yes	Minimum (1)

Reserve rewards before generating a Shopify checkout link. Continue only when the upstream response reports allClaimed=true.

Example:

curl -X POST "$BASE_URL/api/v1/brand/reward/processing" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{"payload":{"nftMarketplaceIds":["<NFTMARKETPLACEIDS>"]}}'

Response: Upstream/service JSON is returned directly, without an extra envelope.

Source: app/v1/controller/nft_controller.ts:271 → markRewardProcessing; routes: routes/v1/nft_route.ts:91.

Related pages

• Batch Commerce API overview
• Wallets and NFT prizes
• Implementation notes