Orders

Orders are specific amounts of CO_2eq to be offset. The requested quantity will be deducted from the account balance. You can generate orders on behalf of your customers using the "certificateRecipientInfo" property in our requests.

You can cancel orders up to 10 days after the purchase or before the certificates are issued.

Order [POST]

BASE URL

https://api-b2b-hml.carbonext.com.br/v1/orders

This request creates an order. In our platform, every order with status PAID generates a CARBONEXT certificate and orders are accumulated to generate VERRA certificates (which are issued when we retire the credits from the VERRA platform). However, the VERRA platform only allows to retire whole numbers: one, two, ten, etc.

To help you design the best integration scenario, we offer four ways to accumulate the credits to generate a VERRA certificate (retirement). You can use the certificateRecipientInfo attribute to control to recipients of the certificates. The options are described below:

Retirement Options

You get the CARBONEXT certificate and we accumulate the credits for your TaxId. In this scenario you DO NOT send certificateRecipientInfo.

{
        "vcuAmount": 0.02,
        "targetCurrency": "BRL",
        "payWithBalance": true
}

Another person receives the CARBONEXT certificate and we accumulate the credits for your TaxId. In this scenario you need to send the information of the CARBOENEXT recipient and also to send your information in order to accumulate the creditis to your TaxId.

{
        "vcuAmount": 0.02,
        "targetCurrency": "BRL",
        "payWithBalance": true,
        "certificateRecipientInfo":{
                "name": "Example First",
                "email": "example@email.com",
                "taxId": "000.000.000-00",
                "retirementName": "<your-name>",
                "retirementEmail": "<your-email>",
                "retirementTaxId": "<your-taxid>"
        }
}

Another person receiveis the CARBONEXT certificate and we accumulate the credits for the TaxId of that person. In this scenario you only send information for the recipient and we issue the CARBONEXT certificate and accumulate credits for the same recipient.

{
        "vcuAmount": 0.02,
        "targetCurrency": "BRL",
        "payWithBalance": true,
        "certificateRecipientInfo":{
                "name": "Example First",
                "email": "example@email.com",
                "taxId": "000.000.000-00",
        }
}

The CARBONEXT and VERRA certificates are issued to different persons, the credits are accumulate to the person you chose as recipient of the certificate. In this scenario, just like in scenario number 2, you send the information for the CARBONEXT certificate recipient as well as the information for the retirement recipient.

{
        "vcuAmount": 0.02,
        "targetCurrency": "BRL",
        "payWithBalance": true,
        "certificateRecipientInfo":{
                "name": "Example First",
                "email": "example@email.com",
                "taxId": "000.000.000-00",
                "retirementName": "Retirement Recipient",
                "retirementEmail": "retirement-recipient@email.com",
                "retirementTaxId": "00.000.000/0001-55"
        }
}

Request Attributes

Attribute	Description
vcuAmount	The amount of VCUs assigned to the order
targetCurrency	The desired currency for the order to be charged in
payWithBalance	Flag to inform if you wish to pay the order with you current balance. If true, the order will be created with status PAID and the CARBONEXT certificate will be issued in a few moments
certificateRecipientInfo	Information of the person to whom the certificate will be issued, if not present we issue certificate and accumulate credits according to scenario 1 of the retirement options
metaData	String field you can use to write extra information about your order. Up to 500 characters

CertificateRecipientInfo	Description
name	Name of the party to whom the certificate will be issued
email	E-mail address of the party to whom the certificate will be issued for. The certificate will be sent to this email
taxId	Document ID of the party to whom the certificate will be issued
retirementName	Name of the party to whom the VERRA certificate will be issued
RetirementEmail	E-mail address of the party to whom the VERRA certificate will be issued for. The certificate will be sent to this email
retirementTaxId	Document ID of the party to whom the VERRA certificate will be issued. We will accumulate credits for this TaxId and issue a retirement every time the accumulated total is greater than 1 VCU

Response Attributes

Attribute	Description
id	The generated order ID
vcuAmount	The total amount of VCUs requested in the order
vcuUnitPrice	The unit price of a VCU at the time of order completion
targetCurrency	The currency in which the order will be charged
status	Discloses the order's current status
createdAt	Discloses the order's current status
metaData	String field you can use to write extra information about your order. Up to 500 characters

Example Request

var axios = require('axios');
var data = JSON.stringify({
        "vcuAmount": 0.02,
        "targetCurrency": "BRL",
        "payWithBalance": true,
        "certificateRecipientInfo": {
                "name": "Example First",
                "email": "example@email.com",
                "taxId": "000.000.000-00",
                "retirementName": "Example Second",
                "retirementEmail": "second@email.com",
                "retirementTaxId": "000.000.000-01"
        }
});

var config = {
        method: 'post',
        url: 'https://api-b2b-hml.carbonext.com.br/v1/orders',
        headers: { 
                'Authorization': 'Bearer <access_token>', 
                'Content-Type': 'application/json'
        },
        data : data
};

axios(config)
        .then(function (response) {
                console.log(JSON.stringify(response.data));
        })
        .catch(function (error) {
                console.log(error);
        });

Example Response

{
        "id": "4158d5d1-9364-46e6-8d0d-451f528261e7",
        "vcuAmount": 0.02,
        "vcuUnitPrice": 110.0,
        "totalPrice": 2.200,
        "targetCurrency": "BRL",
        "status": "Issued",
        "createdAt": "2022-07-24T18:26:44.4176783Z",
        "notifyCertificateTo": null,
        "type": "Postpaid",
        "paymentDate": null,
        "metaData": null,
        "payWithBalance": true,
        "certificateRecipientInfo": {
                "name": "Example First",
                "email": "example@email.com",
                "taxId": "000.000.000-00",
                "retirementName": "Example Second",
                "retirementEmail": "second@email.com",
                "retirementTaxId": "000.000.000-01"
        }
}

