🚧
Beta Feature
Please note that this feature is currently in beta.
It might contain bugs or errors that could lead to unexpected behaviors. We highly recommend testing all beta features thoroughly in a controlled, non-production environment before deploying it into production.
We value your feedback. Should you encounter any problems or bugs, or if you have any suggestions for improvements, please report them in the Co:Create Discord.

Overview

Co:Create's Redemption API enables you to reward your users by allowing them to exchange their ERC-20 tokens for ERC-721 or ERC-1155 tokens.

Use Cases

Online Gaming: With many online games, players often earn in-game currency by completing tasks, winning battles, etc. With the Redemption API, you can allow players to redeem these tokens for special in-game assets, such as unique characters, weapons, or skins, represented as ERC-721 or ERC-1155 tokens. This encourages continued engagement and provides a rewarding experience for the players.
Loyalty Programs: Retail companies can use this API to manage their loyalty program rewards. Members can earn ERC-20 tokens for purchases and then redeem them for rewards, such as exclusive products, discounts, or services, represented as NFTs. This not only boosts customer engagement but also provides a unique, web3-based approach to loyalty programs.
Content Creation Platforms: Social media or content creation platforms can offer ERC-20 tokens to creators based on the popularity of their content. These tokens could then be redeemed for premium features or services, such as enhanced visibility, promotion, or access to exclusive creator tools enabled by NFTs.

How It Works

Redemptions are created by you, and can be claimed by your users (when eligible).

Users exchange their ERC-20 tokens for something rare or desirable, as represented by ERC-721 or ERC-1155 tokens. During the redemption, the ERC-721 or ERC-1155 will be minted on demand by the Co:Create Platform to the user's wallet, and the user's ERC-20 tokens burned by the Platform.

Using the Redemption API

At a simplified level, the Redemption API workflow is the following:

Create a redemption -- Create the redemption using the payable token id (ERC-20), the receivable token id (ERC-721 or ERC-1155), the price per redemption, and any other parameters you wish to set.
Redeem reward -- Provide the redemption id, the user's email, and the number of ERC-20 tokens to redeem to trigger the redemption.

Requirements

You have created an ERC-20 token.
You have created an ERC-721 or ERC-1155 token.

Note: Using Co:Create's Synchronous or Asynchronous APIs to create your token doesn't matter, so long as you have the token ids associated with the tokens you would like to configure the redemption with.

Endpoints

The base URL for the Redemption API is https://api.testcocrt.xyz/alpha/redemption.

Endpoint	Type	Description
Create Redemption	POST	Create a redemption.
List Redemptions	GET	List all redemptions for your org.
Get Redemption	GET	Retrieve a redemption by redemption ID, to fetch detailed information about a specific redemption.
Update Redemption	PATCH	Update an existing redemption to make modifications to a redemption after it has been created. Note: Updates to redemption status are performed using the specified endpoints below.
Delete Redemption	DELETE	Remove a redemption by redemption ID, to remove a redemption that is no longer needed.
Resume Redemption	POST	Sets the redemption status to active.
Pause Redemption	POST	Sets the redemption status to draft and prevents further redemptions from taking place. Can be set to resume from this status.
Cancel Redemption	POST	Sets the redemption status to draft and prevents further redemptions from taking place. Redemption cannot be set to active again.
Redeem Reward	POST	Redeems the reward for the user. A successful request results in ERC-20 tokens burned in the amount of the redemption price, and the reward minted to the user's wallet.
List Redeem request	GET	List redeem requests in a single redemption by providing redemption id.
Get Redeem Request details	GET	Retrieve detailed information about a redeem request by providing redemption id and redeem request id.

Example - ERC721

The following example will walk through a Redemption workflow where the reward is an ERC-721:

Creating a Redemption
Redeeming a Reward
Updating a Redemption
Pausing, Resuming, and Cancelling a Redemption

Creating a Redemption

Consider an existing ERC20 token, called DOGZ, that's being distributed to a community. This token has an erc20_id = d56a253a-7b04-41f0-9cd2-04318877afd2.

The owner of the DOGZ token would like to enable their community members to redeem their DOGZ tokens for TREATZ, a new and exclusive NFT collection that's just been created using Co:Create by the owner. TREATZ is an ERC721 token with an erc721_id = 002b0807-48e1-43f5-8432-d018c6d0eadb.

The DOGZ owner would like the redemption to be configured as follows:

The community to be able to redeem 1,000 DOGZ for 1 TREATZ
There to be 100 total TREATZ available for redemption
Each user can only claim 1 TREATZ per redemption transaction

They would like the redemption to start immediately and stop at the end of 2023.

Example Create Redemption request for this scenario:

curl --request POST \
     --url https://api.testcocrt.xyz/alpha/redemption \
     --header 'Authorization: Bearer [YOUR_KEY_HERE]' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "erc20_id": "d56a253a-7b04-41f0-9cd2-04318877afd2",
  "reward_id": "002b0807-48e1-43f5-8432-d018c6d0eadb",
	"reward_type": "erc721",
  "price_per_redemption": 1000,
  "max_rewards_per_transaction": 1,
  "max_redemption_supply": 100,
  "status": "active",
  "end_date": "2023-12-31T23:59:00.000"
}
'

