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

# Change a policy's offering

> Moves the policy to another offering in its scheme, either now or from its next renewal.

## How to use it

- Send an `Idempotency-Key` header, unique to each change you mean to make, and the same key on a retry. A retry returns the change the first request made.
- With an organizer key, your organization makes the change: member rules and the notice period don't apply, and nothing is charged. `returnUrl` isn't accepted.
- With a member token, only the primary member can ask, and the scheme's member rules and notice period apply. An upgrade made `NOW` may owe the difference, and `payment` says what is due and by when.

## Paying for an upgrade

- A token with the `memberships:billing` scope charges the member's saved card straight away, and `status` is `PAID`.
- Otherwise, or when the card is declined, needs the member's bank to confirm it, or there's no card, `status` is `ACTION_REQUIRED` with a `reason`. Send the member to `url`, our page where they finish paying. The change applies once it's paid.
- Send `returnUrl` to bring the member back afterwards. It must be on the origin of one of your app's redirect URIs, or use the same custom scheme and host. We add `policyChangeId` and `outcome` (`paid`, `failed` or `expired`) to its query.

> [!NOTE]
>
> This endpoint is in beta: its request and response contract can still change while it's being developed.


## OpenAPI

````yaml /openapi.json post /v0/membership-policies/{policyId}/offering-change
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/membership-policies/{policyId}/offering-change:
    post:
      tags:
        - Membership
      summary: Change a policy's offering
      description: >-
        Moves the policy to another offering in its scheme, either now or from
        its next renewal.


        ## How to use it


        - Send an `Idempotency-Key` header, unique to each change you mean to
        make, and the same key on a retry. A retry returns the change the first
        request made.

        - With an organizer key, your organization makes the change: member
        rules and the notice period don't apply, and nothing is charged.
        `returnUrl` isn't accepted.

        - With a member token, only the primary member can ask, and the scheme's
        member rules and notice period apply. An upgrade made `NOW` may owe the
        difference, and `payment` says what is due and by when.


        ## Paying for an upgrade


        - A token with the `memberships:billing` scope charges the member's
        saved card straight away, and `status` is `PAID`.

        - Otherwise, or when the card is declined, needs the member's bank to
        confirm it, or there's no card, `status` is `ACTION_REQUIRED` with a
        `reason`. Send the member to `url`, our page where they finish paying.
        The change applies once it's paid.

        - Send `returnUrl` to bring the member back afterwards. It must be on
        the origin of one of your app's redirect URIs, or use the same custom
        scheme and host. We add `policyChangeId` and `outcome` (`paid`, `failed`
        or `expired`) to its query.
      parameters:
        - schema:
            type: string
            pattern: ^[a-fA-F0-9]{24}$
          in: path
          name: policyId
          required: true
          description: >-
            The id of a membership policy: a member's purchased membership. Each
            seat names its policy in `policyId`.
        - schema:
            type: string
            minLength: 1
            maxLength: 100
          in: header
          name: idempotency-key
          required: true
          description: >-
            Unique per change you mean to make; send the same key on a retry to
            get the first answer back.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MembershipOfferingChangeRequest'
      responses:
        '201':
          description: >-
            The change that was made or scheduled. For an upgrade that needs
            paying for, `payment` says what's due.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipOfferingChange'
        '400':
          description: A parameter or field is missing or malformed. `message` says which.
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - statusCode
                  - message
                properties:
                  code:
                    type: string
                    enum:
                      - MEMBERSHIP_INVALID_REQUEST
                  statusCode:
                    type: integer
                    enum:
                      - 400
                  message:
                    type: string
        '404':
          description: Your organization has no membership policy with this id.
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - statusCode
                  - message
                properties:
                  code:
                    type: string
                    enum:
                      - MEMBERSHIP_RESOURCE_NOT_FOUND
                  statusCode:
                    type: integer
                    enum:
                      - 404
                  message:
                    type: string
        '409':
          description: >-
            The change isn't allowed: the scheme's rules, the household, or a
            pending change or cancellation stand in the way. reasons says which.
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - statusCode
                  - message
                properties:
                  code:
                    type: string
                    enum:
                      - MEMBERSHIP_OFFERING_CHANGE_REFUSED
                  statusCode:
                    type: integer
                    enum:
                      - 409
                  message:
                    type: string
                  reasons:
                    type: array
                    items:
                      type: string
                    description: >-
                      Each reason the change was refused, such as
                      NOT_PRIMARY_MEMBER, RULE_FORBIDS, LEAD_TIME_TOO_SHORT,
                      SEATS_EXCEED_TARGET, PAYMENT_IN_PROGRESS,
                      SWITCH_IN_PROGRESS, CANCELLATION_PENDING,
                      TARGET_UNAVAILABLE or OTHER_SCHEME. More may be added.
        '422':
          description: >-
            This Idempotency-Key was already used for a different change. Use a
            new key for each change you mean to make.
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - statusCode
                  - message
                properties:
                  code:
                    type: string
                    enum:
                      - MEMBERSHIP_IDEMPOTENCY_KEY_REUSED
                  statusCode:
                    type: integer
                    enum:
                      - 422
                  message:
                    type: string
        '503':
          description: Offering changes are switched off for now. Retry later.
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - statusCode
                  - message
                properties:
                  code:
                    type: string
                    enum:
                      - MEMBERSHIP_OFFERING_CHANGES_UNAVAILABLE
                  statusCode:
                    type: integer
                    enum:
                      - 503
                  message:
                    type: string