Orders [GET]

BASE URL

https://api-b2b-hml.carbonext.com.br/v1/orders?page=1&page-size=6

This request returns a paginated list of orders.

Response attributes

Attribute	Description
items	An array of paginated orders from the customer

Example Request

var axios = require('axios');

var config = {
        method: 'get',
        url: 'https://api-b2b-hml.carbonext.com.br/v1/orders?page=1&page-size=100&sort-by=createdAt_desc',
        headers: { 
                'Authorization': 'Bearer <access_token>',
        }
};

axios(config)
        .then(function (response) {
                console.log(JSON.stringify(response.data));
        })
        .catch(function (error) {
                console.log(error);
        });

Example Response

{
        "items": [
                {
                        "id": "4158d5d1-9364-46e6-8d0d-451f528261e7",
                        "vcuAmount": 0.02,
                        "vcuUnitPrice": 110.0,
                        "totalPrice": 2.200,
                        "targetCurrency": "BRL",
                        "status": "Cancelled",
                        "createdAt": "2022-07-24T18:26:44.417678",
                        "notifyCertificateTo": null,
                        "type": "Postpaid",
                        "paymentDate": null,
                        "metaData": null,
                        "retireForRecipient": false,
                        "certificateRecipientInfo": {
                                "name": "Example First",
                                "email": "example@email.com",
                                "taxId": "000.000.000-00"
                        },
                        "invoices": [],
                        "subscriptions": []
                },
                {
                        "id": "07c8543f-752f-43c7-af65-04a6cf3c8841",
                        "vcuAmount": 0.02,
                        "vcuUnitPrice": 110.00,
                        "totalPrice": 2.2000,
                        "targetCurrency": "BRL",
                        "status": "Issued",
                        "createdAt": "2022-07-21T19:11:05.698421",
                        "notifyCertificateTo": null,
                        "type": "Postpaid",
                        "paymentDate": null,
                        "metaData": null,
                        "retireForRecipient": false,
                        "certificateRecipientInfo": {
                                "name": "Example First",
                                "email": "example@email.com",
                                "taxId": "000.000.000-00"
                        },
                        "invoices": [],
                        "subscriptions": []
                }
        ],
        "pageIndex": 1,
        "totalPages": 1,
        "totalCount": 2,
        "aggregations": null,
        "hasPreviousPage": false,
        "hasNextPage": false
}

PARAMS

page: 1
page-size: 6

Cancel Order [POST]

BASE URL

https://api-b2b-hml.carbonext.com.br/v1/orders/:orderId/cancel

This request cancels a pending payment order (Issued status).

Response Attributes

Attribute	Description
Id	The order's Id
vcuAmount	The amount of VCUs that this order was handling
vcuUnitPrice	The VCU price when the order was created
targetCurrency	The currency this order was being handled in.
status	Name of the order's current status, the value will be "Canceled"
createdAt	The date and time this order was created
metaData	String field you can use to write extra information about your order. Up to 500 characters

Example Request

var axios = require('axios');

var config = {
        method: 'post',
        url: 'https://api-b2b-hml.carbonext.com.br/v1/orders/4158d5d1-9364-46e6-8d0d-451f528261e7/cancel',
        headers: { 
                'Authorization': 'Bearer <access_token>',
        }
};

axios(config)
        .then(function (response) {
                console.log(JSON.stringify(response.data));
        })
        .catch(function (error) {
                console.log(error);
        });

Example Response

{
        "id": "4158d5d1-9364-46e6-8d0d-451f528261e7",
        "vcuAmount": 0.02,
        "vcuUnitPrice": 110.0,
        "totalPrice": 2.200,
        "targetCurrency": "BRL",
        "status": "Cancelled",
        "createdAt": "2022-07-24T18:26:44.417678",
        "notifyCertificateTo": null,
        "type": "Postpaid",
        "paymentDate": null,
        "metaData": null,
        "retireForRecipient": false,
        "certificateRecipientInfo": {
                "name": "Example First",
                "email": "example@email.com",
                "taxId": "000.000.000-00"
  }
}

PATH VARIABLES

orderId: 4158d5d1-9364-46e6-8d0d-451f528261e7

Cancel Orders [POST]

BASE URL

https://api-b2b-hml.carbonext.com.br/v1/orders/cancel

Orders can also be canceled in batches.

Request parameters

Parameter	Description
ordersIds	An array of Ids of the orders to be canceled

Example Request

var axios = require('axios');
var data = JSON.stringify({
    "ordersIds":
    [
        "cefefeb3-2b25-eeee-b800-6e5c5f86614f",
        "c0fefef3-2b25-46fc-b800-6e5c5f86614f",
        "c0396eb3-2b25-46fc-b800-6e5c5f86614f"
    ]  
});

var config = {
        method: 'post',
        url: 'https://api-b2b-hml.carbonext.com.br/v1/orders/cancel',
        headers: { 
                'Authorization': 'Bearer <access_token>',
        },
        data: data
};

axios(config)
        .then(function (response) {
                console.log(JSON.stringify(response.data));
        })
        .catch(function (error) {
                console.log(error);
        });

Example Response

{
     true
}

Orders

Order [POST]​

Retirement Options​

Example Request​

Example Response​

Orders [GET]​

Example Request​

Example Response​

Cancel Order [POST]​

Example Request​

Example Response​

Cancel Orders [POST]​

Example Request​

Example Response​

Order [POST]

Retirement Options

Example Request

Example Response

Orders [GET]

Example Request

Example Response

Cancel Order [POST]

Example Request

Example Response

Cancel Orders [POST]

Example Request

Example Response