openapi: 3.0.4
info:
  title: Norce Checkout - Ingrid Adapter API
  description: |-
    Build 2026-01-14 12:35:46

    The Ingrid Adapter API is used to create and manage Ingrid shippings.
  version: 1.0.0
paths:
  /api/checkout/v1/callback/orders/{order_id}/shippings/{shipping_id}/update-ingrid-session:
    post:
      tags:
        - Norce Callbacks
      summary: Handle Cart changed in Norce order.
      description: Cart changed.
      operationId: CartChanged
      parameters:
        - name: x-merchant
          in: header
          description: Merchant identifier.
          required: true
          schema:
            type: string
            example: norce
          example: norce
        - name: x-channel
          in: header
          description: Channel identifier
          required: true
          schema:
            type: string
            example: '1'
          example: '1'
        - name: order_id
          in: path
          description: Order identifier
          required: true
          schema:
            type: string
        - name: shipping_id
          in: path
          description: Shipping identifier
          required: true
          schema:
            type: string
      requestBody:
        description: Updated order
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/NorceOrder'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PatchOperation'
        '404':
          description: Not Found
          content:
            application/json: {}
      security:
        - Bearer: []
  /api/checkout/v1/callback/orders/{order_id}/shippings/{shipping_id}/state-changed:
    post:
      tags:
        - Norce Callbacks
      summary: Handle State changed in Norce order.
      description: State changed.
      operationId: StateChanged
      parameters:
        - name: x-merchant
          in: header
          description: Merchant identifier.
          required: true
          schema:
            type: string
            example: norce
          example: norce
        - name: x-channel
          in: header
          description: Channel identifier
          required: true
          schema:
            type: string
            example: '1'
          example: '1'
        - name: order_id
          in: path
          description: Order identifier
          required: true
          schema:
            type: string
        - name: shipping_id
          in: path
          description: Shipping identifier
          required: true
          schema:
            type: string
      requestBody:
        description: Updated order
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/NorceOrder'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PatchOperation'
        '400':
          description: Bad Request
          content:
            application/json: {}
        '404':
          description: Not Found
          content:
            application/json: {}
      security:
        - Bearer: []
  /api/checkout/v1/callback/orders/{order_id}/shippings/{shipping_id}/shipping-changed:
    post:
      tags:
        - Ingrid client side callbacks
      summary: Shipping changed
      description: Shipping changed.
      operationId: ShippingChanged
      parameters:
        - name: x-merchant
          in: header
          description: Merchant identifier.
          required: true
          schema:
            type: string
            example: norce
          example: norce
        - name: x-channel
          in: header
          description: Channel identifier
          required: true
          schema:
            type: string
            example: '1'
          example: '1'
        - name: order_id
          in: path
          description: Order identifier
          required: true
          schema:
            type: string
        - name: shipping_id
          in: path
          description: Shipping identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json: {}
        '404':
          description: Not Found
          content:
            application/json: {}
      security:
        - Bearer: []
  /api/checkout/v1/callback/orders/{order_id}/shippings/{shipping_id}/customer-changed:
    post:
      tags:
        - Ingrid client side callbacks
      summary: Customer changed
      description: Customer changed inside ingrid shipping form.
      operationId: CustomerChanged
      parameters:
        - name: x-merchant
          in: header
          description: Merchant identifier.
          required: true
          schema:
            type: string
            example: norce
          example: norce
        - name: x-channel
          in: header
          description: Channel identifier
          required: true
          schema:
            type: string
            example: '1'
          example: '1'
        - name: order_id
          in: path
          description: Order identifier
          required: true
          schema:
            type: string
        - name: shipping_id
          in: path
          description: Shipping identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json: {}
        '404':
          description: Not Found
          content:
            application/json: {}
      security:
        - Bearer: []
  /api/checkout/v1/orders/{order_id}/shippings:
    post:
      tags:
        - Ingrid Delivery Experience Orders
      summary: Create a new Ingrid session
      description: Requires an existing order.
      operationId: CreateIngridSession
      parameters:
        - name: order_id
          in: path
          description: Order identifier
          required: true
          schema:
            type: string
        - name: x-merchant
          in: header
          description: Merchant identifier.
          required: true
          schema:
            type: string
            example: norce
          example: norce
        - name: x-channel
          in: header
          description: Channel identifier
          required: true
          schema:
            type: string
            example: '1'
          example: '1'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngridSession'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - Bearer: []
  /api/checkout/v1/orders/{order_id}/shippings/{shipping_id}:
    get:
      tags:
        - Ingrid Delivery Experience Orders
      summary: Get Ingrid session
      description: Used to get the html snippet
      operationId: GetIngridSession
      parameters:
        - name: order_id
          in: path
          description: Order identifier
          required: true
          schema:
            type: string
        - name: shipping_id
          in: path
          description: Shipping identifier
          required: true
          schema:
            type: string
        - name: x-merchant
          in: header
          description: Merchant identifier.
          required: true
          schema:
            type: string
            example: norce
          example: norce
        - name: x-channel
          in: header
          description: Channel identifier
          required: true
          schema:
            type: string
            example: '1'
          example: '1'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngridSession'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - Bearer: []
  /api/checkout/v1/orders/{order_id}/shippings/{shipping_id}/remove:
    post:
      tags:
        - Ingrid Delivery Experience Orders
      summary: Remove an ingrid payment
      description: Requires an existing order.
      operationId: RemoveIngridSession
      parameters:
        - name: order_id
          in: path
          description: Order identifier
          required: true
          schema:
            type: string
        - name: shipping_id
          in: path
          description: Shipping identifier
          required: true
          schema:
            type: string
        - name: x-merchant
          in: header
          description: Merchant identifier.
          required: true
          schema:
            type: string
            example: norce
          example: norce
        - name: x-channel
          in: header
          description: Channel identifier
          required: true
          schema:
            type: string
            example: '1'
          example: '1'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngridSession'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - Bearer: []
