> ## 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.

# Upsert imported line items

> Creates line items on bookings you've already imported, or updates ones an earlier import created. They're imported in the background as a job you poll. See [how imports work](/api-reference/imports).

## How to use it

- Group the line items by booking, naming each booking by `bookingId` or `externalBookingId`.
- Send an `Idempotency-Key` header. It's required.
- A line item that matches one from an earlier import is replaced in full, so leaving out an optional field clears it. Line items created any other way are never updated.
- The request itself is checked straight away. Checks that depend on the booking run in the job and show up as failed rows.

> [!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 put /v0/bookings/line-items/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/bookings/line-items/import:
    put:
      tags:
        - Bookings
      summary: Upsert imported line items
      description: >-
        Creates line items on bookings you've already imported, or updates ones
        an earlier import created. They're imported in the background as a job
        you poll. See [how imports work](/api-reference/imports).


        ## How to use it


        - Group the line items by booking, naming each booking by `bookingId` or
        `externalBookingId`.

        - Send an `Idempotency-Key` header. It's required.

        - A line item that matches one from an earlier import is replaced in
        full, so leaving out an optional field clears it. Line items created any
        other way are never updated.

        - The request itself is checked straight away. Checks that depend on the
        booking run in the job and show up as failed rows.
      parameters:
        - schema:
            type: string
            minLength: 1
            maxLength: 255
          in: header
          name: idempotency-key
          required: true
          description: >-
            Returns the original job when the same request is retried with the
            same key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkUpsertLineItemsRequest'
      responses:
        '202':
          description: >-
            The request was accepted. Poll the job with `jobId` to see each line
            item's result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LineItemImportAccepted'
        '400':
          description: >-
            The request is malformed, or the `Idempotency-Key` header is missing
            or invalid. `message` says which.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                      - 400
                  error:
                    type: string
                  message:
                    type: string
        '404':
          description: Not found. `message` says what's missing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                      - 404
                  error:
                    type: string
                  message:
                    type: string
        '409':
          description: >-
            This `Idempotency-Key` was already used with a different request
            body, or a booking changed while its line items were being imported.
            For the second, send the request again.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                      - 409
                  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/LineItemImportValidationResponse'
        '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:
    BulkUpsertLineItemsRequest:
      title: BulkUpsertLineItemsRequest
      type: object
      properties:
        transactionDate:
          $ref: '#/components/schemas/ISODate'
        bookings:
          type: array
          items:
            $ref: '#/components/schemas/UpsertBookingLineItemsGroup'
          minItems: 1
          maxItems: 1000
      required:
        - bookings
      additionalProperties: false
      description: >-
        Bulk full-replacement upsert of imported financial line items. Callers
        must resend each complete item; omitted optional fields are cleared.
    LineItemImportAccepted:
      title: LineItemImportAccepted
      type: object
      properties:
        jobId:
          type: string
        status:
          type: string
          enum:
            - queued
      required:
        - jobId
        - status
      additionalProperties: false
      example:
        jobId: 65e5f60718293a4b5c6d7e8f
        status: queued
    LineItemImportValidationResponse:
      title: LineItemImportValidationResponse
      type: object
      properties:
        error:
          type: string
          enum:
            - validation_failed
        message:
          type: string
        totalRows:
          type: number
        rowsWithErrors:
          type: number
        errorCount:
          type: number
        summary:
          type: array
          items:
            $ref: '#/components/schemas/LineItemImportValidationSummary'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/LineItemImportValidationDetail'
        truncated:
          type: boolean
          description: Whether the per-row errors were capped. The summary is never capped.
      required:
        - error
        - message
        - totalRows
        - rowsWithErrors
        - errorCount
        - summary
        - errors
        - truncated
      additionalProperties: false
      description: A whole-request validation failure. Nothing was imported.
    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'
    UpsertBookingLineItemsGroup:
      title: UpsertBookingLineItemsGroup
      type: object
      properties:
        bookingId:
          type: string
          description: >-
            The Let's Do This booking id. Send either this or
            `externalBookingId`.
        externalBookingId:
          type: string
          description: The caller's booking id from the booking import.
        lineItems:
          type: array
          items:
            $ref: '#/components/schemas/UpsertLineItemInput'
          description: >-
            Complete replacement line items. Omitted optional fields are
            cleared.
          minItems: 1
          maxItems: 100
      required:
        - lineItems
      additionalProperties: false
    LineItemImportValidationSummary:
      title: LineItemImportValidationSummary
      type: object
      additionalProperties: false
      properties:
        count:
          type: number
        examples:
          type: array
          items:
            $ref: '#/components/schemas/LineItemImportValidationLocator'
        code:
          type: string
        fieldId:
          type: string
        message:
          type: string
      required:
        - code
        - count
        - examples
        - message
    LineItemImportValidationDetail:
      title: LineItemImportValidationDetail
      type: object
      additionalProperties: false
      properties:
        code:
          type: string
        fieldId:
          type: string
        message:
          type: string
        bookingId:
          type: string
        externalBookingId:
          type: string
        groupIndex:
          type: number
        externalLineItemId:
          type: string
        rowIndex:
          type: number
      required:
        - code
        - message
    UpsertLineItemInput:
      title: UpsertLineItemInput
      type: object
      additionalProperties: false
      properties:
        externalLineItemId:
          type: string
          description: The caller's identifier for this line item, unique per organiser.
          minLength: 1
          maxLength: 128
        itemType:
          $ref: '#/components/schemas/ImportLineItemType'
        amount:
          $ref: '#/components/schemas/PriceInt'
        name:
          type: string
          description: >-
            A human-readable description. Defaults from the item type when
            omitted.
          maxLength: 256
        transactionDate:
          $ref: '#/components/schemas/ISODate'
        participantId:
          type: string
          description: >-
            The booking participant this item belongs to. Matched against the
            participant's `participantId`, as returned by `GET
            /v0/bookings/{id}/participants`.


            Required for add-on purchases; see `externalAddOnId`. A `DISCOUNT`
            item defaults to the booking's primary participant when this is
            omitted, and a `TICKET` item on a single-participant booking
            defaults to that participant; supplying it always takes precedence.
          example: abed704b-76d0-4190-a0e7-95b1ec1e48fd
        itemId:
          type: string
          description: >-
            The Let's Do This record this item refers to. What it means depends
            on `itemType`: a ticket id for `TICKET`, an add-on product id for
            merch item types, or the discount code for `DISCOUNT`.


            The record must already exist in Let's Do This and belong to you,
            and must be the kind the item type implies: a product id isn't
            accepted where a ticket is expected. An id that matches nothing,
            matches the wrong kind, or belongs to another organizer fails with
            `ITEM_REFERENCE_NOT_FOUND`.


            For `DISCOUNT`, the matching discount code's id is filled in as
            `itemSelectionId`.


            Optional. It only accepts Let's Do This ids, so if you only hold an
            id from your own system, leave it out.
          maxLength: 128
        itemSelectionId:
          type: string
          description: >-
            The more specific Let's Do This reference: a product variant id for
            merch item types, or the discount-code id for `DISCOUNT`.


            Same existence and ownership rules as `itemId`, reported the same
            way. When both are supplied they must describe the same entity — a
            product and one of its own variants, or a code and its own id — so a
            variant belonging to a different product is rejected with
            `ITEM_REFERENCE_MISMATCH`. For a `DISCOUNT`, this is inferred from
            `itemId` when omitted, and stored in the catalogue's canonical form
            when supplied.
          maxLength: 128
        externalAddOnId:
          type: string
          description: >-
            Your id for the add-on, from an add-on import. Send it with
            `externalVariantId`, and don't also send Let's Do This add-on ids.
          minLength: 1
          maxLength: 255
        externalVariantId:
          type: string
          description: >-
            The `externalVariantId` you gave the variant when you imported its
            add-on. Send it with `externalAddOnId`.
          minLength: 1
          maxLength: 255
        allocationStatus:
          type: string
          enum:
            - ALLOCATED
            - CANCELLED
          description: >-
            For an add-on `BOOKING_ITEM`: whether the add-on is still allocated
            to the participant (`ALLOCATED`) or was canceled (`CANCELLED`). A
            refunded add-on can't be `ALLOCATED`.
        refunded:
          type: boolean
          description: >-
            For an add-on `BOOKING_ITEM`: set `true` to record that the purchase
            was refunded in full. Leave it out to keep the current state. A
            refund can't be undone, so `false` on an add-on that's already
            refunded fails the row. Partial refunds, and more than one refund of
            the same add-on, aren't supported.
        lineItemId:
          type: string
          description: The Let's Do This id returned when the line item was imported.
          minLength: 1
          maxLength: 128
      required:
        - amount
        - itemType
      description: >-
        A financial line item to create or update on an existing booking.
        Matched items are replaced in full: omit an optional field to clear it.
        A discount's `itemSelectionId` is still inferred when its `itemId` is
        supplied. Only items previously created through the import API can be
        matched.
    LineItemImportValidationLocator:
      title: LineItemImportValidationLocator
      type: object
      properties:
        bookingId:
          type: string
        externalBookingId:
          type: string
        groupIndex:
          type: number
        externalLineItemId:
          type: string
        rowIndex:
          type: number
      additionalProperties: false
    ImportLineItemType:
      title: ImportLineItemType
      type: string
      enum:
        - TICKET
        - BOOKING_FEE
        - DISCOUNT
        - CREDIT
        - BOOKING_ITEM
        - MERCH_BOOKING_ITEM_CLOTHING
        - MERCH_BOOKING_ITEM_ITAB
        - MERCH_BOOKING_ITEM_PARKING
        - MERCH_BOOKING_ITEM_MISC
        - DONATION
        - MISC
      description: >-
        The supported financial category for an imported line item. The
        MERCH_BOOKING_ITEM_* values are accepted as aliases of BOOKING_ITEM:
        they import — and read back — as BOOKING_ITEM.
    PriceInt:
      title: PriceInt
      type: object
      properties:
        value:
          $ref: '#/components/schemas/PriceValueInt'
        currencyCode:
          $ref: '#/components/schemas/CurrencyCode'
      required:
        - value
        - currencyCode
      additionalProperties: false
      description: >-
        A monetary value in 100x base unit format whose value must be a whole
        number of minor units. For example, 1 GBP is represented as: _{ "value":
        100, "currencyCode": "GBP" }_
    PriceValueInt:
      title: PriceValueInt
      type: integer
      description: >-
        A whole-number monetary value in 100x base unit format. For example, 1
        GBP is represented as: 100, and 5 cents are represented as: 5.
        Fractional values are rejected.
      example: 5000
    CurrencyCode:
      title: CurrencyCode
      type: string
      enum:
        - AUD
        - CAD
        - DKK
        - EUR
        - GBP
        - INR
        - JPY
        - MXN
        - PHP
        - USD
        - ZERO
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

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