openapi: 3.0.3
info:
  title: 7digital API
  description: >-
    The classic 7digital REST API (v1.2) provides access to the 7digital music
    catalogue (artists, releases, tracks, tags), user lockers, basket/checkout,
    payment, editorial, territories and IP-lookup. All operations are signed
    with OAuth 1.0 and scoped by a consumer key issued under a commercial
    agreement.
  version: '1.2'
  contact:
    name: 7digital / MassiveMusic Client Success
    url: https://docs.massivemusic.com/docs/support
  license:
    name: Commercial — 7digital / MassiveMusic
    url: https://docs.massivemusic.com/docs/sla
  x-last-validated: '2026-05-28'
  x-generated-from: documentation
  x-source-url: https://github.com/7digital/7digital-api/blob/master/assets/7digital-api-schema.json
servers:
  - url: https://api.7digital.com/1.2
    description: 7digital Public API v1.2 (production)
tags:
  - name: Releases
    description: Browse, search, recommend, and chart 7digital releases (albums, singles, EPs).
  - name: Artists
    description: Browse, search, chart, and resolve 7digital artists and their releases.
  - name: Tracks
    description: Search, chart, and look up 7digital track metadata.
  - name: Tags
    description: List the curated tag vocabulary used across the 7digital catalogue.
  - name: Basket
    description: Manage purchase baskets, apply vouchers, and complete PayPal checkout.
  - name: User
    description: Per-user account operations — locker, purchases, payment cards, subscriptions, signup.
  - name: Users
    description: Partner-scoped user directory operations — find and update users.
  - name: Territories
    description: List supported countries / sales territories.
  - name: Translations
    description: Localised translation bundles for the 7digital catalogue.
  - name: IpLookup
    description: Resolve an end-user's country from an IP address.
  - name: Editorial
    description: List 7digital editorial features, banners, and curated content slots.
  - name: Catalogue
    description: Resolve catalogue entities (artist, release) from 7digital web URLs.
  - name: Payment
    description: Payment metadata — supported card types and voucher details.
security:
  - oauth1: []
