BiasDocs

Discounts

A discount takes a fixed amount or a percentage off an invoice or checkout session, or off selected products. Customers can redeem a discount that has a code at checkout. The discounts guide covers how codes are redeemed and how discounts stack.

The Discount object

Name
object
Type
"discount",
Description
The object's type.
Name
id
Type
string,
Description
Unique identifier for the object.
Name
live
Type
boolean,
Description
true if the object is live, or false if it's in a sandbox.
Name
created_at
Type
integer,
Description
When the object was created, in milliseconds since the Unix epoch.
Name
active
Type
boolean,
Description
Whether customers can redeem the code.
Name
amount_off
Type
integer or null,
Description
The amount off, in cents.
Name
applies_to
Type
array of Products or null or null,
Description
Expandable. The products the discount applies to, or an empty list for all products.
Name
code
Type
string or null,
Description
The code customers enter to redeem the discount. Case insensitive.
Name
deleted
Type
boolean,
Description
Whether the discount has been deleted.
Name
expires_at
Type
integer or null,
Description
When the code expires, in milliseconds since the Unix epoch.
Name
first_purchase_only
Type
boolean,
Description
Whether the code works only on a customer's first purchase.
Name
max_redemptions
Type
integer or null,
Description
How many times the code can be redeemed.
Name
metadata
Type
object,
Description
Your own key-value data on the object.
Name
minimum_amount
Type
integer or null,
Description
The smallest order, before discounts, the code applies to, in cents.
Name
name
Type
string,
Description
The discount's name as shown to customers.
Name
once_per_customer
Type
boolean,
Description
Whether each customer can redeem the code only once.
Name
percent_off
Type
number or null,
Description
The percentage off, such as 15 for 15%.
Name
times_redeemed
Type
integer, at least 0,
Description
How many times the code has been redeemed.
Name
updated_at
Type
integer,
Description
When the object was last updated, in milliseconds since the Unix epoch.

The Discount object

{
  "object": "discount",
  "id": "di_0yejjs3V3DfgTCMZdtKIu7",
  "live": false,
  "created_at": 1750000000000,
  "updated_at": 1750000000000,
  "deleted": false,
  "name": "10% off",
  "code": "SAVE10",
  "active": true,
  "amount_off": null,
  "percent_off": 10,
  "expires_at": null,
  "max_redemptions": null,
  "times_redeemed": 0,
  "minimum_amount": null,
  "first_purchase_only": false,
  "once_per_customer": false,
  "applies_to": null,
  "metadata": {}
}

Create a discount

A discount has either amount_off or percent_off. With applies_to, it applies only to those products. Without it, it applies to the whole invoice or checkout session.

Required parameters

Name
name
Type
string,
Description
The discount's name as shown to customers.

Optional parameters

Name
expand
Type
object,
Properties
Name
code
Type
string or null,
Description
The code customers enter to redeem the discount. Case insensitive.
Name
active
Type
boolean, default is true
Description
Whether customers can redeem the code.
Name
amount_off
Type
integer or null,
Description
The amount off, in cents.
Name
percent_off
Type
number or null,
Description
The percentage off, such as 15 for 15%.
Name
expires_at
Type
integer or null,
Description
When the code expires, in milliseconds since the Unix epoch.
Name
max_redemptions
Type
integer or null,
Description
How many times the code can be redeemed.
Name
minimum_amount
Type
integer or null,
Description
The smallest order, before discounts, the code applies to, in cents.
Name
first_purchase_only
Type
boolean, default is false
Description
Whether the code works only on a customer's first purchase.
Name
once_per_customer
Type
boolean, default is false
Description
Whether each customer can redeem the code only once.
Name
applies_to
Type
array of string or null,
Description
The IDs of the products the discount applies to. Without them, it applies to all products.
Name
metadata
Type
object or null,
Description
Your own key-value data on the object.

Returns

Returns the discount object.

Create a discount

const discount = await bias.discounts.create({
  name: "10% off",
  percent_off: 10,
  applies_to: null,
  metadata: {}
});

Response example

