Skip to main content

Promotion Codes

A Promotion Code is a specific, user-facing code that customers can enter at checkout to receive a discount. Each Promotion Code is linked to a parent Coupon, which defines the actual discount (e.g., 20% off, $10 off). This two-level structure allows you to create multiple unique codes that all point to the same underlying discount, making it easy to track different marketing campaigns or distribution channels.

This API allows you to create, manage, and track the usage of Promotion Codes.

The Promotion Code Object

A promotion code object contains all the information about a specific code, including its parent coupon, usage limits, and restrictions.

  • id string — Unique identifier for the promotion code.
  • coupon_id string — The ID of the coupon this promotion code is associated with.
  • code string — The user-facing code that customers enter to apply the discount.
  • description string — An internal description of the promotion code.
  • active boolean — Whether the promotion code is currently active and can be used.
  • max_redemptions number — The maximum number of times this promotion code can be redeemed.
  • times_redeemed number — The number of times this promotion code has been redeemed.
  • expires_at number — A Unix timestamp indicating when the promotion code expires.
  • verification_type string — The method used to verify eligibility for the discount. Can be 'code', 'nft', 'vc', or 'user_restricted'.
  • nft_config object — Configuration for NFT-based verification.
  • vc_config object — Configuration for Verifiable Credential-based verification.
  • customer_dids string[] — An array of customer DIDs who are eligible to use this code.
  • restrictions object — A set of restrictions that apply to this promotion code.
  • metadata object — A set of key-value pairs that you can attach to an object.
  • coupon object — The expanded coupon object associated with this promotion code.
  • livemode boolean — Indicates if the object exists in live mode or test mode.
  • created_at string — Timestamp of when the object was created.
  • updated_at string — Timestamp of when the object was last updated.

Create a Promotion Code

Creates a new promotion code object.

Parameters

  • coupon_id string (required) — The ID of the coupon to associate with this promotion code.
  • code string — The user-facing code. If not provided, a random code will be generated. Maximum 16 characters.
  • description string — An optional internal description for the code. Maximum 250 characters.
  • active boolean (default: true) — Whether the promotion code is active. Defaults to true.
  • max_redemptions number — The maximum number of times the promotion code can be redeemed.
  • expires_at number — A Unix timestamp after which the promotion code is no longer valid.
  • verification_type string (default: code) — Specifies the verification method. Can be code, nft, vc, or user_restricted.
  • nft_config object — Configuration for NFT-based verification. Required if verification_type is nft.
    • addresses string[] — List of contract addresses.
    • tags string[] — List of NFT tags.
    • trusted_issuers string[] — List of trusted issuer DIDs.
    • trusted_parents string[] — List of trusted parent collection IDs.
    • min_balance number (default: 1) — Minimum balance of the required NFT the user must hold.
  • vc_config object — Configuration for Verifiable Credential-based verification. Required if verification_type is vc.
    • roles string[] — List of required roles in the VC.
    • trusted_issuers string[] — List of trusted issuer DIDs for the VC.
  • customer_dids string[] — A list of customer DIDs that are allowed to use this promotion code. Required if verification_type is user_restricted.
  • restrictions object — Defines the conditions for the promotion code to apply.
    • currency_options object — Currency-specific minimum amounts required to apply the promotion code.
      • {currency_code} object
        • minimum_amount number (required) — The minimum transaction amount in the specified currency.
    • first_time_transaction boolean — If true, the promotion code only applies to the customer's first transaction.
  • metadata object — A set of key-value pairs to store additional information about the object.

Returns

Returns the created Promotion Code object.

Create a promotion code

javascript
import payment from '@blocklet/payment-js';

async function createPromotionCode() {
  try {
    const promotionCode = await payment.promotionCodes.create({
      coupon_id: 'coupon_xxxxxxxxxxxxxx', // Replace with a valid Coupon ID
      code: 'SUMMER25',
      description: '25% off for the summer sale',
      max_redemptions: 100,
      expires_at: Math.floor(new Date('2024-09-01').getTime() / 1000),
      active: true,
    });
    console.log('Promotion Code created:', promotionCode);
  } catch (error) {
    console.error('Error creating promotion code:', error.message);
  }
}

