Offer Data API: coded coupons and title-only / auto-applied offers

Code present vs code null

When to use Offer Data API vs siblings

Endpoints table

Bearer auth required. Successful calls count toward monthly API caps. Spec: openapi-customer.yaml.

Curl and JSON examples

curl -sS -X POST "https://api.feedico.io/api/v1/me/coupons" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"page":1,"pageSize":50}'

{
  "ok": true,
  "recordCount": 2,
  "page": 1,
  "pageSize": 50,
  "coupons": [
    {
      "id": "cpn_9001",
      "provider": "cj_affiliate",
      "firmName": "Example Outdoor Co",
      "title": "15% off sitewide",
      "code": "OUTDOOR15",
      "startsAt": "2026-09-01T00:00:00.000Z",
      "endsAt": "2026-09-30T23:59:59.000Z",
      "offerUrl": "https://www.example-outdoor.com/?sid=pub",
      "status": "active"
    },
    {
      "id": "cpn_9002",
      "provider": "cj_affiliate",
      "firmName": "Example Outdoor Co",
      "title": "Free shipping over $75 (auto-applied)",
      "code": null,
      "startsAt": null,
      "endsAt": "2026-09-15T23:59:59.000Z",
      "offerUrl": "https://www.example-outdoor.com/shipping?sid=pub",
      "status": "active"
    }
  ],
  "availableProviders": ["cj_affiliate"]
}

curl -sS -X POST "https://api.feedico.io/api/v1/catalog/coupons" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"page":1,"pageSize":50,"q":"shipping"}'

{
  "ok": true,
  "recordCount": 1,
  "page": 1,
  "pageSize": 50,
  "coupons": [
    {
      "id": "cat_cpn_4411",
      "brandName": "Example Outdoor Co",
      "provider": "cj_affiliate",
      "title": "15% off sitewide",
      "code": "OUTDOOR15",
      "startsAt": "2026-09-01T00:00:00.000Z",
      "endsAt": "2026-09-30T23:59:59.000Z",
      "merchantWebsiteUrl": "https://www.example-outdoor.com"
    }
  ]
}

Field glossary

Architecture workflow: offers into a deals site

1. Sync coupons via connected integrations; upsert on (provider, externalCouponId).
2. Page /me/coupons on a schedule; respect startsAt/endsAt in your CMS.
3. Branch UI: code present → copy control; code null → title + CTA only.
4. Click out through offerUrl on /me, or attach your own tracking when using catalog discovery.
5. Pair with merchants for store pages and commerce data hub for the full stack story.

Firm (merchant)
   |
   +-- Offer / Coupon rows
         |
         +-- code present  →  copy-code UX + offerUrl (/me)
         +-- code null     →  title-only / auto-applied UX
         |
   Eligibility: startsAt .. endsAt

Catalog: /catalog/coupons  →  discovery metadata only (no offerUrl)

Offer Data API FAQ

What is the Offer Data API?

It is the offer-object framing of Feedico coupon rows: coded vouchers (code present) and title-only or auto-applied promotions (code null). Production listing contract details live on /coupon-api; this page explains the offer shape, eligibility windows, and offerUrl behavior.

Which endpoint should I call for offers?

POST /api/v1/me/coupons for account-scoped offers with tracked offerUrl when available. POST /api/v1/catalog/coupons for discovery without tracking URLs. Both require a Bearer token and count toward monthly API caps.

What does code: null mean?

A null code usually means a title-only or auto-applied offer: shoppers may not type a voucher. Render the title and deep-link via offerUrl (on /me) or your own compliant tracking link (when using catalog discovery).

How do eligibility windows work?

startsAt and endsAt mark when an offer is valid. Either may be null for open-ended or unknown windows. Filter expired rows in your CMS or request active-only filters as documented in OpenAPI.

When is offerUrl returned?

Account /me/coupons includes offerUrl when your sync provides a tracked link. Catalog coupons omit offerUrl so other publishers' tracking links are never shared. Attach your own links before publishing.

How is this different from /coupon-api?

/coupon-api is the production coupon listing contract for publishers building code pages and deal sites. /offer-data-api is the conceptual offer-object page: coded vs title-only, windows, and tracking. Link both; implement against the same /me/coupons and /catalog/coupons endpoints.

Can I mix offers with product deals?

Yes. Use offers for promo messaging and /product-deal-feed-api or /product-data-api for SKU-level prices. Keep codes and SKUs as separate UI modules so shoppers are not confused.

Where do I read network field mapping?

See how Feedico normalizes affiliate network schemas and the affiliate marketing network data model for Firm/Coupon relationships and natural keys.