Skip to main content
Represents a coupon in the Stigg system. Coupons provide discounts to customers, either as a percentage off or a fixed amount.

​
Type Definition

type Coupon {
  id: UUID!
  refId: String!
  name: String!
  description: String
  type: CouponType!
  status: CouponStatus!
  source: CouponSource!

  # Discount values
  percentOff: Float
  amountsOff: [Money!]

  # Duration
  durationInMonths: Float

  # Integration
  billingId: String
  billingLinkUrl: String
  syncStates: [SyncState!]

  # Customers
  customers: [Customer!]

  # Metadata
  additionalMetaData: JSON

  # Timestamps
  createdAt: DateTime!
  updatedAt: DateTime!
  environmentId: UUID!
  environment: Environment
}

​
Fields

​
Core Fields

FieldTypeDescription
idUUID!Unique identifier for the coupon
refIdString!Your reference ID for this coupon
nameString!Coupon name/code
descriptionStringCoupon description
typeCouponType!Type of discount (PERCENTAGE, FIXED)
statusCouponStatus!Current status
sourceCouponSource!Where the coupon was created

​
Discount Values

FieldTypeDescription
percentOffFloatPercentage discount (for PERCENTAGE type)
amountsOff[Money!]Fixed amounts off in different currencies

​
Duration

FieldTypeDescription
durationInMonthsFloatHow many months the discount applies (null = forever)

​
Integration

FieldTypeDescription
billingIdStringCoupon ID in billing provider
billingLinkUrlStringURL to coupon in billing provider
syncStates[SyncState!]Integration sync status

​
Customers

FieldTypeDescription
customers[Customer!]Customers using this coupon

​
CouponType Enum

ValueDescription
PERCENTAGEDiscount is a percentage off
FIXEDDiscount is a fixed amount

​
CouponStatus Enum

ValueDescription
ACTIVECoupon is active and can be applied
ARCHIVEDCoupon is no longer available

​
CouponSource Enum

ValueDescription
STIGGCreated in Stigg
BILLINGSynced from billing provider

​
SubscriptionCoupon Type

When a coupon is applied to a subscription: 
type SubscriptionCoupon {
  id: UUID!
  name: String!
  type: CouponType!
  percentOff: Float
  amountsOff: [Money!]
  durationInMonths: Float
  environmentId: UUID!
}

​
Example Response

​
Percentage Coupon

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "refId": "SAVE20",
  "name": "SAVE20",
  "description": "20% off for new customers",
  "type": "PERCENTAGE",
  "status": "ACTIVE",
  "source": "STIGG",
  "percentOff": 20,
  "durationInMonths": null,
  "billingId": "coupon_abc123",
  "billingLinkUrl": "https://dashboard.stripe.com/coupons/coupon_abc123",
  "createdAt": "2024-01-10T10:00:00Z",
  "updatedAt": "2024-01-10T10:00:00Z"
}

​
Fixed Amount Coupon

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "refId": "SAVE10",
  "name": "SAVE10",
  "description": "$10 off your first month",
  "type": "FIXED",
  "status": "ACTIVE",
  "source": "STIGG",
  "amountsOff": [
    {
      "amount": 10.00,
      "currency": "USD"
    },
    {
      "amount": 9.00,
      "currency": "EUR"
    }
  ],
  "durationInMonths": 1,
  "billingId": "coupon_def456",
  "createdAt": "2024-01-15T14:30:00Z",
  "updatedAt": "2024-01-15T14:30:00Z"
}

​
Limited Duration Coupon

{
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "refId": "TRIAL3",
  "name": "TRIAL3",
  "description": "50% off for first 3 months",
  "type": "PERCENTAGE",
  "status": "ACTIVE",
  "source": "STIGG",
  "percentOff": 50,
  "durationInMonths": 3,
  "customers": [
    {
      "customerId": "customer-123",
      "name": "Acme Corp"
    },
    {
      "customerId": "customer-456",
      "name": "Startup Inc"
    }
  ],
  "createdAt": "2024-01-20T09:00:00Z",
  "updatedAt": "2024-01-20T09:00:00Z"
}

​
Archived Coupon

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "refId": "SUMMER2023",
  "name": "SUMMER2023",
  "description": "Summer promotion 2023",
  "type": "PERCENTAGE",
  "status": "ARCHIVED",
  "source": "STIGG",
  "percentOff": 25,
  "durationInMonths": 2,
  "createdAt": "2023-06-01T00:00:00Z",
  "updatedAt": "2023-09-01T00:00:00Z"
}