openapi: 3.1.0
info:
  title: finperks API
  version: 1.0.0
  description: |
    This is the finperks API for viewing giftcard products, creating orders, and receiving webhook notifications.
    Recommended usage pattern:
      - Retrieve and cache products to display them quickly and prioritize them per customer.
      - Refresh the cached product list periodically (e.g., once a day) to ensure updates are reflected.
      - Integrate webhook support to process product update events in real-time.
      - Use the order creation endpoint to place giftcard orders with selected product and amount.
      - Attempt to invalidate the order if unsure whether the transaction succeeded.
servers:
  - url: https://api.finperks.com/v1
    description: Live API
  - url: https://api-sandbox.finperks.com/v1
    description: Sandbox API
tags:
  - name: Products
    x-displayName: Products
    description: Operations related to product management
  - name: ClientPartners
    x-displayName: Client Partners
    description: Operations related to managing client partners
  - name: Orders
    x-displayName: Orders
    description: Operations related to ordering giftcards for an online use case
  - name: RetailOrders
    x-displayName: Retail Orders
    description: Operations related to orders from physical retail locations (stores)
  - name: Balances
    x-displayName: Balances
    description: Operations related to the balance
  - name: Settlements
    x-displayName: Settlements
    description: Operations related to accessing settlement information
  - name: Stores
    x-displayName: Stores
    description: Operations related to managing physical retail locations (stores)
  - name: Ping
    x-displayName: Ping
    description: Simple health check endpoint
  - name: Webhooks
    x-displayName: Webhooks
    description: Webhook endpoint definitions for receiving updates
