AI-ready version:

Create a Certificate with Redeem Code

Description

This API is used to create a gift card certificate or an Eco Club offering with specific configurations. It allows recipients to personalize the certificate, claim it via a redeem URL, and optionally receive it by email.

User Flow

The user receives a redeem link and code from your platform.
The user visits the redeem URL (pre-filling the code using the ac parameter, e.g., https://impact.dots.eco/app/[app-id]/eco-club/claim?ac=[code]).
The user inputs their email address and optionally adds their name or the recipient's name.
If multiple allocation options are available, the user selects the desired impact type.
The user receives the certificate both in the browser and via email.

Endpoint

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

Refer to Headers and Authorization for required headers and authentication details.

Parameters

Name	Required	Type	Description
`app_token`	Yes	`string`	The app token, available in the app dashboard.
`quantity`	Yes	`integer (max=10^11)`	The impact quantity for the created offering.
`mail`	No	`string`	The email address associated with the offering. Required for clubs that aren't code-only.
`limit_allocations`	No	`string`	Comma-separated allocation IDs for setting limits.
`name_on_certificate`	No	`string (max_length=255)`	The name displayed on the certificate.
`activation_date`	No	`date`	The activation date of the offering.
`activation_hour`	No	`hour`	Activation hour in GMT, rounded to 15-minute increments (:00, :15, :30, :45). Non-compliant values are rounded automatically.
`expiration_date`	No	`date`	Expiration date of the offering.
`expiration_hour`	No	`hour`	Expiration hour in GMT with 15-minute increments (:00, :15, :30, :45).
`send_email_on_activation_date`	No	`string`	Set to `yes` to email upon activation or `no` to avoid sending an email. Default based on app settings.
`code`	No	`string (max_length=255)`	A unique activation code for this offering.
`title`	No	`string (max_length=255)`	Title for the Eco Club offering entity.
`remote_user_id`	No	`string`	A unique identifier for the user instead of `email` when enabled in app settings.
`max_claims_total`	No	`integer (max=10^11)`	Total claim limit for the offering (code-only clubs only).
`max_claims_per_email`	No	`integer (max=10^11)`	Limit on the number of claims per email (code-only clubs only).
`langcode`	No	`string (max_length=12)`	Language code for localized responses and claim URLs. Refer to the supported languages.
`currency`	No	`string (max_length=255)`	Currency for the offering. Refer to the supported currencies.
`external_unique_id`	No	`string (max_length=255)`	Unique identifier for ensuring non-duplication and error recovery. Required to handle system issues effectively.

Example Request

Minimal Request Example (Code-Only Club)

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
}'

Full Example Request

{
  "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"
}

Successful Response

Example Response

{
  "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"
}

Response Fields

Field	Type	Description
`uuid`	`string`	The UUID of the Eco Club offering entity.
`quantity`	`integer`	The impact quantity for the created offering.
`limit_allocations`	`string`	Comma-separated allocation IDs.
`name_on_certificate`	`string`	The recipient's name displayed on the certificate.
`activation_date`	`string`	The activation date of the offering in `YYYY-MM-DD` format.
`activation_hour`	`string`	The GMT activation time (e.g., `HH:MM:SS`).
`expiration_date`	`string`	The expiration date of the offering in `YYYY-MM-DD` format.
`expiration_hour`	`string`	The GMT expiration time (e.g., `HH:MM:SS`).
`code`	`string`	The unique activation code for the offering.
`mail`	`string`	The associated user email (if applicable).
`title`	`string`	The title of the Eco Club offering.
`max_claims_total`	`integer`	Total claim limit for the offering (code-only clubs only).
`max_claims_per_email`	`integer`	Claim limit per email address (code-only clubs only).
`send_email_on_activation_date`	`string`	Whether an email is sent on activation (`yes`/`no`).
`remote_user_id`	`string`	A unique user identifier used instead of `email`.
`claim_url`	`string`	Redeem claim URL for the created offering.
`external_unique_id`	`string`	The external unique identifier for the offering, preventing duplication.

Errors

Possible Error Messages

Message	Cause
`"Entity creation problem."`	General issue creating the offering.
`"The app_token is invalid."`	The provided application token is not valid.
`"Provided app is not of type Eco Club."`	The app you're trying to use isn’t of type Eco Club.
`"We cannot use email for this app."`	Your app configuration doesn’t allow the usage of emails.
`"The maximum length of [field]..."`	Input exceeds field maximum length.
`"The maximum value of [field]..."`	Input value exceeds allowed maximum.
`"Required fields cannot be empty."`	Missing required fields.

HTTP Status Code

Code	Description
200	Request was successful.
422	Request contains unprocessable data.

Notes

Activation/Expiration Time Instructions: Must align with 15-minute increments (:00, :15, :30, or :45).
External Unique ID: Essential for identifying and preventing duplicate request processing, especially in error recovery scenarios.
Ensure proper permissions and app configurations when submitting requests.