paths:
  /release/byDate:
    get:
      operationId: getReleasesByDate
      summary: 7digital Get Releases By Date
      description: List releases by release date window. Supports paging and territory filters.
      tags: [Releases]
      parameters:
        - $ref: '#/components/parameters/Country'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paged list of releases.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseListResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/AuthError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /release/details:
    get:
      operationId: getReleaseDetails
      summary: 7digital Get Release Details
      description: Get all available metadata for a release by 7digital release id.
      tags: [Releases]
      parameters:
        - $ref: '#/components/parameters/ReleaseId'
        - $ref: '#/components/parameters/Country'
      responses:
        '200':
          description: Release metadata payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseDetailsResponse'
        '401':
          $ref: '#/components/responses/AuthError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /release/editorial:
    get:
      operationId: getReleaseEditorial
      summary: 7digital Get Release Editorial
      description: Get editorial commentary and review copy for a release.
      tags: [Releases]
      parameters:
        - $ref: '#/components/parameters/ReleaseId'
      responses:
        '200':
          description: Editorial copy for the release.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EditorialResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /release/chart:
    get:
      operationId: getReleaseChart
      summary: 7digital Get Release Chart
      description: Get the current release chart for a given period and territory.
      tags: [Releases]
      parameters:
        - $ref: '#/components/parameters/Country'
        - $ref: '#/components/parameters/Period'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A chart of releases.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /release/recommend:
    get:
      operationId: getReleaseRecommendations
      summary: 7digital Get Release Recommendations
      description: Get recommended releases that fans of a seed release also purchase or stream.
      tags: [Releases]
      parameters:
        - $ref: '#/components/parameters/ReleaseId'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A list of recommended releases.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /release/search:
    get:
      operationId: searchReleases
      summary: 7digital Search Releases
      description: Free-text search the 7digital catalogue for releases matching a query.
      tags: [Releases]
      parameters:
        - $ref: '#/components/parameters/Query'
        - $ref: '#/components/parameters/Country'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paged list of matching releases.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /release/tracks:
    get:
      operationId: getReleaseTracks
      summary: 7digital Get Release Tracks
      description: Get the track listing for a given release.
      tags: [Releases]
      parameters:
        - $ref: '#/components/parameters/ReleaseId'
      responses:
        '200':
          description: A track listing for the release.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /release/tags:
    get:
      operationId: getReleaseTags
      summary: 7digital Get Release Tags
      description: Get the tags / genre labels applied to a release.
      tags: [Releases]
      parameters:
        - $ref: '#/components/parameters/ReleaseId'
      responses:
        '200':
          description: A list of tags for the release.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /release/match/byId:
    get:
      operationId: matchReleaseById
      summary: 7digital Match Release By Id
      description: Match a release in a partner system to the 7digital release using an external identifier (UPC/EAN/GRid).
      tags: [Releases]
      security:
        - oauth1_two_legged: []
      parameters:
        - name: id
          in: query
          required: true
          description: The external identifier to match (e.g., UPC).
          schema:
            type: string
          example: '00602445912025'
      responses:
        '200':
          description: A matched release.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseDetailsResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /release/bytag/new:
    get:
      operationId: getNewReleasesByTags
      summary: 7digital Get New Releases By Tags
      description: List new releases for a given tag or set of tags.
      tags: [Releases]
      parameters:
        - $ref: '#/components/parameters/Tags'
        - $ref: '#/components/parameters/Country'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A list of new releases for the tag(s).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /release/bytag/top:
    get:
      operationId: getTopReleasesByTags
      summary: 7digital Get Top Releases By Tags
      description: List top-performing releases for a given tag or set of tags.
      tags: [Releases]
      parameters:
        - $ref: '#/components/parameters/Tags'
        - $ref: '#/components/parameters/Country'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A list of top releases for the tag(s).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /artist/browse:
    get:
      operationId: browseArtists
      summary: 7digital Browse Artists
      description: Browse artists in the 7digital catalogue whose names start with the given letter(s).
      tags: [Artists]
      parameters:
        - name: letter
          in: query
          required: true
          description: The starting letter or letters to browse by (e.g. `A`, `Be`).
          schema:
            type: string
          example: 'B'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paged list of artists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtistListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /artist/chart:
    get:
      operationId: getArtistChart
      summary: 7digital Get Artist Chart
      description: Get the current artist chart for a given period and territory.
      tags: [Artists]
      parameters:
        - $ref: '#/components/parameters/Country'
        - $ref: '#/components/parameters/Period'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A chart of artists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtistListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /artist/details:
    get:
      operationId: getArtistDetails
      summary: 7digital Get Artist Details
      description: Get all available metadata for an artist by 7digital artist id.
      tags: [Artists]
      parameters:
        - $ref: '#/components/parameters/ArtistId'
      responses:
        '200':
          description: Artist metadata payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtistDetailsResponse'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /artist/releases:
    get:
      operationId: getArtistReleases
      summary: 7digital Get Artist Releases
      description: List releases by a given artist, optionally filtered by release type (album, single, etc.).
      tags: [Artists]
      parameters:
        - $ref: '#/components/parameters/ArtistId'
        - $ref: '#/components/parameters/ReleaseType'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A list of releases by the artist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /artist/similar:
    get:
      operationId: getSimilarArtists
      summary: 7digital Get Similar Artists
      description: List artists similar to the seed artist.
      tags: [Artists]
      parameters:
        - $ref: '#/components/parameters/ArtistId'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A list of similar artists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtistListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /artist/search:
    get:
      operationId: searchArtists
      summary: 7digital Search Artists
      description: Free-text search the 7digital catalogue for artists matching a query.
      tags: [Artists]
      parameters:
        - $ref: '#/components/parameters/Query'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paged list of matching artists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtistListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /artist/topTracks:
    get:
      operationId: getArtistTopTracks
      summary: 7digital Get Artist Top Tracks
      description: List the top-streamed tracks by an artist.
      tags: [Artists]
      parameters:
        - $ref: '#/components/parameters/ArtistId'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A list of top tracks by the artist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /artist/tags:
    get:
      operationId: getArtistTags
      summary: 7digital Get Artist Tags
      description: Get the tags / genre labels applied to an artist.
      tags: [Artists]
      parameters:
        - $ref: '#/components/parameters/ArtistId'
      responses:
        '200':
          description: A list of tags for the artist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /artist/match/byId:
    get:
      operationId: matchArtistById
      summary: 7digital Match Artist By Id
      description: Match an artist in a partner system to the 7digital artist using an external identifier (e.g. MusicBrainz id).
      tags: [Artists]
      security:
        - oauth1_two_legged: []
      parameters:
        - name: id
          in: query
          required: true
          description: External artist identifier to match.
          schema:
            type: string
          example: 'mbid:5b11f4ce-a62d-471e-81fc-a69a8278c7da'
      responses:
        '200':
          description: A matched artist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtistDetailsResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /artist/bytag/top:
    get:
      operationId: getTopArtistsByTags
      summary: 7digital Get Top Artists By Tags
      description: List top-performing artists for a given tag or set of tags.
      tags: [Artists]
      parameters:
        - $ref: '#/components/parameters/Tags'
        - $ref: '#/components/parameters/Country'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A list of top artists for the tag(s).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtistListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /track/chart:
    get:
      operationId: getTrackChart
      summary: 7digital Get Track Chart
      description: Get the current track chart for a given period and territory.
      tags: [Tracks]
      parameters:
        - $ref: '#/components/parameters/Country'
        - $ref: '#/components/parameters/Period'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A chart of tracks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /track/details:
    get:
      operationId: getTrackDetails
      summary: 7digital Get Track Details
      description: Get all available metadata for a track by 7digital track id.
      tags: [Tracks]
      parameters:
        - $ref: '#/components/parameters/TrackId'
        - $ref: '#/components/parameters/Country'
      responses:
        '200':
          description: Track metadata payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackDetailsResponse'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /track/search:
    get:
      operationId: searchTracks
      summary: 7digital Search Tracks
      description: Free-text search the 7digital catalogue for tracks matching a query.
      tags: [Tracks]
      parameters:
        - $ref: '#/components/parameters/Query'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paged list of matching tracks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /track/match/byId:
    get:
      operationId: matchTrackById
      summary: 7digital Match Track By Id
      description: Match a track in a partner system to the 7digital track using an external identifier (e.g. ISRC).
      tags: [Tracks]
      security:
        - oauth1_two_legged: []
      parameters:
        - name: id
          in: query
          required: true
          description: External track identifier to match (e.g. ISRC).
          schema:
            type: string
          example: 'isrc:USRC17607839'
      responses:
        '200':
          description: A matched track.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackDetailsResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /tag:
    get:
      operationId: getAllTags
      summary: 7digital Get All Tags
      description: List all tags in the 7digital tag vocabulary.
      tags: [Tags]
      responses:
        '200':
          description: A list of all tags.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /basket:
    get:
      operationId: getBasket
      summary: 7digital Get Basket
      description: Get the current contents of a basket.
      tags: [Basket]
      parameters:
        - $ref: '#/components/parameters/BasketId'
      responses:
        '200':
          description: The basket contents.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Basket'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /basket/create:
    get:
      operationId: createBasket
      summary: 7digital Create Basket
      description: Create a new basket for a session or user.
      tags: [Basket]
      responses:
        '200':
          description: The newly created basket.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Basket'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /basket/addItem:
    get:
      operationId: addBasketItem
      summary: 7digital Add Basket Item
      description: Add a track or release to a basket.
      tags: [Basket]
      parameters:
        - $ref: '#/components/parameters/BasketId'
        - name: releaseId
          in: query
          description: Release id to add.
          schema:
            type: string
          example: '11700062'
        - name: trackId
          in: query
          description: Track id to add.
          schema:
            type: string
          example: '123456'
      responses:
        '200':
          description: The updated basket.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Basket'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /basket/removeItem:
    get:
      operationId: removeBasketItem
      summary: 7digital Remove Basket Item
      description: Remove a track or release from a basket.
      tags: [Basket]
      parameters:
        - $ref: '#/components/parameters/BasketId'
        - name: itemId
          in: query
          required: true
          description: Basket item id to remove.
          schema:
            type: string
          example: 'item-789012'
      responses:
        '200':
          description: The updated basket.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Basket'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /basket/applyVoucher:
    post:
      operationId: applyBasketVoucher
      summary: 7digital Apply Basket Voucher
      description: Apply a discount voucher to a basket.
      tags: [Basket]
      security:
        - oauth1_two_legged: []
      parameters:
        - $ref: '#/components/parameters/BasketId'
      requestBody:
        required: true
        description: Voucher application payload.
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                voucherCode:
                  type: string
                  description: Voucher code to apply.
                  example: 'SUMMER25'
              required: [voucherCode]
      responses:
        '200':
          description: The basket with voucher applied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Basket'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /basket/addpriceditem:
    get:
      operationId: addPricedBasketItem
      summary: 7digital Add Priced Basket Item
      description: Add an item with a specific price to a basket (partner pricing flow).
      tags: [Basket]
      security:
        - oauth1_two_legged: []
      parameters:
        - $ref: '#/components/parameters/BasketId'
        - name: releaseId
          in: query
          description: Release id to add.
          schema:
            type: string
          example: '11700062'
        - name: price
          in: query
          required: true
          description: Price to apply to the item (in minor units).
          schema:
            type: number
          example: 999
      responses:
        '200':
          description: The updated basket.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Basket'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /basket/paypalurl:
    get:
      operationId: getBasketPayPalUrl
      summary: 7digital Get Basket PayPal Url
      description: Generate a PayPal checkout URL for a basket.
      tags: [Basket]
      parameters:
        - $ref: '#/components/parameters/BasketId'
      responses:
        '200':
          description: A PayPal checkout URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  paypalUrl:
                    type: string
                    format: uri
                    description: The PayPal checkout URL.
                    example: 'https://www.paypal.com/checkoutnow?token=EC-1234'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /basket/completepaypalpurchase:
    post:
      operationId: completeBasketPayPalPurchase
      summary: 7digital Complete Basket PayPal Purchase
      description: Complete a PayPal purchase after the user has authorised payment.
      tags: [Basket]
      security:
        - oauth1_three_legged: []
      parameters:
        - $ref: '#/components/parameters/BasketId'
      requestBody:
        required: true
        description: PayPal purchase completion payload.
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                payerId:
                  type: string
                  description: PayPal payer id.
                  example: 'AB12CD34EF'
                token:
                  type: string
                  description: PayPal token returned to the callback URL.
                  example: 'EC-1234'
              required: [payerId, token]
      responses:
        '200':
          description: The completed purchase.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Purchase'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /user/unlimitedStreaming:
    get:
      operationId: getUserUnlimitedStreaming
      summary: 7digital Get User Unlimited Streaming
      description: Get the status of the unlimited streaming subscription for the authenticated user.
      tags: [User]
      security:
        - oauth1_three_legged: []
      responses:
        '200':
          description: Unlimited streaming subscription details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionStatus'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: updateUserUnlimitedStreaming
      summary: 7digital Update User Unlimited Streaming
      description: Create or update the unlimited streaming subscription for a user (partner-scoped).
      tags: [User]
      security:
        - oauth1_two_legged: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                userId:
                  type: string
                  description: The user id whose subscription is being updated.
                  example: '500123'
                status:
                  type: string
                  description: New subscription status.
                  enum: [active, cancelled, expired]
                  example: active
              required: [userId, status]
      responses:
        '200':
          description: The updated subscription status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionStatus'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /user/locker:
    get:
      operationId: getUserLocker
      summary: 7digital Get User Locker
      description: Get the locker (all purchased tracks and releases) for the authenticated user.
      tags: [User]
      security:
        - oauth1_three_legged: []
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: The user's locker contents.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Locker'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /user/purchase/item:
    get:
      operationId: purchaseUserItem
      summary: 7digital Purchase User Item
      description: Purchase a single track or release for the authenticated user using their default payment method.
      tags: [User]
      security:
        - oauth1_three_legged: []
      parameters:
        - name: releaseId
          in: query
          description: Release id to purchase.
          schema:
            type: string
          example: '11700062'
        - name: trackId
          in: query
          description: Track id to purchase.
          schema:
            type: string
          example: '123456'
      responses:
        '200':
          description: The completed purchase.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Purchase'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /user/purchase/rrpitem:
    get:
      operationId: purchaseUserRrpItem
      summary: 7digital Purchase User Rrp Item
      description: Purchase an item at RRP for the authenticated user.
      tags: [User]
      security:
        - oauth1_three_legged: []
      parameters:
        - name: releaseId
          in: query
          description: Release id to purchase.
          schema:
            type: string
          example: '11700062'
      responses:
        '200':
          description: The completed purchase.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Purchase'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /user/purchase/basket:
    get:
      operationId: purchaseUserBasket
      summary: 7digital Purchase User Basket
      description: Purchase the entire contents of the user's basket.
      tags: [User]
      security:
        - oauth1_three_legged: []
      parameters:
        - $ref: '#/components/parameters/BasketId'
      responses:
        '200':
          description: The completed purchase.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Purchase'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /user/purchase/priceditem:
    get:
      operationId: purchaseUserPricedItem
      summary: 7digital Purchase User Priced Item
      description: Purchase an item at a partner-supplied price.
      tags: [User]
      security:
        - oauth1_three_legged: []
      parameters:
        - name: releaseId
          in: query
          description: Release id to purchase.
          schema:
            type: string
          example: '11700062'
        - name: price
          in: query
          required: true
          description: Partner-supplied price (in minor units).
          schema:
            type: number
          example: 999
      responses:
        '200':
          description: The completed purchase.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Purchase'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /user/payment/card:
    get:
      operationId: listUserPaymentCards
      summary: 7digital List User Payment Cards
      description: List the payment cards registered to the authenticated user.
      tags: [User]
      security:
        - oauth1_three_legged: []
      responses:
        '200':
          description: A list of payment cards.
          content:
            application/json:
              schema:
                type: object
                properties:
                  cards:
                    type: array
                    items:
                      $ref: '#/components/schemas/PaymentCard'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /user/payment/card/select:
    post:
      operationId: selectUserPaymentCard
      summary: 7digital Select User Payment Card
      description: Set a registered payment card as the user's default card.
      tags: [User]
      security:
        - oauth1_three_legged: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                cardId:
                  type: string
                  description: The card id to mark as default.
                  example: 'card-789012'
              required: [cardId]
      responses:
        '200':
          description: Card selected.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /user/payment/card/delete:
    post:
      operationId: deleteUserPaymentCard
      summary: 7digital Delete User Payment Card
      description: Delete a payment card from the authenticated user.
      tags: [User]
      security:
        - oauth1_three_legged: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                cardId:
                  type: string
                  description: The card id to delete.
                  example: 'card-789012'
              required: [cardId]
      responses:
        '200':
          description: Card deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /user/payment/cardregistration:
    post:
      operationId: registerUserPaymentCard
      summary: 7digital Register User Payment Card
      description: Start the registration flow for a new payment card.
      tags: [User]
      security:
        - oauth1_three_legged: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CardRegistrationRequest'
      responses:
        '200':
          description: A card registration handle.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardRegistration'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /user/payment/cardregistration/{id}:
    get:
      operationId: getUserCardRegistration
      summary: 7digital Get User Card Registration
      description: Poll the status of a pending card registration.
      tags: [User]
      security:
        - oauth1_three_legged: []
      parameters:
        - name: id
          in: path
          required: true
          description: Card registration id.
          schema:
            type: string
          example: 'cardreg-789012'
      responses:
        '200':
          description: The card registration record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardRegistration'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /user/deliveritem:
    get:
      operationId: deliverUserItem
      summary: 7digital Deliver User Item
      description: Get a delivery URL for a purchased item (download or stream link).
      tags: [User]
      security:
        - oauth1_three_legged: []
      parameters:
        - name: releaseId
          in: query
          description: Purchased release to deliver.
          schema:
            type: string
          example: '11700062'
        - name: trackId
          in: query
          description: Purchased track to deliver.
          schema:
            type: string
          example: '123456'
      responses:
        '200':
          description: A delivery URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  deliveryUrl:
                    type: string
                    format: uri
                    description: The signed delivery URL.
                    example: 'https://download.7digital.com/abc123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /user/signup:
    post:
      operationId: signupUser
      summary: 7digital Signup User
      description: Sign up a new user with a 7digital account.
      tags: [User]
      security:
        - oauth1_two_legged: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UserSignupRequest'
      responses:
        '200':
          description: The newly created user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /user/create:
    get:
      operationId: createUser
      summary: 7digital Create User
      description: Create a new user partner-side (typically as part of an integrated signup flow).
      tags: [User]
      security:
        - oauth1_two_legged: []
      parameters:
        - name: email
          in: query
          required: true
          description: Email address of the new user.
          schema:
            type: string
            format: email
          example: 'jane.smith@example.com'
      responses:
        '200':
          description: The newly created user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /user/details:
    get:
      operationId: getUserDetails
      summary: 7digital Get User Details
      description: Get the profile of a user (partner-scoped lookup).
      tags: [User]
      security:
        - oauth1_two_legged: []
      parameters:
        - name: userId
          in: query
          required: true
          description: The user id to look up.
          schema:
            type: string
          example: '500123'
      responses:
        '200':
          description: The user profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /user/authenticate:
    post:
      operationId: authenticateUser
      summary: 7digital Authenticate User
      description: Authenticate a user by email and password and return a partner-scoped access token.
      tags: [User]
      security:
        - oauth1_two_legged: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  description: User email.
                  example: 'jane.smith@example.com'
                password:
                  type: string
                  format: password
                  description: User password.
                  example: 'P@ssw0rd123!'
              required: [email, password]
      responses:
        '200':
          description: An authenticated user payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users:
    get:
      operationId: findUsers
      summary: 7digital Find Users
      description: Find users in the partner's user directory.
      tags: [Users]
      security:
        - oauth1_two_legged: []
      parameters:
        - name: email
          in: query
          description: Filter by user email.
          schema:
            type: string
            format: email
          example: 'jane.smith@example.com'
      responses:
        '200':
          description: A list of matching users.
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users/{id}/update:
    put:
      operationId: updateUser
      summary: 7digital Update User
      description: Update a user's profile.
      tags: [Users]
      security:
        - oauth1_three_legged: []
      parameters:
        - name: id
          in: path
          required: true
          description: The user id to update.
          schema:
            type: string
          example: '500123'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UserUpdateRequest'
      responses:
        '200':
          description: The updated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /countries:
    get:
      operationId: getCountries
      summary: 7digital Get Countries
      description: List the supported sales territories with ISO country codes.
      tags: [Territories]
      responses:
        '200':
          description: A list of supported countries.
          content:
            application/json:
              schema:
                type: object
                properties:
                  countries:
                    type: array
                    items:
                      $ref: '#/components/schemas/Country'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /translations:
    get:
      operationId: getTranslations
      summary: 7digital Get Translations
      description: Get localised translation bundles for catalogue strings.
      tags: [Translations]
      parameters:
        - name: locale
          in: query
          required: true
          description: Locale identifier (BCP 47).
          schema:
            type: string
          example: 'en-GB'
      responses:
        '200':
          description: A translation bundle.
          content:
            application/json:
              schema:
                type: object
                properties:
                  locale:
                    type: string
                    description: The locale of the bundle.
                    example: 'en-GB'
                  translations:
                    type: object
                    additionalProperties:
                      type: string
                    description: Key-value translation pairs.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /country/resolve:
    get:
      operationId: resolveCountryForIp
      summary: 7digital Resolve Country For Ip
      description: Resolve the country for an end-user's IP address (for geo-restriction checks).
      tags: [IpLookup]
      parameters:
        - name: ip
          in: query
          required: true
          description: IPv4 or IPv6 address to look up.
          schema:
            type: string
          example: '10.0.0.1'
      responses:
        '200':
          description: A country resolution.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Country'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /editorial/list:
    get:
      operationId: getEditorialList
      summary: 7digital Get Editorial List
      description: List 7digital editorial features, banners and curated slots for a territory.
      tags: [Editorial]
      parameters:
        - $ref: '#/components/parameters/Country'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A list of editorial items.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EditorialListResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /catalogue/artist-byurl:
    get:
      operationId: getArtistIdByUrl
      summary: 7digital Get Artist Id By Url
      description: Resolve a 7digital artist id from a 7digital web URL.
      tags: [Catalogue]
      parameters:
        - name: url
          in: query
          required: true
          description: A 7digital artist web URL.
          schema:
            type: string
            format: uri
          example: 'https://uk.7digital.com/artist/the-beatles'
      responses:
        '200':
          description: The resolved artist id.
          content:
            application/json:
              schema:
                type: object
                properties:
                  artistId:
                    type: string
                    description: The 7digital artist id.
                    example: '12345'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /catalogue/release-byurl:
    get:
      operationId: getReleaseIdByUrl
      summary: 7digital Get Release Id By Url
      description: Resolve a 7digital release id from a 7digital web URL.
      tags: [Catalogue]
      parameters:
        - name: url
          in: query
          required: true
          description: A 7digital release web URL.
          schema:
            type: string
            format: uri
          example: 'https://uk.7digital.com/artist/the-beatles/release/abbey-road-11700062'
      responses:
        '200':
          description: The resolved release id.
          content:
            application/json:
              schema:
                type: object
                properties:
                  releaseId:
                    type: string
                    description: The 7digital release id.
                    example: '11700062'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /payment/card/type:
    get:
      operationId: getPaymentCardTypes
      summary: 7digital Get Payment Card Types
      description: List the payment card types supported by 7digital.
      tags: [Payment]
      responses:
        '200':
          description: A list of card types.
          content:
            application/json:
              schema:
                type: object
                properties:
                  cardTypes:
                    type: array
                    items:
                      type: string
                      example: 'visa'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /payment/voucher/details:
    get:
      operationId: getPaymentVoucherDetails
      summary: 7digital Get Payment Voucher Details
      description: Look up details for a voucher code (validity, value, redemption status).
      tags: [Payment]
      security:
        - oauth1_two_legged: []
      parameters:
        - name: voucherCode
          in: query
          required: true
          description: Voucher code to look up.
          schema:
            type: string
          example: 'SUMMER25'
      responses:
        '200':
          description: Voucher details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Voucher'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    Country:
      name: country
      in: query
      description: ISO 3166-1 alpha-2 country code for the sales territory.
      schema:
        type: string
        minLength: 2
        maxLength: 2
      example: 'GB'
    Page:
      name: page
      in: query
      description: 1-based page number for paged endpoints.
      schema:
        type: integer
        minimum: 1
        default: 1
      example: 1
    PageSize:
      name: pageSize
      in: query
      description: Number of items per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
      example: 20
    Period:
      name: period
      in: query
      description: Chart period — typically `day`, `week`, `month`, `year`.
      schema:
        type: string
        enum: [day, week, month, year]
      example: 'week'
    Query:
      name: q
      in: query
      required: true
      description: Free-text search query.
      schema:
        type: string
      example: 'beatles'
    Tags:
      name: tags
      in: query
      required: true
      description: One or more tag identifiers, comma-separated.
      schema:
        type: string
      example: 'rock,indie'
    ReleaseId:
      name: releaseId
      in: query
      required: true
      description: 7digital release id.
      schema:
        type: string
      example: '11700062'
    ArtistId:
      name: artistId
      in: query
      required: true
      description: 7digital artist id.
      schema:
        type: string
      example: '12345'
    TrackId:
      name: trackId
      in: query
      required: true
      description: 7digital track id.
      schema:
        type: string
      example: '123456'
    BasketId:
      name: basketId
      in: query
      required: true
      description: 7digital basket id.
      schema:
        type: string
        format: uuid
      example: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
    ReleaseType:
      name: type
      in: query
      description: Release type filter.
      schema:
        type: string
        enum: [album, single, ep, compilation]
      example: 'album'
  securitySchemes:
    oauth1:
      type: apiKey
      in: query
      name: oauth_consumer_key
      description: >-
        7digital uses OAuth 1.0 signing. Every request MUST include
        `oauth_consumer_key` as either a query parameter or in the Authorization
        header. Sensitive operations require a 2-legged or 3-legged signature
        with a user access token.
    oauth1_two_legged:
      type: apiKey
      in: query
      name: oauth_consumer_key
      description: 2-legged OAuth 1.0 (partner-scoped — consumer key + secret only).
    oauth1_three_legged:
      type: apiKey
      in: query
      name: oauth_consumer_key
      description: 3-legged OAuth 1.0 (consumer key + secret plus a user access token + secret).
  responses:
    AuthError:
      description: Authentication failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ValidationError:
      description: Request validation failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFoundError:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ErrorResponse:
      type: object
      description: Standard 7digital error envelope.
      properties:
        status:
          type: string
          description: Always `error` on a failure.
          example: 'error'
        error:
          type: object
          properties:
            code:
              type: integer
              description: 7digital error code (1xxx input, 2xxx resource, 3xxx user, 7xxx app, 9xxx server).
              example: 2001
            message:
              type: string
              description: Human-readable error message.
              example: 'Resource not found'
            errors:
              type: array
              description: Per-item errors for batch requests (code 1008).
              items:
                type: object
                properties:
                  code:
                    type: integer
                  message:
                    type: string
                  index:
                    type: integer
    Artist:
      type: object
      description: A 7digital artist.
      properties:
        id:
          type: string
          description: 7digital artist id.
          example: '12345'
        name:
          type: string
          description: Artist name.
          example: 'The Beatles'
        url:
          type: string
          format: uri
          description: Artist page URL on 7digital.
          example: 'https://uk.7digital.com/artist/the-beatles'
        image:
          type: string
          format: uri
          description: Artist image URL.
          example: 'https://artwork-cdn.7static.com/static/img/artistimages/00/000/012/0000001234_350.jpg'
        sortName:
          type: string
          description: Sort form of the artist name.
          example: 'Beatles, The'
        appearsAs:
          type: string
          description: Alternative spellings under which the artist appears.
          example: 'Beatles, The'
    ArtistDetailsResponse:
      type: object
      properties:
        status:
          type: string
          example: 'ok'
        artist:
          $ref: '#/components/schemas/Artist'
    ArtistListResponse:
      type: object
      properties:
        status:
          type: string
          example: 'ok'
        page:
          type: integer
          example: 1
        pageSize:
          type: integer
          example: 20
        totalItems:
          type: integer
          example: 42
        artists:
          type: array
          items:
            $ref: '#/components/schemas/Artist'
    Release:
      type: object
      description: A 7digital release (album, single, EP, compilation).
      properties:
        id:
          type: string
          description: 7digital release id.
          example: '11700062'
        title:
          type: string
          description: Release title.
          example: 'Abbey Road'
        version:
          type: string
          description: Release version (e.g. `Remastered`).
          example: 'Remastered'
        type:
          type: string
          enum: [album, single, ep, compilation]
          example: 'album'
        artist:
          $ref: '#/components/schemas/Artist'
        url:
          type: string
          format: uri
          example: 'https://uk.7digital.com/artist/the-beatles/release/abbey-road-11700062'
        image:
          type: string
          format: uri
          example: 'https://artwork-cdn.7static.com/static/img/sleeveart/00/117/000/0011700062_350.jpg'
        releaseDate:
          type: string
          format: date
          example: '1969-09-26'
        label:
          type: string
          example: 'Apple Records'
        explicit:
          type: boolean
          example: false
        upc:
          type: string
          description: Universal Product Code (UPC/EAN).
          example: '00602445912025'
        price:
          $ref: '#/components/schemas/Price'
    ReleaseDetailsResponse:
      type: object
      properties:
        status:
          type: string
          example: 'ok'
        release:
          $ref: '#/components/schemas/Release'
    ReleaseListResponse:
      type: object
      properties:
        status:
          type: string
          example: 'ok'
        page:
          type: integer
          example: 1
        pageSize:
          type: integer
          example: 20
        totalItems:
          type: integer
          example: 42
        releases:
          type: array
          items:
            $ref: '#/components/schemas/Release'
    Track:
      type: object
      description: A 7digital track.
      properties:
        id:
          type: string
          description: 7digital track id.
          example: '123456'
        title:
          type: string
          description: Track title.
          example: 'Come Together'
        version:
          type: string
          description: Track version (e.g. `Remastered 2019`).
          example: 'Remastered 2019'
        artist:
          $ref: '#/components/schemas/Artist'
        release:
          $ref: '#/components/schemas/Release'
        trackNumber:
          type: integer
          description: Track number on the release.
          example: 1
        duration:
          type: integer
          description: Duration in seconds.
          example: 259
        explicit:
          type: boolean
          example: false
        isrc:
          type: string
          description: International Standard Recording Code.
          example: 'GBAYE6900477'
        previewUrl:
          type: string
          format: uri
          description: URL for the 30-second preview clip.
          example: 'https://previews.7digital.com/clip/123456'
        price:
          $ref: '#/components/schemas/Price'
    TrackDetailsResponse:
      type: object
      properties:
        status:
          type: string
          example: 'ok'
        track:
          $ref: '#/components/schemas/Track'
    TrackListResponse:
      type: object
      properties:
        status:
          type: string
          example: 'ok'
        page:
          type: integer
          example: 1
        pageSize:
          type: integer
          example: 20
        totalItems:
          type: integer
          example: 13
        tracks:
          type: array
          items:
            $ref: '#/components/schemas/Track'
    Tag:
      type: object
      description: A genre/tag label.
      properties:
        id:
          type: string
          example: 'rock'
        name:
          type: string
          example: 'Rock'
        parentId:
          type: string
          nullable: true
          example: null
    TagListResponse:
      type: object
      properties:
        status:
          type: string
          example: 'ok'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
    Price:
      type: object
      description: A price quoted in the requested territory's currency.
      properties:
        formattedPrice:
          type: string
          example: '£9.99'
        amount:
          type: number
          description: Numeric price value.
          example: 9.99
        currency:
          type: string
          description: ISO 4217 currency code.
          example: 'GBP'
    Basket:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
        items:
          type: array
          items:
            $ref: '#/components/schemas/BasketItem'
        total:
          $ref: '#/components/schemas/Price'
        voucherCode:
          type: string
          nullable: true
          example: 'SUMMER25'
    BasketItem:
      type: object
      properties:
        itemId:
          type: string
          example: 'item-789012'
        releaseId:
          type: string
          nullable: true
          example: '11700062'
        trackId:
          type: string
          nullable: true
          example: '123456'
        price:
          $ref: '#/components/schemas/Price'
    Purchase:
      type: object
      properties:
        purchaseId:
          type: string
          example: 'purchase-789012'
        status:
          type: string
          enum: [completed, pending, failed]
          example: 'completed'
        total:
          $ref: '#/components/schemas/Price'
        items:
          type: array
          items:
            $ref: '#/components/schemas/BasketItem'
        receiptUrl:
          type: string
          format: uri
          example: 'https://www.7digital.com/receipts/purchase-789012'
    SubscriptionStatus:
      type: object
      properties:
        userId:
          type: string
          example: '500123'
        status:
          type: string
          enum: [active, cancelled, expired]
          example: 'active'
        startDate:
          type: string
          format: date
          example: '2026-01-01'
        endDate:
          type: string
          format: date
          example: '2026-02-01'
        productId:
          type: string
          example: 'unlimited-streaming'
    Locker:
      type: object
      description: A user's locker of purchased tracks and releases.
      properties:
        status:
          type: string
          example: 'ok'
        page:
          type: integer
          example: 1
        pageSize:
          type: integer
          example: 20
        totalItems:
          type: integer
          example: 42
        releases:
          type: array
          items:
            $ref: '#/components/schemas/Release'
        tracks:
          type: array
          items:
            $ref: '#/components/schemas/Track'
    PaymentCard:
      type: object
      properties:
        cardId:
          type: string
          example: 'card-789012'
        last4:
          type: string
          example: '4242'
        brand:
          type: string
          enum: [visa, mastercard, amex, discover]
          example: 'visa'
        expiryMonth:
          type: integer
          example: 12
        expiryYear:
          type: integer
          example: 2028
        isDefault:
          type: boolean
          example: true
    CardRegistrationRequest:
      type: object
      properties:
        cardNumber:
          type: string
          example: '4242424242424242'
        expiryMonth:
          type: integer
          example: 12
        expiryYear:
          type: integer
          example: 2028
        cvv:
          type: string
          example: '123'
        cardholderName:
          type: string
          example: 'Jane Smith'
      required: [cardNumber, expiryMonth, expiryYear, cvv]
    CardRegistration:
      type: object
      properties:
        registrationId:
          type: string
          example: 'cardreg-789012'
        status:
          type: string
          enum: [pending, registered, failed]
          example: 'registered'
        cardId:
          type: string
          nullable: true
          example: 'card-789012'
    User:
      type: object
      properties:
        id:
          type: string
          example: '500123'
        email:
          type: string
          format: email
          example: 'jane.smith@example.com'
        firstName:
          type: string
          example: 'Jane'
        lastName:
          type: string
          example: 'Smith'
        country:
          type: string
          example: 'GB'
        accessToken:
          type: string
          description: Partner-scoped user access token (returned on signup / authenticate).
          example: 'tok-a1b2c3d4'
        accessTokenSecret:
          type: string
          description: Partner-scoped user access token secret.
          example: 'sec-a1b2c3d4'
    UserSignupRequest:
      type: object
      properties:
        email:
          type: string
          format: email
          example: 'jane.smith@example.com'
        password:
          type: string
          format: password
          example: 'P@ssw0rd123!'
        firstName:
          type: string
          example: 'Jane'
        lastName:
          type: string
          example: 'Smith'
        country:
          type: string
          example: 'GB'
      required: [email, password, country]
    UserUpdateRequest:
      type: object
      properties:
        email:
          type: string
          format: email
          example: 'jane.smith@example.com'
        firstName:
          type: string
          example: 'Jane'
        lastName:
          type: string
          example: 'Smith'
        country:
          type: string
          example: 'GB'
    Country:
      type: object
      properties:
        countryCode:
          type: string
          description: ISO 3166-1 alpha-2 code.
          example: 'GB'
        name:
          type: string
          example: 'United Kingdom'
        currency:
          type: string
          description: ISO 4217 currency code.
          example: 'GBP'
    Voucher:
      type: object
      properties:
        code:
          type: string
          example: 'SUMMER25'
        value:
          $ref: '#/components/schemas/Price'
        type:
          type: string
          enum: [percentage, fixed]
          example: 'percentage'
        expiresAt:
          type: string
          format: date-time
          example: '2026-12-31T23:59:59Z'
        redeemed:
          type: boolean
          example: false
    EditorialItem:
      type: object
      properties:
        id:
          type: string
          example: 'editorial-789012'
        title:
          type: string
          example: 'New Releases This Week'
        description:
          type: string
          example: 'Our pick of the freshest releases this week.'
        type:
          type: string
          enum: [feature, banner, slot]
          example: 'feature'
        url:
          type: string
          format: uri
          example: 'https://uk.7digital.com/editorial/new-releases-this-week'
        image:
          type: string
          format: uri
          example: 'https://artwork-cdn.7static.com/static/img/editorial/789012.jpg'
    EditorialListResponse:
      type: object
      properties:
        status:
          type: string
          example: 'ok'
        editorial:
          type: array
          items:
            $ref: '#/components/schemas/EditorialItem'
    EditorialResponse:
      type: object
      properties:
        status:
          type: string
          example: 'ok'
        editorial:
          $ref: '#/components/schemas/EditorialItem'