Documentation

Authenticate with an API key and send promotion text to CouponBrain. One successful extract uses one credit.

Authentication

Create a key on Generate API key, then send it as a Bearer token. The secret is shown once.

Authorization: Bearer aff_…

Extract

POST /api/extract reads promotion text and returns grounded coupons, tiers, scope flags, campaign events, campaign themes, and an end date.

text

string, required

Promotion source. Max 20,000 characters.

as_of

YYYY-MM-DD, optional

Temporal context for countdowns. Not used as coupon evidence. Defaults to today if omitted.

model

string, optional

latest or couponbrain-mini-1.10. Empty or omitted is latest. Both currently resolve to Mini 1.10.

format

string, optional

json or toon. Empty or omitted is json.

curl https://affensus.com/api/extract \
  -H "Authorization: Bearer aff_…" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Use code SAVE20 for 20% off your order. New customers only. Ends in 3 days.",
    "as_of": "2026-09-27",
    "model": "latest",
    "format": "json"
  }'

Response

success

boolean

True when extraction finished.

result

object | string

Canonical payload when format is json. TOON string when format is toon. Same fields either way.

processing_ms

number | null

Upstream processing time.

credits_used

number

Credits deducted for this request. 1 on a billed extract, 0 on the homepage demo.

credits_remaining

number | null

Credits left after this request.

usage

object | null

Token and generation timing from the model.

{
  "success": true,
  "result": {
    "coupons": [
      {
        "code": "SAVE20",
        "type": "percentage",
        "currency": null,
        "scope": {
          "sitewide": true,
          "new_customers_only": true
        },
        "tiers": [
          {
            "minimum_spend": null,
            "discount_percent": 20
          },
          {
            "minimum_spend": 50,
            "discount_percent": 25,
            "capped_discount": 15
          }
        ]
      },
      {
        "code": "SHIPFREE",
        "type": "free_shipping",
        "currency": "USD",
        "scope": {
          "app_only": true
        },
        "tiers": [
          {
            "minimum_spend": 25
          }
        ]
      },
      {
        "code": "TAKE10",
        "type": "fixed",
        "currency": "EUR",
        "scope": {},
        "tiers": [
          {
            "minimum_spend": null,
            "discount_amount": 10
          }
        ]
      }
    ],
    "end_date": "2026-09-30",
    "campaign_events": ["black_friday"],
    "campaign_themes": ["new_customer_offer"]
  },
  "processing_ms": 150,
  "credits_used": 1,
  "credits_remaining": 9999
}

Result

coupons

array

Grounded coupons only. A code must appear as its own token in the source. Multiple thresholds for the same code stay in tiers, not as duplicate coupons.

coupons[].code

string | null

Code as it appears in the source.

coupons[].type

string

One of percentage, fixed, free_shipping, gift, other, unknown.

coupons[].currency

string | null

ISO currency when the discount is a fixed amount. Null for percentage and most other types.

end_date

YYYY-MM-DD | null

Explicit calendar date in the source, then a countdown resolved against as_of, otherwise null.

Scope

coupons[].scope is an object of boolean flags. A key is present only when it is true. An empty object means no extra limits.

sitewide

boolean

The code applies store-wide, not to one product or category.

new_customers_only

boolean

The code is limited to first-time or new customers.

app_only

boolean

The code is limited to the merchant app.

Tiers

coupons[].tiers holds spend thresholds for the same code. Sort is not guaranteed. minimum_spend is always present. Discount keys are omitted when they do not apply.

minimum_spend

number | null

Basket minimum for this tier. Null when there is no minimum.

discount_percent

number

Percent off. Used with type percentage.

discount_amount

number

Fixed amount off. Used with type fixed. Read with currency.

capped_discount

number

Maximum discount amount when a percent off is capped.

Campaign events

campaign_events is a string array of canonical event IDs named in the source. Empty when none are found. Output only IDs from this taxonomy. Do not invent an ID, and do not infer an event from the calendar date alone.