components:
  schemas:
    MembershipOfferingChangeRequest:
      title: MembershipOfferingChangeRequest
      type: object
      properties:
        toOfferingId:
          type: string
          description: The offering in the policy's scheme to move onto.
        timing:
          type: string
          enum:
            - NOW
            - AT_RENEWAL
          description: >-
            NOW applies straight away once anything due is paid; AT_RENEWAL at
            the renewal on or after notBefore.
        notBefore:
          type: string
          description: >-
            For AT_RENEWAL only: the first renewal on or after this. The next
            renewal when absent.
          format: date-time
        releaseSeatIds:
          type: array
          items:
            type: string
          description: >-
            Secondary seats to end when the change takes effect, so the rest fit
            the target plan. Never the primary seat.
        returnUrl:
          type: string
          description: >-
            Member tokens only: where our payment page sends the member once
            they have paid, failed to or run out of time, with policyChangeId
            and outcome (paid, failed or expired) added to its query. It must be
            on the origin of one of your app's redirect URIs, or use the same
            custom scheme and host.
      required:
        - toOfferingId
        - timing
      additionalProperties: false
    MembershipOfferingChange:
      title: MembershipOfferingChange
      type: object
      properties:
        policyChangeId:
          type: string
        state:
          type: string
          enum:
            - ACCEPTED
            - AWAITING_PAYMENT
          description: >-
            ACCEPTED: it takes effect at effectiveAt, paid for when anything was
            due. AWAITING_PAYMENT: only once payment is made.
        effectiveAt:
          type: string
          format: date-time
        payment:
          anyOf:
            - $ref: '#/components/schemas/MembershipOfferingChangePayment'
            - type: 'null'
          description: 'Null when nothing is due: always for an organizer key.'
      required:
        - policyChangeId
        - state
        - effectiveAt
        - payment
      additionalProperties: false
    MembershipOfferingChangePayment:
      title: MembershipOfferingChangePayment
      type: object
      properties:
        amountDue:
          $ref: '#/components/schemas/MembershipMoney'
        payBy:
          type: string
          description: Unpaid by then, the change fails and can be asked for again.
          format: date-time
        status:
          type: string
          enum:
            - PAID
            - PROCESSING
            - ACTION_REQUIRED
          description: >-
            PAID: the member's saved card was charged and the change applies.
            PROCESSING: the charge is still settling; read the pending change
            later. ACTION_REQUIRED: send the member to url to finish paying.
        reason:
          type:
            - string
            - 'null'
          enum:
            - BILLING_SCOPE_NOT_GRANTED
            - NO_SAVED_CARD
            - CARD_DECLINED
            - AUTHENTICATION_REQUIRED
            - CHECKOUT_UNAVAILABLE
            - null
          description: >-
            Why the member must finish on our page. BILLING_SCOPE_NOT_GRANTED:
            the member token lacks memberships:billing, so their saved card
            isn't charged from the API. NO_SAVED_CARD, CARD_DECLINED and
            AUTHENTICATION_REQUIRED (their bank wants them to confirm it) speak
            for themselves. CHECKOUT_UNAVAILABLE: the payment couldn't be
            started here. Null unless ACTION_REQUIRED.
        url:
          type:
            - string
            - 'null'
          description: >-
            For ACTION_REQUIRED: our page where the signed-in member pays for
            this change. Redirect them straight away and don't store it. Null
            otherwise.
      required:
        - amountDue
        - payBy
        - status
        - reason
        - url
      additionalProperties: false
      description: What the member owes before a change made now applies.
    MembershipMoney:
      title: MembershipMoney
      type: object
      properties:
        value:
          type: number
        currencyCode:
          type: string
      required:
        - value
        - currencyCode
      additionalProperties: false
      description: Money in minor units, e.g. DKK 150 is value 15000.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

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