paths:
  /balances/{currency}:
    get:
      tags:
        - Balances
      summary: Get balance for specific currency
      description: |
        Retrieve the current balance, limit, and available balance for the specified currency.
      operationId: getBalances
      parameters:
        - name: currency
          in: path
          required: true
          example: EUR
          schema:
            type: string
            pattern: ^[A-Z]{3}$
      responses:
        '200':
          description: Balances
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-error-codes:
        - status: 403
          class: forbidden
          code: currency_not_allowed
          description: The given currency is not allowed for the client
    patch:
      servers:
        - url: https://api-sandbox.finperks.com/v1
          description: Sandbox API
      tags:
        - Balances
      summary: 'Sandbox: Patch balance amount for specific currency'
      description: |
        Update the current balance for the specified currency. Sandbox only.
      operationId: patchBalance
      parameters:
        - name: currency
          in: path
          required: true
          schema:
            type: string
            pattern: ^[A-Z]{3}$
            example: EUR
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BalanceUpdate'
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-error-codes:
        - status: 400
          class: invalid_request
          code: invalid_body_parameters
          description: Invalid body parameters with details in the fields attribute
        - status: 403
          class: forbidden
          code: currency_not_allowed
          description: The given currency is not allowed for the client
  /client_partners:
    post:
      tags:
        - ClientPartners
      summary: Create a new client partner
      description: |
        Create a new client partner to allow ordering products for them.
      operationId: postClientPartner
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientPartnerCreate'
      responses:
        '201':
          description: Client Partner entry created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientPartnerResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-error-codes:
        - status: 400
          class: invalid_request
          code: invalid_body_parameters
          description: Invalid body parameters with details in the fields attribute
    get:
      tags:
        - ClientPartners
      summary: List client partners
      description: |
        Retrieve a list of all client partners created for the client.
      operationId: getClientPartners
      parameters:
        - name: next
          in: query
          description: A cursor for use in pagination to retrieve the next page after the cursor.
          schema:
            type: string
        - name: previous
          in: query
          description: A cursor for use in pagination to retrieve the previous page before the cursor.
          schema:
            type: string
        - name: size
          in: query
          description: Determines the maximum size of the result set to be returned. May be lower if fewer entries are available.
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
      responses:
        '200':
          description: Successful response with the list of client partners
          content:
            application/json:
              schema:
                type: object
                properties:
                  client_partners:
                    type: array
                    items:
                      $ref: '#/components/schemas/ClientPartnerResponse'
                  cursors:
                    type: object
                    properties:
                      next:
                        type:
                          - string
                          - 'null'
                        description: A cursor to retrieve the next page to this page. `next` will be null if there is no further page.
                      previous:
                        type:
                          - string
                          - 'null'
                        description: A cursor to retrieve the previous page to this page. `previous` will be null if there is no page prior to this page.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-error-codes:
        - status: 400
          class: invalid_request
          code: invalid_query_parameters
          description: Invalid query parameters with details in the fields attribute
  /client_partners/{id}:
    get:
      tags:
        - ClientPartners
      summary: Retrieve a client partner by its unique identifier
      description: |
        Retrieve the details of a previously created client partner using its unique identifier.
      operationId: getClientPartnerId
      parameters:
        - in: path
          name: id
          description: The unique identifier of the client partner.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful response with the client partner details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientPartnerResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-error-codes:
        - status: 404
          class: not_found
          code: entity_not_found
          description: Entity not found
    patch:
      tags:
        - ClientPartners
      summary: Update a client partner
      description: |
        Update an existing client partner to keep their information up to date, e.g. when a company is renamed.
      operationId: patchClientPartner
      parameters:
        - in: path
          name: id
          description: The unique identifier of the client partner.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientPartnerUpdate'
      responses:
        '200':
          description: Client partner updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientPartnerResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Client partner not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-error-codes:
        - status: 400
          class: invalid_request
          code: invalid_body_parameters
          description: Invalid body parameters with details in the fields attribute
        - status: 404
          class: not_found
          code: entity_not_found
          description: The client partner with the given ID was not found
  /client_partners/{id}/actions/trigger_event:
    post:
      servers:
        - url: https://api-sandbox.finperks.com/v1
          description: Sandbox API
      tags:
        - ClientPartners
      summary: 'Sandbox: Trigger an event for a specific client partner'
      description: |
        Trigger an event for a specific client partner. Sandbox only.
      operationId: postClientPartnersCodeActionsTriggerEvent
      parameters:
        - in: path
          name: id
          description: The unique identifier of the client partner.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientPartnerTriggerEvent'
      responses:
        '204':
          description: A successful response
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-error-codes:
        - status: 400
          class: invalid_request
          code: invalid_body_parameters
          description: Invalid body parameters with details in the fields attribute
        - status: 400
          class: invalid_state
          code: client_partner_event_invalid
          description: The event cannot be triggered for the client partner in its current state.
        - status: 404
          class: not_found
          code: entity_not_found
          description: Entity not found
  /orders:
    post:
      tags:
        - Orders
      summary: Create a new order entry
      description: |
        Create a new order entry to purchase a giftcard product for a specific customer.

        The order will be processed either synchronously or asynchronously based on the `processing_mode` parameter.

        - `sync`: the request will only return once the order has been fully processed and the delivery information is available.
        - `async`: the request will return as soon as the order has been created and processing will continue in the background.

        The client can then poll the order status to retrieve the delivery information once available or use webhooks to be notified about the order status changes.

        **Note:** The request must include an `Idempotency-Key` header to ensure that duplicate requests are not processed multiple times.
        Retrying with the same key and an identical request body returns the previously created order in its current state instead of creating a duplicate.
        Note that the returned order may still be in the `processing` state even in `sync` mode if the original request is still being processed.
      operationId: postOrder
      parameters:
        - in: header
          name: Idempotency-Key
          required: true
          schema:
            type: string
            maxLength: 40
            pattern: ^[a-zA-Z0-9_\-]+$
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreate'
      responses:
        '201':
          description: Order entry created and processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '202':
          description: Order entry created successfully with asynchronous delivery in the background.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-error-codes:
        - status: 400
          class: invalid_request
          code: invalid_body_parameters
          description: Invalid body parameters with details in the fields attribute
        - status: 400
          class: invalid_state
          code: order_not_allowed_for_product
          description: The given product is disabled for the client
        - status: 409
          class: invalid_state
          code: out_of_stock
          description: The product is currently out of stock and cannot be delivered synchronously. Retry later or place the order with processing_mode set to async.
        - status: 400
          class: idempotency
          code: invalid_idempotency_key_header
          description: The Idempotency-Key header is invalid or missing
        - status: 400
          class: idempotency
          code: reused_idempotency_key
          description: The Idempotency-Key has already been used for a previous request with a different request body
        - status: 403
          class: forbidden
          code: insufficient_available_balance
          description: The client does not have sufficient available balance to place the order
        - status: 403
          class: forbidden
          code: currency_not_allowed
          description: The given currency is not allowed for the client
        - status: 403
          class: forbidden
          code: customer_amount_limit_exceeded
          description: The requested amount exceeds the maximum allowed value for the customer
  /orders/{id}:
    get:
      tags:
        - Orders
      summary: Get an order by its unique identifier
      description: |
        Retrieve detailed information about a specific order using its unique identifier as provided in the order creation response.

        This can be used to poll the order status in case of asynchronous processing or to retrieve the delivery information again later on.
      operationId: getOrderId
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-error-codes:
        - status: 404
          class: not_found
          code: entity_not_found
          description: Entity not found
  /orders/{id}/actions/invalidate:
    post:
      tags:
        - Orders
      summary: Invalidate an order
      description: |
        Invalidate an order due to technical issues or if the client is unsure whether the transaction succeeded.

        Invalidation is only possible once an order reached the completed state.
        While still in processing state, the order might be partially processed and no clean invalidation can be guaranteed.
        Invalidation is only allowed for a limited amount of time and should be executed as soon as possible after the order was created.

        Once an order was invalidated, it cannot be used anymore.
      operationId: postOrderIdActionsInvalidate
      responses:
        '200':
          description: Order details with the updated state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-error-codes:
        - status: 404
          class: not_found
          code: entity_not_found
          description: Entity not found
        - status: 400
          class: invalid_state
          code: order_processing
          description: The order is still processing and cannot be invalidated
        - status: 400
          class: invalid_state
          code: order_invalidated
          description: The order has already been invalidated
        - status: 400
          class: invalid_state
          code: order_failed
          description: The order already failed
        - status: 400
          class: invalid_state
          code: order_invalidation_period_expired
          description: The order invalidation period has expired
        - status: 400
          class: invalid_state
          code: order_invalidation_not_supported
          description: The order cannot be invalidated
  /orders/{id}/actions/refund:
    post:
      servers:
        - url: https://api-sandbox.finperks.com/v1
          description: Sandbox API
      tags:
        - Orders
      summary: 'Sandbox: Refund an order'
      description: |
        Trigger a refund of the order. This endpoint is only available in the sandbox environment and can be used to simulate a refund of an order for testing purposes.

        A refund is only possible once an order reached the completed state.
        In live mode, refunds are triggered by finperks based on specific agreements with finperks and after thorough review of the support case.
        Once an order was refunded, it cannot be used anymore and no code details will be returned anymore.
      operationId: postOrderIdActionsRefund
      responses:
        '200':
          description: Order details with the updated state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-error-codes:
        - status: 404
          class: not_found
          code: entity_not_found
          description: Entity not found
        - status: 400
          class: invalid_state
          code: order_not_completed
          description: The order is not in a completed state and cannot be refunded
  /ping:
    get:
      tags:
        - Ping
      summary: Ping the API
      description: |
        The GET /v1/ping endpoint allows checking if the API is reachable and if the signature calculation is working correctly without otherwise having side effects on orders or products
      operationId: getPing
      responses:
        '200':
          description: API is reachable
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /products:
    get:
      tags:
        - Products
      summary: Get a list of products
      description: |
        Get a list of products available to the client. Products accessible to the client will be returned, including those that are not currently available for sale, so that they can still be referenced if necessary.
      operationId: getProducts
      parameters:
        - name: country
          in: query
          description: Filter products that are available in the specified ISO 3166-1 alpha-2 country code.
          schema:
            type: string
        - name: distribution_scheme
          in: query
          description: Filter products that are available in the specified distribution scheme
          schema:
            type: string
            enum:
              - agency
              - resale
        - name: next
          in: query
          description: A cursor for use in pagination to retrieve the next page after the cursor.
          schema:
            type: string
        - name: previous
          in: query
          description: A cursor for use in pagination to retrieve the previous page before the cursor.
          schema:
            type: string
        - name: size
          in: query
          description: Determines the maximum size of the result set to be returned. May be lower if fewer entries are available.
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
      responses:
        '200':
          description: List of products
          content:
            application/json:
              schema:
                type: object
                properties:
                  products:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProductResponse'
                  cursors:
                    type: object
                    properties:
                      next:
                        type:
                          - string
                          - 'null'
                        description: A cursor to retrieve the next page to this page. `next` will be null if there is no further page.
                      previous:
                        type:
                          - string
                          - 'null'
                        description: A cursor to retrieve the previous page to this page. `previous` will be null if there is no page prior to this page.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-error-codes:
        - status: 400
          class: invalid_request
          code: invalid_query_parameters
          description: Invalid query parameters with details in the fields attribute
  /products/{code}:
    get:
      tags:
        - Products
      summary: Get a product by its unique product code
      description: |
        Retrieve detailed information about a specific product using its unique code as provided in the product list.
      operationId: getProductCode
      parameters:
        - name: code
          in: path
          description: Unique identifier of the product as provided in the product list.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Product details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-error-codes:
        - status: 404
          class: not_found
          code: entity_not_found
          description: Entity not found
  /products/{code}/actions/trigger_event:
    post:
      servers:
        - url: https://api-sandbox.finperks.com/v1
          description: Sandbox API
      tags:
        - Products
      summary: 'Sandbox: Trigger an event for a specific product'
      description: |
        Trigger an event for a specific product. Sandbox only.
      operationId: postProductsCodeActionsTriggerEvent
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
            pattern: ^[a-z0-9_\-]+$
            example: 3724efdc-b1c9-43df-8289-8ca649c9a70a
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductTriggerEvent'
      responses:
        '204':
          description: A successful response
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-error-codes:
        - status: 400
          class: invalid_request
          code: invalid_body_parameters
          description: Invalid body parameters with details in the fields attribute
        - status: 404
          class: not_found
          code: entity_not_found
          description: Entity not found
  /retail_orders:
    post:
      tags:
        - RetailOrders
      summary: Create a new retail order entry
      description: |
        :::note
        This endpoint is a work in progress and may change before being stabilized.
        :::

        Create a new order entry to purchase a giftcard product in a physical retail location.
        This will not actually trigger the purchase and is only responsible for preliminary checks and verification.

        **Note:** The request must include an `Idempotency-Key` header to ensure that duplicate requests are not processed multiple times.
      operationId: postRetailOrder
      parameters:
        - in: header
          name: Idempotency-Key
          required: true
          schema:
            type: string
            maxLength: 40
            pattern: ^[a-zA-Z0-9_\-]+$
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetailOrderCreate'
      responses:
        '201':
          description: Retail Order entry created and processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetailOrderResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-error-codes:
        - status: 400
          class: invalid_request
          code: invalid_body_parameters
          description: Invalid body parameters with details in the fields attribute
        - status: 400
          class: invalid_state
          code: product_not_available
          description: The given product does not exist or is disabled for the client
        - status: 400
          class: idempotency
          code: invalid_idempotency_key_header
          description: The Idempotency-Key header is invalid or missing
        - status: 400
          class: idempotency
          code: reused_idempotency_key
          description: The Idempotency-Key has already been used for a previous request with a different request body
        - status: 403
          class: forbidden
          code: insufficient_available_balance
          description: The client does not have sufficient available balance to place the order
        - status: 403
          class: forbidden
          code: currency_not_allowed
          description: The given currency is not allowed for the client
        - status: 403
          class: forbidden
          code: store_limit_exceeded
          description: The requested amount exceeds the maximum allowed value for the store
        - status: 403
          class: forbidden
          code: terminal_limit_exceeded
          description: The requested amount exceeds the maximum allowed value for the terminal
        - status: 403
          class: forbidden
          code: receipt_limit_exceeded
          description: The requested amount exceeds the maximum allowed value for the receipt
        - status: 403
          class: forbidden
          code: product_limit_exceeded
          description: The requested amount exceeds the maximum allowed value for the product
        - status: 403
          class: forbidden
          code: processing_declined
          description: The order processing was declined
        - status: 403
          class: forbidden
          code: fraudulent_processing_declined
          description: The order processing was declined due to fraudulent behaviour.
  /retail_orders/{id}:
    get:
      tags:
        - RetailOrders
      summary: Retrieve a retail order by its unique identifier
      description: |
        :::note
        This endpoint is a work in progress and may change before being stabilized.
        :::

        Retrieve the details of a previously created retail order using its unique identifier.
      operationId: getRetailOrderId
      parameters:
        - in: path
          name: id
          description: The unique identifier of the retail order.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful response with the retail order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetailOrderResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-error-codes:
        - status: 404
          class: not_found
          code: entity_not_found
          description: Entity not found
  /retail_orders/{id}/actions/invalidate:
    post:
      tags:
        - RetailOrders
      summary: Invalidate a retail order
      description: |
        :::note
        This endpoint is a work in progress and may change before being stabilized.
        :::

        Invalidate a previously created retail order. This action marks the order as invalid and prevents any further processing or fulfillment.

        Use this endpoint when you need to invalidate an order that has not yet been completed or shortly after completion depending on the product to correct for user or technical issues.

        **Note:** Once an order is invalidated, it cannot be reactivated or processed again. A new order needs to be created.
      operationId: postRetailOrderInvalidate
      parameters:
        - in: path
          name: id
          description: The unique identifier of the retail order to be invalidated.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Retail order invalidated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetailOrderResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-error-codes:
        - status: 404
          class: not_found
          code: entity_not_found
          description: Entity not found
        - status: 400
          class: invalid_state
          code: order_processing
          description: The order is still processing and cannot be invalidated
        - status: 400
          class: invalid_state
          code: order_invalidated
          description: The order has already been invalidated
        - status: 400
          class: invalid_state
          code: order_failed
          description: The order already failed
        - status: 400
          class: invalid_state
          code: order_invalidation_period_expired
          description: The order invalidation period has expired
  /retail_orders/{id}/actions/confirm:
    post:
      tags:
        - RetailOrders
      summary: Confirm a retail order
      description: |
        :::note
        This endpoint is a work in progress and may change before being stabilized.
        :::

        Confirm a previously created order. This action finalizes the order and triggers the activation of the associated giftcard product.

        Use this endpoint when the payment has been successfully collected.
        Activating the order may take some time depending on the product and the retail location.
      operationId: postRetailOrderConfirm
      parameters:
        - in: path
          name: id
          description: The unique identifier of the retail order to be confirmed.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetailOrderConfirm'
      responses:
        '200':
          description: Retail order confirmed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetailOrderResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-error-codes:
        - status: 404
          class: not_found
          code: entity_not_found
          description: Entity not found
        - status: 400
          class: invalid_state
          code: order_invalidated
          description: The order has been invalidated and cannot be completed
        - status: 400
          class: invalid_state
          code: order_failed
          description: The order already failed and cannot be completed
        - status: 400
          class: invalid_state
          code: order_already_completed
          description: The order has already been completed
  /settlements:
    get:
      servers:
        - url: https://api.finperks.com/v1
          description: Live API
      tags:
        - Settlements
      summary: Get a list of settlements
      description: |
        Get a list of settlements with the newest settlements returned first.

        **Note:** In live API only, not available in sandbox API.
      operationId: getSettlements
      parameters:
        - name: states
          in: query
          description: |
            Filter settlements by their states. Multiple states can be provided, separated by commas. Possible values are: `pending`, `paid`.
          schema:
            type: string
        - name: next
          in: query
          description: A cursor for use in pagination to retrieve the next page after the cursor.
          schema:
            type: string
        - name: previous
          in: query
          description: A cursor for use in pagination to retrieve the previous page before the cursor.
          schema:
            type: string
        - name: size
          in: query
          description: Determines the maximum size of the result set to be returned. May be lower if fewer entries are available.
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
      responses:
        '200':
          description: List of settlements
          content:
            application/json:
              schema:
                type: object
                properties:
                  settlements:
                    type: array
                    items:
                      $ref: '#/components/schemas/SettlementResponse'
                  cursors:
                    type: object
                    properties:
                      next:
                        type:
                          - string
                          - 'null'
                        description: A cursor to retrieve the next page to this page. `next` will be null if there is no further page.
                      previous:
                        type:
                          - string
                          - 'null'
                        description: A cursor to retrieve the previous page to this page. `previous` will be null if there is no page prior to this page.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-error-codes:
        - status: 400
          class: invalid_request
          code: invalid_query_parameters
          description: Invalid query parameters with details in the fields attribute
  /settlements/{id}:
    get:
      servers:
        - url: https://api.finperks.com/v1
          description: Live API
      tags:
        - Settlements
      summary: Get a settlement by its ID
      description: |
        Get a settlement by its unique identifier.

        **Note:** In live API only, not available in sandbox API.
      operationId: getSettlementById
      parameters:
        - name: id
          in: path
          required: true
          description: The settlement's unique identifier.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Settlement details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-error-codes:
        - status: 404
          class: not_found
          code: entity_not_found
          description: Entity not found
  /settlements/{id}/media/pdf:
    get:
      servers:
        - url: https://api.finperks.com/v1
          description: Live API
      tags:
        - Settlements
      summary: Get a settlement's PDF media
      description: |
        Get the PDF media of a settlement by its unique identifier.

        **Note:** In live API only, not available in sandbox API.
      operationId: getSettlementPdfMedia
      parameters:
        - name: id
          in: path
          required: true
          description: The settlement's unique identifier.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: PDF media of the settlement
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-error-codes:
        - status: 404
          class: not_found
          code: entity_not_found
          description: Entity not found
  /settlements/{id}/media/csv:
    get:
      servers:
        - url: https://api.finperks.com/v1
          description: Live API
      tags:
        - Settlements
      summary: Get a settlement's CSV media
      description: |
        Get the CSV media of a settlement by its unique identifier.

        **Note:** In live API only, not available in sandbox API.
      operationId: getSettlementCsvMedia
      parameters:
        - name: id
          in: path
          required: true
          description: The settlement's unique identifier.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: CSV media of the settlement
          content:
            text/csv:
              schema:
                type: string
                format: binary
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-error-codes:
        - status: 404
          class: not_found
          code: entity_not_found
          description: Entity not found
  /stores:
    post:
      tags:
        - Stores
      summary: Create a new store
      description: |
        :::note
        This endpoint is a work in progress and may change before being stabilized.
        :::

        Create a new store with the provided details.
      operationId: postStore
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreCreate'
      responses:
        '201':
          description: Store created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-error-codes:
        - status: 400
          class: invalid_request
          code: invalid_body_parameters
          description: Invalid body parameters with details in the fields attribute
    get:
      tags:
        - Stores
      summary: List stores
      description: |
        :::note
        This endpoint is a work in progress and may change before being stabilized.
        :::

        Retrieve a list of stores. Supports pagination through `next` and `previous` cursors.
      operationId: getStores
      parameters:
        - name: next
          in: query
          description: A cursor for use in pagination to retrieve the next page after the cursor.
          schema:
            type: string
        - name: previous
          in: query
          description: A cursor for use in pagination to retrieve the previous page before the cursor.
          schema:
            type: string
        - name: size
          in: query
          description: Determines the maximum size of the result set to be returned. May be lower if fewer entries are available.
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
      responses:
        '200':
          description: Stores retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  stores:
                    type: array
                    items:
                      $ref: '#/components/schemas/StoreResponse'
                  cursors:
                    type: object
                    properties:
                      next:
                        type:
                          - string
                          - 'null'
                        description: A cursor to retrieve the next page to this page. `next` will be null if there is no further page.
                      previous:
                        type:
                          - string
                          - 'null'
                        description: A cursor to retrieve the previous page to this page. `previous` will be null if there is no page prior to this page.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-error-codes:
        - status: 400
          class: invalid_request
          code: invalid_query_parameters
          description: Invalid query parameters with details in the fields attribute
  /stores/{id}:
    get:
      tags:
        - Stores
      summary: Retrieve store details
      description: |
        :::note
        This endpoint is a work in progress and may change before being stabilized.
        :::

        Retrieve the details of a store by its ID.
      operationId: getStore
      parameters:
        - name: id
          in: path
          description: Unique identifier of the store as initially provided on creation.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Store details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Store not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-error-codes:
        - status: 400
          class: invalid_request
          code: invalid_path_parameters
          description: Invalid path parameters with details in the fields attribute
        - status: 404
          class: not_found
          code: entity_not_found
          description: The store with the given ID was not found
    patch:
      tags:
        - Stores
      summary: Update store details
      description: |
        :::note
        This endpoint is a work in progress and may change before being stabilized.
        :::

        Update the details of a store by its ID.
      operationId: patchStore
      parameters:
        - name: id
          in: path
          description: Unique identifier of the store as initially provided on creation.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreUpdate'
      responses:
        '200':
          description: Store updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Store not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-error-codes:
        - status: 400
          class: invalid_request
          code: invalid_body_parameters
          description: Invalid body parameters with details in the fields attribute
        - status: 404
          class: not_found
          code: entity_not_found
          description: The store with the given ID was not found
  /path/at/partner/system/order/events:
    post:
      servers:
        - url: https://your-server.com
          description: Partner's server
      tags:
        - Webhooks
      summary: Order Update Event
      description: |
        Webhook endpoint on the partner's system to receive order update events. This endpoint should be implemented by the partner to receive notifications about order state changes.
      operationId: postOrderUpdateWebhook
      parameters:
        - $ref: '#/components/parameters/FpSignatureHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderUpdateWebhook'
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
  /path/at/partner/system/product/events:
    post:
      servers:
        - url: https://your-server.com
          description: Partner's server
      tags:
        - Webhooks
      summary: Product Update Event
      description: |
        Webhook endpoint on the partner's system to receive product update events. This endpoint should be implemented by the partner to receive notifications about product changes.
      operationId: postProductUpdateWebhook
      parameters:
        - $ref: '#/components/parameters/FpSignatureHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductUpdateWebhook'
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
  /path/at/partner/system/settlement/events:
    post:
      servers:
        - url: https://your-server.com
          description: Partner's server
      tags:
        - Webhooks
      summary: Settlement Update Event
      description: |
        Webhook endpoint on the partner's system to receive settlement update events. This endpoint should be implemented by the partner to receive notifications about settlement state changes.
      operationId: postSettlementUpdateWebhook
      parameters:
        - $ref: '#/components/parameters/FpSignatureHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SettlementUpdateWebhook'
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
  /path/at/partner/system/client_partner/events:
    post:
      servers:
        - url: https://your-server.com
          description: Partner's server
      tags:
        - Webhooks
      summary: Client Partner Update Event
      description: |
        Webhook endpoint on the partner's system to receive client partner update events. This endpoint should be implemented by the partner to receive notifications about client partner changes.
      operationId: postClientPartnerUpdateWebhook
      parameters:
        - $ref: '#/components/parameters/FpSignatureHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientPartnerUpdateWebhook'
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
security:
  - Authorization: []
    Date: []
