> ## Documentation Index > Fetch the complete documentation index at: https://docs.paylead.fr/llms.txt > Use this file to discover all available pages before exploring further. # List offers visible to this consumer in the program's catalog. ## OpenAPI ````yaml /program/api/openapi/2.0.0/perks/openapi.json get /perks/consumers/{consumer_id}/offers openapi: 3.1.0 info: description: | Paylead Program API. You can find complete documentation in https://docs.paylead.com/ license: name: Proprietary url: https://docs.paylead.com/ title: Perks version: 2.0.0 servers: - description: Sandbox url: https://api-{programRef}.sandbox.paylead.tech variables: programRef: default: changeme description: Program reference provided by Paylead security: - oauth2: [] tags: - description: Routes used to query consumers resources name: Consumers x-displayName: Consumers - name: UPM x-displayName: UPM - name: Brands x-displayName: Brands - name: KYC x-displayName: KYC - name: Offers x-displayName: Offers - name: Rewards x-displayName: Rewards - name: Segments x-displayName: Segments - name: Voucher Orders x-displayName: Voucher Orders paths: /perks/consumers/{consumer_id}/offers: get: tags: - Offers summary: List offers visible to this consumer in the program's catalog. operationId: perks__consumers__consumer_id__offers__get parameters: - in: path name: consumer_id required: true schema: example: consumer-12345 examples: - consumer-12345 maxLength: 100 minLength: 2 pattern: ^[a-zA-Z0-9_-]+$ title: Consumer Id type: string - in: query name: page required: false schema: default: 1 minimum: 1 title: Page type: integer - in: query name: per_page required: false schema: default: 50 maximum: 1000 minimum: 1 title: Per Page type: integer - description: >- Sort field, prefixed by `-` for descending (e.g. `-rate`). `rate` orders on whichever rate the offer advertises — `perks.cashback.cashback_rate`, `perks.voucher.discount_rate` or `perks.coupon.discount_rate` — all compared as percentages, so offer types rank against each other. An offer advertising no rate at all, such as a coupon carrying a fixed discount value, sorts last either way. Omit to keep the catalog's default order. in: query name: sort required: false schema: anyOf: - enum: - rate - '-rate' - start_date - '-start_date' example: rate type: string - type: 'null' description: >- Sort field, prefixed by `-` for descending (e.g. `-rate`). `rate` orders on whichever rate the offer advertises — `perks.cashback.cashback_rate`, `perks.voucher.discount_rate` or `perks.coupon.discount_rate` — all compared as percentages, so offer types rank against each other. An offer advertising no rate at all, such as a coupon carrying a fixed discount value, sorts last either way. Omit to keep the catalog's default order. example: '-rate' examples: - '-rate' title: Sort - description: Filter offers by brand. in: query name: brand_id required: false schema: anyOf: - format: uuid type: string - type: 'null' description: Filter offers by brand. example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 title: Brand Id - description: Filter offers by brand name (case-insensitive partial match). in: query name: brand__name required: false schema: anyOf: - type: string - type: 'null' description: Filter offers by brand name (case-insensitive partial match). example: nike examples: - nike title: Brand Name - description: >- Filter offers by the universe name of their brand (case-insensitive partial match). A brand sitting in several matching universes is still returned once. in: query name: universe__name required: false schema: anyOf: - type: string - type: 'null' description: >- Filter offers by the universe name of their brand (case-insensitive partial match). A brand sitting in several matching universes is still returned once. example: fashion examples: - fashion title: Universe Name - description: Filter by offer type. in: query name: type required: false schema: anyOf: - $ref: '#/components/schemas/Perks_OfferType' - type: 'null' description: Filter by offer type. example: CASHBACK examples: - CASHBACK title: Type - description: >- Filter by display prominence. One of HIGHEST, HIGH or NORMAL — any other value matches no offer and returns an empty listing. Offers with no prominence set count as NORMAL. in: query name: highlight_level required: false schema: anyOf: - type: string - type: 'null' description: >- Filter by display prominence. One of HIGHEST, HIGH or NORMAL — any other value matches no offer and returns an empty listing. Offers with no prominence set count as NORMAL. example: HIGHEST examples: - HIGHEST title: Highlight Level - description: >- Filter on offers whose cashback rate is currently above their default rate — the same signal reported as `perks.cashback.boosted`. Offers that carry no cashback (vouchers, coupons) are never boosted, so they are returned by `false` and excluded by `true`. in: query name: is_boosted required: false schema: anyOf: - type: boolean - type: 'null' description: >- Filter on offers whose cashback rate is currently above their default rate — the same signal reported as `perks.cashback.boosted`. Offers that carry no cashback (vouchers, coupons) are never boosted, so they are returned by `false` and excluded by `true`. example: true examples: - true title: Is Boosted - description: >- Filter on `is_consumed`. Whether this consumer already used the offer — a claimed coupon, or a cashback earned up to the offer's cap. in: query name: is_consumed required: false schema: anyOf: - type: boolean - type: 'null' description: >- Filter on `is_consumed`. Whether this consumer already used the offer — a claimed coupon, or a cashback earned up to the offer's cap. example: false examples: - false title: Is Consumed - examples: default: value: 2.0.0 in: header name: x-api-version required: true schema: default: 2.0.0 title: X-Api-Version type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/Perks_Page_OfferSchema_' description: Successful Response '400': content: application/json: example: code: PL-400-00 errors: - loc: - body - field msg: Field required type: missing instance: /path/of/the/request status: 400 title: Bad Request schema: $ref: '#/components/schemas/ErrorResponse' description: Bad Request '401': content: application/json: examples: PL-401-00: summary: Unauthorized value: code: PL-401-00 status: 401 title: Unauthorized schema: $ref: '#/components/schemas/ErrorResponse' description: Unauthorized '404': content: application/json: examples: PL-404-02: summary: Consumer Not Enrolled value: code: PL-404-02 status: 404 title: Consumer Not Enrolled schema: $ref: '#/components/schemas/ErrorResponse' description: Not Found components: schemas: Perks_OfferType: enum: - CASHBACK - LBS_CASHBACK - VOUCHER example: CASHBACK title: OfferType type: string Perks_Page_OfferSchema_: properties: items: items: $ref: '#/components/schemas/Perks_OfferSchema' title: Items type: array meta: $ref: '#/components/schemas/Perks_PageMeta' required: - items - meta title: Page[OfferSchema] type: object ErrorResponse: additionalProperties: false description: >- An error response object (PayLead profile). Extension members (e.g. ``errors`` for validation) are allowed and serialised as top-level keys. properties: code: description: Error code describing the issue example: PL-4XX-YY title: Code type: string errors: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' default: null description: A list of individual error occurrences found example: - loc: - body - field msg: Field required type: missing title: Errors instance: anyOf: - type: string - type: 'null' default: null description: A URI reference to the problematic resource example: api/resource/424242 title: Instance status: description: HTTP code returned by the API example: 400 title: Status type: integer title: description: Description of the issue example: The request was invalid. title: Title type: string required: - code - title - status title: ErrorResponse type: object Perks_OfferSchema: properties: application_channel: $ref: '#/components/schemas/Perks_ApplicationChannel' description: >- Where the offer applies: in store (OFFLINE), online (ONLINE), or both. example: ONLINE examples: - ONLINE brand: $ref: '#/components/schemas/Perks_OfferBrandSchema' end_date: anyOf: - format: date-time type: string - type: 'null' description: >- When the offer stops being available, null when open-ended. For a cashback offer running through successive phases, the current phase's end date bounds this window. example: '2026-09-30T23:59:59Z' examples: - '2026-09-30T23:59:59Z' title: End Date highlight_level: $ref: '#/components/schemas/Perks_ProgramOfferHighlights' description: >- How prominently the program manager wants the offer displayed, for contextual surfaces such as a banner or a carousel. Offers with no prominence set are reported as NORMAL. example: NORMAL examples: - NORMAL id: example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 format: uuid title: Id type: string is_consumed: description: >- Whether this consumer already used the offer — a claimed coupon, or a cashback earned up to the offer's cap. example: false examples: - false title: Is Consumed type: boolean perks: $ref: '#/components/schemas/Perks_OfferPerksSchema' picture: anyOf: - $ref: '#/components/schemas/Perks_LogoSchema' - type: 'null' description: >- The offer's own illustration, distinct from `brand.logo`. Null when the offer carries no picture. start_date: description: >- When the offer became available to this consumer: the offer's start date, or the date the consumer was reached when that happened later. example: '2026-07-01T00:00:00Z' examples: - '2026-07-01T00:00:00Z' format: date-time title: Start Date type: string required: - id - brand - perks - application_channel - is_consumed - highlight_level - start_date title: OfferSchema type: object Perks_PageMeta: properties: page: example: 1 examples: - 1 title: Page type: integer per_page: example: 50 examples: - 50 title: Per Page type: integer total: example: 137 examples: - 137 title: Total type: integer required: - page - per_page - total title: PageMeta type: object Perks_ApplicationChannel: description: >- How an offer applies: in store, online, or both. Stored in the `application_channel_type` PG enum. enum: - BOTH - ONLINE - OFFLINE example: BOTH title: ApplicationChannel type: string Perks_OfferBrandSchema: properties: id: example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 format: uuid title: Id type: string logo: $ref: '#/components/schemas/Perks_LogoSchema' name: example: Nike examples: - Nike title: Name type: string required: - id - name - logo title: OfferBrandSchema type: object Perks_ProgramOfferHighlights: description: >- How prominently an offer is displayed. Stored in the `program_offer_highlights` PG enum. enum: - HIGHEST - HIGH - NORMAL example: HIGHEST title: ProgramOfferHighlights type: string Perks_OfferPerksSchema: properties: cashback: anyOf: - $ref: '#/components/schemas/Perks_OfferCashbackSchema' - type: 'null' coupon: anyOf: - $ref: '#/components/schemas/Perks_OfferCouponSchema' - type: 'null' voucher: anyOf: - $ref: '#/components/schemas/Perks_OfferVoucherSchema' - type: 'null' title: OfferPerksSchema type: object Perks_LogoSchema: properties: url: anyOf: - format: uri maxLength: 2083 minLength: 1 type: string - type: 'null' description: >- Absolute CDN URL of the image; null when there is none or no CDN is configured. example: https://static.sandbox.paylead.fr/123455.jpeg examples: - https://static.sandbox.paylead.fr/123455.jpeg title: Url title: LogoSchema type: object Perks_OfferCashbackSchema: properties: boosted: default: false description: >- Whether the cashback rate is currently above the offer's default rate. example: false examples: - false title: Boosted type: boolean cashback_rate: description: Cashback rate as a percentage (e.g. 5.00 for 5%). example: '5.00' examples: - '5.00' pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Cashback Rate type: string frequency: description: Whether the offer rewards repeat purchases (loyalty cashback). example: false examples: - false title: Frequency type: boolean max_amount: anyOf: - pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ type: string - type: 'null' description: >- Caps the share of a transaction that earns cashback: above it the cashback stops growing, but the transaction stays eligible. Null when unbounded. example: '200.00' examples: - '200.00' title: Max Amount max_cashbacks_per_consumer: anyOf: - type: integer - type: 'null' description: >- How many cashbacks this consumer may earn on the offer. Null when unbounded example: 3 examples: - 3 title: Max Cashbacks Per Consumer max_eligible_amount: anyOf: - pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ type: string - type: 'null' description: >- Transactions above this amount earn no cashback at all. Null when unbounded. example: '500.00' examples: - '500.00' title: Max Eligible Amount min_amount: anyOf: - pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ type: string - type: 'null' description: >- Transactions below this amount earn no cashback. Null when unbounded — including when the offer stores a zero minimum, which excludes no transaction. example: '10.00' examples: - '10.00' title: Min Amount required: - cashback_rate - frequency title: OfferCashbackSchema type: object Perks_OfferCouponSchema: properties: diffusion_type: anyOf: - $ref: '#/components/schemas/Perks_CouponDiffusionType' - type: 'null' description: >- How the coupon code is rendered to the consumer: a QR code (QR), a barcode (EAN) or a plain alphanumeric code (CODE). example: CODE examples: - CODE discount_rate: anyOf: - pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ type: string - type: 'null' description: Coupon discount as a percentage. example: '15.00' examples: - '15.00' title: Discount Rate discount_value: anyOf: - pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ type: string - type: 'null' description: Coupon discount as a fixed amount, in the offer currency. example: '5.00' examples: - '5.00' title: Discount Value max_per_consumer: anyOf: - type: integer - type: 'null' description: >- How many coupons this consumer may claim on the offer. Null for a generic coupon, whose single code is shared by every consumer. example: 1 examples: - 1 title: Max Per Consumer title: OfferCouponSchema type: object Perks_OfferVoucherSchema: properties: amount_step: anyOf: - pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ type: string - type: 'null' description: Increment purchasable amounts must follow inside the min/max range. example: '5.00' examples: - '5.00' title: Amount Step amounts: description: >- Fixed purchasable amounts. Empty when the offer sells any amount in the min/max range. example: - '10.00' - '25.00' - '50.00' examples: - - '10.00' - '25.00' - '50.00' items: pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ type: string title: Amounts type: array discount_rate: description: Consumer-facing voucher discount as a percentage. example: '7.50' examples: - '7.50' pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Discount Rate type: string max_amount: anyOf: - pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ type: string - type: 'null' description: Highest purchasable voucher amount. example: '250.00' examples: - '250.00' title: Max Amount min_amount: anyOf: - pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ type: string - type: 'null' description: Lowest purchasable voucher amount. example: '10.00' examples: - '10.00' title: Min Amount validity_months: anyOf: - type: integer - type: 'null' description: How many months a purchased voucher stays valid. example: 12 examples: - 12 title: Validity Months required: - discount_rate title: OfferVoucherSchema type: object Perks_CouponDiffusionType: description: >- How a coupon code is handed to the consumer. Stored in the `program_offer_diffusion_type` PG enum. enum: - QR - EAN - CODE example: QR title: CouponDiffusionType type: string securitySchemes: oauth2: flows: clientCredentials: scopes: ALL: Full access to all resources (wildcard). LOYALTIES: Access to loyalties features. PERKS: Access to perks features. TX_INJECTION: Access to transaction sharing. tokenUrl: /tokens type: oauth2 ````