ID	Name
new_year	New year
lunar_new_year	Lunar new year
valentines_day	Valentines day
international_womens_day	International womens day
easter	Easter
mothers_day	Mothers day
fathers_day	Fathers day
labor_day	Labor day
members_day	Members day
halloween	Halloween
black_friday	Black friday
cyber_monday	Cyber monday
christmas	Christmas
boxing_day	Boxing day
singles_day_11_11	Singles day 11 11
1_1	1 1
2_2	2 2
3_3	3 3
4_4	4 4
5_5	5 5
6_6	6 6
7_7	7 7
8_8	8 8
9_9	9 9
10_10	10 10
12_12	12 12
ramadan	Ramadan
eid_al_fitr	Eid al fitr
eid_al_adha	Eid al adha
deepavali	Deepavali
mid_autumn_festival	Mid autumn festival
vesak_day	Vesak day
merdeka	Merdeka
malaysia_day	Malaysia day
singapore_national_day	Singapore national day
singapore_retail_sale	Singapore retail sale
songkran	Songkran
loy_krathong	Loy krathong
indonesia_independence_day	Indonesia independence day
kartini_day	Kartini day
tet	Tet
vietnam_national_day	Vietnam national day
philippines_independence_day	Philippines independence day
philippines_ber_months	Philippines ber months
australia_day	Australia day
click_frenzy	Click frenzy
french_days	French days
afterpay_day	Afterpay day
eofy	Eofy
back_to_school	Back to school
back_to_work	Back to work
graduation	Graduation
wedding_season	Wedding season
travel_fair	Travel fair

Campaign themes

campaign_themes is a string array of canonical theme IDs named in the source. Empty when none are found. Output only IDs from this taxonomy.

ID	Name
payday_sale	Payday sale
mid_month_sale	Mid month sale
month_end_sale	Month end sale
flash_sale	Flash sale
weekend_sale	Weekend sale
one_day_sale	One day sale
limited_time_sale	Limited time sale
early_bird_sale	Early bird sale
clearance_sale	Clearance sale
warehouse_sale	Warehouse sale
closing_down_sale	Closing down sale
spring_sale	Spring sale
summer_sale	Summer sale
autumn_sale	Autumn sale
winter_sale	Winter sale
mid_season_sale	Mid season sale
end_of_season_sale	End of season sale
mid_year_sale	Mid year sale
year_end_sale	Year end sale
anniversary_sale	Anniversary sale
member_sale	Member sale
vip_sale	Vip sale
loyalty_sale	Loyalty sale
new_customer_offer	New customer offer
app_exclusive_sale	App exclusive sale
online_exclusive_sale	Online exclusive sale
new_collection	New collection
launch_sale	Launch sale
preorder_sale	Preorder sale
early_access_sale	Early access sale
last_chance_sale	Last chance sale
mega_sale	Mega sale
super_brand_day	Super brand day
voucher_day	Voucher day
free_shipping_event	Free shipping event
bundle_sale	Bundle sale
buy_more_save_more	Buy more save more
friends_family_sale	Friends family sale
student_sale	Student sale
travel_early_booking	Travel early booking
travel_last_minute	Travel last minute
tax_free_sale	Tax free sale
trade_in_event	Trade in event
gift_event	Gift event
mystery_sale	Mystery sale
live_sale	Live sale
bank_card_sale	Bank card sale
wallet_payment_sale	Wallet payment sale
newsletter_exclusive	Newsletter exclusive
private_sale	Private sale

Credits

A successful extract deducts one credit from the earliest-expiring pack. Failed extracts do not deduct. Unused credits expire 12 months after purchase.

Errors

400

Invalid request

Missing text, text too long, as_of is not a date, or model / format is unknown.

401

Unauthorized

Missing or invalid API key.

402

No credits

No remaining credits on an unexpired pack.

502

Extraction failed

Upstream extract did not complete. Credit is refunded.

JavaScript

const response = await fetch("https://affensus.com/api/extract", {
  method: "POST",
  headers: {
    Authorization: "Bearer aff_…",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "Use code SAVE20 for 20% off your order",
    as_of: "2026-09-27",
    model: "latest",
    format: "json",
  }),
});

const data = await response.json();

Playground

Use Playground to try extract with your key. The API accepts json and toon. Playground can also preview TEXT. Empty model or format is latest and json.