BiasDocs

Discounts

Discounts define reusable discount terms. A discount contains either a fixed amount_off or a percent_off, and can apply to an entire invoice or checkout session or only to selected products.

Give a discount an optional code that customers can enter during checkout. Merchant integrations apply it with { discount: discount_id }; normal code redemption uses { code: "SAVE10" }. Applying either form creates an immutable applied discount record on the transaction.

Discount terms, code, redemption limits, expiry, restrictions, and product applicability are immutable after creation. Only a discount’s customer-visible name, metadata, and active status can be updated. Active status affects code redemption only; merchant application by discount ID is an explicit override.

Redeeming by code enforces active status, expiry, the redemption cap, minimum purchase amount, first-purchase-only and once-per-customer restrictions, and product eligibility. The minimum uses the pre-discount merchandise subtotal and excludes tax and shipping. times_redeemed increases only after a successful code-backed payment. Applying the same discount by ID bypasses those redemption checks and does not increment the counter.

The Discount object

Name
object
Type
"discount",
Description
Literal representing the object's type.
Name
id
Type
string,
Description
Unique identifier for the object.
Name
live
Type
boolean,
Description
Has the value true if the object exists in a production environment or the value false if the object exists in a sandbox environment.
Name
created_at
Type
integer,
Description
Time at which the object was created. Measured in milliseconds since the Unix epoch.
Name
active
Type
boolean,
Description
Whether this discount can be redeemed by code.
Name
amount_off
Type
integer or null,
Description
The fixed discount amount in cents.
Name
applies_to
Type
array of Products or null or null,
Description
Expandable. Products this discount applies to. When null, it applies to all products.
Name
code
Type
string or null,
Description
The optional customer-redeemable code. Case insensitive.
Name
deleted
Type
boolean,
Description
Whether the discount has been deleted.
Name
expires_at
Type
integer or null,
Description
The epoch timestamp after which this discount cannot be redeemed.
Name
first_purchase_only
Type
boolean,
Description
Whether the code is restricted to a customer's first purchase.
Name
max_redemptions
Type
integer or null,
Description
The maximum number of successful code redemptions.
Name
metadata
Type
object,
Description
A key-value store that is attached to the object. Useful for storing miscellaneous structured data for your integration's internal use.
Name
minimum_amount
Type
integer or null,
Description
The minimum pre-discount merchandise subtotal required, 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 may redeem the code only once.
Name
percent_off
Type
number or null,
Description
The percentage discount amount, for example 15 for 15%.
Name
times_redeemed
Type
integer, at least 0,
Description
The number of successful code redemptions.
Name
updated_at
Type
integer,
Description
Time at which the object was last updated. Measured 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

Create a reusable discount. Specify exactly one of amount_off or percent_off. Set applies_to to product IDs to limit the discount to those products; otherwise it applies to the transaction as a whole.

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 optional customer-redeemable code. Case insensitive.
Name
active
Type
boolean, default is true
Description
Whether this discount can be redeemed by code.
Name
amount_off
Type
integer or null,
Description
The fixed discount amount in cents.
Name
percent_off
Type
number or null,
Description
The percentage discount amount, for example 15 for 15%.
Name
expires_at
Type
integer or null,
Description
The epoch timestamp after which this discount cannot be redeemed.
Name
max_redemptions
Type
integer or null,
Description
The maximum number of successful code redemptions.
Name
minimum_amount
Type
integer or null,
Description
The minimum pre-discount merchandise subtotal required, in cents.
Name
first_purchase_only
Type
boolean, default is false
Description
Whether the code is restricted to a customer's first purchase.
Name
once_per_customer
Type
boolean, default is false
Description
Whether each customer may redeem the code only once.
Name
applies_to
Type
array of string or null,
Description
Expandable. Products this discount applies to. When null, it applies to all products.
Name
metadata
Type
object or null,
Description
A key-value store that is attached to the object. Useful for storing miscellaneous structured data for your integration's internal use.

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

Update a discount’s customer-visible name, metadata, or active status. Its code, economic terms, restrictions, and product applicability cannot be changed.

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 this discount can be redeemed by code.
Name
metadata
Type
object or null,
Description
A key-value store that is attached to the object. Useful for storing miscellaneous structured data for your integration's internal use.

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

Returns a paginated list of reusable discounts in reverse chronological order.

Optional parameters

Name
expand
Type
object,
Properties
Name
ending_before
Type
string,
Name
starting_after
Type
string,
Name
limit
Type
number, at least 1, at most 1000, default is 50
Description
Maximum number of objects to return.
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": false
}

Delete a discount

Delete a discount so it cannot be applied to new transactions. Existing applied discounts retain their snapshotted 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
}
Previous
Next

Built by Bias in California