> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperline.co/llms.txt
> Use this file to discover all available pages before exploring further.

# List promotion codes

> Retrieve existing promotion codes.



## OpenAPI

````yaml get /v1/promotion-codes
openapi: 3.1.0
info:
  title: Hyperline API
  version: 0.0.0
servers:
  - url: https://api.hyperline.co
  - url: https://sandbox.api.hyperline.co
security: []
paths:
  /v1/promotion-codes:
    get:
      tags:
        - Coupons > Promotion codes
      summary: List promotion codes
      description: Retrieve existing promotion codes.
      operationId: listPromotionCodes
      parameters:
        - schema:
            type:
              - number
              - 'null'
            minimum: 0
            maximum: 100
            default: 50
          required: false
          name: take
          in: query
        - schema:
            type:
              - number
              - 'null'
            minimum: 0
            default: 0
          required: false
          name: skip
          in: query
        - schema:
            type: string
          required: false
          name: coupon_id
          in: query
        - schema:
            type: string
          required: false
          name: coupon_id__not
          in: query
        - schema:
            type: string
          required: false
          name: coupon_id__isNull
          in: query
        - schema:
            type: string
          required: false
          name: coupon_id__isNotNull
          in: query
        - schema:
            type: string
          required: false
          name: coupon_id__equals
          in: query
        - schema:
            type: string
          required: false
          name: coupon_id__contains
          in: query
        - schema:
            type: string
          required: false
          name: coupon_id__startsWith
          in: query
        - schema:
            type: string
          required: false
          name: coupon_id__endWith
          in: query
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedPromotionCode'
      security:
        - bearer: []
components:
  schemas:
    PaginatedPromotionCode:
      type: object
      properties:
        meta:
          type: object
          properties:
            total:
              type: number
              description: Total of existing items.
              example: 1
            taken:
              type: number
              description: Number of items returned.
              example: 1
            skipped:
              type: number
              description: Number of items skipped.
              example: 0
          required:
            - total
            - taken
            - skipped
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Promotion code ID.
                example: promo_DKL4Xcb5VSa8CQ
              code:
                type: string
                description: Promotion code.
                example: PROMO123
              coupon_id:
                type: string
                description: Coupon ID.
                example: cou_DKL4Xcb5VSa8CQ
              client_id:
                type: string
                description: Client ID.
                example: cli_DKL4Xcb5VSa8CQ
              customer_id:
                type:
                  - string
                  - 'null'
                description: >-
                  If a `customer_id` is set, this promotion code will only be
                  available to this customer.
                example: cus_DKL4Xcb5VSa8CQ
              plan_id:
                type:
                  - string
                  - 'null'
                description: >-
                  If a `plan_id` is set, this promotion code will only be
                  available for subscriptions with this plan ID.
                example: plan_DKL4Xcb5VSa8CQ
              product_id:
                type:
                  - string
                  - 'null'
                description: >-
                  If a `product_id` is set, this promotion code will only be
                  available for subscriptions with this product ID.
                example: itm_DKL4Xcb5VSa8CQ
              created_at:
                type: string
                format: date-time
                description: >-
                  Promotion code creation date. UTC date time string in the [ISO
                  8601](https://en.wikipedia.org/wiki/ISO_8601) format.
                example: '2021-01-01T00:00:00.000Z'
              updated_at:
                type: string
                format: date-time
                description: >-
                  Promotion code last edition date. UTC date time string in the
                  [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
                example: '2021-01-01T00:00:00.000Z'
              expires_at:
                type:
                  - string
                  - 'null'
                format: date-time
                description: Date and time when the promotion code expires.
                example: '2021-01-01T00:00:00.000Z'
              max_redemptions:
                type:
                  - number
                  - 'null'
                description: >-
                  Maximum number of redemptions for the promotion code.
                  Independent from coupon's max redemptions.
                example: 10
              current_redemptions:
                type:
                  - number
                  - 'null'
                description: Current number of redemptions for the promotion code.
                example: 0
              duration_count:
                type:
                  - number
                  - 'null'
                description: >-
                  Duration count applied to the subscription for the promotion
                  code. 0 or null for `once`
                example: 1
              duration_period:
                type:
                  - string
                  - 'null'
                enum:
                  - once
                  - days
                  - weeks
                  - months
                  - years
                description: >-
                  Duration period applied to the subscription for the promotion
                  code for the promotion code. Valid values are `once`, `days`,
                  `weeks`, `months`, `years`
                example: months
              only_for_first_time_order:
                type:
                  - boolean
                  - 'null'
                description: >-
                  Whether the promotion code is only for first time orders.
                  Defaults to `false`
                example: false
            required:
              - id
              - code
              - coupon_id
              - client_id
              - customer_id
              - plan_id
              - product_id
              - created_at
              - updated_at
              - expires_at
              - max_redemptions
              - current_redemptions
              - duration_count
              - duration_period
              - only_for_first_time_order
          description: List of PromotionCode.
      required:
        - meta
        - data
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````