> ## 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, now or from a renewal. Send an Idempotency-Key header, unique per change you mean to make, and the same one on a retry: a retry answers with the change the first request made, and reusing a key for a different change returns 422 MEMBERSHIP_IDEMPOTENCY_KEY_REUSED. With an organizer key the change is made by your organization: member rules and the notice period don't apply and nothing is charged. With a member token only the primary member may ask, the scheme's member rules and notice period apply, and an upgrade made NOW may owe the difference: payment then says what is due and by when. A token with the memberships:billing scope has the member's saved card charged straight away (status PAID). Without that scope, or when the card needs the member's bank to confirm it, is declined or there is none, status is ACTION_REQUIRED with a reason, and url is our page where the signed-in member finishes paying; the change applies once it is paid. Send returnUrl, on the origin of one of your app's redirect URIs or in the same custom scheme and host, and that page sends the member back to it afterwards with policyChangeId and outcome (paid, failed or expired) added to its query. returnUrl is refused for an organizer key. A refused change returns 409 MEMBERSHIP_OFFERING_CHANGE_REFUSED with reasons. Returns 503 MEMBERSHIP_OFFERING_CHANGES_UNAVAILABLE while offering changes are switched off; retry later. > [!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: >- Organizer-owned products that can be purchased and allocated to participants. Imported products retain stable external identities. - 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, now or from a renewal. Send an Idempotency-Key header, unique per change you mean to make, and the same one on a retry: a retry answers with the change the first request made, and reusing a key for a different change returns 422 MEMBERSHIP_IDEMPOTENCY_KEY_REUSED. With an organizer key the change is made by your organization: member rules and the notice period don't apply and nothing is charged. With a member token only the primary member may ask, the scheme's member rules and notice period apply, and an upgrade made NOW may owe the difference: payment then says what is due and by when. A token with the memberships:billing scope has the member's saved card charged straight away (status PAID). Without that scope, or when the card needs the member's bank to confirm it, is declined or there is none, status is ACTION_REQUIRED with a reason, and url is our page where the signed-in member finishes paying; the change applies once it is paid. Send returnUrl, on the origin of one of your app's redirect URIs or in the same custom scheme and host, and that page sends the member back to it afterwards with policyChangeId and outcome (paid, failed or expired) added to its query. returnUrl is refused for an organizer key. A refused change returns 409 MEMBERSHIP_OFFERING_CHANGE_REFUSED with reasons. Returns 503 MEMBERSHIP_OFFERING_CHANGES_UNAVAILABLE while offering changes are switched off; retry later. parameters: - schema: type: string pattern: ^[a-fA-F0-9]{24}$ in: path name: policyId required: true - 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: Default Response content: application/json: schema: $ref: '#/components/schemas/MembershipOfferingChange' '400': description: Default Response content: application/json: schema: type: object required: - code - statusCode - message properties: code: type: string enum: - MEMBERSHIP_RESOURCE_NOT_FOUND - MEMBERSHIP_INVALID_REQUEST - MEMBERSHIP_PORTAL_CONFIGURATION_REQUIRED - MEMBERSHIP_BILLING_UNAVAILABLE - MEMBERSHIP_FROZEN - MEMBERSHIP_ALREADY_CANCELLED - MEMBERSHIP_PRIMARY_MEMBER_ONLY - MEMBERSHIP_OFFERING_CHANGE_REFUSED - MEMBERSHIP_OFFERING_CHANGES_UNAVAILABLE - MEMBERSHIP_IDEMPOTENCY_KEY_REUSED - MEMBERSHIP_FEATURE_NOT_ENABLED - MEMBERSHIP_WAITLIST_ENTRY_NOT_SELECTABLE - MEMBERSHIP_WAITLIST_CHARGING_PAUSED description: >- Stable error identifier. RESOURCE_NOT_FOUND covers missing and foreign resources alike. INVALID_REQUEST covers malformed input or fields that cannot be edited. PORTAL_CONFIGURATION_REQUIRED requires account setup; BILLING_UNAVAILABLE means billing cannot be resolved or reached. FROZEN and ALREADY_CANCELLED are reserved for future lifecycle writes. PRIMARY_MEMBER_ONLY means only the primary member of the policy can do this. OFFERING_CHANGE_REFUSED means the scheme’s rules, the household or a pending change or cancellation don’t allow the offering change; reasons says which. OFFERING_CHANGES_UNAVAILABLE means offering changes are switched off for now; retry later. IDEMPOTENCY_KEY_REUSED means the Idempotency-Key was already used for a different request. FEATURE_NOT_ENABLED means the endpoint is restricted and not enabled for your organisation. WAITLIST_ENTRY_NOT_SELECTABLE means the waitlist entry was withdrawn or refused. WAITLIST_CHARGING_PAUSED means selection is paused; try again later. statusCode: type: integer message: type: string reasons: type: array items: type: string description: >- Only with OFFERING_CHANGE_REFUSED: each reason, 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. '404': description: Default Response content: application/json: schema: type: object required: - code - statusCode - message properties: code: type: string enum: - MEMBERSHIP_RESOURCE_NOT_FOUND - MEMBERSHIP_INVALID_REQUEST - MEMBERSHIP_PORTAL_CONFIGURATION_REQUIRED - MEMBERSHIP_BILLING_UNAVAILABLE - MEMBERSHIP_FROZEN - MEMBERSHIP_ALREADY_CANCELLED - MEMBERSHIP_PRIMARY_MEMBER_ONLY - MEMBERSHIP_OFFERING_CHANGE_REFUSED - MEMBERSHIP_OFFERING_CHANGES_UNAVAILABLE - MEMBERSHIP_IDEMPOTENCY_KEY_REUSED - MEMBERSHIP_FEATURE_NOT_ENABLED - MEMBERSHIP_WAITLIST_ENTRY_NOT_SELECTABLE - MEMBERSHIP_WAITLIST_CHARGING_PAUSED description: >- Stable error identifier. RESOURCE_NOT_FOUND covers missing and foreign resources alike. INVALID_REQUEST covers malformed input or fields that cannot be edited. PORTAL_CONFIGURATION_REQUIRED requires account setup; BILLING_UNAVAILABLE means billing cannot be resolved or reached. FROZEN and ALREADY_CANCELLED are reserved for future lifecycle writes. PRIMARY_MEMBER_ONLY means only the primary member of the policy can do this. OFFERING_CHANGE_REFUSED means the scheme’s rules, the household or a pending change or cancellation don’t allow the offering change; reasons says which. OFFERING_CHANGES_UNAVAILABLE means offering changes are switched off for now; retry later. IDEMPOTENCY_KEY_REUSED means the Idempotency-Key was already used for a different request. FEATURE_NOT_ENABLED means the endpoint is restricted and not enabled for your organisation. WAITLIST_ENTRY_NOT_SELECTABLE means the waitlist entry was withdrawn or refused. WAITLIST_CHARGING_PAUSED means selection is paused; try again later. statusCode: type: integer message: type: string reasons: type: array items: type: string description: >- Only with OFFERING_CHANGE_REFUSED: each reason, 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. '409': description: Default Response content: application/json: schema: type: object required: - code - statusCode - message properties: code: type: string enum: - MEMBERSHIP_RESOURCE_NOT_FOUND - MEMBERSHIP_INVALID_REQUEST - MEMBERSHIP_PORTAL_CONFIGURATION_REQUIRED - MEMBERSHIP_BILLING_UNAVAILABLE - MEMBERSHIP_FROZEN - MEMBERSHIP_ALREADY_CANCELLED - MEMBERSHIP_PRIMARY_MEMBER_ONLY - MEMBERSHIP_OFFERING_CHANGE_REFUSED - MEMBERSHIP_OFFERING_CHANGES_UNAVAILABLE - MEMBERSHIP_IDEMPOTENCY_KEY_REUSED - MEMBERSHIP_FEATURE_NOT_ENABLED - MEMBERSHIP_WAITLIST_ENTRY_NOT_SELECTABLE - MEMBERSHIP_WAITLIST_CHARGING_PAUSED description: >- Stable error identifier. RESOURCE_NOT_FOUND covers missing and foreign resources alike. INVALID_REQUEST covers malformed input or fields that cannot be edited. PORTAL_CONFIGURATION_REQUIRED requires account setup; BILLING_UNAVAILABLE means billing cannot be resolved or reached. FROZEN and ALREADY_CANCELLED are reserved for future lifecycle writes. PRIMARY_MEMBER_ONLY means only the primary member of the policy can do this. OFFERING_CHANGE_REFUSED means the scheme’s rules, the household or a pending change or cancellation don’t allow the offering change; reasons says which. OFFERING_CHANGES_UNAVAILABLE means offering changes are switched off for now; retry later. IDEMPOTENCY_KEY_REUSED means the Idempotency-Key was already used for a different request. FEATURE_NOT_ENABLED means the endpoint is restricted and not enabled for your organisation. WAITLIST_ENTRY_NOT_SELECTABLE means the waitlist entry was withdrawn or refused. WAITLIST_CHARGING_PAUSED means selection is paused; try again later. statusCode: type: integer message: type: string reasons: type: array items: type: string description: >- Only with OFFERING_CHANGE_REFUSED: each reason, 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: Default Response content: application/json: schema: type: object required: - code - statusCode - message properties: code: type: string enum: - MEMBERSHIP_RESOURCE_NOT_FOUND - MEMBERSHIP_INVALID_REQUEST - MEMBERSHIP_PORTAL_CONFIGURATION_REQUIRED - MEMBERSHIP_BILLING_UNAVAILABLE - MEMBERSHIP_FROZEN - MEMBERSHIP_ALREADY_CANCELLED - MEMBERSHIP_PRIMARY_MEMBER_ONLY - MEMBERSHIP_OFFERING_CHANGE_REFUSED - MEMBERSHIP_OFFERING_CHANGES_UNAVAILABLE - MEMBERSHIP_IDEMPOTENCY_KEY_REUSED - MEMBERSHIP_FEATURE_NOT_ENABLED - MEMBERSHIP_WAITLIST_ENTRY_NOT_SELECTABLE - MEMBERSHIP_WAITLIST_CHARGING_PAUSED description: >- Stable error identifier. RESOURCE_NOT_FOUND covers missing and foreign resources alike. INVALID_REQUEST covers malformed input or fields that cannot be edited. PORTAL_CONFIGURATION_REQUIRED requires account setup; BILLING_UNAVAILABLE means billing cannot be resolved or reached. FROZEN and ALREADY_CANCELLED are reserved for future lifecycle writes. PRIMARY_MEMBER_ONLY means only the primary member of the policy can do this. OFFERING_CHANGE_REFUSED means the scheme’s rules, the household or a pending change or cancellation don’t allow the offering change; reasons says which. OFFERING_CHANGES_UNAVAILABLE means offering changes are switched off for now; retry later. IDEMPOTENCY_KEY_REUSED means the Idempotency-Key was already used for a different request. FEATURE_NOT_ENABLED means the endpoint is restricted and not enabled for your organisation. WAITLIST_ENTRY_NOT_SELECTABLE means the waitlist entry was withdrawn or refused. WAITLIST_CHARGING_PAUSED means selection is paused; try again later. statusCode: type: integer message: type: string reasons: type: array items: type: string description: >- Only with OFFERING_CHANGE_REFUSED: each reason, 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. '503': description: Default Response content: application/json: schema: type: object required: - code - statusCode - message properties: code: type: string enum: - MEMBERSHIP_RESOURCE_NOT_FOUND - MEMBERSHIP_INVALID_REQUEST - MEMBERSHIP_PORTAL_CONFIGURATION_REQUIRED - MEMBERSHIP_BILLING_UNAVAILABLE - MEMBERSHIP_FROZEN - MEMBERSHIP_ALREADY_CANCELLED - MEMBERSHIP_PRIMARY_MEMBER_ONLY - MEMBERSHIP_OFFERING_CHANGE_REFUSED - MEMBERSHIP_OFFERING_CHANGES_UNAVAILABLE - MEMBERSHIP_IDEMPOTENCY_KEY_REUSED - MEMBERSHIP_FEATURE_NOT_ENABLED - MEMBERSHIP_WAITLIST_ENTRY_NOT_SELECTABLE - MEMBERSHIP_WAITLIST_CHARGING_PAUSED description: >- Stable error identifier. RESOURCE_NOT_FOUND covers missing and foreign resources alike. INVALID_REQUEST covers malformed input or fields that cannot be edited. PORTAL_CONFIGURATION_REQUIRED requires account setup; BILLING_UNAVAILABLE means billing cannot be resolved or reached. FROZEN and ALREADY_CANCELLED are reserved for future lifecycle writes. PRIMARY_MEMBER_ONLY means only the primary member of the policy can do this. OFFERING_CHANGE_REFUSED means the scheme’s rules, the household or a pending change or cancellation don’t allow the offering change; reasons says which. OFFERING_CHANGES_UNAVAILABLE means offering changes are switched off for now; retry later. IDEMPOTENCY_KEY_REUSED means the Idempotency-Key was already used for a different request. FEATURE_NOT_ENABLED means the endpoint is restricted and not enabled for your organisation. WAITLIST_ENTRY_NOT_SELECTABLE means the waitlist entry was withdrawn or refused. WAITLIST_CHARGING_PAUSED means selection is paused; try again later. statusCode: type: integer message: type: string reasons: type: array items: type: string description: >- Only with OFFERING_CHANGE_REFUSED: each reason, 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. 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.