> ## Documentation Index
> Fetch the complete documentation index at: https://partner-help.letsdothis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Import discount codes

> Imports a batch of discount codes, created in the background as a job you poll. See [how imports work](/api-reference/imports).

Each `code` is imported once. Importing a code that already exists leaves it unchanged and reports `alreadyImported`.

> [!WARNING]
>
> This endpoint is restricted and not generally available: organizations that have not been enabled receive a `403`. Contact your Let's Do This representative if you'd like access.


## OpenAPI

````yaml /openapi.json post /v0/discount-codes/import
openapi: 3.1.0
info:
  title: Let's Do This API
  version: 0.1.0
  description: >
    The full reference — getting started, pagination, error responses, rate
    limits and the changelog — lives at

    [partner-help.letsdothis.com/api-reference](https://partner-help.letsdothis.com/api-reference/overview).

    This page is the interactive OpenAPI view of the same specification.


    # Authentication


    Create an API key from **Settings** → **Credentials** in your Let's Do This
    account and send it as a bearer token:


    ```bash

    curl --request GET \
     --url "https://api.letsdothis.com/v0/participants" \
     --header "Authorization: Bearer YOUR-API-KEY"
    ```


    Keep the key secret: it identifies your organization, so do not ship it in a
    website or native app. If a key is exposed,

    revoke it from the same section and create a replacement.


    # OpenAPI schema


    Download the [OpenAPI schema](https://api.letsdothis.com/documentation/json)
    to use with Postman or an OpenAPI client

    generator.
servers:
  - url: https://api.letsdothis.com
    description: Production
  - url: https://api.staging.letsdothis.com
    description: Staging
security:
  - bearerAuth: []
tags:
  - name: Events
    x-group: Events
    description: Events that participants can register for.
  - name: EventOccurrences
    x-group: Event occurrences
    description: >-
      Event occurrences scoped to the organizer associated with your Public API
      credentials. Unlike the public Events catalog, results are limited to your
      own events.
  - name: Races
    x-group: Races
    description: >-
      Races within an event occurrence. An event occurrence may have one or more
      races, for example a 5K and a 10K within the same race day.
  - name: Tickets
    x-group: Tickets
    description: Tickets that are available for events.
  - name: BookingForms
    x-group: Booking forms
    description: >-
      Booking forms define the questions a booker answers when registering for a
      ticket. A ticket usually references a single booking form, so expect zero
      or one, while a booking form may be shared across multiple tickets.
  - name: BookingFormFields
    x-group: Booking form fields
    description: >-
      Booking form fields are the individual questions on a booking form — their
      type, label, options, and whether an answer is required. A field can be
      reused across multiple forms.
  - name: Bookings
    x-group: Bookings
    description: >-
      Bookings are the transaction record for a registration. A booking may
      contain one or more participants (entries).
  - name: Membership
    x-group: Memberships
    description: >-
      Membership schemes, purchased policies and the seats on them, owned by
      your organizer. Policies are billing contracts; a seat is one person's
      place on a policy.
  - name: Participant
    x-group: Participants
    description: Participants are users who successfully booked an event.
  - name: LineItem
    x-group: Line items
    description: Financial details related to individual items within transactions.
  - name: AddOns
    x-group: Add-ons
    description: >-
      Your add-on products, such as merchandise or extras, that participants buy
      with their entry. Imported products keep the ids you gave them.
  - name: DiscountCodes
    x-group: Discount codes
    description: >-
      Discount codes participants enter at checkout to reduce the price of a
      booking.
  - name: Credits
    x-group: Credits
    description: >-
      Credits are balances participants can spend at checkout, identified by
      their email address.
  - name: Referrals
    x-group: Referrals
    description: >-
      Referral programs, the referrers registered on them, and asynchronous
      imports of historical referrals.
  - name: Teams
    x-group: Teams
    description: >-
      Teams group participants of an event occurrence under a team program.
      Teams can be imported for participants whose bookings were imported.
  - name: Application
    x-group: Applications
    description: >-
      Applications are created when a user applies for tickets that are set up
      to require an application process, such as balloted or "Good For Age"
      entries.
  - name: Partner
    x-group: Partners
    description: >-
      Partners that were created by the organization who can have Reserved
      Entries assigned to them.
  - name: ReservedEntries
    x-group: Reserved entries
    description: >-
      Reserved Entries are entries that are reserved for a partner. After being
      assigned, the partner can then allocate these entries to participants.
  - name: Timing
    x-group: Timing
    description: >-
      Timing providers push bib numbers and bib-pack shipments back to Let's Do
      This for the startlist entries they received. Available to select timing
      partners only.
  - name: Identity
    x-group: API key
    description: >-
      What your API key can reach. Available to every key, including scoped
      ones.
paths:
  /v0/discount-codes/import:
    post:
      tags:
        - DiscountCodes
      summary: Import discount codes
      description: >-
        Imports a batch of discount codes, created in the background as a job
        you poll. See [how imports work](/api-reference/imports).


        Each `code` is imported once. Importing a code that already exists
        leaves it unchanged and reports `alreadyImported`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscountCodeImportRequest'
      responses:
        '202':
          description: >-
            The batch passed the check and was accepted. Poll the job with
            `jobId` to see each row's result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscountCodeImportAccepted'
        '400':
          description: >-
            The request is malformed, or the `Idempotency-Key` header is
            invalid. `message` says which.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                      - 400
                  error:
                    type: string
                  message:
                    type: string
        '409':
          description: >-
            This `Idempotency-Key` was already used with a different request
            body. Use a new key for each new batch.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                      - 409
                  error:
                    type: string
                  message:
                    type: string
        '413':
          description: The batch is too large. Split it into smaller batches.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                      - 413
                  error:
                    type: string
                  message:
                    type: string
        '422':
          description: >-
            Nothing was imported because at least one row has a problem.
            `summary` and `errors` list every problem; fix them and send the
            batch again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscountCodeImportValidationFailure'
        '429':
          description: >-
            Too many requests. Wait the number of seconds in `retry-after` when
            the response has it, or back off for a few seconds, then retry.
          headers:
            retry-after:
              schema:
                type: integer
              description: Seconds to wait before retrying the request.
            x-ratelimit-limit:
              schema:
                type: integer
              description: Requests permitted in the current window.
            x-ratelimit-remaining:
              schema:
                type: integer
              description: Requests still permitted in the current window.
            x-ratelimit-reset:
              schema:
                type: integer
              description: Seconds until the current window resets.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                      - 429
                  error:
                    type: string
                  message:
                    type: string
components:
  schemas:
    DiscountCodeImportRequest:
      title: DiscountCodeImportRequest
      type: object
      properties:
        discountCodes:
          type: array
          items:
            $ref: '#/components/schemas/DiscountCodeImportRow'
          description: The discount codes to import.
          minItems: 1
          maxItems: 1000
      required:
        - discountCodes
      additionalProperties: false
      description: >-
        An asynchronous discount code import request: the whole batch is
        accepted or none of it.


        The first row takes the defaults: it discounts entries only, once per
        transaction. The second widens what it reaches with `appliesTo`, which
        replaces the default rather than adding to it, and uses `appliesPer` to
        come off every entry in the basket instead of the basket as a whole. The
        third has `flatRate: 0`, so it applies no discount and is kept only for
        tracking.
      example:
        discountCodes:
          - code: FLEETFEET5
            description: Fleet Feet post-race in-store incentive
            flatRate: 500
            maxValue: 500
            startDate: '2026-09-01T00:00:00Z'
            expiresAt: '2026-12-31T23:59:59Z'
            limitUsage: 1
            limitUsagePerUser: 1
            eventOccurrenceIds:
              - '21111177799'
            group: fleet-feet-2026
          - code: EARLYBIRD15
            percentage: 15
            eventIds:
              - '268365'
            appliesTo:
              - TICKETS
              - BOOKING_FEE
            appliesPer: ENTRY
          - code: CLUBMEMBER
            description: Club members, tracked for reporting
            flatRate: 0
            group: club-members-2026
    DiscountCodeImportAccepted:
      title: DiscountCodeImportAccepted
      type: object
      properties:
        jobId:
          type: string
          description: The id of the queued import job.
        status:
          type: string
          enum:
            - queued
      required:
        - jobId
        - status
      additionalProperties: false
      example:
        jobId: 661718293a4b5c6d7e8f901a
        status: queued
    DiscountCodeImportValidationFailure:
      title: DiscountCodeImportValidationFailure
      type: object
      properties:
        error:
          type: string
          enum:
            - validation_failed
        message:
          type: string
          description: A human summary of the failure.
        totalRows:
          type: number
          description: How many rows the batch contained.
        rowsWithErrors:
          type: number
          description: How many rows had at least one error.
        errorCount:
          type: number
          description: How many errors were found in total.
        summary:
          type: array
          items:
            $ref: '#/components/schemas/DiscountCodeImportErrorSummary'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/DiscountCodeImportRowErrors'
        truncated:
          type: boolean
          description: Whether `errors` was capped. `summary` is never capped.
      required:
        - error
        - message
        - totalRows
        - rowsWithErrors
        - errorCount
        - summary
        - errors
        - truncated
      additionalProperties: false
      description: >-
        The batch failed the check, so nothing was imported. `summary` groups
        every problem by type, most common first, and is never cut short.
        `errors` lists problems row by row and can be cut short for a large
        batch; `truncated` is then `true`.
    DiscountCodeImportRow:
      title: DiscountCodeImportRow
      type: object
      properties:
        code:
          type: string
          description: >-
            The code participants enter at checkout. Codes are unique per
            organizer and stored uppercase; imports are create-once per code —
            re-importing an existing code returns it untouched, reported as
            `alreadyImported`.
          minLength: 1
          maxLength: 128
        description:
          type: string
          description: >-
            An internal description of the code, shown in the organizer
            dashboard.
          maxLength: 1024
        percentage:
          type: integer
          description: >-
            The percentage discount the code applies. Exactly one of
            `percentage` or `flatRate` is required.


            `0` is not accepted here. To import a code that has no value, send
            `flatRate: 0` and leave `percentage` out.
          minimum: 1
          maximum: 100
        flatRate:
          type: integer
          description: >-
            The fixed discount the code applies, in the minor unit of the
            event's currency (e.g. pence, cents). Exactly one of `percentage` or
            `flatRate` is required.


            `0` is allowed: it creates a tracking-only code that applies no
            discount. Use it for a code you want to keep for reporting, such as
            one carried over from another platform. Everything else on the row
            still applies as it does to any other code: event and occurrence
            restrictions, usage limits, start and expiry dates, `group` and
            `description`.
          minimum: 0
        maxValue:
          type: integer
          description: >-
            The maximum total value the code can discount, in the minor unit of
            the event's currency.
          minimum: 1
        expiresAt:
          $ref: '#/components/schemas/ISODate'
        startDate:
          $ref: '#/components/schemas/ISODate'
        firstBookingOnly:
          type: boolean
          description: Whether the code only applies to a booker's first booking.
        limitUsage:
          type: integer
          description: How many times the code can be used in total.
          minimum: 1
        limitUsagePerUser:
          type: integer
          description: How many times a single user can use the code.
          minimum: 1
        limitUsagePerTransaction:
          type: integer
          description: >-
            How many entries a single transaction can apply the code to. Only a
            per-entry code can be capped this way, so supplying this requires
            `appliesPer` to be `ENTRY`.
          minimum: 1
        eventIds:
          type: array
          items:
            type: string
          description: Restrict the code to these events. Omit to allow all of your events.
          minItems: 1
          maxItems: 100
        eventOccurrenceIds:
          type: array
          items:
            type: string
          description: Restrict the code to these event occurrences. Omit to allow all.
          minItems: 1
          maxItems: 100
        appliesTo:
          type: array
          items:
            $ref: '#/components/schemas/DiscountCodeAppliesTo'
          description: >-
            Which parts of the basket the code discounts. Defaults to
            `["TICKETS"]`, so an imported code comes off entries only. Supply
            the full set you want when a code should also reach fees,
            merchandise and add-ons, form items or memberships — the value
            replaces the default rather than adding to it.


            The discount is applied to every matching line item in the basket,
            so a code covering more of the basket discounts more of it. Cap the
            total with `maxValue`.


            A code targets these categories, not a particular product. There is
            no way to make one specific item free. The closest is `percentage:
            100` with `appliesTo: ["MERCH_AND_ADDONS"]` and `maxValue` set to
            the item's price. That takes up to that amount off any merchandise
            or add-ons in the basket, not only the intended item. A participant
            who buys a cheaper item instead gets it free, and a more expensive
            one is discounted only up to the cap.
          minItems: 1
          maxItems: 5
        appliesPer:
          $ref: '#/components/schemas/DiscountCodeAppliesPer'
        group:
          type: string
          description: A free-form grouping label, shown in the organizer dashboard.
          maxLength: 256
      required:
        - code
      additionalProperties: false
      description: One discount code to import.
    DiscountCodeImportErrorSummary:
      title: DiscountCodeImportErrorSummary
      type: object
      properties:
        code:
          type: string
        fieldId:
          type: string
          description: The row field the class relates to, when field-scoped.
        count:
          type: number
          description: How many times this class occurred across the batch.
        message:
          type: string
          description: A representative message for the class.
        examples:
          type: array
          items:
            $ref: '#/components/schemas/DiscountCodeImportErrorLocator'
          description: The first few occurrences, located.
      required:
        - code
        - count
        - message
        - examples
      additionalProperties: false
      description: One validation problem class, aggregated across the batch.
    DiscountCodeImportRowErrors:
      title: DiscountCodeImportRowErrors
      type: object
      properties:
        discountCode:
          type: string
          description: The `code` of the row.
        rowIndex:
          type: number
          description: The zero-based position of the row in `discountCodes`.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/DiscountCodeImportErrorDetail'
      required:
        - rowIndex
        - errors
      additionalProperties: false
      description: The per-row detail of a failed validation, grouped by row.
    ISODate:
      title: ISODate
      type: string
      description: >-
        Represents a date and time in ISO 8601 format as a string.


        The string should follow the format `YYYY-MM-DDTHH:mm:ss.sssZ`, where:

        - `YYYY`: Four-digit year

        - `MM`: Two-digit month (01-12)

        - `DD`: Two-digit day of the month (01-31)

        - `T`: Delimiter indicating the start of the time component

        - `HH`: Two-digit hour in 24-hour format (00-23)

        - `mm`: Two-digit minutes (00-59)

        - `ss.sss`: Seconds with milliseconds (00.000-59.999)

        - `Z`: UTC timezone designator


        **Example:** To represent 11:30 AM on May 8th, 2026, the value would be:
        `"2026-05-08T11:30:00.000Z"`.
      example: '2026-05-08T11:30:00.000Z'
    DiscountCodeAppliesTo:
      title: DiscountCodeAppliesTo
      type: string
      enum:
        - TICKETS
        - BOOKING_FEE
        - MERCH_AND_ADDONS
        - FORM_ITEMS
        - MEMBERSHIPS
      description: >-
        The part of the basket a discount code applies to. These are the same
        categories the organizer dashboard offers, so a code created through the
        API and one created in the dashboard describe themselves the same way.


        `MERCH_AND_ADDONS` covers every merchandise and add-on category;
        `FORM_ITEMS` covers the remaining booking form items.
    DiscountCodeAppliesPer:
      title: DiscountCodeAppliesPer
      type: string
      enum:
        - TRANSACTION
        - ENTRY
      description: >-
        How often a discount code comes off a basket. These are the same two
        options the organizer dashboard offers as its discount type.


        `TRANSACTION` discounts the basket once, however many entries it holds.
        `ENTRY` discounts each participant's entry separately, so a basket of
        three entries is discounted three times.
    DiscountCodeImportErrorLocator:
      title: DiscountCodeImportErrorLocator
      type: object
      properties:
        discountCode:
          type: string
          description: The `code` of the offending row.
        rowIndex:
          type: number
          description: The zero-based position of the offending row in `discountCodes`.
        value:
          type: string
          description: The offending submitted value, when one exists.
      required:
        - rowIndex
      additionalProperties: false
      description: Where in the batch a validation error occurred.
    DiscountCodeImportErrorDetail:
      title: DiscountCodeImportErrorDetail
      type: object
      properties:
        code:
          type: string
        fieldId:
          type: string
        message:
          type: string
      required:
        - code
        - message
      additionalProperties: false
      description: One occurrence of a validation error.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.