Private API reference

Coupon

Private Coupon API endpoints

Endpoints

GET/coupons
POST/coupons
GET/coupons/{coupon_id}
PATCH/coupons/{coupon_id}
POST/coupons/{coupon_id}/archive

Get list of coupons

GET /coupons

An API endpoint to get a paginated list of coupons.

Query parameters

idsoptionalinteger[]

Filter by coupon IDs

queryoptionalstring

Search by coupon code or name

activeoptionalinteger

Filter by active status (0 or 1)

Possible values: 0, 1.

trashedoptionalinteger

Include soft-deleted coupons (0 or 1)

Possible values: 0, 1.

sort[field]optionalstring

Sort field

Possible values: id, name.

sort[direction]optionalstring

Sort direction; defaults to asc.

Possible values: asc, desc.

Defaults to "asc".

pageoptionalinteger

Page number

per_pageoptionalinteger

Items per page

expand[]optionalstring[]

List of relations to expand in the response.

Returnsobject

Coupons list response

curl https://api.subbly.co/private/v1/coupons \
  -H 'X-API-KEY: <api-key>'

Response

{
  "pagination": {
    "current_page": 1,
    "last_page": 2,
    "from": 1,
    "to": 1,
    "total": 20
  },
  "data": [
    {
      "id": 1234,
      "coupon_id": "SAVE20",
      "name": "20% off",
      "duration": "once",
      "duration_in_months": 3,
      "remove_gifts_after_end_of_duration": false,
      "max_redemptions": 100,
      "times_redeemed": 5,
      "active": true,
      "limit_one_per_customer": false,
      "redeem_by": "2026-12-31 23:59:59",
      "valid": true,
      "condition": {
        "id": 10,
        "type": "product",
        "operator": "only",
        "products": [
          {}
        ],
        "collections": [
          {}
        ],
        "cart_value": {
          "min": 1,
          "max": 1
        },
        "cart_quantity": {
          "min": 1,
          "max": 1
        }
      },
      "discount": {
        "id": 20,
        "amount_off": 500,
        "percent_off": 20,
        "skip_payment_method": false,
        "first_shipment_only": false,
        "products": [
          "389855",
          "389856"
        ],
        "products_operator": "only",
        "item_types": [
          "subscription",
          "setup_fee"
        ]
      },
      "gift": {
        "id": 30,
        "amount_off": 1,
        "percent_off": 100,
        "addon_duration": "once",
        "remove_products_after_coupon_detached": false,
        "products": [
          {}
        ]
      },
      "rules": {
        "emails": {},
        "customers": {},
        "subscriptions": {}
      },
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-01-15T10:30:00Z",
      "deleted_at": "2026-01-15T10:30:00Z"
    }
  ]
}

Create a coupon

POST /coupons

Create a new coupon. Must include either a discount or a gift (or both).

Query parameters

expand[]optionalstring[]

List of relations to expand in the response.

Request body

nameRequiredstring

coupon_codeRequiredstring

Unique coupon code within the shop

durationRequiredstring

Possible values: once, forever, multiple.

duration_in_monthsoptionalinteger

Required when duration is "multiple". Prohibited when duration is "once" or "forever".

remove_gifts_after_end_of_durationoptionalinteger

Possible values: 0, 1.

max_redemptionsoptionalinteger | null

limit_one_per_customeroptionalinteger

Possible values: 0, 1.

redeem_byoptionalstring | null

Expiry date in Y-m-dTH:i:s format, interpreted as UTC. Must be after tomorrow.

Format: date-time.

conditionoptionalobject | null

Coupon condition. Set to null for no condition.

discountoptionalobject | null

Discount action. Required if gift is not provided.

giftoptionalobject | null

Gift action. Required if discount is not provided.

rulesoptionalobject | null

Coupon restriction rules

ReturnsCoupon

Coupon created

curl -X POST https://api.subbly.co/private/v1/coupons \
  -H 'X-API-KEY: <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "name",
  "coupon_code": "coupon_code",
  "duration": "once",
  "duration_in_months": 1,
  "remove_gifts_after_end_of_duration": 0,
  "max_redemptions": 1,
  "limit_one_per_customer": 0,
  "redeem_by": "2026-12-31T23:59:59",
  "condition": {
    "type": "product",
    "operator": "any",
    "products": {
      "create": [
        {
          "product_id": 1
        }
      ]
    },
    "collections": {
      "create": [
        {
          "collection_id": 1
        }
      ]
    },
    "cart_value": {
      "min": 1,
      "max": 1
    },
    "cart_quantity": {
      "min": 1,
      "max": 1
    }
  },
  "discount": {
    "amount_off": 1,
    "percent_off": 1.5,
    "item_types": [
      "subscription"
    ],
    "products": [
      1
    ],
    "products_operator": "only",
    "skip_payment_method": 0,
    "first_shipment_only": 0
  },
  "gift": {
    "amount_off": 1,
    "percent_off": 1.5,
    "addon_duration": "once",
    "remove_products_after_coupon_detached": 0,
    "products": {
      "create": [
        {
          "product_id": 1
        }
      ]
    }
  },
  "rules": {
    "emails": {
      "create": [
        "customer@example.com"
      ]
    },
    "customers": {
      "create": [
        1
      ]
    },
    "subscriptions": {
      "create": [
        1
      ]
    }
  }
}'

