openapi: "3.0.3"
info:
  title: "CharityChoice Partner REST API"
  description: |
    The CharityChoice Partner REST API allows authorized clients to integrate charity search, donation processing, 
    and retailer gift card redemption functionality.
    
    **Note:** Access is restricted to authorized partners. To acquire permissions, please contact admin@charity-choice.org.
  version: "1.4.3"
  contact:
    name: "CharityChoice API Support"
    email: "admin@charity-choice.org"
    url: "https://www.charitygiftcertificates.org/"

servers:
  - url: "https://www.charitygiftcertificates.org/api"
    description: "Production Server"
  - url: "https://www.charitygiftcertificates.org/api"
    description: "Development Sandbox"

components:
  securitySchemes:
    basicAuth:
      type: "http"
      scheme: "basic"
      description: "Use your UserId:ClientId as the username and your CharityChoice password as the password."

  parameters:
    CgcMode:
      name: cgc-mode
      in: header
      required: true
      description: Use 'prod' for live transactions or 'dev' for the sandbox environment.
      schema:
        type: string
        enum: [prod, dev]
    CgcAppId:
      name: cgc-app-id
      in: header
      required: true
      description: The application identifier (e.g., CGC_REST_API_VERSION_0142).
      schema:
        type: string

  schemas:
    ApiResponse:
      type: object
      properties:
        Succeeded:
          type: boolean
        ErrorMessage:
          type: string
          nullable: true

    Order:
      type: object
      properties:
        OrderId:
          type: integer
        PurchaseDate:
          type: string
          format: date-time
        Type:
          type: string
        Denomination:
          type: number
          format: float
        Quantity:
          type: integer
        TotalForCards:
          type: number
          format: float

    Charity:
      type: object
      properties:
        CharityId:
          type: integer
        CategoryId:
          type: integer
        CategoryName:
          type: string
        CharityName:
          type: string
        ShortDescription:
          type: string
        LogoURL:
          type: string
        URL:
          type: string
        City:
          type: string
        State:
          type: string
        Country:
          type: string
        IsLocal:
          type: boolean
        Rank:
          type: integer

    CharityInfoResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            CharityInfo:
              $ref: '#/components/schemas/Charity'

    Category:
      type: object
      properties:
        CategoryId:
          type: integer
        CategoryName:
          type: string

    DonorInformation:
      type: object
      required:
        - DonorFirstName
        - DonorLastName
        - DonorEmail
        - DonorPhone
        - DonorMailingAddress
      properties:
        DonorFirstName:
          type: string
        DonorLastName:
          type: string
        DonorEmail:
          type: string
        DonorPhone:
          type: string
        DonorMailingAddress:
          type: string

    DonationRequest:
      type: object
      required:
        - Amount
        - CharityIds
      properties:
        Amount:
          type: number
          format: float
        CharityIds:
          type: array
          items:
            type: integer
        DonorInformation:
          $ref: '#/components/schemas/DonorInformation'

    DonationResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            OrderId:
              type: integer
            Amount:
              type: number
              format: float
            CharityIds:
              type: array
              items:
                type: integer

    OrderStatusResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            Codes:
              type: array
              items:
                type: object
                properties:
                  Code:
                    type: string
                  WasRedeemed:
                    type: boolean
                  RedeemDate:
                    type: string
                    format: date-time
                    nullable: true

    Retailer:
      type: object
      properties:
        RetailerId:
          type: integer
        Name:
          type: string
        AcceptsEcode:
          type: boolean
        IsCreditCard:
          type: boolean
        ECodePercent:
          type: number
          format: float
        PhysicalPercent:
          type: number
          format: float
        Minimum:
          type: number
          format: float
        Maximum:
          type: number
          format: float
        ValidationRules:
          type: array
          items:
            type: object
            properties:
              CardNumberLength:
                type: integer
              PinLength:
                type: integer

    RetailerInfoResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            RetailerInfo:
              $ref: '#/components/schemas/Retailer'

    DYCDonateRequest:
      type: object
      required:
        - RetailerId
        - CardNumber
        - Balance
        - CharityIds
        - ContactInfo
      properties:
        RetailerId:
          type: integer
        CardNumber:
          type: string
        PIN:
          type: string
          nullable: true
        CVV:
          type: string
          nullable: true
        ExpireDate:
          type: string
          nullable: true
        Balance:
          type: number
          format: float
        CharityIds:
          type: array
          items:
            type: integer
        ContactInfo:
          type: object
          required:
            - FirstName
            - LastName
            - Email
            - CompanyName
            - Phone
            - Address
            - AddressLine2
            - City
            - State
            - Zip
            - Country
            - ShareWithCharities
          properties:
            FirstName:
              type: string
            LastName:
              type: string
            Email:
              type: string
            CompanyName:
              type: string
              nullable: true
            Phone:
              type: string
              nullable: true
            Address:
              type: string
              nullable: true
            AddressLine2:
              type: string
              nullable: true
            City:
              type: string
              nullable: true
            State:
              type: string
              nullable: true
            Zip:
              type: string
              nullable: true
            Country:
              type: string
              nullable: true
            ShareWithCharities:
              type: boolean
              nullable: true

    DYCDonateResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            OrderId:
              type: integer
            DonorId:
              type: integer
            CardId:
              type: integer
            GetStatusUrl:
              type: string

    DYCStatusResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            CardId:
              type: integer
            DateDonated:
              type: string
              format: date-time
            RetailerId:
              type: integer
            CardNumber:
              type: string
            PIN:
              type: string
            CVV:
              type: string
              nullable: true
            ExpireDate:
              type: string
              nullable: true
            Balance:
              type: number
              format: float
            IsVerified:
              type: boolean
            CharityIds:
              type: array
              items:
                type: integer

    RedeemURLItem:
      type: object
      properties:
        RedeemCode:
          type: string
        RedeemURL:
          type: string
        QRCodeImageURL:
          type: string

    CharitySpecificCodeItem:
      type: object
      properties:
        CharityId:
          type: integer
        Codes:
          type: array
          items:
            type: string
        RedeemURLs:
          type: array
          items:
            $ref: '#/components/schemas/RedeemURLItem'
        DonationQCCode:
          type: string
        DonationQCCodeRedeemUrl:
          $ref: '#/components/schemas/RedeemURLItem'

    ActivateCodesRequest:
      type: object
      required:
        - Denomination
        - NumberOfCodes
      properties:
        Denomination:
          type: number
          format: float
        NumberOfCodes:
          type: integer
        HideDenomination:
          type: boolean
        CharityIds:
          type: array
          items:
            type: integer

    ActivateCodesResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            OrderId:
              type: integer
            Codes:
              type: array
              items:
                type: string
            RedeemURLs:
              type: array
              items:
                $ref: '#/components/schemas/RedeemURLItem'
            DonationQCCode:
              type: string
            DonationQCCodeRedeemUrl:
              $ref: '#/components/schemas/RedeemURLItem'
            CharitySpecificCodes:
              type: array
              items:
                $ref: '#/components/schemas/CharitySpecificCodeItem'

    ActivateSuppliedCodesRequest:
      type: object
      required:
        - Denomination
        - Codes
      properties:
        Denomination:
          type: number
          format: float
        Codes:
          type: array
          items:
            type: string
            pattern: "^[a-zA-Z]{4,}[0-9]{4,}$"

    ActivateSuppliedCodesResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            OrderId:
              type: integer

    DigitalCard:
      type: object
      properties:
        CardId:
          type: integer
        CardName:
          type: string
        ImageUrl:
          type: string
        OccasionId:
          type: integer
        OccasionName:
          type: string
        HasCustomSection:
          type: boolean
        CustomSectionDefaultHtml:
          type: string
          nullable: true
        AltTag:
          type: string
          nullable: true
        PresetDenomination:
          type: number
          format: float

    ColorScheme:
      type: object
      properties:
        SchemeName:
          type: string
        SchemeText:
          type: string
        BackgroundColor:
          type: string

    SendDigitalCardsRequest:
      type: object
      required:
        - Denomination
        - Greeting
        - Message
        - Recipients
      properties:
        Denomination:
          type: number
          format: float
        Greeting:
          type: string
        Message:
          type: string
        CardId:
          type: integer
          nullable: true
        CardColor:
          type: string
          nullable: true
        CustomImageURL:
          type: string
          nullable: true
        SendDate:
          type: string
          format: date-time
          nullable: true
        DonorName:
          type: string
          nullable: true
        DonorEmail:
          type: string
          nullable: true
        Recipients:
          type: array
          items:
            type: object
            properties:
              FirstName:
                type: string
                nullable: true
              LastName:
                type: string
                nullable: true
              Email:
                type: string
                nullable: true
              Cel:
                type: string
                nullable: true

    SendDigitalCardsResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            OrderId:
              type: integer
            Cards:
              type: array
              items:
                type: object
                properties:
                  FirstName:
                    type: string
                  LastName:
                    type: string
                  Email:
                    type: string
                  Cel:
                    type: string
                    nullable: true
                  RedemptionCode:
                    type: string
                  RedeemURL:
                    type: string
                  IsValid:
                    type: boolean
                  Notes:
                    type: string
                    nullable: true
            InvalidCards:
              type: array
              items:
                type: object

    PhysicalCardOrderRequest:
      type: object
      required:
        - Cards
        - ShippingInfo
      properties:
        Cards:
          type: array
          items:
            type: object
            required:
              - Denomination
              - PhysicalCardTypeId
              - NumberOfCards
            properties:
              Denomination:
                type: integer
              PhysicalCardTypeId:
                type: integer
              NumberOfCards:
                type: integer
        ShippingInfo:
          type: object
          required:
            - ShippingTypeId
            - FirstName
            - LastName
            - AddressLine1
            - City
            - State
            - Zip
          properties:
            ShippingTypeId:
              type: integer
            FirstName:
              type: string
            LastName:
              type: string
            Attention:
              type: string
              nullable: true
            AddressLine1:
              type: string
            AddressLine2:
              type: string
              nullable: true
            City:
              type: string
            State:
              type: string
            Zip:
              type: string
            Email:
              type: string
              nullable: true
            Phone:
              type: string
              nullable: true
            Greeting:
              type: string
              nullable: true
            Message:
              type: string
              nullable: true
        ShipsToRecipient:
          type: boolean

    PhysicalCardOrderResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            OrderId:
              type: integer
            TotalForCards:
              type: number
              format: float
            TotalForShipping:
              type: number
              format: float
            TotalCost:
              type: number
              format: float
            Cards:
              type: array
              items:
                type: object
                properties:
                  RedemptionCode:
                    type: string
                  Denomination:
                    type: integer
                  PhysicalCardTypeId:
                    type: integer
                  RedeemURL:
                    type: string
            ShippingInfo:
              type: object
            ShipsToRecipient:
              type: boolean

    PhysicalCardType:
      type: object
      properties:
        PhysicalCardTypeId:
          type: integer
        CardTypeName:
          type: string
        Description:
          type: string
        ImageUrl:
          type: string
        Denominations:
          type: array
          items:
            type: object
            properties:
              Denomination:
                type: number
                format: float
              Stock:
                type: integer

    PhysicalCardTypesResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            List:
              type: array
              items:
                $ref: '#/components/schemas/PhysicalCardType'

    ShippingType:
      type: object
      properties:
        ShippingTypeId:
          type: integer
        ShippingCompanyName:
          type: string
        FullDisplayText:
          type: string
        IsExpeditedShipping:
          type: boolean
        BaseShippingCost:
          type: number
          format: float
        ExpeditedShippingCost:
          type: number
          format: float

    ShippingTypesResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            List:
              type: array
              items:
                $ref: '#/components/schemas/ShippingType'

    RedeemCodeRequest:
      type: object
      required:
        - RedeemCode
        - RedeemerFirstName
        - RedeemerLastName
        - RedeemerEmail
        - Charities
      properties:
        RedeemCode:
          type: string
        RedeemerFirstName:
          type: string
        RedeemerLastName:
          type: string
        RedeemerEmail:
          type: string
        Charities:
          type: array
          items:
            type: object
            properties:
              CharityId:
                type: integer
              CharityProject:
                type: string
                nullable: true
              Amount:
                type: number
                format: float

    OrderType:
      type: object
      properties:
        OrderTypeId:
          type: integer
        OrderTypeName:
          type: string

    CodeStatusResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            Codes:
              type: array
              items:
                type: object
                properties:
                  Code:
                    type: string
                  Denomination:
                    type: number
                    format: float
                  WasRedeemed:
                    type: boolean
                  AmountLeftToRedeem:
                    type: number
                    format: float
                  RedeemDate:
                    type: string
                    format: date-time
                    nullable: true
                  CharityIds:
                    type: array
                    items:
                      type: integer

    GenerateCodesResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            Codes:
              type: array
              items:
                type: string

    ReportCodeItem:
      type: object
      properties:
        CodeId:
          type: integer
        ItemId:
          type: integer
        RedemptionCode:
          type: string
        WasRedeemed:
          type: boolean
        RedeemDate:
          type: string
          format: date-time
          nullable: true
        RedeemerFirstName:
          type: string
          nullable: true
        RedeemerLastName:
          type: string
          nullable: true
        RedeemerEmail:
          type: string
          nullable: true
        Charities:
          type: array
          items:
            type: integer

    ReportOrderItem:
      type: object
      properties:
        OrderId:
          type: integer
        ItemId:
          type: integer
        Type:
          type: string
        Denomination:
          type: number
          format: float
        Codes:
          type: array
          items:
            $ref: '#/components/schemas/ReportCodeItem'

    ReportOrder:
      type: object
      properties:
        OrderId:
          type: integer
        OrderDate:
          type: string
          format: date-time
        TotalForCards:
          type: number
          format: float
        TotalForShipping:
          type: number
          format: float
        TotalExtraForCustomPhysicalCards:
          type: number
          format: float
        TotalWithoutDiscounts:
          type: number
          format: float
        TotalWithoutDiscountsAtCheckout:
          type: number
          format: float
        DiscountPercentAtCheckout:
          type: number
          format: float
        FinalPriceAtCheckout:
          type: number
          format: float
        OrderItems:
          type: array
          items:
            $ref: '#/components/schemas/ReportOrderItem'

    OrdersReport:
      type: object
      properties:
        Orders:
          type: array
          items:
            $ref: '#/components/schemas/ReportOrder'

    OrdersReportResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            Report:
              $ref: '#/components/schemas/OrdersReport'

