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.

5 subfields
vc_config
object

Configuration for Verifiable Credential-based verification. Required if verification_type is vc.

2 subfields
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.

2 subfields
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

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#

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

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

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

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#

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

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

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

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#

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

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

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#

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