Sometimes you may want to issue percent and/or flat discounts on your products, based upon factors such as time frame (e.g., a seasonal sale), for specific customers, or for specific payment methods.

The coupon object makes it simple to apply discounts. Through it, you can also issue discounts that end by a certain date, are tied to an NFT collection, have a max number of redemptions, and more.

How it works

(1) Create a coupon to define the parameters of your discount.

(2) You then have two choices:

Choice 1: Promotion Codes

Create promotionCode objects to allow your customers to redeem discounts from coupons by entering a relevant promotion code string at checkout.

Choice 2: NFT Discounts

Specify a collectionId public key in the coupon to automatically apply the coupon's discount to customers who own that specific NFT collection in the wallet that they will pay with.

Note: Choice (2) is currently mutually exclusive with promotion codes, meaning that if you specify a collectionId and attempt to connect a promotionCode to the coupon, the API will return an error.

(3) Pass in the id of the coupon to a payment method.

This will connect your relevant coupon to the payment method that you'd like to offer a discount through (and its corresponding line items). You can either create your coupon objects first and pass them as fields when creating your payment methods, or retroactively update them with the coupons that you create.

The coupon object

Let's take a look at the full coupon object.

{
  "id": "coupon_c248d748af484ec49d16fed9cd51a311",
  "name": "SummerSale2023",
  "active": true,
  "amountOff": 50,
  "currency": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "term": "oneTime",
  "maxRedemptions": 500,
  "percentOff": 20,
  "redeemBy": "2023-12-31T00:00:00.000Z",
  "collectionId": null,
  "timesRedeemed": 0,
  "unitAmountOff": "5_000_000",
  "updated": "2021-08-01T00:00:00.000Z",
  "created": "2021-08-01T00:00:00.000Z"
}

id: string Unique identifier for the object. Auto-generated by Sphere upon creation.

name: string The name of the coupon for your reference. Hidden from users. Max length (500).

active: boolean Denotes whether the coupon is usable by a promotionCode.

amountOff: number Defines the flat amount of the discount. Adjusted to be in decimal format.

e.g., amountOff: 5 means that the discounted payment will cost 5 currency less.
Mutually exclusive with percentOff. API will return an error if both are included.

currency: string Defines the underlying token or money for the discount.

For crypto, it is the public key for the mint address (Solana) or token contract address (EVM).
For fiat, it is one of usd, euro, and gbp .

term: enum Specifies whether the coupon is for oneTime or indefinite (forever) usage. Most relevant in the context of a subscription, where you may want to discount some or all future payments.

maxRedemptions: number Defines the max number of redemptions for the coupon.

A redemption is when someone receives a discount on payment: either by entering a promotion code at checkout, or by having a member of the NFT collection specified in collectionId in their wallet.
Because you may have multiple promotion codes that inherit from a single coupon, each use of a promotion code will contribute to the total maxRedemptions of the parent coupon.

percentOff: number Defines the percentage deduction of the discount.

e.g., percentOff: 20 means that the discounted payment will cost 20% less.
Mutually exclusive with amountOff. API will return an error if both are included.

redeemBy: string datetime by which the coupon must be redeemed.

collectionId: number The public key for the NFT collection that this coupon applies to.

Useful if you would like to offer specific collection holders a discount on your products.
Mutually exclusive with promo codes. API will error if this field is non-null and you attempt to create a promotion code as a child object. Support for non-mutual exclusivity coming soon.

updated: string datetime for when the coupon was last updated.

created: string datetime for when the coupon was created.

Now that we've examined the coupon object in full, the next steps are to create a coupon and, if relevant, to make it available for your users by connecting it to a promotion code!