Here's the response that would be received:

{
  "data": {
    "id": "3b919f2f-caef-4523-93a4-740a53854bf7",
    "org_id": "nifty_swanson_74",
    "erc20_id": "d56a253a-7b04-41f0-9cd2-04318877afd2",
    "reward_id": "002b0807-48e1-43f5-8432-d018c6d0eadb",
    "reward_type": "erc721",
    "reward_token_id": null,
    "price_per_redemption": 1000,
    "max_rewards_per_transaction": 1,
    "max_reward_supply": null,
    "start_date": null,
    "end_date": "2023-12-31T23:59:00+00:00",
    "status": "active",
    "total_redemptions": 0,
    "created_at": "2023-07-19T20:34:53.309155+00:00"
  }
}

📘
Using Start & End Dates
To enable more control over when a redemption can begin, and for how long it will run, use start & end dates.

All start dates & end dates must be in the future. Start dates cannot be later than or equal to end dates.

You may only pass an active status in the request body as a parameter if and only if a start date is not also passed in the body as a parameter (i.e. there is no defined start date).

If a start date is passed in the body as a parameter, the start date must be in the future and the status will default to draft whether an draft status is passed or not. When the start date arrives, the Co:Create platform will automatically set the status to active on your behalf.

Redeeming a Reward

Continuing with the DOGZ example outlined above, a user with the email address [email protected] would like to redeem 1000 DOGZ for 1 TREATZ. To do so, they would submit a POST request to the redeem endpoint.

Example Redeem Request for this scenario:

curl --request POST \
     --url https://api.testcocrt.xyz/alpha/redemption/3b919f2f-caef-4523-93a4-740a53854bf7/redeem \
     --header 'Authorization: Bearer [YOUR_KEY_HERE]' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "email": "[email protected]",
  "reward_quantity_to_obtain": 1
}
'

Here's the response received:

{
  "data": {
    "id": "550550b9-b4e6-4b12-ab50-908f3ba75b86",
    "redemption_id": "3b919f2f-caef-4523-93a4-740a53854bf7",
    "org_id": "nifty_swanson_74",
    "reward_quantity_to_obtain": 1,
    "email": "[email protected]",
    "created_at": "2023-07-19T20:34:53.309155+00:00"
  }
}

Updating a Redemption

In the meantime the DOGZ team created a separate redemption (with id 04ccd7ad-f5bb-4a5a-8b6f-501486acd852), and seeing the success of the first one they would like to update the end_date of the new one to the end of 2024 & increase to supply from 100 to 200 total TREATZ to allow for more community members to claim TREATZ.

To do this, they would make a PATCH request to the Redemption endpoint with the two parameters that they would like to update.

Example Update Request for this scenario:

curl --request PATCH \
     --url https://api.testcocrt.xyz/alpha/redemption/04ccd7ad-f5bb-4a5a-8b6f-501486acd852 \
     --header 'Authorization: Bearer [YOUR_KEY_HERE]' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "end_date": "2024-12-31T23:59:00.000",
  "max_redemption_supply": 200
}
'

Here's the response received:

{
  "data": {
    "id": "04ccd7ad-f5bb-4a5a-8b6f-501486acd852",
    "org_id": "nifty_swanson_74",
    "erc20_id": "d56a253a-7b04-41f0-9cd2-04318877afd2",
    "reward_id": "002b0807-48e1-43f5-8432-d018c6d0eadb",
    "reward_type": "erc721",
    "reward_token_id": null,
    "price_per_redemption": 1000,
    "max_rewards_per_transaction": 1,
    "max_reward_supply": null,
    "start_date": null,
    "end_date": "2024-12-31T23:59:00+00:00",
    "status": "draft",
    "total_redemptions": 2,
    "created_at": "2023-07-19T20:34:53.309155+00:00"
  }
}

Listing all redeem requests

At any given time you can list all redeem requests that have been created for a given redemption. For our original TREATZ redemption this would look as follows:

curl --request GET \
     --url https://api.testcocrt.xyz/alpha/redemption/3b919f2f-caef-4523-93a4-740a53854bf7/redeem \
     --header 'Authorization: Bearer [YOUR_KEY_HERE]'

With the response:

{
  "data":[
  	{
    	"id": "550550b9-b4e6-4b12-ab50-908f3ba75b86",
    	"redemption_id": "3b919f2f-caef-4523-93a4-740a53854bf7",
    	"org_id": "nifty_swanson_74",
    	"reward_quantity_to_obtain": 1,
    	"email": "[email protected]",
    	"created_at": "2023-07-19T20:34:53.309155+00:00"
  	},
    {
     	"id": "32fcb78d-da16-4c78-a766-8f63b365dcd7",
    	"redemption_id": "3b919f2f-caef-4523-93a4-740a53854bf7",
    	"org_id": "nifty_swanson_74",
    	"reward_quantity_to_obtain": 3,
    	"email": "[email protected]",
    	"created_at": "2023-08-19T20:34:53.309155+00:00" 
  	}]
}

