SingleUse Coupon

Let's start by answering the obvious question - what makes a SingleUseCoupon different from a CartCoupon & VariantCoupon? Well, as its name suggests, it is for single use. Which technically translates to the max_count field's value strictly being 1. You can think of it as a restricted version of the other two types of coupons.

One other major difference is the fact that a SingleUseCoupon can also be associated with a Product instead of just with the Variants.

A SingleUseCoupon can only be one among a Cart (min_cart_value), Product (product_id) or Variant (variant_id) Coupon at a time.

These are mostly created via Single Use Coupon Campaigns. Once a campaign of kind single-use is created, it generates the defined quantity of SingleUseCoupons in the background. These are rarely created via the admin as well as a part of Orders created by admins when they want to just create a coupon on the fly in order to apply some discount value. The admin created ones won't have a CouponCampaign associated with them.

Cart Coupon Object¶

Below is the json representation of the Cart Coupon object, followed by a data table

Cart Coupon Object

{
  "id": "3af61f11-5247-4558-981d-96b55ea55e30",
  "code": "Q5Ixcv",
  "status": "inactive",
  "starts_at": "2023-05-23T06:44:47.621Z",
  "ends_at": "2023-05-23T06:44:47.621Z",
  "max_count": 1,
  "used_count": 0,
  "min_cart_value": null,
  "discount_type": "flat",
  "discount_value": null,
  "variant_id": null,
  "coupon_campaign_id": null,
  "extradata": null,
  "created_at": "2023-05-23T06:44:47.621Z",
  "updated_at": "2023-05-23T06:44:47.621Z",
  "account_id": "b303a002-899c-40d5-9897-d5bf62a5486f",
  "product_id": null,
  "notes": null,
  "placed_by_staff_id": null
}

All Fields¶

Field	Data Type	Description
`id`	string	UUID of the Single Use Coupon.
`code`	string	The value that the customer enters for availing the coupon. Automatically generated as a combination of the associated `CouponCampaign`'s `prefix` and 6 random alphanumeric characters.
`status`	string	Represents the current status of the coupon.
`starts_at`	string	UTC timestamp that represents the time at which the Coupon can be active & be ready to be used.
`ends_at`	string	UTC timestamp that represents the time at which the Coupon will cease to be active & hence can't be used no more.
`max_count`	integer	Number of times this coupon can be used. Has to be set to `1`.
`used_count`	integer	Represents the number of times this coupon has been used so far. Once this becomes equal to `max_count`, the coupon can't be used anymore.
`min_cart_value`	integer	Represents the minimum amount the cart / order should have in order for this coupon be eligible to be applied.
`dicount_type`	string	The type of discount this coupon offers. Should be either `percentage` or `flat`.
`discount_value`	string	The value of discount this coupon offers. Will be calculated based on `discount_type`.
`variant_id`	string	UUID of the variant that this coupon belongs to, and hence can be applied on.
`coupon_campaign_id`	string	UUID of the associated `Coupon Campaign`. See coupon campaign page for more details.
`extradata`	object	NA
`created_at`	string	UTC timestamp at which the Coupon was created.
`updated_at`	string	UTC timestamp at which the Coupon was last updated.
`account_id`	string	UUID of the account. See accounts page for more details.
`product_id`	string	UUID of the product that this coupon belongs to, and hence helps identify the bunch of variants that it can be applied on.
`notes`	object	See notes section for more details.
`placed_by_staff_id`	string	UUID of the staff who created the coupon.

Objects¶

Notes Object

Notes object containing two values related to a SingleUseCoupon being created via admin.

Field	Data Type	Description
`placed_from_admin_panel`	boolean	Represents whether the coupon was created directly from admin. Hence won't require an associated `CouponCampaign` to be present for activation.
`reason_for_admin_discount`	string	If created from admin, then the reason why it was done so.

Status State Machine¶

The status field represents whether or not a coupon is currently active and hence whether or not the customers are able to avail it. The initial state is inactive during which a coupon can't be used and an active state represents a coupon that can be used. As the name itself suggests, the time_expired & count_expired statuses represents coupons that have their ends_at past and their used_count having reached their max_count respectively.

Possible values: inactive, active, time_expired and count_expired. Below diagram shows possible transitions on the Cart Coupon status.

graph LR
  A[inactive] --> |activate| B[active];
  B --> |deactivate| A;
  B --> |expire_time| C[time_expired];
  B --> |expire_count| D[count_expired];
  C --> |activate| B;
  D --> |activate| B;
  A --> |reconcile_count_status| D;
  D --> |reconcile_count_status| B;
  A --> |reconcile_count_status| A;
  D --> |reconcile_count_status| D;
  B --> |reconcile_count_status| B;
  C --> |extend_expiry_and_activate| B;
  B --> |extend_expiry_and_activate| B;
  A --> |extend_expiry_and_activate| B;
  A --> |extend_expiry_and_activate| D;
  D --> |extend_expiry_and_activate| D;

API¶

List Coupons¶

GET /api/platform/v1/coupon_campaigns/{coupon_campaign_id}/coupons

Returns a list of Coupons associated with the CouponCampaign defined by coupon_campaign_id.

Query Params

TODO

curl command

TODO

Response Body

TODO