Offers

The public offer flow has one buyer offer and, when the seller chooses, one seller counter-offer. The buyer cannot counter again; the buyer must accept or reject the seller counter.

Prerequisites

• The product is currently available to this buyer.
• The product reports offers_allowed: true.
• The collector authorized the relevant offer scopes.
• A usable saved payment method and default shipping address are required before accepting a counter-offer or when an offer completes a purchase immediately.

Sequence

1. Submit POST /api/public/v1/offers with product_id, buyer amount, and a new external ID.
2. Inspect the response:
   • An offer response represents the current offer thread.
   • A purchase response means the offer completed a purchase immediately.
3. Read GET /api/public/v1/offers/{offerId} or consume offer webhooks for changes.
4. When the latest offer is PENDING and from_side is SELLER, either:
   • Accept it with POST /api/public/v1/offers/{offerId}/accept.
   • Reject it with POST /api/public/v1/offers/{offerId}/reject.
5. An accepted counter returns the same purchase schema as the buy endpoint.

Use GET /api/public/v1/offers?status=ACTIVE to return only offer threads whose latest offer is pending and has not expired. The filter is applied before pagination.

Identifiers

• id identifies the latest offer message returned by Mascot.
• thread_id is stable across the original buyer offer and seller counter-offer.
• Request external_id values are generated by your integration and provide idempotency.

Use a distinct external ID for creating the offer and for each accept or reject action. Reusing an action ID for a different offer or action returns 409 idempotency_conflict.

Webhooks

• offer.created is sent when the buyer offer is created.
• offer.updated is sent when the current offer state changes, including a seller counter-offer.
• purchase.created is sent when an accepted offer becomes a purchase.

Webhook deliveries can be duplicated, so use the envelope event ID for deduplication.