Coupon Campaigns

Coupon Campaigns encapsulate the information that is required for running a sale / promotion offer on your store where you intend to give out a bunch of Coupons within a fixed period of time.

Coupon Campaign Object¶

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

Coupon Campaign Object

{
    "created_at": "2023-04-17T04:10:20.712Z",
    "ends_at": "2023-04-29T07:48:00.000Z",
    "id": "c9e0f639-eebb-466e-a63a-70f93542a9ef",
    "kind": "group",
    "name": "Campaign",
    "prefix": "camp-",
    "settings": {
        "display_code_on_listing": true,
        "low_coupons_threshold": 10
    },
    "extradata": null,
    "starts_at": "2023-04-17T07:48:00.000Z",
    "status": "draft",
    "updated_at": "2023-04-17T07:48:56.539Z",
    "account_id": "c9e0f639-eebb-466e-a63a-70f93542a9em"
}

Fields¶

All Fields¶

Field	Data Type	Description
`created_at`	string	UTC timestamp at which the Coupon Campaign was created.
`ends_at`	string	UTC timestamp at which the Coupon Campaign will end. This will be copied over to any coupons associated with the campaign.
`id`	string	UUID of the Coupon Campaign.
`kind`	string	Kind of the Coupon Campaign. Possible values are `single-use`, `group` & `lightning`.
`name`	string	Name of the Coupon Campaign.
`prefix`	string	Will be used on all the corresponding coupon codes being generated (if they don't already have a code). Will be unique at the campaign level.
`settings`	object	An object containing various configurable fields that allow you to control the campaign & related coupon functionality. See settings section for more details.
`extradata`	object	NA
`starts_at`	string	UTC timestamp at which the Coupon Campaign will start at.
`status`	string	Represents the current status of the Coupon Campaign.
`updated_at`	string	UTC timestamp at which the Coupon Campaign was last updated.
`account_id`	string	UUID of the account. See accounts page for more details.

Objects¶

Settings Object

Settings object containing various configurable fields that allows you to control the campaign & related coupon functionality

Field	Data Type	Description
`discount_type`	integer	The type of discount that will be set on the corresponding coupons. Should be either `percentage` or `flat`.
`discount_value`	integer	The value of discount that will be set on the corresponding coupons.
`display_code_on_listing`	boolean	Helps the frontend decide whether or not to show the code on the coupon listing.
`low_coupons_threshold`	integer	Helps the frontend decide whether or not to show a "low coupon" expiry message.
`single_use_min_cart_value`	string	The minimum cart value set on the coupons generated if the campaign `kind` is `single-use`.
`single_use_product_id`	string	The product that the coupon should belong to if the campaign `kind` is `single-use`.
`single_use_quantity`	integer	The number of coupons to be generated if the campaign `kind` is `single-use`.
`single_use_variant_id`	string	The variant that the coupon should belong to if the campaign `kind` is `single-use`.

Status State Machine¶

The status field represents whether or not a campaign is currently active and hence whether or not the customers are able to avail the corresponding coupons. The initial state is draft and an archived campaign represents a historical sale / promotion that is not active any longer. A campaign that is live and running will have the active state, the opposite of which is inactive which represents a campaign that has been deactivated or ended.

Possible values: draft, active, inactive and archived. Below diagram shows possible transitions on the Coupon Campaign status.

graph LR
  A[draft] --> |activate| B[active];
  B --> |deactivate| C[inactive];
  C --> |extend_expiry_and_activate| B;
  B --> |extend_expiry_and_activate| B;

API¶

List Coupon Campaigns¶

GET /api/platform/v1/coupon_campaigns

Returns a list of CouponCampaigns.

Query Params

TODO

curl command

TODO

Response Body

TODO

Create Coupon Campaign¶

POST /api/platform/v1/coupon_campaigns

Creates a CouponCampaign. Only name & kind fields are required for creation.

Request Body

TODO

curl command

TODO

Response Body

TODO

Get Coupon Campaign¶

GET /api/platform/v1/coupon_campaigns/{id}

Fetches the CouponCampaign identified by id.

curl command

TODO

Response Body

TODO

Update Coupon Campaign¶

PATCH /api/platform/v1/coupon_campaigns/{id}

Updates the CouponCampaign identified by id. Use the /transition endpoint for updating status.

Request Body

TODO

curl command

TODO

Response Body

TODO

Delete Coupon Campaign¶

DELETE /api/platform/v1/coupon_campaigns/{id}

Deletes the CouponCampaign identified by id and all the associated Coupons.

curl command

TODO

Response Body

TODO

Transition Coupon Campaign Status¶

POST /api/platform/v1/coupon_campaigns/{id}/transition

Transitions the CouponCampaign identified by id into the states defined in the state machine.

Request Body

TODO

curl command

TODO

Response Body

TODO

Search Coupon Campaign¶

POST /api/platform/v1/coupon_campaigns/{id}/search

Lists CouponCampaigns. Uses the ElasticSearch data for the result set instead of the DB data.

Request Body

TODO

curl command

TODO

Response Body

TODO

Export Single-Use-Coupon data¶

GET /api/platform/v1/coupon_campaigns/{id}/export_coupons

Downloads a CSV of SingleUseCoupon data associated with the CouponCampaign identified by id.

curl command

TODO

Response Body

TODO