security:
  - basicAuth: []

paths:
  /account/orders:
    get:
      summary: Get Orders
      description: Gets a list of orders in your account.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
      responses:
        '200':
          description: A list of orders.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
        '400':
          description: The order list cannot be retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /account/orders/{orderTypeId}:
    get:
      summary: Get Orders Filtered by Type
      description: Gets a list of orders in your account filtered by order type ID.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
        - name: orderTypeId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: A list of orders.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
        '400':
          description: The order list cannot be retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /donate/ordertypes:
    get:
      summary: Get Order Types
      description: Gets a list of the CharityChoice Order Types.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
      responses:
        '200':
          description: A list of order types.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderType'

  /account/orders/report/{month}/{year}:
    get:
      summary: Get Orders Report (Monthly)
      description: Gets a report of orders for a specific month and year.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
        - name: month
          in: path
          required: true
          schema:
            type: integer
        - name: year
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: A report of orders.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrdersReportResponse'
        '400':
          description: Invalid month or parameters supplied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /account/orders/report/{fromDate}/{toDate}:
    get:
      summary: Get Orders Report (Date Range)
      description: Gets a report of orders within a specified date range.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
        - name: fromDate
          in: path
          required: true
          description: The beginning date (e.g. MM-DD-YYYY or DD-MMM-YYYY).
          schema:
            type: string
        - name: toDate
          in: path
          required: true
          description: The ending date (e.g. MM-DD-YYYY or DD-MMM-YYYY).
          schema:
            type: string
      responses:
        '200':
          description: A report of orders.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrdersReportResponse'
        '400':
          description: Dates are not formatted correctly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /charity/{charityId}:
    get:
      summary: Charity Information
      description: Gets detailed information for a single charity.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
        - name: charityId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Charity information retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CharityInfoResponse'
        '400':
          description: Not a valid CharityChoice Charity Id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /charity/list:
    get:
      summary: Get Charity List
      description: Gets the full list of public charities.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
      responses:
        '200':
          description: A list of charities.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Charity'

  /charity/list/{listName}:
    get:
      summary: Get Charity List Filtered by Scope
      description: Gets a list of charities filtered by scope (main, local, or all).
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
        - name: listName
          in: path
          required: true
          schema:
            type: string
            enum: [main, local, all]
      responses:
        '200':
          description: A list of charities.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Charity'

  /charity/list/{listName}/{categoryId}:
    get:
      summary: Get Charity List Filtered by Scope and Category
      description: Gets a list of charities filtered by scope and category ID.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
        - name: listName
          in: path
          required: true
          schema:
            type: string
            enum: [main, local, all]
        - name: categoryId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: A list of charities.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Charity'

  /charity/list/search/{searchText}:
    get:
      summary: Search for a Charity
      description: Searches for Charities by the given search text.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
        - name: searchText
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A list of matching charities.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Charity'

  /charity/list/search/{searchText}/{includeDescription}:
    get:
      summary: Search for a Charity (Optionally within descriptions)
      description: Searches for Charities by name, and optionally within short descriptions.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
        - name: searchText
          in: path
          required: true
          schema:
            type: string
        - name: includeDescription
          in: path
          required: true
          schema:
            type: boolean
      responses:
        '200':
          description: A list of matching charities.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Charity'

  /charity/cats/list:
    get:
      summary: Get Category List
      description: Gets a list of the CharityChoice Charity Categories.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
      responses:
        '200':
          description: A list of charity categories.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Category'

  /donate:
    post:
      summary: Charity Donation
      description: Donate to one or more charities.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DonationRequest'
      responses:
        '201':
          description: Donation completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DonationResponse'
        '400':
          description: Donation failed (invalid format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /donate/{orderId}:
    get:
      summary: Order Status
      description: Returns a list of codes in this order with their redemption status.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Request completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderStatusResponse'
        '400':
          description: Invalid order id supplied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '401':
          description: Unauthorized to view this order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
    delete:
      summary: Void Order
      description: Void a previously made order. USE WITH CAUTION!
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Order has been voided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          description: Request not formatted correctly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '403':
          description: Not allowed to void this order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '417':
          description: Order cannot be voided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /dyc/retailer/list:
    get:
      summary: Gift Card Retailers List
      description: Gets a list of Card Retailers.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
      responses:
        '200':
          description: A list of retailers.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Retailer'

  /dyc/retailer/{retailerId}:
    get:
      summary: Gift Card Retailer Information
      description: Gets the information for a single gift card retailer.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
        - name: retailerId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Retailer information retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetailerInfoResponse'
        '400':
          description: Invalid retailer id supplied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /dyc/donate:
    post:
      summary: Donate Retailer Gift Card
      description: Donate a retailer gift card to charity.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DYCDonateRequest'
      responses:
        '201':
          description: Gift card donation completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DYCDonateResponse'
        '400':
          description: Invalid format or missing fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '417':
          description: Card has already been donated or processing error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /dyc/{donorId}/{cardId}:
    get:
      summary: Get Gift Card Status
      description: Get the current status and basic information of a previously donated Retailer Gift Card.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
        - name: donorId
          in: path
          required: true
          schema:
            type: integer
        - name: cardId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Card status retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DYCStatusResponse'
        '400':
          description: Combination does not refer to a valid card.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /codes/activate:
    post:
      summary: Activate Codes
      description: Acquire active CharityChoice redemption codes. Creates an order in your account.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivateCodesRequest'
      responses:
        '201':
          description: Code activation completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivateCodesResponse'
        '400':
          description: Activation failed due to format issues.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /codes/activateCodes:
    post:
      summary: Activate Supplied Codes
      description: Activates the codes in the supplied list of codes for redemption of the given amount.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivateSuppliedCodesRequest'
      responses:
        '201':
          description: Code activation completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivateSuppliedCodesResponse'
        '400':
          description: No codes provided in request data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '417':
          description: Activation failed for all codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /codes/remove/{codes}:
    delete:
      summary: De-activate Codes
      description: De-activate one or more redemption codes.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
        - name: codes
          in: path
          required: true
          description: A comma-separated list of codes to be de-activated.
          schema:
            type: string
      responses:
        '200':
          description: All codes successfully removed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '202':
          description: Partially successful removal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          description: No codes in request URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '417':
          description: Removal failed entirely.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /digital/digitalCardsList:
    get:
      summary: Get Digital Cards List
      description: Gets a list of the CharityChoice Digital Cards with their images.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
      responses:
        '200':
          description: A list of digital cards.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DigitalCard'

  /digital/send:
    post:
      summary: Send Digital Cards
      description: Send one or more redeemable Digital Cards.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendDigitalCardsRequest'
      responses:
        '200':
          description: Digital cards sent or scheduled successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendDigitalCardsResponse'
        '400':
          description: Request not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /physical:
    post:
      summary: Order Physical Cards
      description: Order any number of Physical Charity Gift Cards.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhysicalCardOrderRequest'
      responses:
        '201':
          description: Order completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhysicalCardOrderResponse'
        '400':
          description: Request not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /physical/cardTypes:
    get:
      summary: Get Physical Card Types
      description: Gets a list of Physical Card Types with denominations and stock levels.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
      responses:
        '200':
          description: A list of physical card types.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhysicalCardTypesResponse'

  /physical/shippingTypes:
    get:
      summary: Get Shipping Types
      description: Gets a list of Shipping Types for physical cards orders.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
      responses:
        '200':
          description: A list of shipping types.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShippingTypesResponse'

  /codes/generateCodes/{prefix}/{numberOfCodes}:
    get:
      summary: Generate and Reserve Redemption Codes
      description: Acquire a list of valid non-active CharityChoice redemption codes.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
        - name: prefix
          in: path
          required: true
          schema:
            type: string
            pattern: "^[a-zA-Z]{4,}$"
        - name: numberOfCodes
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Codes generated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateCodesResponse'
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /codes/generateCodes/{prefix}/{numberOfCodes}/{charityId}:
    get:
      summary: Generate and Reserve Charity-Specific Redemption Codes
      description: Acquire a list of non-active redemption codes dedicated to a specific charity ID.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
        - name: prefix
          in: path
          required: true
          schema:
            type: string
            pattern: "^[a-zA-Z]{4,}$"
        - name: numberOfCodes
          in: path
          required: true
          schema:
            type: integer
        - name: charityId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Codes generated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateCodesResponse'
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /codes/status/{redemptionCode}:
    get:
      summary: Get Code Status (Single)
      description: Get the status of the given redemption code.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
        - name: redemptionCode
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Code status retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeStatusResponse'
        '400':
          description: Invalid request format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /codes/status:
    post:
      summary: Get Multiple Codes Status
      description: Gets the status multiple redemption codes.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                Codes:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Code statuses retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeStatusResponse'

  /codes/redeem:
    post:
      summary: Redeem a Code
      description: Redeem a CharityChoice redemption code for one or more charities.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedeemCodeRequest'
      responses:
        '201':
          description: Code redemption completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          description: Redemption failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'

  /codes/redeem/{redemptionCode}:
    delete:
      summary: Remove Redemption
      description: Remove previous redemption information from a previously redeemed CharityChoice code.
      parameters:
        - $ref: '#/components/parameters/CgcMode'
        - $ref: '#/components/parameters/CgcAppId'
        - name: redemptionCode
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Redemption information successfully removed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          description: Removal failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'