Response

{
  "id": 1234,
  "coupon_id": "SAVE20",
  "name": "20% off",
  "duration": "once",
  "duration_in_months": 3,
  "remove_gifts_after_end_of_duration": false,
  "max_redemptions": 100,
  "times_redeemed": 5,
  "active": true,
  "limit_one_per_customer": false,
  "redeem_by": "2026-12-31 23:59:59",
  "valid": true,
  "condition": {
    "id": 10,
    "type": "product",
    "operator": "only",
    "products": [
      {}
    ],
    "collections": [
      {}
    ],
    "cart_value": {
      "min": 1,
      "max": 1
    },
    "cart_quantity": {
      "min": 1,
      "max": 1
    }
  },
  "discount": {
    "id": 20,
    "amount_off": 500,
    "percent_off": 20,
    "skip_payment_method": false,
    "first_shipment_only": false,
    "products": [
      "389855",
      "389856"
    ],
    "products_operator": "only",
    "item_types": [
      "subscription",
      "setup_fee"
    ]
  },
  "gift": {
    "id": 30,
    "amount_off": 1,
    "percent_off": 100,
    "addon_duration": "once",
    "remove_products_after_coupon_detached": false,
    "products": [
      {}
    ]
  },
  "rules": {
    "emails": {},
    "customers": {},
    "subscriptions": {}
  },
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z",
  "deleted_at": "2026-01-15T10:30:00Z"
}

Get coupon by ID

GET /coupons/{coupon_id}

Get a single coupon by its ID.

Path parameters

coupon_idRequiredinteger

Coupon ID

Query parameters

expand[]optionalstring[]

List of relations to expand in the response.

ReturnsCoupon

Coupon object response

curl https://api.subbly.co/private/v1/coupons/{coupon_id} \
  -H 'X-API-KEY: <api-key>'

Response

{
  "id": 1234,
  "coupon_id": "SAVE20",
  "name": "20% off",
  "duration": "once",
  "duration_in_months": 3,
  "remove_gifts_after_end_of_duration": false,
  "max_redemptions": 100,
  "times_redeemed": 5,
  "active": true,
  "limit_one_per_customer": false,
  "redeem_by": "2026-12-31 23:59:59",
  "valid": true,
  "condition": {
    "id": 10,
    "type": "product",
    "operator": "only",
    "products": [
      {}
    ],
    "collections": [
      {}
    ],
    "cart_value": {
      "min": 1,
      "max": 1
    },
    "cart_quantity": {
      "min": 1,
      "max": 1
    }
  },
  "discount": {
    "id": 20,
    "amount_off": 500,
    "percent_off": 20,
    "skip_payment_method": false,
    "first_shipment_only": false,
    "products": [
      "389855",
      "389856"
    ],
    "products_operator": "only",
    "item_types": [
      "subscription",
      "setup_fee"
    ]
  },
  "gift": {
    "id": 30,
    "amount_off": 1,
    "percent_off": 100,
    "addon_duration": "once",
    "remove_products_after_coupon_detached": false,
    "products": [
      {}
    ]
  },
  "rules": {
    "emails": {},
    "customers": {},
    "subscriptions": {}
  },
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z",
  "deleted_at": "2026-01-15T10:30:00Z"
}

Update a coupon

PATCH /coupons/{coupon_id}

Partially update a coupon. All fields are optional.

Path parameters

coupon_idRequiredinteger

Coupon ID

Query parameters

expand[]optionalstring[]

List of relations to expand in the response.

Request body

nameoptionalstring

durationoptionalstring

Possible values: once, forever, multiple.

duration_in_monthsoptionalinteger

Required when duration is "multiple". Prohibited when duration is "once" or "forever".

remove_gifts_after_end_of_durationoptionalinteger

Possible values: 0, 1.

max_redemptionsoptionalinteger | null

limit_one_per_customeroptionalinteger

Possible values: 0, 1.

redeem_byoptionalstring | null

Expiry date in Y-m-dTH:i:s format, interpreted as UTC. Must be after tomorrow.

Format: date-time.

conditionoptionalobject | null

Set to null to remove the condition.

discountoptionalobject | null

Update discount settings.

giftoptionalobject | null

Update gift settings.

rulesoptionalobject | null

Update restriction rules. Omit a type to leave it unchanged.

ReturnsCoupon

Coupon updated

