BYBE Redemptions API
Redemptions are created to disburse money to a consumer for their specific purchases.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/bybe-redemptions-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: BYBE Redemptions 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 "
servers:
- url: https://api.bybe.io
description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: Redemptions
description: Redemptions are created to disburse money to a consumer for their specific purchases.
paths:
/v1/redemption_disbursements:
get:
summary: list redemption disbursements
tags:
- Redemptions
security:
- basic_auth: []
description: This endpoint retrieves all redemption disbursements with the ability to filter by retailer consumer ID.
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 redemption disbursements per page
schema:
type: integer
- name: consumer_retailer_identifier
in: query
required: false
description: Filter by a retailer consumer ID.
schema:
type: string
responses:
'200':
description: successfully list redemption disbursements
content:
application/json:
examples:
unfiltered list of redemption disbursements:
value:
redemption_disbursements:
- id: 980190962
status: pending
retailer_identifier: RETAILERREDEMPTIONID
payment_method: closed_loop_card
amount_cents: 300
amount_currency: USD
email: email@example.com
card_redemption_url: null
card_expiration: null
created_at: '2026-06-17T13:55:38.925Z'
updated_at: '2026-06-17T13:55:38.925Z'
consumer:
id: 980190962
retailer_identifier: RETAILERCONSUMERID
created_at: '2026-06-17T13:55:38.873Z'
redemptions:
- id: 980190962
status: accepted
offer:
id: 980190962
name: Holiday sale on spirits
image_url: thing.jpg
discount_cents: 300
payment_method: closed_loop_card
redemptions_remaining: 0
meta:
current_page: 1
total_pages: 1
per_page_limit: 5000
total_records: 1
count: 1
post:
summary: create a redemption disbursement
tags:
- Redemptions
description: This endpoint allows the creation of a new redemption disbursement for a consumer. BYBE will run the purchase data through its rules engine to determine whether the offers applied to the purchase line items are valid. Redemptions will be created for each valid offer and line item combination, and BYBE will disburse money totaling the value of only the valid redemptions.
security:
- basic_auth: []
parameters:
- name: ignore_unknown_upcs
in: query
required: false
description: Whether to ignore unknown UPCs during redemption processing. Default is false.
schema:
type: boolean
responses:
'201':
description: Created a redemption disbursement, check the response for the status of each redemption created in this disbursement.
content:
application/json:
examples:
'201: Accepted: Creates a single redemption disbursement successfully':
value:
redemption_disbursement:
id: 980190963
status: pending
retailer_identifier: my_consumers_redeption_disbursement_1
payment_method: payout_flow
amount_cents: 300
amount_currency: USD
email: example_consumer@example.bybe.com
redemptions:
- id: 980190963
status: accepted
payment_method: payout_flow
redemptions_remaining: 0
per_consumer_limit_reached: true
daily_redemptions_remaining: null
daily_limit_reached: false
purchase:
id: 980190963
retailer_identifier: my_purchase_identifier
offer:
id: 980190962
warnings: {}
'201: Rejected: Rejects redemption when household limit is reached':
value:
redemption_disbursement:
id: 980190965
status: failed_no_redemptions
retailer_identifier: 27a54a63-70d8-4f74-8d72-eeaef672fbfe
payment_method: payout_flow
amount_cents: 0
amount_currency: USD
email: example_consumer@example.bybe.com
redemptions:
- id: 980190965
status: rejected_household_limit
payment_method: payout_flow
redemptions_remaining: 0
per_consumer_limit_reached: true
daily_redemptions_remaining: null
daily_limit_reached: false
purchase:
id: 980190965
retailer_identifier: BOUGHTTWOOFTWO
offer:
id: 36642025
warnings: {}
'201: Accepted: Uses default payout_flow when payment method is missing':
value:
redemption_disbursement:
id: 980190967
status: pending
retailer_identifier: my_consumers_redemption_disbursement_3
payment_method: payout_flow
amount_cents: 500
amount_currency: USD
email: example_consumer@example.bybe.com
redemptions:
- id: 980190969
status: rejected_product_not_purchased
payment_method: payout_flow
redemptions_remaining: 1
per_consumer_limit_reached: false
daily_redemptions_remaining: null
daily_limit_reached: false
purchase:
id: 980190967
retailer_identifier: my_purchase_identifier
offer:
id: 36642025
- id: 980190968
status: accepted
payment_method: payout_flow
redemptions_remaining: 1
per_consumer_limit_reached: false
daily_redemptions_remaining: null
daily_limit_reached: false
purchase:
id: 980190967
retailer_identifier: my_purchase_identifier
offer:
id: 36642025
warnings: {}
'201: Accepted: Forces payout_flow when override flag is set':
value:
redemption_disbursement:
id: 980190969
status: pending
retailer_identifier: my_consumers_redeption_disbursement_3
payment_method: payout_flow
amount_cents: 500
amount_currency: USD
email: example_consumer@example.bybe.com
redemptions:
- id: 980190973
status: rejected_product_not_purchased
payment_method: payout_flow
redemptions_remaining: 1
per_consumer_limit_reached: false
daily_redemptions_remaining: null
daily_limit_reached: false
purchase:
id: 980190969
retailer_identifier: my_purchase_identifier
offer:
id: 36642025
- id: 980190972
status: accepted
payment_method: payout_flow
redemptions_remaining: 1
per_consumer_limit_reached: false
daily_redemptions_remaining: null
daily_limit_reached: false
purchase:
id: 980190969
retailer_identifier: my_purchase_identifier
offer:
id: 36642025
warnings: {}
'201: Accepted: Accepts two redemptions in a single request with separate line items':
value:
redemption_disbursement:
id: 980190971
status: pending
retailer_identifier: my_consumers_redeption_disbursement_3
payment_method: payout_flow
amount_cents: 1000
amount_currency: USD
email: example_consumer@example.bybe.com
redemptions:
- id: 980190976
status: accepted
payment_method: payout_flow
redemptions_remaining: 0
per_consumer_limit_reached: true
daily_redemptions_remaining: null
daily_limit_reached: false
purchase:
id: 980190971
retailer_identifier: my_purchase_identifier
offer:
id: 36642025
- id: 980190977
status: accepted
payment_method: payout_flow
redemptions_remaining: 0
per_consumer_limit_reached: true
daily_redemptions_remaining: null
daily_limit_reached: false
purchase:
id: 980190971
retailer_identifier: my_purchase_identifier
offer:
id: 36642025
warnings: {}
'201: Accepted: Allows one redemption for a daily-limit offer':
value:
redemption_disbursement:
id: 980190977
status: pending
retailer_identifier: daily_limit_one_purchase
payment_method: payout_flow
amount_cents: 100
amount_currency: USD
email: daily_limit@example.bybe.com
redemptions:
- id: 980190987
status: accepted
payment_method: payout_flow
redemptions_remaining: 3
per_consumer_limit_reached: false
daily_redemptions_remaining: 0
daily_limit_reached: true
purchase:
id: 980190977
retailer_identifier: purchase_one
offer:
id: 545172206
warnings: {}
'201: Accepted: Allows one redemption per day for daily-limit offer':
value:
redemption_disbursement:
id: 980190979
status: pending
retailer_identifier: daily_limit_disbursement
payment_method: payout_flow
amount_cents: 200
amount_currency: USD
email: daily_limit@example.bybe.com
redemptions:
- id: 980190990
status: accepted
payment_method: payout_flow
redemptions_remaining: 2
per_consumer_limit_reached: false
daily_redemptions_remaining: 0
daily_limit_reached: true
purchase:
id: 980190980
retailer_identifier: purchase_day1
offer:
id: 545172206
- id: 980190991
status: accepted
payment_method: payout_flow
redemptions_remaining: 2
per_consumer_limit_reached: false
daily_redemptions_remaining: 0
daily_limit_reached: true
purchase:
id: 980190981
retailer_identifier: purchase_day2
offer:
id: 545172206
warnings: {}
'201: Accepted: Defaults daily-limit calculation to current day when purchase date is missing':
value:
redemption_disbursement:
id: 980190981
status: pending
retailer_identifier: daily_limit_one_purchase
payment_method: payout_flow
amount_cents: 100
amount_currency: USD
email: daily_limit@example.bybe.com
redemptions:
- id: 980190993
status: accepted
payment_method: payout_flow
redemptions_remaining: 3
per_consumer_limit_reached: false
daily_redemptions_remaining: 0
daily_limit_reached: true
purchase:
id: 980190983
retailer_identifier: purchase_one
offer:
id: 545172206
warnings: {}
'201: Accepted: Ignores unknown UPCs when configured to do so':
value:
redemption_disbursement:
id: 980190991
status: pending
retailer_identifier: my_consumers_redeption_disbursement_3
payment_method: payout_flow
amount_cents: 500
amount_currency: USD
email: example_consumer@example.bybe.com
redemptions:
- id: 980191007
status: accepted
payment_method: payout_flow
redemptions_remaining: 1
per_consumer_limit_reached: false
daily_redemptions_remaining: null
daily_limit_reached: false
purchase:
id: 980190997
retailer_identifier: my_purchase_identifier
offer:
id: 36642025
warnings:
unknown_upcs:
- Unknown upcs 235252362363262, 34634634122352
'422':
description: unprocessable entity
content:
application/json:
examples:
'422: Error: Returns a 422 for unknown UPCs when ignore_unknown_upcs is not passed or false':
value:
redemption_disbursement:
errors:
unknown_upcs:
- Unknown upcs 929352935829352935
'422: Error: Always returns a 422 for unknown retailer identifiers':
value:
redemption_disbursement:
errors:
unknown_retailer_identifiers:
- Unknown retailer identifiers 929352935829352935
'422: Error: Returns a error for both invalid purchase date format and unknown UPCs':
value:
redemption_disbursement:
errors:
purchase_date:
- 'Purchase date Invalid purchase date format: not-a-date'
unknown_upcs:
- Unknown upcs 76767675457467676
'422: Error: Returns error if purchase_date is incorrectly formatted':
value:
redemption_disbursement:
errors:
purchase_date:
- 'Purchase date Invalid purchase date format: not-a-date'
'422: Error: Returns error if payment method is not valid':
value:
redemption_disbursement:
errors:
payment_method:
- must exist
- can't be blank
- must be present
purchases.store:
- must exist
- can't be blank
requestBody:
content:
application/json:
schema:
type: object
required:
- redemption_disbursement
properties:
redemption_disbursement:
type: object
required:
- retailer_identifier
- consumer
- purchases
properties:
payment_method:
type: string
description: The method by which the consumer wishes to receive their disbursement. The recommended value is 'payout_flow' (this is also the default when not provided), which allows the consumer to accrue a balance and choose their preferred payment method. Supported values may vary by retailer. Please contact your BYBE representative to confirm which values are enabled for your retailer.
retailer_identifier:
type: string
description: Unique retailer ID for the redemption disbursement.
email:
type: string
description: The email address to send the disbursement email to. If the consumer's email was already provided during consumer creation using the Consumers or Clips API, then it is not required to be sent again in this request.
consumer:
type: object
required:
- retailer_identifier
properties:
retailer_identifier:
type: string
purchases:
type: array
description: A list of Purchase objects from which redemptions will be generated for inclusion in this redemption disbursement.
items:
type: object
properties:
retailer_identifier:
description: Unique retailer ID for the purchase. Typically this would be your internal purchase ID or transaction ID.
type: string
purchase_date:
type: string
description: The date of the purchase in ISO 8601 format, preferably in the timezone of the store (e.g., "2023-10-01T08:00:00-04:00"). This is optional and defaults to the current time if not provided.
store:
type: object
description: Store information where the purchase was made. This must match to a store sent to BYBE previously and will be used for validating redemptions.
properties:
retailer_identifier:
type: string
redemptions:
type: array
description: A list of offers to attempt to redeem against this purchase. If wanting to redeem multiple times for the same offer most include multiple entries for the same offer ID.
items:
type: object
properties:
offer_id:
type: integer
line_items:
type: array
items:
type: object
properties:
product:
type: object
description: Product information used for validating redemptions. One of `upc` or `retailer_identifier` is required. `upc` is the preferred identifier. If using `retailer_identifier`, you must provide your custom product codes (e.g., SKUs) to BYBE in advance.
properties:
upc:
type: string
description: Universal Product Code. Preferred identifier for products.
retailer_identifier:
type: string
description: Custom product code (e.g., SKU). Must be pre-registered with BYBE.
quantity:
type: integer
price_cents:
type: integer
examples:
'201: Accepted: Creates a single redemption disbursement successfully':
summary: '201: Accepted: Creates a single redemption disbursement successfully'
value:
redemption_disbursement:
payment_method: payout_flow
retailer_identifier: my_consumers_redeption_disbursement_1
email: example_consumer@example.bybe.com
consumer:
retailer_identifier: ANOTHER_RETAILER_CONSUMER
purchases:
- retailer_identifier: my_purchase_identifier
store:
retailer_identifier: CBUS
redemptions:
- offer_id: 980190962
line_items:
- product:
retailer_identifier: 123ABC
quantity: 1
price_cents: 999
'201: Rejected: Rejects redemption when household limit is reached':
summary: '201: Rejected: Rejects redemption when household limit is reached'
value:
redemption_disbursement:
payment_method: payout_flow
retailer_identifier: 27a54a63-70d8-4f74-8d72-eeaef672fbfe
email: example_consumer@example.bybe.com
consumer:
retailer_identifier: ANOTHER_RETAILER_CONSUMER_TWO
purchases:
- retailer_identifier: BOUGHTTWOOFTWO
store:
retailer_identifier: CHI
redemptions:
- offer_id: 36642025
line_items:
- product:
retailer_identifier: 456DEF
quantity: 1
price_cents: 999
'201: Accepted: Uses default payout_flow when payment method is missing':
summary: '201: Accepted: Uses default payout_flow when payment method is missing'
value:
redemption_disbursement:
payment_method: payout_flow
retailer_identifier: my_consumers_redemption_disbursement_3
email: example_consumer@example.bybe.com
consumer:
retailer_identifier: ANOTHER_RETAILER_CONSUMER
purchases:
- retailer_identifier: my_purchase_identifier
store:
retailer_identifier: 0000Valid
redemptions:
- offer_id: 36642025
- offer_id: 36642025
line_items:
- product:
upc: '767676767676'
quantity: 1
price_cents: 999
- product:
upc: '767676767676'
quantity: 1
price_cents: 999
'201: Accepted: Forces payout_flow when override flag is set':
summary: '201: Accepted: Forces payout_flow when override flag is set'
value:
redemption_disbursement:
payment_method: payout_flow
retailer_identifier: my_consumers_redeption_disbursement_3
email: example_consumer@example.bybe.com
consumer:
retailer_identifier: ANOTHER_RETAILER_CONSUMER
purchases:
- retailer_identifier: my_purchase_identifier
store:
retailer_identifier: 0000Valid
redemptions:
- offer_id: 36642025
- offer_id: 36642025
line_items:
- product:
upc: '767676767676'
quantity: 1
price_cents: 999
- product:
upc: '767676767676'
quantity: 1
price_cents: 999
'201: Accepted: Accepts two redemptions in a single request with separate line items':
summary: '201: Accepted: Accepts two redemptions in a single request with separate line items'
value:
redemption_disbursement:
payment_method: payout_flow
retailer_identifier: my_consumers_redeption_disbursement_3
email: example_consumer@example.bybe.com
consumer:
retailer_identifier: ANOTHER_RETAILER_CONSUMER
purchases:
- retailer_identifier: my_purchase_identifier
store:
retailer_identifier: 0000Valid
redemptions:
- offer_id: 36642025
- offer_id: 36642025
line_items:
- product:
upc: '767676767676'
quantity: 1
price_cents: 999
- product:
upc: '989898989898'
quantity: 3
price_cents: 999
'201: Accepted: Allows one redemption for a daily-limit offer':
summary: '201: Accepted: Allows one redemption for a daily-limit offer'
value:
redemption_disbursement:
payment_method: payout_flow
retailer_identifier: daily_limit_one_purchase
email: daily_limit@example.bybe.com
consumer:
retailer_identifier: ANOTHER_RETAILER_CONSUMER
purchases:
- retailer_identifier: purchase_one
purchase_date: '2023-10-01T12:00:00-04:00'
store:
retailer_identifier: 0000Valid
redemptions:
- offer_id: 545172206
line_items:
- product:
upc: '767676767676'
quantity: 1
'201: Accepted: Allows one redemption per day for daily-limit offer':
summary: '201: Accepted: Allows one redemption per day for daily-limit offer'
value:
redemption_disbursement:
payment_method: payout_flow
retailer_identifier: daily_limit_disbursement
email: daily_limit@example.bybe.com
consumer:
retailer_identifier: ANOTHER_RETAILER_CONSUMER
purchases:
- retailer_identifier: purchase_day1
purchase_date: '2023-10-01T10:00:00-04:00'
store:
retailer_identifier: 0000Valid
redemptions:
- offer_id: 545172206
line_items:
- product:
upc: '767676767676'
quantity: 1
- retailer_identifier: purchase_day2
purchase_date: '2023-10-02T10:00:00-04:00'
store:
retailer_identifier: 0000Valid
redemptions:
- offer_id: 545172206
line_items:
- product:
upc: '767676767676'
quantity: 1
'201: Accepted: Defaults daily-limit calculation to current day when purchase date is missing':
summary: '201: Accepted: Defaults daily-limit calculation to current day when purchase date is missing'
value:
redemption_disbursement:
payment_method: payout_flow
retailer_identifier: daily_limit_one_purchase
email: daily_limit@example.bybe.com
consumer:
retailer_identifier: ANOTHER_RETAILER_CONSUMER
purchases:
- retailer_identifier: purchase_one
store:
retailer_identifier: 0000Valid
redemptions:
- offer_id: 545172206
line_items:
- product:
upc: '767676767676'
quantity: 1
'201: Accepted: Ignores unknown UPCs when configured to do so':
summary: '201: Accepted: Ignores unknown UPCs when configured to do so'
value:
redemption_disbursement:
payment_method: payout_flow
retailer_identifier: my_consumers_redeption_disbursement_3
email: example_consumer@example.bybe.com
consumer:
retailer_identifier: ANOTHER_RETAILER_CONSUMER
purchases:
- re
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bybe/refs/heads/main/openapi/bybe-redemptions-api-openapi.yml