createPromotionCode();

Example Response

json
{
  "id": "pc_xxxxxxxxxxxxxx",
  "coupon_id": "coupon_xxxxxxxxxxxxxx",
  "code": "SUMMER25",
  "description": "25% off for the summer sale",
  "active": true,
  "max_redemptions": 100,
  "times_redeemed": 0,
  "expires_at": 1725148800,
  "verification_type": "code",
  "nft_config": null,
  "vc_config": null,
  "customer_dids": null,
  "restrictions": {},
  "metadata": {},
  "livemode": false,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "coupon": {
    "id": "coupon_xxxxxxxxxxxxxx",
    "name": "Summer Sale",
    "percent_off": 25,
    // ... other coupon details
  }
}

Retrieve a Promotion Code

Retrieves the details of an existing promotion code.

Parameters

  • id string (required) — The unique identifier of the promotion code to retrieve.

Returns

Returns the Promotion Code object.

Retrieve a promotion code

javascript
import payment from '@blocklet/payment-js';

async function getPromotionCode(promotionCodeId) {
  try {
    const promotionCode = await payment.promotionCodes.retrieve(promotionCodeId);
    console.log('Retrieved Promotion Code:', promotionCode);
  } catch (error) {
    console.error('Error retrieving promotion code:', error.message);
  }
}

getPromotionCode('pc_xxxxxxxxxxxxxx'); // Replace with a valid Promotion Code ID

Update a Promotion Code

Updates the specified promotion code by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Note that once a promotion code has been used, only its metadata can be updated.

Parameters

  • id string (required) — The unique identifier of the promotion code to update.
  • description string — An optional internal description for the code. Maximum 250 characters.
  • active boolean — Whether the promotion code is active.
  • max_redemptions number — The maximum number of times the promotion code can be redeemed.
  • expires_at number — A Unix timestamp after which the promotion code is no longer valid.
  • restrictions object — Defines the conditions for the promotion code to apply.
  • metadata object — A set of key-value pairs to store additional information about the object.

Returns

Returns the updated Promotion Code object.

Update a promotion code

javascript
import payment from '@blocklet/payment-js';

async function updatePromotionCode(promotionCodeId) {
  try {
    const updatedPromotionCode = await payment.promotionCodes.update(promotionCodeId, {
      description: 'Updated summer sale description',
      metadata: { campaign_id: 'summer-2024' },
    });
    console.log('Promotion Code updated:', updatedPromotionCode);
  } catch (error) {
    console.error('Error updating promotion code:', error.message);
  }
}

updatePromotionCode('pc_xxxxxxxxxxxxxx'); // Replace with a valid Promotion Code ID

List Promotion Codes

Returns a list of your promotion codes.

Parameters

  • page number (default: 1) — The page number for pagination.
  • pageSize number (default: 20) — The number of items per page.
  • coupon_id string — Filter promotion codes by the associated coupon ID.
  • active boolean — Filter promotion codes by their active status.

Returns

A paginated list of Promotion Code objects.

List promotion codes

javascript
import payment from '@blocklet/payment-js';

async function listPromotionCodes() {
  try {
    const promotionCodes = await payment.promotionCodes.list({
      active: true,
      pageSize: 5,
    });
    console.log('Active Promotion Codes:', promotionCodes.list);
  } catch (error) {
    console.error('Error listing promotion codes:', error.message);
  }
}

listPromotionCodes();

Example Response

