Create a certificate with redeem code

Description

This API endpoint is suitable for a gift card creation, or cases if which you would like to allow a receiver to add it’s name or the recipient name, and get / send it by email.

The user flow:

The user will get the gift card / impact from your platform (redeem URL + code )
The user will visit the redeem URL (the code can be prefilled in the form using the “ac” param, for example, https://impact.dots.eco/app/[app-id]/eco-club/claim?ac=[code] and add his email address
The user will add his / the recipient's name
If there is more than one allocation defined for the offering, the user will select the impact type
The user will get the certificate on his browser and by email

Request a new eco club offering.

POST https://impact.dots.eco/api/v1/eco-club-offering/add

Please check Headers and authorization.

Example body

{
    "app_token": "101-5653d113",
    "quantity": 10,
    "limit_allocations": "32,31,14",
    "name_on_certificate": "John Doe",
    "activation_date": "2022-12-24",
    "activation_hour": "01:00:00",
    "expiration_date": "2022-12-31",
    "expiration_hour": "01:00:00",
    "send_email_on_activation_date": "yes",
    "code": "e-826254",
    "mail": "test@test.com",
    "title": "Test title",
    "remote_user_id": "remote_user_id_example",
    "max_claims_total": 3,
    "max_claims_per_email": 2,
    "langcode": "en",
    "currency": "USD",
    "external_unique_id": "2132-1232-22"
}

Parameters

app_token - required^*, string - The app token can be found in the app dashboard.

quantity - required^*, integer max_value=10^11 - The impact quantity for the created offering.

mail - optional for code-only clubs, string - Set the email address associated with this offering.

limit_allocations - optional, string - Ids of the Allocations to set for this offering. A comma separated values for allocation ids is accepted.

name_on_certificate - optional, string max_length=255 - The name of the user that certificate is issued for.

activation_date - optional, date - The activation date of this offering.

activation_hour - optional, hour - the activation GMT time of this offering. Activation time must be set in 15-minute increments: :00, :15, :30, or :45. If a time outside of these increments is provided, it will automatically be rounded to the nearest 15-minute window.

expiration_date - optional, date - The expiration date of this offering.

expiration_hour - optional, hour - The expiration GMT time of this offering. Expiration time must be set in 15-minute increments: :00, :15, :30, or :45. If a time outside of these increments is provided, it will automatically be rounded to the nearest 15-minute window.

* We always aim to send the activation email from Dots.eco promptly. However, sometimes emails can take a little longer than expected to arrive due to technical reasons beyond our control. If you don't receive the email right away, please be patient and also check your spam or junk folders just in case.

send_email_on_activation_date - optional, string - if equal to yes the activation email will be sent to mail,
if equal to no activation email will not be sent. When the parameter is not provided, default value is set based on application settings.

code - optional, string max_length=255 - Set the activation code for this offering. If code is provided it has to be unique.

mail - optional, string - Set the user for this offering. Eco Club Offering can be created with mail only when Code Only Club is unchecked.

title - optional, string max_length=255 - Set the title for the eco club offering entity.

remote_user_id - optional, string - set the user for this offering. Eco Club Offering can be created with remote_user_id when use remote_user_id instead of email in Eco Club Offerings is check.

max_claims_total - optional, integer max_value=10^11, only available for code-only clubs - set the number of times users can claim the offer.

max_claims_per_email - optional, integer max_value=10^11, only available for code-only clubs - set the number of times the same email can claim the offer.

langcode - optional, string max_length=12 - Returns the response in the provided language code, with the claim URL in the correct language. List of supported languages can be found here.

currency - optional, string max_length=255 - set the currency for the eco club offering. List of supported currencies can be found here.

external_unique_id - optional, string max_length=255 - Unique identifier for the eco club offerings. If provided, must be unique across all eco club offerings.

Error Recovery: In the event of system malfunctions, the External unique ID is the sole identifier that can be used to assess if a request was processed, ensuring that administrators or automated systems can recover or retry operations without duplication.
Preventing Duplicate Processing: The External unique ID helps prevent duplicate processing by confirming whether a request has already been handled, even when regular status flags or logs are incomplete or corrupted.

Example request

The minimal request that will work with a code-only club. The other clubs

curl --location --request POST 'https://impact.dots.eco/api/v1/eco-club-offering/add' \
--header 'Content-Type: application/json' \
--header 'auth-token: YOUR_AUTH_TOKEN' \
--data-raw '{
    "app_token": "YOUR_APPLICATION_TOKEN",
    "quantity": 10
}'

Key/Value pairs response body

"uuid": [string]: The uuid for the eco club offering entity.
"quantity": [integer] - The impact quantity for the created offering.
"limit_allocations": [string] - A comma separated values of the Allocations to set for this offering.
"name_on_certificate": [string] - The name of the user that certificate is issued for.
"activation_date": [string] - The activation date of this offering.
"activation_hour": [string] - The activation hour in GMT time.
"expiration_date": [string] - The expiration date of this offering,
"expiration_hour": [string] - The expiration hour in GMT time,
"code": [string] - The activation code for this offering.
"mail": [string] - The user for this offering.
"title": [string] - The title for the eco club offering entity.
"max_claims_total": [integer] - The amount how many times offering can be claimed.
"max_claims_per_email": [string/integer] - The amount how many times the same email can be used.
"send_email_on_activation_date": [string] - The information if email will be sent on activation date.
"remote_user_id": [string] - The remote user id.
"claim_url": [URL] - URL to the claim form. Will return the claim URL according the requested language. Default is English.
"external_unique_id": [string] - External ID of that offerings

Example response

success

{
    "uuid": "1da0ef10-edb2-4142-badb-8b9d8e83c2f6",
    "quantity": 10,
    "limit_allocations": "32,31,14",
    "name_on_certificate": "John Doe",
    "activation_date": "2022-12-24",
    "activation_hour": "01:00:00",
    "expiration_date": "2022-12-31",
    "expiration_hour": "01:00:00",
    "code": "e-826254",
    "mail": "test@test.com",
    "title": "Test title",
    "max_claims_total": 3,
    "max_claims_per_email": 2,
    "send_email_on_activation_date": "yes",
    "remote_user_id": "remote_user_id_example",
    "claim_url": "https://impact.dots.eco/app/6/eco-club/claim",
    "external_unique_id": "2132-1232-22"
}