openapi: 3.1.0
info:
  title: Brand Promo Codes API
  version: v11
  description: "Manage promo codes used to track partner involvement and attribute credit. \nPromo codes can be linked to Deals to sync start/end dates and discount details.\n"
servers:
- url: https://api.impact.com
security:
- basicAuth: []
paths:
  /Advertisers/{AccountSID}/PromoCodes:
    get:
      operationId: listPromoCodes
      tags:
      - Promo Codes
      summary: List all promo codes
      description: Returns a list of promo codes in your program.
      parameters:
      - name: AccountSID
        in: path
        required: true
        description: The unique identifier for the account.
        schema:
          type: string
      - name: CampaignId
        in: query
        required: false
        description: Filter by program ID.
        schema:
          type: integer
      - name: Code
        in: query
        required: false
        description: Filter by a specific UTF-8 URL-encoded promo code.
        schema:
          type: string
      - name: StartDate
        in: query
        required: false
        description: Filter by start date (ISO 8601).
        schema:
          type: string
          format: date-time
      - name: EndDate
        in: query
        required: false
        description: Filter by end date (ISO 8601).
        schema:
          type: string
          format: date-time
      - name: State
        in: query
        required: false
        description: Filter by promo code state.
        schema:
          type: string
          enum:
          - ACTIVE
          - INACTIVE
      responses:
        '200':
          description: A list of promo code objects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  PromoCodes:
                    type: array
                    description: The list of promo code objects.
                    items:
                      $ref: '#/components/schemas/PromoCode'
    post:
      operationId: createPromoCode
      tags:
      - Promo Codes
      summary: Create a promo code
      description: Creates a new promo code for tracking partner-driven actions.
      parameters:
      - name: AccountSID
        in: path
        required: true
        description: The unique identifier for the account.
        schema:
          type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - AssignedPartnerId
              - CampaignId
              - CreditPolicy
              - Code
              - Type
              properties:
                AssignedPartnerId:
                  type: integer
                  description: The partner account ID this promo code is assigned to.
                  example: 2552842
                CampaignId:
                  type: integer
                  description: The program ID this promo code applies to.
                  example: 1000
                CreditPolicy:
                  type: string
                  description: How credit is awarded for actions involving this code.
                  enum:
                  - ALWAYS
                  - INVOLVED
                  - WINNER
                Code:
                  type: string
                  description: The promo code value.
                  example: SUMMER25
                Type:
                  type: string
                  description: LI for Exact match, RE for Regex.
                  enum:
                  - LI
                  - RE
                StartDate:
                  type: string
                  format: date-time
                  description: The date and time the promo code becomes active.
                  example: '2026-06-01T00:00:00-07:00'
                EndDate:
                  type: string
                  format: date-time
                  description: The date and time the promo code expires.
                  example: '2026-08-31T23:59:59-07:00'
                DealId:
                  type: integer
                  description: The unique identifier of a Deal to link this promo code to.
                  example: 3
                DealName:
                  type: string
                  description: The display name of the linked Deal.
                  example: AcmeDeal3
      responses:
        '200':
          description: The promo code was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusUriResponse'
  /Advertisers/{AccountSID}/PromoCodes/{PromoCodeId}:
    get:
      operationId: getPromoCode
      tags:
      - Promo Codes
      summary: Retrieve a promo code
      parameters:
      - name: AccountSID
        in: path
        required: true
        description: The unique identifier for the account.
        schema:
          type: string
      - name: PromoCodeId
        in: path
        required: true
        description: The unique identifier for the promo code.
        schema:
          type: integer
      responses:
        '200':
          description: A single promo code object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromoCode'
    delete:
      operationId: expirePromoCode
      tags:
      - Promo Codes
      summary: Expire a promo code
      description: Deactivates the promo code. impact.com will no longer track its usage after expiration.
      parameters:
      - name: AccountSID
        in: path
        required: true
        description: The unique identifier for the account.
        schema:
          type: string
      - name: PromoCodeId
        in: path
        required: true
        description: The unique identifier for the promo code to expire.
        schema:
          type: integer
      responses:
        '200':
          description: The promo code was successfully expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusUriResponse'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
  schemas:
    PromoCode:
      type: object
      properties:
        Id:
          type: integer
          description: The unique identifier for the promo code.
          example: 12345
        Code:
          type: string
          description: The promo code value.
          example: SUMMER25
        Type:
          type: string
          description: LI for Exact match, RE for Regex.
          enum:
          - LI
          - RE
        CreditPolicy:
          type: string
          description: How credit is awarded for actions involving this code.
          enum:
          - ALWAYS
          - INVOLVED
          - WINNER
        CampaignId:
          type: integer
          description: The unique identifier of the program this promo code applies to.
          example: 1000
        CampaignName:
          type: string
          description: The display name of the program.
          example: Acme Campaign
        AssignedPartnerId:
          type: integer
          description: The unique identifier of the partner this promo code is assigned to.
          example: 2552842
        AssignedPartnerName:
          type: string
          description: The display name of the assigned partner.
          example: Wile E. Coyote Facebook
        CreatedDate:
          type: string
          format: date-time
          description: The date and time the promo code was created.
          example: '2026-01-15T10:00:00-08:00'
        StartDate:
          type: string
          format: date-time
          nullable: true
          description: The date and time the promo code becomes active.
          example: '2026-06-01T00:00:00-07:00'
        EndDate:
          type: string
          format: date-time
          nullable: true
          description: The date and time the promo code expires.
          example: '2026-08-31T23:59:59-07:00'
        State:
          type: string
          description: The current state of the promo code.
          enum:
          - ACTIVE
          - INACTIVE
        DealId:
          type: integer
          nullable: true
          description: The unique identifier of the Deal this promo code is linked to, if any.
          example: 3
        DealName:
          type: string
          nullable: true
          description: The display name of the linked Deal.
          example: AcmeDeal3
        DealState:
          type: string
          nullable: true
          description: The state of the linked Deal.
          example: ACTIVE
        DealType:
          type: string
          nullable: true
          description: The type of the linked Deal.
          example: GENERAL_SALE
        DealScope:
          type: string
          nullable: true
          description: The scope of the linked Deal.
          example: PRODUCT
        DealStartDate:
          type: string
          format: date-time
          nullable: true
          description: The start date of the linked Deal.
          example: '2026-06-01T00:00:00-07:00'
        DealEndDate:
          type: string
          format: date-time
          nullable: true
          description: The end date of the linked Deal.
          example: '2026-08-31T23:59:59-07:00'
        DiscountType:
          type: string
          nullable: true
          description: How the discount is calculated.
          example: FIXED
        DiscountAmount:
          type: number
          format: decimal
          nullable: true
          description: The flat discount amount, when DiscountType is FIXED.
          example: 5.0
        DiscountCurrency:
          type: string
          nullable: true
          description: Three-letter ISO 4217 currency code for the discount.
        DiscountPercent:
          type: number
          format: float
          nullable: true
          description: The discount percentage, when DiscountType is PERCENT.
        MinimumPurchaseAmount:
          type: number
          format: decimal
          nullable: true
          description: The minimum order amount required for the deal to apply.
        MaximumSavingsAmount:
          type: number
          format: decimal
          nullable: true
          description: The maximum total savings the deal can apply to a single order.
        PurchaseLimitQuantity:
          type: integer
          description: Maximum number of times the deal can be applied per order.
        BogoBuyQuantity:
          type: integer
          description: Quantity the customer must buy in a BOGO deal.
        BogoBuyName:
          type: string
          nullable: true
          description: Name of the item the customer must buy in a BOGO deal.
        BogoGetQuantity:
          type: integer
          description: Quantity the customer receives in a BOGO deal.
        BogoGetName:
          type: string
          nullable: true
          description: Name of the item the customer receives in a BOGO deal.
        BogoGetDiscountType:
          type: string
          nullable: true
          description: How the discount on the "get" item is calculated in a BOGO deal.
        SynchAdsPromoCodes:
          type: boolean
          description: Whether to synchronize promo codes with ads.
        Uri:
          type: string
          format: uri-reference
          description: The unique reference to this promo code in the impact.com API.
          example: /Advertisers/<AccountSID>/PromoCodes/7777777
    StatusUriResponse:
      type: object
      properties:
        Status:
          type: string
          description: Indicates whether the operation was successful.
          example: OK
        Uri:
          type: string
          format: uri-reference
          description: The unique reference to the affected promo code.
          example: /Advertisers/<AccountSID>/PromoCodes/7777777