State Management - Pausing, Resuming, and Cancelling a Redemption

📘
Pause vs. Cancel - What's the difference?

Paused redemptions can be resumed.

Cancelled redemptions cannot be resumed. A new redemption must be created.

Pause

Pause Example Request

curl --request POST \
     --url https://api.testcocrt.xyz/alpha/redemption/3b919f2f-caef-4523-93a4-740a53854bf7/pause \
     --header 'Authorization: Bearer [YOUR_KEY_HERE]' \
     --header 'accept: application/json'

Pause Example Response

{
  "data": {
    "id": "3b919f2f-caef-4523-93a4-740a53854bf7",
    "org_id": "nifty_swanson_74",
    "erc20_id": "d56a253a-7b04-41f0-9cd2-04318877afd2",
    "reward_id": "002b0807-48e1-43f5-8432-d018c6d0eadb",
    "reward_type": "erc721",
    "reward_token_id": null,
    "price_per_redemption": 1000,
    "max_rewards_per_transaction": 1,
    "max_reward_supply": null,
    "start_date": null,
    "end_date": "2024-12-31T23:59:00+00:00",
    "status": "paused",
    "total_redemptions": 2,
    "created_at": "2023-07-19T20:34:53.309155+00:00"
  }
}

Resume

Resume Example Request

curl --request POST \
     --url https://api.testcocrt.xyz/alpha/redemption/3b919f2f-caef-4523-93a4-740a53854bf7/resume \
     --header 'Authorization: Bearer [YOUR_KEY_HERE]' \
     --header 'accept: application/json'

Resume Example Response

{
  "data": {
    "id": "3b919f2f-caef-4523-93a4-740a53854bf7",
    "org_id": "nifty_swanson_74",
    "erc20_id": "d56a253a-7b04-41f0-9cd2-04318877afd2",
    "reward_id": "002b0807-48e1-43f5-8432-d018c6d0eadb",
    "reward_type": "erc721",
    "reward_token_id": null,
    "price_per_redemption": 1000,
    "max_rewards_per_transaction": 1,
    "max_reward_supply": null,
    "start_date": null,
    "end_date": "2024-12-31T23:59:00+00:00",
    "status": "active",
    "total_redemptions": 2,
    "created_at": "2023-07-19T20:34:53.309155+00:00"
  }
}

Cancel

Cancel Example Response

curl --request POST \
     --url https://api.testcocrt.xyz/alpha/redemption/e2a47a9d-0b6c-4878-9537-c5fbfa298ecb/cancel \
     --header 'Authorization: Bearer [YOUR_KEY_HERE]' \
     --header 'accept: application/json'

Cancel Example Request

{
  "data": {
    "id": "e2a47a9d-0b6c-4878-9537-c5fbfa298ecb",
    "org_id": "nifty_swanson_74",
    "erc20_id": "d56a253a-7b04-41f0-9cd2-04318877afd2",
    "reward_id": "002b0807-48e1-43f5-8432-d018c6d0eadb",
    "reward_type": "erc721",
    "reward_token_id": null,
    "price_per_redemption": 1000,
    "max_rewards_per_transaction": 1,
    "max_reward_supply": null,
    "start_date": null,
    "end_date": "2023-12-31T23:59:00+00:00",
    "status": "canceled",
    "total_redemptions": 3,
    "created_at": "2023-07-19T20:27:34.597155+00:00"
  }
}

Delete

Delete Example Request

curl --request DELETE \
     --url https://api.testcocrt.xyz/alpha/redemption/e2a47a9d-0b6c-4878-9537-c5fbfa298ecb \
     --header 'Authorization: Bearer [YOUR_KEY_HERE]' \
     --header 'accept: application/json'

Delete Example Response

{
  "data": {
    "id": "e2a47a9d-0b6c-4878-9537-c5fbfa298ecb"
  }
}

👍
Get Help
If you get stuck at any time, reach out to us on Discord or contact us via email at [email protected].

🏆 Redemptions

🚧
Beta Feature

Overview

Use Cases

How It Works

Using the Redemption API

Requirements

Endpoints

Example - ERC721

Creating a Redemption

📘
Using Start & End Dates

Redeeming a Reward

Updating a Redemption

Listing all redeem requests

State Management - Pausing, Resuming, and Cancelling a Redemption

📘
Pause vs. Cancel - What's the difference?

Pause

Resume

Cancel

Delete

👍
Get Help

🚧Beta Feature

Overview

Use Cases

How It Works

Using the Redemption API

Requirements

Endpoints

Example - ERC721

Creating a Redemption

📘Using Start & End Dates

Redeeming a Reward

Updating a Redemption

Listing all redeem requests

State Management - Pausing, Resuming, and Cancelling a Redemption

📘Pause vs. Cancel - What's the difference?

Pause

Resume

Cancel

Delete

👍Get Help

🚧
Beta Feature

📘
Using Start & End Dates

📘
Pause vs. Cancel - What's the difference?

👍
Get Help