Clips

Clipping is the act of a member "saving" or "activating" a deal. Think of it like clipping a coupon - the member signals intent to use a particular offer. Once clipped, the deal is removed from future delivery results for that member and becomes associated with their wallet.

How Clips Work

1. A deal is shown to a member via delivery
2. The member activates the deal (e.g. taps "Save" or "Clip")
3. You call wallet.clip/save to record the clip
4. The deal is excluded from future list-eligible calls for that member - it has been claimed
5. When the member makes a qualifying purchase, the clip is redeemed and a cashback reward is triggered

Saving a Clip

When a member activates a deal, save the clip using the creative_id from the delivery response:

curl -X POST https://<your-instance-url>/publisher.v1/wallet.clip/save \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "creative_id": "dc_abc",
    "member_id": "m_x1y2z3"
  }'

Listing Clips with Creative Content

To display a member's saved deals (e.g. in a "My Offers" section), list their clips with the associated creative content:

curl -X POST https://<your-instance-url>/publisher.v1/wallet.clip/list-with-creative \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "member_id": "m_x1y2z3",
    "pagination": { "limit": 20 }
  }'

Response:

{
  "data": [
    {
      "id": "dclip_xyz789",
      "deal_id": "deal_001",
      "variant_id": "var_001",
      "creative_id": "dc_abc",
      "deal_creative_format": "banner",
      "deal_creative_content": {
        "surface": {
          "title": "10% cashback at Store",
          "summary": "Earn cashback on your next purchase",
          "image_url": "https://cdn.example.com/banner.png",
          "reward": { "percent": 10 }
        },
        "details": {
          "title": "Store Cashback Deal",
          "image_url": "https://cdn.example.com/detail.png",
          "description": "Get 10% back on purchases over $20",
          "summary": "Limited time offer"
        }
      },
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "redeemed_at": null
    }
  ],
  "page": {
    "page_size": 20,
    "cursor": null,
    "more": false
  }
}

You can also filter by specific clip IDs:

{
  "member_id": "m_x1y2z3",
  "clip_ids": ["dclip_xyz789", "dclip_abc456"]
}

Getting a Single Clip

{
  "id": "dclip_xyz789"
}

Deleting a Clip

If a member wants to "unsave" a deal before it has been redeemed:

{
  "id": "dclip_xyz789"
}

Once deleted, the deal becomes eligible for delivery again for that member.

Clip Lifecycle

State	redeemed_at	Description
Active	null	Deal is clipped, awaiting a qualifying purchase
Redeemed	timestamp	A qualifying transaction was matched and cashback was triggered

Once a clip is redeemed, it cannot be deleted or re-used.

Integration Pattern

A typical clip flow in your application:

1. Call list-eligible → display deals to member
2. Member taps "Save" on a deal
3. Call wallet.clip/save with the creative_id + member_id
4. Update UI to show the deal as "Saved"
5. In the member's wallet/offers section, call list-with-creative to show their active clips
6. When a qualifying purchase occurs (via transaction ingestion), the clip is redeemed automatically by the platform
7. Display the redeemed state to the member