Promo Codes

This object represents a promo code in your system. Use it to manage discounts and promotions.

promo-codes.read promo-codes.write

Core principles

A promo code should be unique by its code.

SBPromoCode

Create a promo code

Create a new promo code. Requires scope promo-codes.write

POST https://api.smartbills.io/v1/promo-codes

Request Body

Requires body of type PromoCodeCreateRequest

Parameter	Description	Type	Required
`name`	Name of the promo code	`string`	`required`
`amount`	Amount of the promo code	`SBMoney`	`required`
`percentage`	Percentage discount of the promo code	`number`	`optional`
`type`	Type of the promo code	`SBPromoCodeType`	`required`
`isActive`	Whether the promo code is active	`boolean`	`required`

PromoCodeCreateRequest

{
  "name": "SUMMER21",
 
  "percentage": 20,
  "type": "percentage",
  "isActive": true
}

Response

Returns a SBPromoCodeResponse

SBPromoCodeResponse

{
  "id": 0,
  "name": "SUMMER21",
  "type": "percentage",
 
  "percentage": 20,
  "createdAt": "2025-01-21T00:56:42.273Z",
  "updatedAt": "2025-01-21T00:56:42.273Z"
}

Code example

import { SBClient, SBPromoCode, PromoCodeCreateRequest } from "@smartbills/sdk"
 
const client = new SBClient();
const request = {
	"name": "SUMMER21",
	"amount": {
		"currency": "USD",
		"amount": 20
	},
	"type": "amount",
	"isActive": true
};
 
const promoCode = await client.promoCodes.create(request);

Retrieve promo code

Retrieve a promo code by ID. Requires scope promo-codes.read

GET https://api.smartbills.io/v1/promo-codes/:id

Path parameters

Parameter	Description	Type	Required
`id`	ID of the promo code to retrieve	`long`	`required`

Response

Returns a SBPromoCodeResponse

SBPromoCodeResponse

{
  "id": 0,
  "name": "SUMMER21",
  "type": "percentage",
  "percentage": 20,
  "createdAt": "2025-01-21T00:56:42.273Z",
  "updatedAt": "2025-01-21T00:56:42.273Z"
}

Code example

import { SBClient, SBPromoCode } from "@smartbills/sdk"
 
const client = new SBClient();
const promoCode = await client.promoCodes.getByIdAsync(1);

List promo codes

Retrieve a list of promo codes. Requires scope promo-codes.read

GET https://api.smartbills.io/v1/promo-codes?page=1&pageSize=100

Query parameters

Requires query parameters of type PromoCodeListRequest

Parameter	Description	Type	Required	Default
`page`	Current page	`long`	`required`	1
`pageSize`	Number of records to return	`long`	`required`	100
`orderBy`	Order the results by a key of SBPromoCode	`keyof SBPromoCode`		`createdAt`
`sortOrder`	Order of the sort	`asc` or `desc`		`desc`

PromoCodeListRequest

{
    "page": 1,
    "pageSize": 100,
	"orderBy": "createdAt",
	"sortOrder": "desc",
}

Response

Returns a SBPromoCodeResponseSBList

SBPromoCodeResponseSBList

{
    "data": [{
        "id": 0,
        "name": "SUMMER21",
        "type": "percentage",
        "amount": {
          "currency": "USD",
          "amount": 20
        },
        "percentage": 20,
        "createdAt": "2025-01-21T00:56:42.273Z",
        "updatedAt": "2025-01-21T00:56:42.273Z"
    }],
    "metadata": {
        "page": 1,
        "pageSize": 100,
        "totalPages": 1,
        "count": 1
    }
}

Code example

import { SBClient, SBPromoCode, SBList, PromoCodeListRequest } from "@smartbills/sdk"
 
const client = new SBClient();
const request = {
	"page": 1,
	"pageSize": 100,
	"orderBy": "createdAt",
	"sortOrder": "desc"
};
 
const promoCodes = await client.promoCodes.list(request);

Update a promo code

Update information about a promo code. Requires scope promo-codes.write

PUT https://api.smartbills.io/v1/promo-codes/:id

Path parameters

Parameter	Description	Type	Required
`id`	ID of the promo code to update	`long`	`required`

Body parameters

Requires a body of type PromoCodeUpdateRequest

Parameter	Description	Type	Required
`isActive`	Whether the promo code is active	`boolean`	`required`

PromoCodeUpdateRequest

{
  "isActive": true
}

Response

Returns a SBPromoCodeResponse

SBPromoCodeResponse

{
  "id": 0,
  "name": "SUMMER21",
  "type": "percentage",
  "amount": {
    "currency": "USD",
    "amount": 25
  },
  "percentage": 25,
  "createdAt": "2025-01-21T00:56:42.273Z",
  "updatedAt": "2025-01-21T00:56:42.273Z"
}

Code example

import { SBClient, SBPromoCode, PromoCodeUpdateRequest } from "@smartbills/sdk"
	
const client = new SBClient();
const request = {
	"isActive": true
};
 
const promoCode = await client.promoCodes.updateAsync(1, request);

Delete a promo code

Delete a promo code. Requires scope promo-codes.write

DELETE https://api.smartbills.io/v1/promo-codes/:id

Path parameters

Parameter	Description	Type	Required
`id`	ID of the promo code to delete	`long`	`required`

Response

Returns a SBPromoCodeResponse

SBPromoCodeResponse

{
  "id": 0,
  "name": "SUMMER21",
  "type": "percentage",
  "percentage": 20,
  "createdAt": "2025-01-21T00:56:42.273Z",
  "updatedAt": "2025-01-21T00:56:42.273Z"
}

Code example

import { SBClient, SBPromoCode } from "@smartbills/sdk"
	
const client = new SBClient();
const promoCode = await client.promoCodes.deleteAsync(1);

Fees API Receipts API