The BYBE Retail API, version 1. A REST/JSON API over BYBE's records of manufacturers, rebate offers and products, plus the write surface that clips offers for consumers, validates redemptions against purchases, and disburses consumer payouts. 16 operations across 7 tags, authenticated with HTTP Basic (API key as username, API secret as password). US only - the state filter on offers and stores is how BYBE's state-by-state alcohol compliance boundary is expressed in the contract.
---
openapi: 3.0.1
info:
title: BYBE API
version: v1
description: "\n Welcome to the BYBE API, V1.\n\n You can use this API to access
our records of manufacturers,\n rebate offers, and products,\n as well as to validate
redemptions for transactions and disburse payouts.\n\n Each route is documented
below via the OpenAPI specification.\n Authorization details can be entered using
the `Authorize` button on the right.\n "
paths:
"/v1/clips":
get:
summary: list clips
tags:
- Clips
description: List clips, optionally filtering by offer_id, the consumer's retailer_identifier,
or other options.
security:
- basic_auth: []
parameters:
- name: page
in: query
required: false
description: Page of results to return
schema:
type: integer
- name: limit
in: query
required: false
description: Number of clips per page
schema:
type: integer
- name: offer_id
in: query
required: false
description: Filter to a specific offer
schema:
type: integer
- name: consumer_retailer_identifier
in: query
required: false
description: Filter to a specific consumer
schema:
type: string
responses:
'200':
description: list of clips
content:
application/json:
examples:
unfiltered list of clips:
value:
clips:
- id: 980190962
consumer:
id: 980190962
retailer_identifier: RETAILERCONSUMERID
created_at: '2026-06-17T13:55:38.873Z'
retailer_identifier: 123ABC
latitude: '10.12331'
longitude: "-120.02332"
created_at: '2026-06-17T13:55:38.862Z'
offer:
id: 980190962
name: Holiday sale on spirits
clip_limit: 5
clips_remaining: -3
budget_limit_cents: 2000
budget_limit_currency: USD
budget_remaining_cents: 1700
budget_remaining_currency: USD
discount_cents: 300
discount_currency: USD
conditions: Offer open to residents of KY. Must be 21 years
of age.
details: Offer details
start_date: '2017-10-27T02:13:25.000Z'
end_date: '2026-07-17T13:55:38.000Z'
per_consumer_limit: 1
redemptions_available: 10
redemptions_remaining: 9
offer_type: discount
created_at: '2026-06-17T13:55:38.857Z'
updated_at: '2026-06-17T13:55:38.857Z'
- id: 1018350795
consumer:
id: 980190962
retailer_identifier: RETAILERCONSUMERID
created_at: '2026-06-17T13:55:38.873Z'
retailer_identifier: 789ABC
latitude: '10.12331'
longitude: "-120.02332"
created_at: '2026-06-17T13:55:38.862Z'
offer:
id: 621189049
name: Buy one of these, get cash
clip_limit: 5
clips_remaining: 3
budget_limit_cents: 2000
budget_limit_currency: USD
budget_remaining_cents: 2000
budget_remaining_currency: USD
discount_cents: 300
discount_currency: USD
conditions: Buy three in OH.
details: Offer details
start_date: '2017-10-27T02:13:25.000Z'
end_date: '2026-07-17T13:55:38.000Z'
per_consumer_limit: 1
redemptions_available: 10
redemptions_remaining: 10
offer_type: discount
created_at: '2026-06-17T13:55:38.857Z'
updated_at: '2026-06-17T13:55:38.857Z'
- id: 51848956
consumer:
id: 980190962
retailer_identifier: RETAILERCONSUMERID
created_at: '2026-06-17T13:55:38.873Z'
retailer_identifier: 189DDD
latitude: '10.12331'
longitude: "-120.02332"
created_at: '2026-06-17T13:55:38.862Z'
offer:
id: 955136116
name: Beer Club
clip_limit: 5
clips_remaining: 3
budget_limit_cents: 5000
budget_limit_currency: USD
budget_remaining_cents: 5000
budget_remaining_currency: USD
discount_cents: 500
discount_currency: USD
conditions: Buy 6 get 5 back
details: Offer details
start_date: '2017-10-27T02:13:25.000Z'
end_date: '2026-07-17T13:55:38.000Z'
per_consumer_limit: 1
redemptions_available: 1
redemptions_remaining: 1
offer_type: club
created_at: '2026-06-17T13:55:38.857Z'
updated_at: '2026-06-17T13:55:38.857Z'
- id: 374648174
consumer:
id: 980190962
retailer_identifier: RETAILERCONSUMERID
created_at: '2026-06-17T13:55:38.873Z'
retailer_identifier: 189EEE
latitude: '10.12331'
longitude: "-120.02332"
created_at: '2026-06-17T13:55:38.862Z'
offer:
id: 849914497
name: Beer Club Two
clip_limit: 5
clips_remaining: 3
budget_limit_cents: 5000
budget_limit_currency: USD
budget_remaining_cents: 5000
budget_remaining_currency: USD
discount_cents: 100
discount_currency: USD
conditions: Buy 2 get 1 back
details: Offer details
start_date: '2017-10-27T02:13:25.000Z'
end_date: '2026-07-17T13:55:38.000Z'
per_consumer_limit: 1
redemptions_available: 1
redemptions_remaining: 1
offer_type: club
created_at: '2026-06-17T13:55:38.857Z'
updated_at: '2026-06-17T13:55:38.857Z'
meta:
current_page: 1
total_pages: 1
per_page_limit: 5000
total_records: 4
count: 4
list clips for a specific consumer:
value:
clips:
- id: 980190962
consumer:
id: 980190962
retailer_identifier: RETAILERCONSUMERID
created_at: '2026-06-17T13:55:38.873Z'
retailer_identifier: 123ABC
latitude: '10.12331'
longitude: "-120.02332"
created_at: '2026-06-17T13:55:38.862Z'
offer:
id: 980190962
name: Holiday sale on spirits
clip_limit: 5
clips_remaining: -3
budget_limit_cents: 2000
budget_limit_currency: USD
budget_remaining_cents: 1700
budget_remaining_currency: USD
discount_cents: 300
discount_currency: USD
conditions: Offer open to residents of KY. Must be 21 years
of age.
details: Offer details
start_date: '2017-10-27T02:13:25.000Z'
end_date: '2026-07-17T13:55:38.000Z'
per_consumer_limit: 1
redemptions_available: 10
redemptions_remaining: 9
offer_type: discount
created_at: '2026-06-17T13:55:38.857Z'
updated_at: '2026-06-17T13:55:38.857Z'
- id: 1018350795
consumer:
id: 980190962
retailer_identifier: RETAILERCONSUMERID
created_at: '2026-06-17T13:55:38.873Z'
retailer_identifier: 789ABC
latitude: '10.12331'
longitude: "-120.02332"
created_at: '2026-06-17T13:55:38.862Z'
offer:
id: 621189049
name: Buy one of these, get cash
clip_limit: 5
clips_remaining: 3
budget_limit_cents: 2000
budget_limit_currency: USD
budget_remaining_cents: 2000
budget_remaining_currency: USD
discount_cents: 300
discount_currency: USD
conditions: Buy three in OH.
details: Offer details
start_date: '2017-10-27T02:13:25.000Z'
end_date: '2026-07-17T13:55:38.000Z'
per_consumer_limit: 1
redemptions_available: 10
redemptions_remaining: 10
offer_type: discount
created_at: '2026-06-17T13:55:38.857Z'
updated_at: '2026-06-17T13:55:38.857Z'
- id: 51848956
consumer:
id: 980190962
retailer_identifier: RETAILERCONSUMERID
created_at: '2026-06-17T13:55:38.873Z'
retailer_identifier: 189DDD
latitude: '10.12331'
longitude: "-120.02332"
created_at: '2026-06-17T13:55:38.862Z'
offer:
id: 955136116
name: Beer Club
clip_limit: 5
clips_remaining: 3
budget_limit_cents: 5000
budget_limit_currency: USD
budget_remaining_cents: 5000
budget_remaining_currency: USD
discount_cents: 500
discount_currency: USD
conditions: Buy 6 get 5 back
details: Offer details
start_date: '2017-10-27T02:13:25.000Z'
end_date: '2026-07-17T13:55:38.000Z'
per_consumer_limit: 1
redemptions_available: 1
redemptions_remaining: 1
offer_type: club
created_at: '2026-06-17T13:55:38.857Z'
updated_at: '2026-06-17T13:55:38.857Z'
- id: 374648174
consumer:
id: 980190962
retailer_identifier: RETAILERCONSUMERID
created_at: '2026-06-17T13:55:38.873Z'
retailer_identifier: 189EEE
latitude: '10.12331'
longitude: "-120.02332"
created_at: '2026-06-17T13:55:38.862Z'
offer:
id: 849914497
name: Beer Club Two
clip_limit: 5
clips_remaining: 3
budget_limit_cents: 5000
budget_limit_currency: USD
budget_remaining_cents: 5000
budget_remaining_currency: USD
discount_cents: 100
discount_currency: USD
conditions: Buy 2 get 1 back
details: Offer details
start_date: '2017-10-27T02:13:25.000Z'
end_date: '2026-07-17T13:55:38.000Z'
per_consumer_limit: 1
redemptions_available: 1
redemptions_remaining: 1
offer_type: club
created_at: '2026-06-17T13:55:38.857Z'
updated_at: '2026-06-17T13:55:38.857Z'
meta:
current_page: 1
total_pages: 1
per_page_limit: 5000
total_records: 4
count: 4
list clips for a specific offer:
value:
clips:
- id: 1018350795
consumer:
id: 980190962
retailer_identifier: RETAILERCONSUMERID
created_at: '2026-06-17T13:55:38.873Z'
retailer_identifier: 789ABC
latitude: '10.12331'
longitude: "-120.02332"
created_at: '2026-06-17T13:55:38.862Z'
offer:
id: 621189049
name: Buy one of these, get cash
clip_limit: 5
clips_remaining: 3
budget_limit_cents: 2000
budget_limit_currency: USD
budget_remaining_cents: 2000
budget_remaining_currency: USD
discount_cents: 300
discount_currency: USD
conditions: Buy three in OH.
details: Offer details
start_date: '2017-10-27T02:13:25.000Z'
end_date: '2026-07-17T13:55:38.000Z'
per_consumer_limit: 1
redemptions_available: 10
redemptions_remaining: 10
offer_type: discount
created_at: '2026-06-17T13:55:38.857Z'
updated_at: '2026-06-17T13:55:38.857Z'
meta:
current_page: 1
total_pages: 1
per_page_limit: 5000
total_records: 1
count: 1
post:
summary: create a clip
tags:
- Clips
description: A clip represents a consumer's intent to redeem an offer. Offer
clip data will display in the BYBE dashboard to let your team know how many
people intended to redeem the offer.
security:
- basic_auth: []
parameters: []
responses:
'201':
description: successfully created a clip
content:
application/json:
example:
clip:
id: 1018350796
retailer_identifier: your_clip_identifier
latitude: '42.068443'
longitude: "-81.195412"
created_at: '2026-06-17T13:55:39.253Z'
offer:
id: 980190962
name: Holiday sale on spirits
budget_limit_cents: 2000
budget_limit_currency: USD
budget_remaining_cents: 1700
budget_remaining_currency: USD
discount_cents: 300
discount_currency: USD
conditions: Offer open to residents of KY. Must be 21 years of
age.
details: Offer details
start_date: '2017-10-27T02:13:25.000Z'
end_date: '2026-07-17T13:55:38.000Z'
per_consumer_limit: 1
redemptions_available: 10
redemptions_remaining: 9
offer_type:
id: 568374289
name: discount
created_at: '2026-06-17T13:55:38.868Z'
updated_at: '2026-06-17T13:55:38.868Z'
created_at: '2026-06-17T13:55:38.857Z'
updated_at: '2026-06-17T13:55:38.857Z'
consumer:
id: 113629430
retailer_identifier: ANOTHER_RETAILER_CONSUMER
created_at: '2026-06-17T13:55:38.873Z'
'303':
description: clip already exists for the same offer and consumer
content:
application/json:
example:
location: "/v1/clips/980190962"
clip:
errors:
retailer_identifier:
- has already been taken
duplicate_clip:
- Duplicate clips are not permitted
'409':
description: a different clip already exists with this retailer_identifier
content:
application/json:
example:
clip:
errors:
retailer_identifier:
- has already been taken
'422':
description: a required field is missing
content:
application/json:
example:
clip:
errors:
retailer_identifier:
- can't be blank
requestBody:
content:
application/json:
schema:
type: object
required:
- clip
properties:
clip:
type: object
required:
- offer_id
- retailer_identifier
properties:
offer_id:
type: integer
description: The ID of the offer to clip
retailer_identifier:
type: string
description: Your unique identifier for this clip
consumer:
type: object
required:
- retailer_identifier
properties:
retailer_identifier:
type: string
email:
type: string
description: The email address of the consumer clipping
the offer
payout_email_override:
type: string
description: An override email address for payout purposes
if different from the consumer email. Only send this if
the consumer specifically provided a different email for
BYBE rebates
latitude:
type: number
minimum: -90
maximum: 90
longitude:
type: number
minimum: -180
maximum: 180
"/v1/clips/{id}":
parameters:
- name: id
in: path
description: id of the clip
required: true
schema:
type: string
get:
summary: show clip
tags:
- Clips
security:
- basic_auth: []
responses:
'200':
description: successful
content:
application/json:
example:
clip:
id: 980190962
consumer:
id: 980190962
retailer_identifier: RETAILERCONSUMERID
created_at: '2026-06-17T13:55:38.873Z'
retailer_identifier: 123ABC
latitude: '10.12331'
longitude: "-120.02332"
created_at: '2026-06-17T13:55:38.862Z'
offer:
id: 980190962
name: Holiday sale on spirits
clip_limit: 5
clips_remaining: -3
budget_limit_cents: 2000
budget_limit_currency: USD
budget_remaining_cents: 1700
budget_remaining_currency: USD
discount_cents: 300
discount_currency: USD
conditions: Offer open to residents of KY. Must be 21 years of
age.
details: Offer details
start_date: '2017-10-27T02:13:25.000Z'
end_date: '2026-07-17T13:55:38.000Z'
per_consumer_limit: 1
redemptions_available: 10
redemptions_remaining: 9
offer_type: discount
created_at: '2026-06-17T13:55:38.857Z'
updated_at: '2026-06-17T13:55:38.857Z'
"/v1/consumers":
post:
summary: create a consumer
tags:
- Consumers
description: Creates a consumer object ahead of time, it is recommended to create
consumers automatically by creating clips / redemptions instead.
security:
- basic_auth: []
parameters: []
responses:
'200':
description: successful
content:
application/json:
example:
consumer:
id: 1018350796
retailer_identifier: your_consumers_id
created_at: '2026-06-17T13:55:39.350Z'
requestBody:
content:
application/json:
schema:
type: object
required:
- consumer
properties:
consumer:
type: object
required:
- retailer_identifier
properties:
retailer_identifier:
type: string
payout_email_override:
type: string
"/v1/consumers/{retailer_identifier}":
parameters:
- name: retailer_identifier
in: path
description: the retailer identifier of the consumer that was sent with the
clip or redemption requests
required: true
schema:
type: string
get:
summary: show consumer
tags:
- Consumers
security:
- basic_auth: []
responses:
'200':
description: successful
content:
application/json:
example:
consumer:
id: 980190962
retailer_identifier: RETAILERCONSUMERID
created_at: '2026-06-17T13:55:38.873Z'
"/v1/manufacturers":
get:
summary: list manufacturers
tags:
- Manufacturers
security:
- basic_auth: []
parameters:
- name: page
in: query
required: false
description: Page of results to return
schema:
type: integer
- name: limit
in: query
required: false
description: Number of manufacturers per page
schema:
type: integer
responses:
'200':
description: successfully list manufacturers
content:
application/json:
examples:
list all manufacturers:
value:
manufacturers:
- id: 1039554827
name: AB InBev
logo_image_url: https://s3.us-east-2.amazonaws.com/bybe-cdn/manufacturers/abinbev.png
meta:
current_page: 1
total_pages: 1
per_page_limit: 5000
total_records: 1
count: 1
"/v1/manufacturers/{id}":
parameters:
- name: id
in: path
description: manufacturer_id
required: true
schema:
type: string
get:
summary: show a manufacturer
tags:
- Manufacturers
security:
- basic_auth: []
responses:
'200':
description: successful
content:
application/json:
examples:
test_example:
value:
manufacturer:
id: 1039554827
name: AB InBev
logo_image_url: https://s3.us-east-2.amazonaws.com/bybe-cdn/manufacturers/abinbev.png
"/v1/offers":
get:
summary: list offers
tags:
- Offers
security:
- basic_auth: []
parameters:
- name: show_stores
in: query
required: false
description: Defaults to true. When false, stores associated with offers are
omitted from the response.
schema:
type: boolean
- name: show_clips
in: query
required: false
description: Requires consumer_retailer_identifier. When true, includes clip
information for each offer indicating whether it has been clipped by the
specified consumer.
schema:
type: boolean
- name: show_details
in: query
required: false
description: Defaults to false. When true, includes additional store details
in the response.
schema:
type: boolean
- name: prelive
in: query
required: false
description: Defaults to false. When true, includes offers that are not yet
live. Client applications should ensure pre-live offers are hidden from
end users.
schema:
type: boolean
- name: state
in: query
schema:
"$ref": "#/components/schemas/state_string_enum"
required: false
description: By default offers from all states are returned. When a state
is specified, only offers available in that state are returned.
- name: consumer_retailer_identifier
in: query
required: false
description: Adds consumer-specific information to the response, such as whether
the offers have been clipped by the specified consumer as well as how many
redemptions remain for each offer based on the consumer's previous redemptions.
schema:
type: string
responses:
'200':
description: successfully list offers
content:
application/json:
examples:
unfiltered list of offers:
value:
offers:
- id: 36642025
name: 1Super Saver Special
image_url: thing.jpg
clip_limit: 5
clips_remaining: 5
budget_limit_cents: 5000
budget_limit_currency: USD
budget_remaining_cents: 4000
budget_remaining_currency: USD
discount_cents: 500
discount_currency: USD
conditions: Buy 2 get 1 back
details: Offer details
start_date: '2017-10-27'
end_date: '2026-06-27'
per_consumer_limit: 2
daily_per_consumer_limit:
redemptions_available: 4
redemptions_remaining: 2
redemptions_used: 2
offer_type: discount
created_at: '2026-06-17T13:55:38.857Z'
updated_at: '2026-06-17T13:55:38.857Z'
featured: false
vibrant_colors:
image_content_height:
required_products:
- quantity: 2
product:
retailer_identifier: 123ABC
name: 12 Pack of Beer
upcs:
- '767676767676'
image_url: https://s3.amazonaws.com/bybe-product-images/coppola-chardonnay.png
product_type:
name: Beer
products:
- retailer_identifier: 123ABC
name: 12 Pack of Beer
upcs:
- '767676767676'
image_url: https://s3.amazonaws.com/bybe-product-images/coppola-chardonnay.png
product_type:
name: Beer
- retailer_identifier:
name: Jug of Vodka
upcs:
- '434363463463'
image_url: https://s3.amazonaws.com/bybe-product-images/coppola-chardonnay.png
product_type:
name: Cider
- retailer_identifier: 123ABC
name: Soft Apple Cider
upcs:
- '123123123123'
- '989898989898'
image_url: https://s3.amazonaws.com/bybe-product-images/coppola-chardonnay.png
product_type:
name: Cider
states:
- abbreviation: OH
name: Ohio
- abbreviation: IL
name: Illinois
stores:
- retailer_identifier: 0000Valid
- retailer_identifier: CBUS
- id: 373731297
name: Buy 2x and Y
image_url: thing.jpg
clip_limit: 5
clips_remaining: 5
budget_limit_cents: 5000
budget_limit_currency: USD
budget_remaining_cents: 5000
budget_remaining_currency: USD
discount_cents: 100
discount_currency: USD
conditions: Buy 2x and y get z back
details: Offer details
start_date: '2017-10-27'
end_date: '2026-06-27'
per_consumer_limit: 2
daily_per_consumer_limit:
redemptions_available: 4
redemptions_remaining: 4
redemptions_used: 0
offer_type: discount
created_at: '2026-06-17T13:55:38.857Z'
updated_at: '2026-06-17T13:55:38.857Z'
featured: false
vibrant_colors:
image_content_height:
required_products:
- quantity: 2
product:
retailer_identifier: 123ABC
name: 12 Pack of Beer
upcs:
- '767676767676'
# --- truncated at 32 KB (164 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bybe/refs/heads/main/openapi/bybe-api-openapi-original.yml