components:
  parameters:
    FpSignatureHeader:
      in: header
      name: Fp-Signature
      required: true
      schema:
        type: string
        description: |
          Header containing the signature for the webhook requests which can be used to verify that the request came from finperks. example: FP1-HMAC-SHA256 KeyId=ID, Signature=Signature
  securitySchemes:
    Authorization:
      type: apiKey
      in: header
      name: Authorization
      description: |
        finperks Signature Version 1. Clients must sign the request and include:
          - `Authorization: FP1-HMAC-SHA256 KeyId=..., Signature=...`
    Date:
      type: apiKey
      in: header
      name: Date
      description: |
        [RFC7231](http://tools.ietf.org/html/rfc7231#section-7.1.1.2) Date Header
  schemas:
    CodeDisplayType:
      type:
        - string
        - 'null'
      description: |
        Describes the type of code that was delivered and how it should be visualized.
        This is primarily relevant for in store usage where a specific format might be expected by the point of sale system.

        New options may be added in the future, depending on the different visualization types chosen by the brand for the product.
        Field will only be returned if the code data is available.

        For some products the code must not be rendered as a barcode. In that case this field is omitted entirely: render the `code` as text only and do not generate a barcode/QR.
      enum:
        - aztec
        - code128
        - code39
        - ean13
        - itf
        - pdf417
        - qr
    ErrorResponse:
      type: object
      properties:
        class:
          type: string
          description: A machine-readable error class, grouping the errors into broad categories
          example: invalid_request
        code:
          type: string
          description: A machine-readable error code
          example: invalid_parameters
        message:
          type: string
          description: A human-readable error message
          example: At least some of the parameters were invalid.
        fields:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: A machine-readable field name
                example: customer.id
              code:
                type: string
                description: A machine-readable detailed code
                example: missing
    BalanceResponse:
      type: object
      properties:
        currency:
          type: string
          description: ISO 4217 code describing the currency
          example: EUR
        balance:
          type: string
          description: Current balance the client has for the given currency
          pattern: ^-?[0-9]+\.[0-9]+$
          example: '1000.00'
        limit:
          type: string
          description: Current limit the client has for the given currency
          pattern: ^-?[0-9]+\.[0-9]+$
          example: '500.00'
        available:
          type: string
          description: |
            Total available balance for executing orders for the given currency.
            It is calculated as `balance + limit`.
            Executing orders that would exceed the available balance will be rejected.
          pattern: ^-?[0-9]+\.[0-9]+$
          example: '1500.00'
    BalanceUpdate:
      type: object
      required:
        - balance
      properties:
        balance:
          type: string
          pattern: ^\d{1,8}(\.\d{1,2})?$
          description: The new balance amount the client has for the given currency.
          example: '100000.50'
    ClientPartnerCreate:
      type: object
      required:
        - legal_entity_name
        - registration
      properties:
        legal_entity_name:
          type: string
          description: Official name of the company partnering with the client.
          pattern: ^[A-Za-z0-9\-\.,&\s]{1,100}$
          example: finperks GmbH
        registration:
          type: object
          required:
            - country
            - identifier
          properties:
            identifier:
              type: string
              description: Company register identifier of the legal entity.
              pattern: ^[A-Za-z0-9\-_]{1,50}$
              example: HRB12345
            country:
              type: string
              description: ISO 3166-1 alpha-2 country code in which the company is located and registered.
              example: DE
              pattern: ^[A-Z]{2}$
    ClientPartnerUpdate:
      type: object
      properties:
        legal_entity_name:
          type: string
          description: Official name of the company partnering with the client.
          pattern: ^[A-Za-z0-9\-\.,&\s]{1,100}$
          example: finperks GmbH
    ClientPartnerResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the client partner.
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        legal_entity_name:
          type: string
          description: Official name of the company partnering with the client.
          pattern: ^[A-Za-z0-9\-\.,&\s]{1,100}$
          example: finperks GmbH
        registration:
          type: object
          properties:
            identifier:
              type: string
              description: Company register identifier of the legal entity.
              pattern: ^[A-Za-z0-9\-_]{1,50}$
              example: HRB12345
            country:
              type: string
              description: ISO 3166-1 alpha-2 country code in which the company is located and registered.
              example: DE
              pattern: ^[A-Z]{2}$
        state:
          type: string
          description: Current state of the client partner.
          enum:
            - pending
            - approved
            - rejected
            - revoked
          example: approved
    ClientPartnerTriggerEvent:
      type: object
      required:
        - event
      properties:
        event:
          type: string
          enum:
            - created
            - updated
            - approved
            - revoked
            - rejected
          description: The event to be applied to the client partner.
          example: created
    ClientPartnerUpdateWebhook:
      type: object
      required:
        - id
        - event_scope
        - event
        - event_at
        - data
      properties:
        id:
          type: string
          description: Unique identifier of the webhook event. Will stay the same across retries
          maxLength: 40
          example: 5e943c75-2065-46cb-a74b-69a13e034333
        event_scope:
          type: string
          description: Scope in which the event is occuring. For client partner events this will always be `client_partners`.
          example: client_partners
        event:
          type: string
          description: A label for the type of event that occurred
          example: updated
        event_at:
          type: date-time
          description: Represents [RFC 3339, section 5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) date-time.
          example: 2025-07-16T18:16:12.000Z
        data:
          $ref: '#/components/schemas/ClientPartnerResponse'
    OrderCreate:
      type: object
      required:
        - product_code
        - customer
        - country
        - face_value
        - processing_mode
        - delivery_method
      properties:
        product_code:
          type: string
          description: Unique code of the product to order from the list available from the product list.
          example: b713c564-9e18-4810-a9bb-7b2d86afc8cd
        customer:
          type: object
          description: |
            Information about the customer for which the order is created.
          required:
            - id
          properties:
            id:
              type: string
              description: Unique identifier of the customer within the client system.
              pattern: ^[A-Za-z0-9_-]+$
              example: 91fa2215-c563-422f-9915-2bd332309a1c
        client_partner:
          type: object
          description: |
            Information about the client partner for which the order is created.

            Required if client partner tracking is enabled for the client.
            Otherwise passing the client partner object is rejected.
          required:
            - id
          properties:
            id:
              type: string
              description: |
                Unique identifier of the client partner as created through the client partners endpoint.

                The field is required if the client is not the direct company interacting with the end customer.

                Required if client partner tracking is enabled for the client.
                Otherwise passing the field is rejected.
              pattern: ^[A-Za-z0-9_-]+$
              example: 128c674a-8a7d-48bb-902c-72ba2351bdc9
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code for which the product should be ordered.
          example: DE
          pattern: ^[A-Z]{2}$
        face_value:
          type: object
          required:
            - currency
            - amount
          properties:
            currency:
              type: string
              enum:
                - EUR
              pattern: ^[A-Z]{3}$
              description: Currency of the product.
              example: EUR
            amount:
              type: string
              description: Face value of the requested product.
              pattern: ^-?[0-9]+\.[0-9]+$
              example: '100.0'
        processing_mode:
          type: string
          description: |
            Determines whether the order should be processed synchronously or asynchronously.

              - `sync`: the request will only return once the order has been fully processed and the delivery information is available.
              - `async`: the request will return as soon as the order has been created and processing will continue in the background.

            The client can then poll the order status to retrieve the delivery information once available or use webhooks to be notified about the order status changes.
          enum:
            - sync
            - async
        delivery_method:
          oneOf:
            - type: object
              title: Code Delivery
              required:
                - type
              properties:
                type:
                  type: string
                  description: Determines the type of delivery method to be used.
                  enum:
                    - code
                  example: code
            - type: object
              title: URL Delivery
              required:
                - type
              properties:
                type:
                  type: string
                  description: Determines the type of delivery method to be used.
                  enum:
                    - url
                  example: url
            - type: object
              title: Email Delivery
              required:
                - type
                - data
              properties:
                type:
                  type: string
                  description: Determines the type of delivery method to be used.
                  enum:
                    - email
                  example: email
                data:
                  type: object
                  required:
                    - email
                  properties:
                    email:
                      type: string
                      description: Target email address for delivering the code.
                      example: joe@example.com
          discriminator:
            propertyName: type
            mapping:
              code: '#/components/schemas/OrderCreate/properties/delivery_method/oneOf/0'
              url: '#/components/schemas/OrderCreate/properties/delivery_method/oneOf/1'
              email: '#/components/schemas/OrderCreate/properties/delivery_method/oneOf/2'
    OrderDeliveryUrl:
      type: object
      properties:
        type:
          type: string
          description: Describes the type of URL provided. The available types depend on the product. It may be extended in the future.
          enum:
            - card_pdf
            - redemption
            - success_page
            - apple_wallet_pass
            - google_wallet_pass
            - success_page_with_challenge_code
            - code_link
          example: card_pdf
        value:
          type: string
          description: URL associated with the given type.
          example: https://cdn.finperks.com/examples/voucher.pdf
        supplementary_info:
          type:
            - object
            - 'null'
          description: Supplementary info specific to the given URL type.
          properties:
            success_page_with_challenge_code:
              type:
                - object
                - 'null'
              description: Supplementary info for the `success_page_with_challenge_code` URL type.
              properties:
                challenge_code:
                  type: string
                  description: Challenge code.
                  example: '123456'
    OrderResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the order which can be used to retrieve the order information.
          format: uuid
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        product:
          type: object
          description: Provides basic information about the product associated with the order.
          properties:
            code:
              type: string
              description: Unique identifier for the product.
              example: b713c564-9e18-4810-a9bb-7b2d86afc8cd
            name:
              type: string
              description: Name of the product.
              example: Brand Gift Card
            description:
              type: string
              description: Description of the product
              example: A gift card that can be used at Brand stores and online.
            seller:
              $ref: '#/components/schemas/ProductSellerResponse'
        customer:
          type: object
          properties:
            id:
              type:
                - string
                - 'null'
              description: |
                Unique identifier of the customer with the client.
                Will be null only for orders that were created without customer id. Orders created with a customer id will always return the value.
              pattern: ^[A-Za-z0-9_-]+$
              example: 91fa2215-c563-422f-9915-2bd332309a1c
        client_partner:
          type: object
          description: |
            Provides information about the client partner associated with the order.
            Only returned if a client partner was set during creation.
          properties:
            id:
              type: string
              description: Unique identifier of the client partner as returned after creation.
              pattern: ^[A-Za-z0-9_-]+$
              example: 4cce7ffa-a975-46f1-8cf0-3a8ace1bb5bf
        state:
          type: string
          description: Describes the current order state.
          example: processing
          enum:
            - processing
            - completed
            - failed
            - invalidated
            - refunded
        face_value:
          type: object
          description: Face value of the requested product.
          properties:
            currency:
              type: string
              description: Currency of the amount value as 3-letter ISO 4217 code.
              example: EUR
            amount:
              type: string
              description: Monetary amount of the given currency.
              pattern: ^-?[0-9]+\.[0-9]+$
              example: '100.0'
        margin_value:
          type: object
          description: Margin value represents the commission or discount applied to the face value. Whether it is a commission or discount depends on the distribution scheme and the contractual agreement with finperks.
          properties:
            currency:
              type: string
              description: Currency of the amount value as 3-letter ISO 4217 code.
              example: EUR
            amount:
              type: string
              description: Monetary amount of the given currency.
              pattern: ^-?[0-9]+\.[0-9]+$
              example: '5.0'
        net_value:
          type: object
          description: Net value represents the face value amount minus the margin value to indicate the actual cost of the order to the client post settlement.
          properties:
            currency:
              type: string
              description: Currency of the amount value as 3-letter ISO 4217 code.
              example: EUR
            amount:
              type: string
              description: Monetary amount of the given currency.
              pattern: ^-?[0-9]+\.[0-9]+$
              example: '95.0'
        distribution_scheme:
          type: string
          description: Describes whether the order sale was a `resale` or an `agency` sale.
          example: agency
          enum:
            - resale
            - agency
        assets:
          $ref: '#/components/schemas/ProductAssetsResponse'
        contents:
          $ref: '#/components/schemas/ProductContentsResponse'
        delivery_method:
          oneOf:
            - type: object
              title: Code Delivery
              properties:
                type:
                  type: string
                  enum:
                    - code
                data:
                  type: object
                  description: |
                    Contains the actual code information delivered to the end user.
                    The data fields `code` and `serial` will be returned for `completed` orders.
                    `type` is returned for completed orders unless the product renders no barcode, in which case it is omitted (render the code as text).
                    `security_code` and `url` will be returned if available.
                  properties:
                    type:
                      $ref: '#/components/schemas/CodeDisplayType'
                    code:
                      type:
                        - string
                        - 'null'
                      description: Textual representation of the code. Will be null if the order is not yet completed.
                      example: ABCD-EFGH-IJKL-MNOP
                    serial:
                      type:
                        - string
                        - 'null'
                      description: Serial number of the code. Useful for interactions with the brand customer support. Will be null or not set if the order is not yet completed.
                      example: '1234567890'
                    security_code:
                      type:
                        - string
                        - 'null'
                      description: Security code/PIN of the code. Will be null or not set if the product does not have a security code or if the order is not yet completed.
                      example: '9876'
                    urls:
                      type:
                        - array
                        - 'null'
                      description: List of URLs associated with the code, e.g. a PDF voucher download link. Will be null or not set if the order is not yet completed.
                      items:
                        $ref: '#/components/schemas/OrderDeliveryUrl'
            - type: object
              title: URL Delivery
              properties:
                type:
                  type: string
                  enum:
                    - url
                data:
                  type: object
                  description: |
                    The data field `urls` will be returned for completed orders.
                    The additional fields will be returned if data for them is available.
                  properties:
                    urls:
                      type:
                        - array
                        - 'null'
                      description: |
                        List of URLs associated with the code, e.g. a PDF voucher download link. Will be null, not set or empty if the order is not completed.
                        Will contain at least one entry otherwise.
                      items:
                        $ref: '#/components/schemas/OrderDeliveryUrl'
                    type:
                      $ref: '#/components/schemas/CodeDisplayType'
                    code:
                      type:
                        - string
                        - 'null'
                      description: |
                        Textual representation of the code. Will be null or not set if the order is not completed or no data is available.
                      example: ABCD-EFGH-IJKL-MNOP
                    serial:
                      type:
                        - string
                        - 'null'
                      description: Serial number of the code. Useful for interactions with the brand customer support. Will be null or not set if the order is not completed or no data is available.
                      example: '1234567890'
                    security_code:
                      type:
                        - string
                        - 'null'
                      description: Security code/PIN of the code. Will be null or not set if the product does not have a security code, the data is not available, or if the order is not completed.
                      example: '9876'
            - type: object
              title: Email Delivery
              properties:
                type:
                  type: string
                  enum:
                    - email
                data:
                  type: object
                  description: Contains the email address used for delivering the order information. Will be null once the email address is no longer needed for processing.
                  properties:
                    email:
                      type:
                        - string
                        - 'null'
                      description: Target email address for delivering the code. Will be null once the email address is no longer needed.
                      example: joe@example.com
          discriminator:
            propertyName: type
            mapping:
              code: '#/components/schemas/OrderResponse/properties/delivery_method/oneOf/0'
              url: '#/components/schemas/OrderResponse/properties/delivery_method/oneOf/1'
              email: '#/components/schemas/OrderResponse/properties/delivery_method/oneOf/2'
    OrderUpdateWebhook:
      type: object
      required:
        - id
        - event_scope
        - event
        - event_at
        - data
      properties:
        id:
          type: string
          description: Unique identifier of the webhook event. Will stay the same across retries
          maxLength: 40
          example: 690b65bc-12da-4ec1-9104-ee3e9df5996b
        event_scope:
          type: string
          description: Scope in which the event is occuring. For order events this will always be `orders`.
          example: orders
        event:
          type: string
          description: A label for the type of event that occurred
          example: completed
          enum:
            - processing
            - completed
            - failed
            - invalidated
            - refunded
        event_at:
          type: date-time
          description: Represents [RFC 3339, section 5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) date-time.
          example: 2025-07-16T18:16:12.000Z
        data:
          $ref: '#/components/schemas/OrderResponse'
    ProductResponse:
      type: object
      properties:
        code:
          type: string
          description: unique identifier for the product
          example: b713c564-9e18-4810-a9bb-7b2d86afc8cd
        name:
          type: string
          description: Name of the product
          example: Brand Gift Card
        description:
          type: string
          description: Description of the product
          example: A gift card that can be used at Brand stores and online.
        currency:
          type: string
          description: ISO 4217 code describing the currency
          example: EUR
        denominations:
          type: object
          description: Describes the options for how the face value/amount may be provided
          properties:
            type:
              type: string
              description: |
                Describes whether only values from the list of values are allowed or any within a specified range.
                With type `variable`, any values within the min_value and max_value range are allowed. Entries in the `fixed_values` list only serve to provide recommendations. With type `fixed`, only the values from within the `fixed_values` list are allowed.
              enum:
                - fixed
                - variable
              example: fixed
            fixed_values:
              type: array
              description: Provides a list of allowed or recommended values for the product. May return an empty list if type is `variable` and no recommended values are available.
              items:
                type: string
                pattern: ^-?[0-9]+\.[0-9]+$
                example: '50.00'
            min_value:
              type:
                - string
                - 'null'
              description: Provides the minimum amount that may be provided for this product. May be null if type is `fixed`.
              pattern: ^-?[0-9]+\.[0-9]+$
              example: '5.00'
            max_value:
              type:
                - string
                - 'null'
              description: Provides the maximum amount that may be provided for this product. May be null if type is `fixed`.
              pattern: ^-?[0-9]+\.[0-9]+$
              example: '50.00'
            increment:
              type:
                - string
                - 'null'
              description: |
                The minimum step size for the face value amount. This defines the precision of valid values for variable denomination products.

                  - `"0.01"` allows every cent (e.g., 10.01, 10.02, 10.99)
                  - `"0.10"` allows only 10-cent increments (e.g., 10.10, 10.20, but not 10.05)
                  - `"1.00"` allows only whole values (e.g., 10.00, 11.00, but not 10.50)

                May be null if type is `fixed`.
              pattern: ^[0-9]+\.[0-9]{2}$
              example: '0.01'
        margin_percentage:
          type: string
          description: |
            Provides the margin percentage that will be applied to the face value for orders of this product.
          pattern: ^[0-9]+\.[0-9]+$
          example: '5.0'
        state:
          type: string
          description: Describes whether a product can be sold or not at a given time.
          enum:
            - available
            - not_available
          example: available
        assets:
          $ref: '#/components/schemas/ProductAssetsResponse'
        contents:
          $ref: '#/components/schemas/ProductContentsResponse'
        delivery_methods:
          type: array
          description: List of supported delivery methods
          items:
            type: string
            enum:
              - code
              - url
              - email
          example:
            - code
            - url
            - email
        available_countries:
          type: array
          description: List of ISO 3166-1 alpha-2 country codes in which the product is available for sale.
          items:
            type: string
          example:
            - DE
        redemption_methods:
          type: array
          description: List of possible ways to redeem the code.
          items:
            type: string
            enum:
              - online
              - in_store
          example:
            - online
            - in_store
        redemption_attributes:
          type: object
          description: |
            A set of structured attributes specifying certain attributes to consider during redemption. The individual attributes can be used to programmatically make UI choices to highlight the relevant cases. They will only be returned for products where relevant.
          properties:
            activation_delay_hours:
              type:
                - integer
                - 'null'
              description: Describes the number of hours it may take between purchasing the giftcard and the giftcard being activated for use by the brand. The attribute will only be returned if it is relevant explicitly for the product.
              example: 24
        distribution_scheme:
          type: string
          description: Describes whether the product is sold in `resale` or `agency` model.
          enum:
            - resale
            - agency
          example: resale
        use_cases:
          type: array
          description: List of possible use cases for the product. Currently `gifting`, `cashback`, `employee_benefit`, `promotion`
          items:
            type: string
          example:
            - gifting
            - employee_benefit
            - cashback
        processing_modes:
          type: array
          description: |
            List of supported processing modes for orders of this product.

              - `sync`: orders can be processed synchronously - the request will only return once the order has been fully processed and the delivery information is available.
              - `async`: orders can be processed asynchronously - the request will return as soon as the order has been created and processing will continue in the background.

            Products support either async-only (`["async"]`) or both modes (`["sync", "async"]`).
          items:
            type: string
            enum:
              - sync
              - async
          example:
            - sync
            - async
        seller:
          $ref: '#/components/schemas/ProductSellerResponse'
    ProductAssetsResponse:
      type: object
      description: Provides a list of assets available for displaying the content
      properties:
        logo_url:
          type: string
          description: A URL for the brand logo associated with the product.
          example: https://cdn.finperks.com/logos/brand.png
        giftcard_logo_url:
          type: string
          description: A URL for the giftcard logo associated with the product.
          example: https://cdn.finperks.com/logos/giftcard.png
    ProductContentsResponse:
      type: object
      description: Provides URLs for content related to the product
      properties:
        markdown:
          type: object
          description: Provides URLs for content in markdown format
          properties:
            redemption_instructions_url:
              type: string
              description: A URL for the redemption instructions for the product in markdown format. The redemption instructions contain information on how to redeem the giftcard.
              example: https://cdn.finperks.com/products/redemption_instructions.md
            terms_and_conditions_url:
              type: string
              description: A URL for the detailed terms and conditions for the product in markdown format.
              example: https://cdn.finperks.com/products/terms_and_conditions.md
            redemption_notes_url:
              type:
                - string
                - 'null'
              description: A URL for the redemption notes for the product in markdown format. The redemption notes contain additional information, such as restrictions, which can be displayed separate from the redemption instructions. The field is optional and will not be returned if no separate information is set.
              example: https://cdn.finperks.com/products/redemption_notes.md
    ProductSellerResponse:
      type: object
      description: |
        Identifies the seller of a product distributed under the `agency` distribution scheme. The seller is the legal entity from which the end user acquires the product. This object is only returned when the seller is a legally distinct entity from the issuing brand. If seller and brand are the same entity, the seller object is omitted and the brand object applies as the seller. This field is never returned for products distributed under the `resale` distribution scheme.
      properties:
        name:
          type: string
          description: Name of the seller.
          example: Best Seller Inc.
        street_and_number:
          type: string
          description: Street and number of the seller's address.
          example: Uhlandstr. 32
        zipcode:
          type: string
          description: Zipcode of the seller's address.
          example: '10719'
        city:
          type: string
          description: City of the seller's address.
          example: Berlin
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code of the seller's address.
          example: DE
    ProductTriggerEvent:
      type: object
      required:
        - event
      properties:
        event:
          type: string
          enum:
            - created
            - updated
          description: The event to be applied to the product.
          example: created
    ProductUpdateWebhook:
      type: object
      required:
        - id
        - event_scope
        - event
        - event_at
        - data
      properties:
        id:
          type: string
          description: Unique identifier of the webhook event. Will stay the same across retries
          maxLength: 40
          example: 5e943c75-2065-46cb-a74b-69a13e034333
        event_scope:
          type: string
          description: Scope in which the event is occuring. For product events this will always be `products`.
          example: products
        event:
          type: string
          description: A label for the type of event that occurred
          example: updated
          enum:
            - created
            - updated
        event_at:
          type: date-time
          description: Represents [RFC 3339, section 5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) date-time.
          example: 2025-07-16T18:16:12.000Z
        data:
          $ref: '#/components/schemas/ProductResponse'
    RetailOrderCreate:
      type: object
      required:
        - product_code
        - store_id
        - terminal_id
        - receipt_id
        - country
        - face_value
        - receipt_printing
      properties:
        product_code:
          type: string
          description: Unique code of the product to order from the list available from the product list.
          pattern: ^[A-Za-z0-9]{4,255}$
          example: 4001232232332
        serial:
          type: string
          description: An optional serial number for the order, if applicable.
          pattern: ^[a-zA-Z0-9\.\-]{1,100}$
          example: 12312312
        store_id:
          type: string
          description: The identifier of the retail store where the order is being made.
          pattern: ^[0-9a-zA-Z\-_]{1,8}$
          example: A1234
        terminal_id:
          type: string
          description: The identifier of the terminal used for the order.
          pattern: ^[A-Za-z0-9\-_]{1,8}$
          example: T01
        receipt_id:
          type: string
          description: The identifier of the receipt for the order.
          pattern: ^[A-Za-z0-9\-_]{1,20}$
          example: R1234567890
        cashier_id:
          type: string
          description: An optional identifier for the cashier processing the order.
          pattern: ^[A-Za-z0-9\-_]{1,20}$
          example: C001
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code for which the product should be ordered.
          example: DE
          pattern: ^[A-Z]{2}$
        face_value:
          type: object
          description: Face value of the requested product.
          required:
            - currency
          properties:
            currency:
              type: string
              enum:
                - EUR
              pattern: ^[A-Z]{3}$
              description: Currency of the product.
              example: EUR
            amount:
              type: string
              description: Face value of the requested product. Only required if the product has a variable amount.
              pattern: ^-?[0-9]+\.[0-9]+$
              example: '100.0'
        receipt_printing:
          type: object
          required:
            - characters_per_line
            - locale
          properties:
            characters_per_line:
              type: integer
              description: The number of characters per line the receipt printer supports.
              minimum: 10
              maximum: 100
              example: 40
            locale:
              type: string
              description: The language the receipt is printed in, as [RFC 5646](https://tools.ietf.org/html/rfc5646) language-region code.
              pattern: ^[a-z]{2,3}-[A-Z]{2}$
              example: de-DE
    RetailOrderConfirm:
      type: object
      properties:
        payment_method:
          type: string
          description: An optional value describing the payment method used to pay for the order.
          enum:
            - cash
            - credit_card
            - debit_card
            - contactless_credit
            - contactless_debit
            - virtual_wallet
            - mobile_payment
            - other
            - not_available
        receipt_value:
          type: object
          description: An optional total amount paid for the final receipt and its currency.
          required:
            - currency
            - amount
          properties:
            currency:
              type: string
              enum:
                - EUR
              pattern: ^[A-Z]{3}$
              description: Currency of the total amount.
              example: EUR
            amount:
              type: string
              description: Total amount paid on the receipt for the order.
              pattern: ^-?[0-9]+\.[0-9]+$
              example: '120.0'
    RetailOrderResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the retail order.
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        product_code:
          type: string
          description: Unique code of the product ordered.
          pattern: ^[A-Za-z0-9]{4,255}$
          example: 4001232232332
        store_id:
          type: string
          description: The identifier of the retail store where the order was made.
          pattern: ^[0-9a-zA-Z\-_]{1,8}$
          example: A1234
        terminal_id:
          type: string
          description: The identifier of the terminal used for the order.
          pattern: ^[A-Za-z0-9\-_]{1,8}$
          example: T01
        receipt_id:
          type: string
          description: The identifier of the receipt for the order.
          pattern: ^[A-Za-z0-9\-_]{1,20}$
          example: R1234567890
        cashier_id:
          type:
            - string
            - 'null'
          description: An optional identifier for the cashier processing the order. Will be null or not returned if not provided.
          pattern: ^[A-Za-z0-9\-_]{1,20}$
          example: C001
        state:
          type: string
          description: Current state of the retail order.
          enum:
            - processing
            - completed
            - invalidated
            - failed
          example: completed
        face_value:
          type: object
          properties:
            currency:
              type: string
              enum:
                - EUR
              pattern: ^[A-Z]{3}$
              description: Currency of the product.
              example: EUR
            amount:
              type: string
              description: Face value of the requested product.
              pattern: ^-?[0-9]+\.[0-9]+$
              example: '100.0'
        distribution_scheme:
          type: string
          description: Describes whether the order sale was a `resale` or an `agency` sale.
          example: agency
          enum:
            - resale
            - agency
        receipt_printing:
          type: object
          properties:
            lines:
              type: array
              description: |
                The lines to print on the receipt. May be empty if no receipt is to be printed.

                Contains fallback receipt information if the confirmation fails and cannot be resolved.
              items:
                type: string
              example:
                - Thank you for your purchase!
                - 'Product Code: 4001232232332'
                - 'Face Value: 100.00 EUR'
    SettlementResponse:
      type: object
      properties:
        id:
          type: string
          description: The settlement's unique identifier.
          example: e887aa12-9d6d-4ed9-adf1-d7aeb9a1c2af
        settlement_identifier:
          type: string
          description: The settlement's human readable identifier used for settlements.
          example: CEX123-00001
        currency:
          type: string
          description: The settlement currency in ISO 4217 format.
          example: EUR
        total_amount:
          type: string
          description: The settlement total amount including VAT (if applicable) in the given currency. The value will be returned positive if money needs to be paid to finperks and negative if money would need to be paid by finperks (e.g. commissions).
          pattern: ^-?[0-9]+\.[0-9]+$
          example: '-100.23'
        period:
          type: object
          properties:
            from:
              type: string
              format: date
              description: The beginning date of the period covered by the settlement.
              example: '2026-01-01'
            to:
              type: string
              format: date
              description: The end date of the period covered by the settlement.
              example: '2026-01-31'
        settlement_date:
          type: string
          format: date
          description: The official settlement date in ISO 8601 format, representing the creation.
          example: '2026-02-05'
        payment_due_date:
          type: string
          format: date
          description: The date by which the settlement payment is due in ISO 8601 format.
          example: '2026-02-10'
        state:
          type: string
          description: |
            The settlement's current state. Possible values are: `pending`, `paid`.
          example: paid
        paid_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The settlement's paid timestamp in ISO 8601 format. The value is null if the settlement is not yet paid.
          example: 2026-02-08T15:30:00.000Z
    SettlementUpdateWebhook:
      type: object
      required:
        - id
        - event_scope
        - event
        - event_at
        - data
      properties:
        id:
          type: string
          description: Unique identifier of the webhook event. Will stay the same across retries
          maxLength: 40
          example: 5e943c75-2065-46cb-a74b-69a13e034333
        event_scope:
          type: string
          description: Scope in which the event is occuring. For settlement events this will always be `settlements`.
          example: settlements
        event:
          type: string
          description: A label for the type of event that occurred
          example: paid
          enum:
            - created
            - paid
        event_at:
          type: date-time
          description: Represents [RFC 3339, section 5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) date-time.
          example: 2025-07-16T18:16:12.000Z
        data:
          $ref: '#/components/schemas/SettlementResponse'
    StoreCreate:
      type: object
      required:
        - store_id
        - name
        - street_and_number
        - zipcode
        - city
        - country
        - latitude
        - longitude
        - opening_hours
      properties:
        store_id:
          description: An identifier for the store in the partner's system
          type: string
          example: A12345
        name:
          type: string
          example: Location XY
        street_and_number:
          type: string
          example: Uhlandstr. 32
        zipcode:
          type: string
          example: '10719'
        city:
          type: string
          example: Berlin
        country:
          type: string
          example: DE
        latitude:
          type: string
          pattern: ^-?[0-9]+\.[0-9]+$
          example: '52.5004185'
        longitude:
          type: string
          pattern: ^-?[0-9]+\.[0-9]+$
          example: '13.3222062'
        opening_hours:
          type: array
          description: Weekly opening hours of the store with one entry per day of the week. Days without an entry are considered closed.
          items:
            type: object
            required:
              - day
              - open
            properties:
              day:
                type: string
                enum:
                  - mon
                  - tue
                  - wed
                  - thu
                  - fri
                  - sat
                  - sun
                example: mon
              open:
                type: array
                description: Opening intervals for the day, e.g. two intervals if the store closes over lunch.
                items:
                  type: object
                  required:
                    - begin
                    - end
                  properties:
                    begin:
                      type: string
                      pattern: ^([01]\d|2[0-3]):?([0-5]\d)$
                      example: '09:00'
                    end:
                      type: string
                      pattern: ^([01]\d|2[0-3]):?([0-5]\d)$
                      example: '18:00'
        enabled:
          type: boolean
          description: Whether the store should be enabled or disabled for processing
          example: true
          default: false
    StoreUpdate:
      type: object
      properties:
        name:
          type: string
          example: Location XY
        street_and_number:
          type: string
          example: Uhlandstr. 32
        zipcode:
          type: string
          example: '10719'
        city:
          type: string
          example: Berlin
        country:
          type: string
          example: DE
        latitude:
          type: string
          pattern: ^-?[0-9]+\.[0-9]+$
          example: '52.5004185'
        longitude:
          type: string
          pattern: ^-?[0-9]+\.[0-9]+$
          example: '13.3222062'
        opening_hours:
          type: array
          description: Weekly opening hours of the store with one entry per day of the week. Days without an entry are considered closed.
          items:
            type: object
            required:
              - day
              - open
            properties:
              day:
                type: string
                enum:
                  - mon
                  - tue
                  - wed
                  - thu
                  - fri
                  - sat
                  - sun
                example: mon
              open:
                type: array
                description: Opening intervals for the day, e.g. two intervals if the store closes over lunch.
                items:
                  type: object
                  required:
                    - begin
                    - end
                  properties:
                    begin:
                      type: string
                      pattern: ^([01]\d|2[0-3]):?([0-5]\d)$
                      example: '09:00'
                    end:
                      type: string
                      pattern: ^([01]\d|2[0-3]):?([0-5]\d)$
                      example: '18:00'
        enabled:
          type: boolean
          description: Whether the store should be enabled or disabled for processing
          example: true
    StoreResponse:
      type: object
      properties:
        id:
          type: string
          description: An identifier unique for the client as provided on creation
          example: A12345
        name:
          type: string
          example: Location XY
        street_and_number:
          type: string
          example: Uhlandstr. 32
        zipcode:
          type: string
          example: '10719'
        city:
          type: string
          example: Berlin
        country:
          type: string
          example: DE
        latitude:
          type: string
          pattern: ^-?[0-9]+\.[0-9]+$
          example: '52.5004185'
        longitude:
          type: string
          pattern: ^-?[0-9]+\.[0-9]+$
          example: '13.3222062'
        opening_hours:
          type: array
          description: Weekly opening hours of the store with one entry per day of the week. Days without an entry are considered closed.
          items:
            type: object
            required:
              - day
              - open
            properties:
              day:
                type: string
                enum:
                  - mon
                  - tue
                  - wed
                  - thu
                  - fri
                  - sat
                  - sun
                example: mon
              open:
                type: array
                description: Opening intervals for the day, e.g. two intervals if the store closes over lunch.
                items:
                  type: object
                  required:
                    - begin
                    - end
                  properties:
                    begin:
                      type: string
                      pattern: ^([01]\d|2[0-3]):?([0-5]\d)$
                      example: '09:00'
                    end:
                      type: string
                      pattern: ^([01]\d|2[0-3]):?([0-5]\d)$
                      example: '18:00'
        enabled:
          type: boolean
          description: Whether the store is enabled or disabled for processing
          example: true