components:
  schemas:
    Addon:
      type: object
      properties:
        reference:
          type: string
        price:
          type: number
          format: double
      additionalProperties: false
    Address:
      type: object
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/CustomerType'
        givenName:
          type: string
        familyName:
          type: string
        careOf:
          type: string
        reference:
          type: string
        organizationName:
          type: string
        streetAddress:
          type: string
        streetAddress2:
          type: string
        postalCode:
          type: string
        city:
          type: string
        region:
          type: string
        country:
          type: string
        phone:
          type: string
        email:
          type: string
        nationalIdentificationNumber:
          type: string
        organizationIdentificationNumber:
          type: string
        attributes:
          type: object
          additionalProperties:
            nullable: true
      additionalProperties: false
    Callback:
      type: object
      properties:
        id:
          type: string
        adapterId:
          type: string
        event:
          allOf:
            - $ref: '#/components/schemas/CallbackEvent'
        url:
          type: string
      additionalProperties: false
    CallbackEvent:
      enum:
        - validate
        - accept
        - complete
      type: string
    Cart:
      type: object
      properties:
        reference:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/Discount'
        total:
          allOf:
            - $ref: '#/components/schemas/Price'
        attributes:
          type: object
          additionalProperties:
            nullable: true
      additionalProperties: false
    Consent:
      type: object
      properties:
        id:
          type: string
        checked:
          type: boolean
        text:
          type: string
        required:
          type: boolean
      additionalProperties: false
    Customer:
      type: object
      properties:
        billing:
          allOf:
            - $ref: '#/components/schemas/Address'
        shipping:
          allOf:
            - $ref: '#/components/schemas/Address'
        type:
          allOf:
            - $ref: '#/components/schemas/CustomerType'
        attributes:
          type: object
          additionalProperties:
            nullable: true
      additionalProperties: false
    CustomerType:
      enum:
        - person
        - organization
      type: string
    Delivery:
      type: object
      properties:
        reference:
          type: string
        deliveryDetails:
          allOf:
            - $ref: '#/components/schemas/DeliveryDetails'
        addons:
          type: array
          items:
            $ref: '#/components/schemas/Addon'
        price:
          allOf:
            - $ref: '#/components/schemas/Price'
        vatRate:
          type: number
          format: double
        items:
          type: array
          items:
            $ref: '#/components/schemas/DeliveryItem'
      additionalProperties: false
    DeliveryDetails:
      type: object
      properties:
        carrier:
          type: string
        carrierProductId:
          type: string
        class:
          type: string
        product:
          allOf:
            - $ref: '#/components/schemas/Product'
        pickupLocation:
          allOf:
            - $ref: '#/components/schemas/PickupLocation'
      additionalProperties: false
    DeliveryItem:
      type: object
      properties:
        sku:
          type: string
        quantity:
          type: integer
          format: int32
      additionalProperties: false
    Discount:
      type: object
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/DiscountType'
        name:
          type: string
        code:
          type: string
        value:
          allOf:
            - $ref: '#/components/schemas/Price'
        attributes:
          type: object
          additionalProperties:
            nullable: true
      additionalProperties: false
    DiscountType:
      enum:
        - item
        - shipping
      type: string
    Error:
      type: object
      properties:
        code:
          enum:
            - internal-server-error
            - unauthorized
            - configuration-error
            - configuration-not-found
            - order-not-found
            - order-error
            - order-bad-request
            - order-conflict
            - order-validation
            - order-unknown-validation-error
            - shipping-not-found
            - shipping-error
            - payment-not-found
            - payment-error
            - payment-conflict
            - ingrid-error
            - ingrid-validation
            - ingrid-empty-cart-not-allowed
            - ingrid-bad-request
            - translation-not-found
          type: string
          description: Error code
          example: ingrid-error
        message:
          type: string
          description: Detailed error information
          example: No warehouse configured for this region
        ingridError:
          allOf:
            - $ref: '#/components/schemas/IngridError'
          description: Error if originating from Ingrid
      additionalProperties: false
    Hook:
      type: object
      properties:
        id:
          type: string
        adapterId:
          type: string
        subscribeTo:
          type: string
        target:
          type: string
        invoke:
          type: string
      additionalProperties: false
    IngridError:
      type: object
      properties:
        errorCode:
          type: string
        errorMessages:
          type: array
          items:
            type: string
        correlationId:
          type: string
      additionalProperties: false
    IngridSession:
      type: object
      properties:
        shippingId:
          type: string
          description: Shipping identifier
        htmlSnippet:
          type: string
          description: Ingrid html snippet
        sessionId:
          type: string
          description: Session id
        useAddressForm:
          type: boolean
          description: Use address form
      additionalProperties: false
    Item:
      type: object
      properties:
        id:
          type: string
        reference:
          type: string
        name:
          type: string
        sku:
          type: string
        url:
          type: string
        imageUrl:
          type: string
        quantity:
          type: integer
          format: int32
        unit:
          type: string
        price:
          allOf:
            - $ref: '#/components/schemas/Price'
        total:
          allOf:
            - $ref: '#/components/schemas/Price'
        originalTotal:
          allOf:
            - $ref: '#/components/schemas/Price'
        vatRate:
          type: number
          format: double
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/Discount'
        logistics:
          allOf:
            - $ref: '#/components/schemas/Logistics'
        attributes:
          type: object
          additionalProperties:
            nullable: true
      additionalProperties: false
    Logistics:
      type: object
      properties:
        weight:
          type: integer
          format: int32
        height:
          type: integer
          format: int32
        width:
          type: integer
          format: int32
        length:
          type: integer
          format: int32
        tags:
          type: array
          items:
            type: string
        shippingDate:
          type: string
          format: date-time
      additionalProperties: false
    NorceOrder:
      type: object
      properties:
        id:
          type: string
        merchant:
          type: string
        channel:
          type: string
        reference:
          type: string
        created:
          type: string
          format: date-time
        lastModified:
          type: string
          format: date-time
        state:
          allOf:
            - $ref: '#/components/schemas/State'
        culture:
          type: string
        currency:
          type: string
        country:
          type: string
        cart:
          allOf:
            - $ref: '#/components/schemas/Cart'
        shippings:
          type: array
          items:
            $ref: '#/components/schemas/Shipping'
        payments:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
        customer:
          allOf:
            - $ref: '#/components/schemas/Customer'
        consents:
          type: array
          items:
            $ref: '#/components/schemas/Consent'
        validations:
          type: array
          items:
            $ref: '#/components/schemas/Callback'
        hooks:
          type: array
          items:
            $ref: '#/components/schemas/Hook'
        notifications:
          type: array
          items:
            $ref: '#/components/schemas/Callback'
        total:
          allOf:
            - $ref: '#/components/schemas/Price'
        attributes:
          type: object
          additionalProperties:
            nullable: true
      additionalProperties: false
    OrderStatus:
      enum:
        - checkout
        - processing
        - accepted
        - completed
        - declined
        - removed
      type: string
    PatchOperation:
      type: object
      properties:
        op:
          type: string
        path:
          type: string
        value: {}
      additionalProperties: false
    Payment:
      type: object
      properties:
        id:
          type: string
        adapterId:
          type: string
        name:
          type: string
        merchant:
          type: string
        channel:
          type: string
        currency:
          type: string
        type:
          allOf:
            - $ref: '#/components/schemas/PaymentType'
        orderId:
          type: string
        amount:
          type: number
          format: double
        upperLimitAmount:
          type: number
          format: double
        state:
          allOf:
            - $ref: '#/components/schemas/PaymentState'
        reference:
          type: string
        attributes:
          type: object
          additionalProperties:
            nullable: true
        actions:
          type: array
          items:
            $ref: '#/components/schemas/PaymentAction'
        recurring:
          allOf:
            - $ref: '#/components/schemas/Recurring'
      additionalProperties: false
    PaymentAction:
      type: object
      properties:
        id:
          type: string
        adapterId:
          type: string
        type:
          type: string
        url:
          type: string
      additionalProperties: false
    PaymentState:
      enum:
        - intent
        - removed
        - processing
        - failed
        - confirmed
        - pending
        - declined
        - reserved
        - credited
        - captured
        - cancelled
        - refunded
      type: string
    PaymentType:
      enum:
        - default
        - prepaid
        - voucher
      type: string
    PickupLocation:
      type: object
      properties:
        reference:
          type: string
        name:
          type: string
        address:
          allOf:
            - $ref: '#/components/schemas/PickupLocationAddress'
      additionalProperties: false
    PickupLocationAddress:
      type: object
      properties:
        streetAddress:
          type: string
        city:
          type: string
        postalCode:
          type: string
        country:
          type: string
      additionalProperties: false
    Price:
      type: object
      properties:
        includingVat:
          type: number
          format: double
        excludingVat:
          type: number
          format: double
      additionalProperties: false
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
          format: int32
        detail:
          type: string
        instance:
          type: string
      additionalProperties: {}
    Product:
      type: object
      properties:
        reference:
          type: string
        name:
          type: string
      additionalProperties: false
    Recurring:
      type: object
      properties:
        token:
          type: string
        description:
          type: string
        attributes:
          type: object
          additionalProperties:
            nullable: true
      additionalProperties: false
    Shipping:
      type: object
      properties:
        id:
          type: string
        merchant:
          type: string
        channel:
          type: string
        state:
          allOf:
            - $ref: '#/components/schemas/ShippingState'
        reference:
          type: string
        tmsReference:
          type: string
        orderId:
          type: string
        adapterId:
          type: string
        name:
          type: string
        total:
          allOf:
            - $ref: '#/components/schemas/Price'
        vatRate:
          type: number
          format: double
        deliveryDetails:
          allOf:
            - $ref: '#/components/schemas/DeliveryDetails'
        addons:
          type: array
          items:
            $ref: '#/components/schemas/Addon'
        deliveries:
          type: array
          items:
            $ref: '#/components/schemas/Delivery'
        attributes:
          type: object
          additionalProperties:
            nullable: true
      additionalProperties: false
    ShippingState:
      enum:
        - intent
        - removed
        - processing
        - failed
        - confirmed
      type: string
    State:
      type: object
      properties:
        currentStatus:
          allOf:
            - $ref: '#/components/schemas/OrderStatus'
        transitions:
          type: array
          items:
            $ref: '#/components/schemas/Transition'
      additionalProperties: false
    Transition:
      type: object
      properties:
        status:
          allOf:
            - $ref: '#/components/schemas/OrderStatus'
        timeStamp:
          type: string
          format: date-time
      additionalProperties: false
  securitySchemes:
    Bearer:
      type: apiKey
      description: >-
        Authorization header using the bearer scheme. Example: 'Bearer
        a3bcdABCaB12abc3AbCDAB5AbcABCaBcABC5ab3c5A0='
      name: Authorization
      in: header