json
{
  "count": 50,
  "list": [
    {
      "id": "pc_xxxxxxxxxxxxxx",
      "code": "SUMMER25",
      // ... other promotion code details
    }
    // ... more promotion codes
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}

Archive a Promotion Code

Deactivates a promotion code, making it no longer redeemable. This action is irreversible.

Parameters

  • id string (required) — The unique identifier of the promotion code to archive.

Returns

Returns the archived Promotion Code object with active set to false.

Archive a promotion code

javascript
import payment from '@blocklet/payment-js';

async function archivePromotionCode(promotionCodeId) {
  try {
    const archivedCode = await payment.promotionCodes.archive(promotionCodeId);
    console.log('Promotion Code archived:', archivedCode);
  } catch (error) {
    console.error('Error archiving promotion code:', error.message);
  }
}

archivePromotionCode('pc_xxxxxxxxxxxxxx'); // Replace with a valid Promotion Code ID

Delete a Promotion Code

Deletes a promotion code. This action is only possible if the promotion code has not been redeemed. If it has been used, it will be locked and cannot be deleted; you should archive it instead.

Parameters

  • id string (required) — The unique identifier of the promotion code to delete.

Returns

Returns the deleted Promotion Code object.

Delete a promotion code

javascript
import payment from '@blocklet/payment-js';

async function deletePromotionCode(promotionCodeId) {
  try {
    const deletedCode = await payment.promotionCodes.del(promotionCodeId);
    console.log('Promotion Code deleted:', deletedCode);
  } catch (error) {
    console.error('Error deleting promotion code:', error.message);
  }
}

deletePromotionCode('pc_xxxxxxxxxxxxxx'); // Replace with an unused Promotion Code ID

Check if Used

Checks whether a promotion code has been redeemed at least once.

Parameters

  • id string (required) — The unique identifier of the promotion code to check.

Returns

An object containing a boolean used property.

Check if a promotion code is used

javascript
import payment from '@blocklet/payment-js';

async function checkUsage(promotionCodeId) {
  try {
    const result = await payment.promotionCodes.used(promotionCodeId);
    console.log(`Is promotion code used? ${result.used}`);
  } catch (error) {
    console.error('Error checking promotion code usage:', error.message);
  }
}

checkUsage('pc_xxxxxxxxxxxxxx'); // Replace with a valid Promotion Code ID

Example Response

json
{
  "used": true
}

Retrieve by Code

Retrieves a promotion code's details by its user-facing code string.

Parameters

  • code string (required) — The user-facing code string.

Returns

Returns the Promotion Code object.

Retrieve a promotion code by its code string

javascript
import payment from '@blocklet/payment-js';

async function getByCode(code) {
  try {
    const promotionCode = await payment.promotionCodes.byCode(code);
    console.log('Found promotion code:', promotionCode);
  } catch (error) {
    console.error('Error retrieving promotion code by code:', error.message);
  }
}

getByCode('SUMMER25');

List Redemptions

Retrieves a list of customers and subscriptions that have redeemed a specific promotion code.

Parameters

  • id string (required) — The unique identifier of the promotion code.
  • page number (default: 1) — The page number for pagination.
  • pageSize number (default: 20) — The number of items per page.
  • type 'customer' | 'subscription' — The type of redemption to list. Can be customer or subscription.

Returns

An object containing redemption data, including lists of customers and subscriptions.

List redemptions for a promotion code

javascript
import payment from '@blocklet/payment-js';

async function listRedemptions(promotionCodeId) {
  try {
    const redemptions = await payment.promotionCodes.redemptions({
      id: promotionCodeId,
      type: 'customer',
      pageSize: 10
    });
    console.log('Redemptions:', redemptions);
  } catch (error) {
    console.error('Error listing redemptions:', error.message);
  }
}

listRedemptions('pc_xxxxxxxxxxxxxx'); // Replace with a valid Promotion Code ID

Example Response

json
{
  "count": 5,
  "subscriptions": [],
  "customers": [
    {
      "id": "cus_yyyyyyyyyyyyyy",
      "did": "did:abt:z...",
      // ... other customer details
    }
    // ... more customers
  ],
  "paging": {
    "page": 1,
    "pageSize": 10
  }
}