Promotion and discount rule management for direct, bundle, package, and buy/get offers

Offers

Offers let you define promotion rules across your catalog using product identity fields already used in Linkit (iv_id, barcode, product ID, SKU ID).

Supported offer types:

direct_discount
package_deal
bundle_deal
bogo
btgo
buy_x_get_discount

Offer Object

{
  "id": "ofr_123",
  "organization_id": "org_abc",
  "organization_app_id": "org_app_1",
  "name": "Weekend 15%",
  "offer_type": "direct_discount",
  "status": "active",
  "is_active": true,
  "target_scope": "product",
  "target_iv_id": "PRD-1001",
  "target_barcode": "6281000001111",
  "discount_type": "percentage",
  "discount_value": 15,
  "start_at": "2026-03-25T00:00:00Z",
  "end_at": "2026-03-31T23:59:59Z",
  "meta": {
    "campaign": "ramadan-weekend"
  }
}

Endpoints

Method	Endpoint	Description
`GET`	`/api/v1/offers`	List offers with pagination and filters
`GET`	`/api/v1/offers/{id}`	Get one offer
`POST`	`/api/v1/offers`	Create offer
`PUT`	`/api/v1/offers/{id}`	Update offer
`PATCH`	`/api/v1/offers/{id}/status`	Update status/is_active
`DELETE`	`/api/v1/offers/{id}`	Delete offer
`POST`	`/api/v1/offers/bulk`	Bulk upsert offers
`GET`	`/api/v1/reports/offers`	Offers analytics report

Create Offer

POST /api/v1/offers

Direct Discount Example

{
  "name": "Weekend 15%",
  "offer_type": "direct_discount",
  "status": "active",
  "target_scope": "product",
  "target_iv_id": "PRD-1001",
  "discount_type": "percentage",
  "discount_value": 15
}

BOGO Example

{
  "name": "Buy 1 Get 1",
  "offer_type": "bogo",
  "status": "active",
  "buy_qty": 1,
  "get_qty": 1,
  "buy_iv_id": "PRD-2001",
  "get_iv_id": "PRD-2002"
}

Buy X Get Discount Example

{
  "name": "Buy 2 Get 30% Off",
  "offer_type": "buy_x_get_discount",
  "status": "active",
  "buy_qty": 2,
  "buy_iv_id": "PRD-3001",
  "get_discount_percent": 30
}

List Filters

GET /api/v1/offers supports:

page, limit, sort
status
offer_type
target_scope
organization_app_id
target_iv_id
target_barcode
is_active
synced
search

Bulk Upsert

POST /api/v1/offers/bulk

{
  "offers": [
    {
      "name": "Direct 10",
      "offer_type": "direct_discount",
      "status": "active",
      "target_scope": "product",
      "target_iv_id": "PRD-1",
      "discount_type": "percentage",
      "discount_value": 10
    },
    {
      "name": "Buy 2 Get 1",
      "offer_type": "package_deal",
      "status": "scheduled",
      "buy_qty": 2,
      "get_qty": 1,
      "buy_iv_id": "PRD-2",
      "get_iv_id": "PRD-3"
    }
  ]
}

Report Endpoint

GET /api/v1/reports/offers?days=90

Returns:

summary: total, active, scheduled, draft, expired, synced, average discount
byType: offer volume grouped by type
byStatus: offer volume grouped by status
recentOffers: latest offer updates
topTargets: most targeted products/identities
appBreakdown: offer distribution by organization_app_id

Identity Compatibility

Offer hooks and API validation keep targeting aligned with your current schema, including iv_id and barcode resolution for product and SKU scopes.

Offers

On this page