openapi: 3.0.0 info: title: Renewal options version: "1.0" description: Read the products that the signed-in contact can renew each fixed-term subscription or membership onto. tags: - name: Renewal paths: /products/renewal-options: get: operationId: getRenewalOptions summary: Get renewal options description: >- Returns the renewal options of the contact in the bearer token. A fixed-term subscription, such as a membership for one season, does not renew automatically. The contact renews it by buying a product for the next term. The response has one renewal group for each active fixed-term subscription of the contact. Each group lists the products that the subscription can be renewed onto. OneBasket removes the products that the contact is not eligible for. To renew, add one of the options to a basket with [Add product to basket](/docs/api/baskets/add-product-to-basket). Send the `productId`, the `variantId` as `productVariantId`, the `subscriptionKey`, and `currentSubscription.subscriptionId` as `subscriptionRenewId`. Then check out the basket. Do not offer renewal when `currentSubscription.status.isLocked` is `true`. tags: - Renewal parameters: - name: currency in: header required: false description: The ISO 4217 code of the currency to return prices in, for example `GBP`. The default currency of the store is used when the header is missing or the value is not a known currency. schema: type: string - name: x-user-country in: header required: false description: The ISO 3166-1 alpha-2 code of the country of the contact, for example `GB`. It is used for rules that depend on the country. When the header is missing, OneBasket uses the country it detects from the request. schema: type: string responses: "200": description: The renewal groups of the contact. `renewalGroups` is empty when the contact has no active fixed-term subscription. content: application/json: schema: $ref: "#/components/schemas/RenewalOptions" "400": description: The request is not valid. content: application/problem+json: schema: $ref: "#/components/schemas/ProblemDetails" "401": description: The API key or the bearer token is missing or not valid. security: - BearerAuth: [] ApiKeyAuth: [] components: schemas: RenewalOptions: type: object required: - renewalGroups properties: renewalGroups: type: array items: $ref: "#/components/schemas/RenewalGroup" RenewalGroup: type: object description: The renewal options of one current subscription. required: - currentSubscription - options properties: currentSubscription: $ref: "#/components/schemas/CurrentSubscription" options: type: array description: The products the subscription can be renewed onto. Empty when there are none. `warning` then says why. items: $ref: "#/components/schemas/RenewalOption" warning: type: string nullable: true description: The reason `options` is empty. The text is in English and is meant for developers, not for display to the contact. existingBasket: allOf: - $ref: "#/components/schemas/ExistingRenewalBasket" nullable: true description: Set when a basket of the contact already contains a renewal of this subscription. Continue with that basket instead of creating a second one. renewalDeadline: type: string format: date-time nullable: true description: The last moment at which the subscription can be renewed. CurrentSubscription: type: object required: - subscriptionId - productId - variantId - productName - status properties: subscriptionId: type: string format: uuid description: The id of the subscription, as returned by [List subscriptions](/docs/api/subscriptions/list-subscriptions). Send it as `subscriptionRenewId` when you add a renewal option to a basket. productId: type: string variantId: type: string nullable: true productName: type: string status: $ref: "#/components/schemas/CurrentSubscriptionStatus" subscriptionEndDate: type: string format: date-time nullable: true description: When the current term ends. CurrentSubscriptionStatus: type: object required: - type - isLocked properties: type: type: string description: "`pending-renewal` means a renewal has been bought and is being processed. `pending-cancellation` means cancellation of the subscription has been requested." enum: - active - trial - pending-renewal - pending-cancellation isLocked: type: boolean description: When `true`, the subscription cannot be renewed at the moment. It is `true` for `pending-renewal` and `pending-cancellation`. RenewalOption: type: object required: - productId - variantId - productName - isSuggestedDefault - isRecommended - subscriptionKey properties: productId: type: string variantId: type: string nullable: true productName: type: string isSuggestedDefault: type: boolean description: The option to select by default. At most one option of a group has this set. It is usually the closest match to the current product. It can depend on the age of the contact when the next term starts. isRecommended: type: boolean description: Whether the organisation has marked this option as recommended. Use it to highlight the option. subscriptionKey: type: string description: Send it as `subscriptionKey` when you add the option to a basket. price: allOf: - $ref: "#/components/schemas/Price" nullable: true ExistingRenewalBasket: type: object required: - basketId - productId - productName - price properties: basketId: type: string description: The id of the basket. Read it with [Get basket](/docs/api/baskets/get-basket). productId: type: string variantId: type: string nullable: true productName: type: string price: $ref: "#/components/schemas/Price" Price: type: object required: - amount - currencyCode properties: amount: type: number description: The price as a decimal number in the main unit of the currency. For example `45.00` with `GBP` is £45.00. example: 45 currencyCode: type: string description: The ISO 4217 currency code. example: GBP ProblemDetails: type: object description: An error in the problem details format. See [Errors](/docs/errors). properties: type: type: string title: type: string status: type: integer detail: type: string instance: type: string securitySchemes: BearerAuth: type: http scheme: bearer ApiKeyAuth: type: apiKey in: header name: x-api-key servers: - url: "{baseUrl}" description: Your Storefront API host variables: baseUrl: default: https://your-storefront-api-host description: The Storefront API base URL for your store. Your Stadion technical contact provides it.