{
  "object": "discount",
  "id": "di_0yejjs3V3DfgTCMZdtKIu7",
  "live": false,
  "created_at": 1750000000000,
  "updated_at": 1750000000000,
  "deleted": false,
  "name": "10% off",
  "code": "SAVE10",
  "active": true,
  "amount_off": null,
  "percent_off": 10,
  "expires_at": null,
  "max_redemptions": null,
  "times_redeemed": 0,
  "minimum_amount": null,
  "first_purchase_only": false,
  "once_per_customer": false,
  "applies_to": null,
  "metadata": {}
}

Get a discount

Retrieve a discount by its ID.

Required parameters

Name
id
Type
string,

Optional parameters

Name
expand
Type
object,
Properties

Returns

Returns the discount object.

Retrieve a discount

const discount = await bias.discounts.get("id");

Response example

{
  "object": "discount",
  "id": "di_0yejjs3V3DfgTCMZdtKIu7",
  "live": false,
  "created_at": 1750000000000,
  "updated_at": 1750000000000,
  "deleted": false,
  "name": "10% off",
  "code": "SAVE10",
  "active": true,
  "amount_off": null,
  "percent_off": 10,
  "expires_at": null,
  "max_redemptions": null,
  "times_redeemed": 0,
  "minimum_amount": null,
  "first_purchase_only": false,
  "once_per_customer": false,
  "applies_to": null,
  "metadata": {}
}

Update a discount

Only a discount’s name, active and metadata can change. To change its terms, create a new discount. With active: false, customers can’t redeem its code.

Required parameters

Name
id
Type
string,

Optional parameters

Name
expand
Type
object,
Properties
Name
name
Type
string,
Description
The discount's name as shown to customers.
Name
active
Type
boolean,
Description
Whether customers can redeem the code.
Name
metadata
Type
object or null,
Description
Your own key-value data on the object.

Returns

Returns the updated discount object.

Update a discount

const discount = await bias.discounts.update("id", {
  name: "Summer discount"
});

Response example

{
  "object": "discount",
  "id": "di_0yejjs3V3DfgTCMZdtKIu7",
  "live": false,
  "created_at": 1750000000000,
  "updated_at": 1750000000000,
  "deleted": false,
  "name": "10% off",
  "code": "SAVE10",
  "active": true,
  "amount_off": null,
  "percent_off": 10,
  "expires_at": null,
  "max_redemptions": null,
  "times_redeemed": 0,
  "minimum_amount": null,
  "first_purchase_only": false,
  "once_per_customer": false,
  "applies_to": null,
  "metadata": {}
}

List all discounts

Retrieve a paginated list of discounts, most recently created first.

Optional parameters

Name
expand
Type
object,
Properties
Name
ending_before
Type
string,
Name
starting_after
Type
string,
Name
limit
Type
integer, at least 1, at most 1000, default is 50
Description
The maximum number of objects to return, from 1 to 1000. Defaults to 50.
Name
filters
Type
object, object, or object,
Properties

Returns

Returns a list of discount objects.

List all discounts

const discount = await bias.discounts.list();

Response example

{
  "object": "list",
  "items": [
    {
      "object": "discount",
      "id": "di_0yejjs3V3DfgTCMZdtKIu7",
      "live": false,
      "created_at": 1750000000000,
      "updated_at": 1750000000000,
      "deleted": false,
      "name": "10% off",
      "code": "SAVE10",
      "active": true,
      "amount_off": null,
      "percent_off": 10,
      "expires_at": null,
      "max_redemptions": null,
      "times_redeemed": 0,
      "minimum_amount": null,
      "first_purchase_only": false,
      "once_per_customer": false,
      "applies_to": null,
      "metadata": {}
    }
  ],
  "has_more": true
}

Delete a discount

A deleted discount can’t be applied again. Invoices and checkout sessions that already have it keep its terms.

Required parameters

Name
id
Type
string,

Returns

A deleted object stub.

Delete a discount

const discount = await bias.discounts.delete("id");

Response example

{
  "object": "discount",
  "id": "di_0yejjs3V3DfgTCMZdtKIu7",
  "deleted": true
}