curl -X PATCH https://api.subbly.co/private/v1/coupons/{coupon_id} \
  -H 'X-API-KEY: <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "name",
  "duration": "once",
  "duration_in_months": 1,
  "remove_gifts_after_end_of_duration": 0,
  "max_redemptions": 1,
  "limit_one_per_customer": 0,
  "redeem_by": "2026-12-31T23:59:59",
  "condition": {
    "type": "product",
    "operator": "any",
    "products": {
      "create": [
        {
          "product_id": 1
        }
      ],
      "delete": [
        {
          "id": 1
        }
      ]
    },
    "collections": {
      "create": [
        {
          "collection_id": 1
        }
      ],
      "delete": [
        {
          "id": 1
        }
      ]
    },
    "cart_value": {
      "min": 1,
      "max": 1
    },
    "cart_quantity": {
      "min": 1,
      "max": 1
    }
  },
  "discount": {
    "amount_off": 1,
    "percent_off": 1.5,
    "item_types": [
      "subscription"
    ],
    "products": [
      1
    ],
    "products_operator": "only",
    "skip_payment_method": 0,
    "first_shipment_only": 0
  },
  "gift": {
    "amount_off": 1,
    "percent_off": 1.5,
    "addon_duration": "once",
    "remove_products_after_coupon_detached": 0,
    "products": {
      "create": [
        {
          "product_id": 1
        }
      ],
      "delete": [
        {
          "id": 1
        }
      ]
    }
  },
  "rules": {
    "emails": {
      "create": [
        "customer@example.com"
      ],
      "delete": [
        "customer@example.com"
      ]
    },
    "customers": {
      "create": [
        1
      ],
      "delete": [
        1
      ]
    },
    "subscriptions": {
      "create": [
        1
      ],
      "delete": [
        1
      ]
    }
  }
}'

Response

{
  "id": 1234,
  "coupon_id": "SAVE20",
  "name": "20% off",
  "duration": "once",
  "duration_in_months": 3,
  "remove_gifts_after_end_of_duration": false,
  "max_redemptions": 100,
  "times_redeemed": 5,
  "active": true,
  "limit_one_per_customer": false,
  "redeem_by": "2026-12-31 23:59:59",
  "valid": true,
  "condition": {
    "id": 10,
    "type": "product",
    "operator": "only",
    "products": [
      {}
    ],
    "collections": [
      {}
    ],
    "cart_value": {
      "min": 1,
      "max": 1
    },
    "cart_quantity": {
      "min": 1,
      "max": 1
    }
  },
  "discount": {
    "id": 20,
    "amount_off": 500,
    "percent_off": 20,
    "skip_payment_method": false,
    "first_shipment_only": false,
    "products": [
      "389855",
      "389856"
    ],
    "products_operator": "only",
    "item_types": [
      "subscription",
      "setup_fee"
    ]
  },
  "gift": {
    "id": 30,
    "amount_off": 1,
    "percent_off": 100,
    "addon_duration": "once",
    "remove_products_after_coupon_detached": false,
    "products": [
      {}
    ]
  },
  "rules": {
    "emails": {},
    "customers": {},
    "subscriptions": {}
  },
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z",
  "deleted_at": "2026-01-15T10:30:00Z"
}

Archive a coupon

POST /coupons/{coupon_id}/archive

Archive (deactivate) a coupon.

Path parameters

coupon_idRequiredinteger

Coupon ID

ReturnsCoupon

Coupon archived

curl -X POST https://api.subbly.co/private/v1/coupons/{coupon_id}/archive \
  -H 'X-API-KEY: <api-key>'

Response

{
  "id": 1234,
  "coupon_id": "SAVE20",
  "name": "20% off",
  "duration": "once",
  "duration_in_months": 3,
  "remove_gifts_after_end_of_duration": false,
  "max_redemptions": 100,
  "times_redeemed": 5,
  "active": true,
  "limit_one_per_customer": false,
  "redeem_by": "2026-12-31 23:59:59",
  "valid": true,
  "condition": {
    "id": 10,
    "type": "product",
    "operator": "only",
    "products": [
      {}
    ],
    "collections": [
      {}
    ],
    "cart_value": {
      "min": 1,
      "max": 1
    },
    "cart_quantity": {
      "min": 1,
      "max": 1
    }
  },
  "discount": {
    "id": 20,
    "amount_off": 500,
    "percent_off": 20,
    "skip_payment_method": false,
    "first_shipment_only": false,
    "products": [
      "389855",
      "389856"
    ],
    "products_operator": "only",
    "item_types": [
      "subscription",
      "setup_fee"
    ]
  },
  "gift": {
    "id": 30,
    "amount_off": 1,
    "percent_off": 100,
    "addon_duration": "once",
    "remove_products_after_coupon_detached": false,
    "products": [
      {}
    ]
  },
  "rules": {
    "emails": {},
    "customers": {},
    "subscriptions": {}
  },
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z",
  "deleted_at": "2026-01-15T10:30:00Z"
}