fabric Checkout Session API

openapi: 3.0.1
info:
  title: Cart Actions Endpoints Checkout Session API
  description: fabric's **Cart API** lets you add, update, and remove items from your Storefront cart, either as a guest user or as a logged-in user. It also provides functionality to merge carts when you switch from guest user to logged-in user, and apply coupons and other attributes (for example, gift wrapping) to the line items. Additionally, the API supports more advanced tasks such as using multiple carts within a B2B organization, sharing carts, and supporting a unified cart experience for multi-region and multi-brand businesses.<p>The Cart API provides high performance, scalability, multi-tenancy, and configurability to the end-to-end order processing actions that start from the item being added to the cart; through the pre-checkout stage that includes billing, shipping, and payment details; to the checkout stage where the order is processed and confirmed by fabric's Order Management System (OMS)
  contact:
    name: Cart Support
    email: support.cnc@fabric.inc
  license:
    name: fabric API License
    url: https://fabric.inc/api-license
  version: 3.0.0
servers:
- url: https://api.fabric.inc/v3
security:
- bearerAuth: []
tags:
- name: Checkout Session
  description: The Checkout Session endpoint lets you create and complete a checkout session, and place an order for the cart items.
paths:
  /checkout/sessions:
    post:
      tags:
      - Checkout Session
      summary: Create and Complete a Checkout Session
      description: Create and complete checkout session on all the items in a specific cart, identified by a `cartId`. Along with `cartId`, the checkout operation includes merchant account ID, amount to be paid, tax to be imposed on cart items, shipping address, and other details.
      operationId: createSession
      parameters:
      - $ref: '#/components/parameters/xFabricTenantId'
      - $ref: '#/components/parameters/xFabricChannelId'
      - $ref: '#/components/parameters/xFabricRequestId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/checkoutSessionRequest'
        required: true
      responses:
        '200':
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/checkoutSessionResponse'
              example:
                state: COMPLETED
                orderId: 111-121-1234
        '400':
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error400'
        '401':
          description: Unauthorized
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error401'
        '404':
          description: Not found
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestId'
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/cartNotFound'
                - $ref: '#/components/schemas/lineItemShippingDetailsNotFound'
        '424':
          description: Dependency failure
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/checkoutSessionErrorResponse'
        '500':
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error500'
components:
  schemas:
    shippingTaxes:
      description: Shipping taxes
      type: object
      required:
      - shippingDetailsId
      properties:
        shippingDetailsId:
          type: string
          description: Unique shipping ID
          nullable: true
          example: fef78121-bee3-4448-bf1c-d5b5461dbda2
        amount:
          type: number
          format: double
          description: Currency amount
          example: 150.25
        currency:
          type: string
          description: Three-letter currency code as defined by ISO-4217
          example: USD
        name:
          type: string
          description: Tax name
          nullable: true
          example: state tax
    name:
      description: Individual's name
      type: object
      properties:
        firstName:
          type: string
          description: Individual's first name
          example: Pat
        middleName:
          type: string
          description: Individual's middle name or initial
          nullable: true
          example: E
        lastName:
          type: string
          description: Individual's last name
          example: Kake
    money:
      type: object
      description: Payment amount
      properties:
        amount:
          type: number
          format: double
          description: Currency amount
          example: 150.25
        currency:
          type: string
          description: Three-letter currency code as defined by ISO-4217
          example: USD
    billingPhone:
      description: Individual's phone details (for billing purposes)
      type: object
      properties:
        number:
          type: string
          description: Phone number
          example: 123-456-7890
        type:
          type: string
          description: Phone type
          nullable: true
          example: office
    cartNotFound:
      type: object
      description: Cart not found error
      properties:
        type:
          description: Error code
          type: string
          example: NOT_FOUND
        message:
          description: Error description
          type: string
          example: Cart not found
    dependencyFailure:
      description: Checkout dependency failure type
      type: string
      example: PAYMENT
      enum:
      - CART
      - PAYMENT
      - ORDER
    note:
      description: Notes section for use by customer service representative only
      type: object
      properties:
        notedAt:
          allOf:
          - $ref: '#/components/schemas/date'
          - description: Time note was created
        user:
          type: string
          description: Customer service representative ID
          nullable: true
          example: 261AF48
        notes:
          type: string
          description: Note content
          nullable: true
          example: Additional notes...
    checkoutSessionErrorResponse:
      description: Checkout error response details
      type: object
      properties:
        type:
          type: string
          description: Error type
          example: PAYMENT_FAILURE
        message:
          type: string
          description: Error description
          example: Payment authorization failed due to payment mismatch
        pointOfFailure:
          $ref: '#/components/schemas/dependencyFailure'
        details:
          type: object
          description: Error details
          oneOf:
          - $ref: '#/components/schemas/paymentErrorResponse'
    itemTaxes:
      description: Cart line item tax
      type: object
      properties:
        lineItemId:
          type: string
          description: Line item ID
          example: d7e78a21-bee3-4448-bf1c-d5b5461dbda2
        position:
          type: integer
          description: Item sequence number
          format: int32
          example: 1
        amount:
          type: number
          format: double
          description: Currency amount
          example: 150.25
        currency:
          type: string
          description: Three-letter currency code as defined by ISO-4217
          example: USD
        name:
          type: string
          description: Tax name
          nullable: true
          example: state tax
        rateType:
          type: string
          description: Rate type
          nullable: true
          example: PERCENTAGE
        rate:
          type: number
          description: Rate
          format: double
          nullable: true
          example: 10
    feeTaxes:
      description: Fee taxes
      type: object
      required:
      - feeId
      properties:
        feeId:
          type: string
          description: Unique fee tax ID
          example: fef78121-bee3-4448-bf1c-d5b5461dbda2
        name:
          type: string
          description: Fee tax type
          nullable: true
          example: State tax
        amount:
          type: number
          format: double
          description: Fee tax amount
          example: 150.25
        currency:
          type: string
          description: Three-letter currency code as defined by ISO-4217
          example: USD
    error401:
      type: object
      description: Unauthorized error
      properties:
        type:
          description: Error type
          type: string
          example: UNAUTHORIZED
        message:
          description: Error description
          type: string
          example: Unauthorized user
    paymentDetailsRequest:
      description: Payment request details.Empty if there is no payment configuration.
      type: object
      required:
      - paymentProvider
      properties:
        paymentProvider:
          type: string
          description: Payment gateway service provider
          example: authorize.net
        paymentMethod:
          type: string
          description: Payment method
          nullable: true
          example: card
        paymentToken:
          type: object
          properties:
            token:
              type: string
              description: Payment token
              example: pi_34tr6787rt
            paymentType:
              type: string
              description: Payment type, for credit card payments
              example: VISA
          description: Order payment token model
        amount:
          type: number
          format: double
          description: Payment amount
          example: 150.25
        currency:
          type: string
          description: Three-letter currency code as defined by ISO-4217
          example: USD
        billingAddress:
          $ref: '#/components/schemas/billingAddress'
        attributes:
          type: object
          additionalProperties: true
          description: Additional data passed by the caller
          nullable: true
          example:
            paymentId: 620d8896058edb0009385311
    billingAddress:
      allOf:
      - $ref: '#/components/schemas/customerAddress'
      - description: Billing address
        type: object
        properties:
          name:
            $ref: '#/components/schemas/name'
          phone:
            $ref: '#/components/schemas/billingPhone'
          email:
            type: string
            description: Receiver email ID
            example: user@example.com
          customerId:
            type: string
            description: Customer profile ID, created by the payment gateway, for payment instruction. This ID is specific to payment flow.
            nullable: true
            example: 62cffd65e8d7eb868c6a29d6
          type:
            type: string
            description: Address type
            nullable: true
            example: residence
          latitude:
            type: number
            format: double
            description: Address latitude
            nullable: true
            example: 47.6205
          longitude:
            type: number
            format: double
            description: Address longitude
            nullable: true
            example: -122.3493
    checkoutSessionResponse:
      description: Checkout response details
      type: object
      properties:
        state:
          type: string
          enum:
          - COMPLETED
          - PENDING
          description: 'Checkout session state.<br />COMPLETED: Checkout is complete<br />PENDING: Checkout is incomplete'
          example: COMPLETED
        orderId:
          type: string
          description: Order ID
          nullable: true
          example: 111-123-4421
    customerAddress:
      type: object
      description: Customer's address
      properties:
        addressLine1:
          description: Address line 1
          type: string
          example: 123 Main St.
        addressLine2:
          description: Address line 2
          type: string
          example: Suite 100
        addressLine3:
          type: string
          description: Address line 3
          example: Seventh floor
        addressLine4:
          type: string
          description: Address line 4
          example: 'Attention: Pat E. Kake'
        city:
          description: City
          type: string
          example: Seattle
        region:
          type: string
          description: Region or state
          example: WA
        postalCode:
          type: string
          description: Postal or zip code
          example: '98121'
        country:
          description: Country (can be full name, or ISO 3166-1 alpha-2 or alpha-3 code)
          type: string
          example: US
    error400:
      type: object
      description: Bad request
      properties:
        type:
          description: Error type
          type: string
          example: BAD_REQUEST
        message:
          description: Error description
          type: string
          example: Bad Request
    lineItemShippingDetailsNotFound:
      type: object
      description: Ship to not found error
      properties:
        type:
          description: Error code
          type: string
          example: NOT_FOUND
        message:
          description: Error description
          type: string
          example: Cart item ship to's are missing.
    date:
      description: Date and time in ISO-8601 format
      type: string
      format: date-time
      example: '2022-09-06T14:07:17.000Z'
    error500:
      type: object
      description: Internal server error
      properties:
        type:
          description: Error type
          type: string
          example: INTERNAL_SERVER_ERROR
        message:
          description: Error description
          type: string
          example: Internal server error
    checkoutSessionRequest:
      description: Checkout request body
      required:
      - cartId
      - payments
      - tax
      type: object
      properties:
        cartId:
          type: string
          description: Unique cart ID
          example: d7e78a21-bee3-4448-bf1c-d5b5461dbda2
        customer:
          description: Customer making payment
          type: object
          properties:
            name:
              type: object
              properties:
                firstName:
                  type: string
                  description: Contact person's first name
                  example: Pat
                middleName:
                  type: string
                  description: Contact person's middle name or initial
                  example: E
                lastName:
                  type: string
                  description: Contact person's last name
                  example: Kake
              description: Order contact person's details
            email:
              type: string
              description: Contact person's email
              example: test@example.com
            phone:
              type: object
              properties:
                number:
                  type: string
                  description: Contact person's phone number
                  example: '5555555555'
                type:
                  type: string
                  description: Contact number type
                  example: MOBILE
                  enum:
                  - MOBILE
                  - HOME
                  - BUSINESS
              description: Contact person's phone number
            userId:
              type: string
              description: User ID
              example: 62272e917b12209e68751d94
            accountId:
              type: string
              description: Account ID such as loyalty account ID
              example: 62272e917b12209e68751d94
            employeeId:
              type: string
              description: Employee ID used when the customer is the employee
              example: 62272e917b12209e68751d94
            company:
              type: string
              description: Company
              example: fabric
        payments:
          type: array
          description: Payment detail list
          items:
            $ref: '#/components/schemas/paymentDetailsRequest'
        tax:
          $ref: '#/components/schemas/estimatedTax'
        orderMetadata:
          type: object
          description: Additional order information
          properties:
            orderType:
              type: string
              description: Order type (WEB, CSC, MOBILE_APP, POS, etc.)
              nullable: true
              example: MOBILE_APP
            orderSubtype:
              type: string
              description: Order subtype (Android, IOS, International, etc.)
              nullable: true
              example: Android
            notes:
              type: array
              description: Customer service representative's notes
              items:
                $ref: '#/components/schemas/note'
    paymentErrorResponse:
      description: Payment mismatch response details. It's displayed when `totalAmount` and `orderTotal` are different. The user must authorize payment of the total order amount.
      type: object
      properties:
        paymentError:
          type: object
          description: Indicates payment error details
          properties:
            totalAmount:
              allOf:
              - $ref: '#/components/schemas/money'
              - description: Total authorized amount
            orderTotal:
              allOf:
              - $ref: '#/components/schemas/money'
              - description: Order total. It includes cart amount + taxes.
    estimatedTax:
      description: Estimated taxes for items, shipping and fees
      required:
      - itemTaxes
      - shippingTaxes
      type: object
      properties:
        itemTaxes:
          type: array
          description: Item taxes
          items:
            $ref: '#/components/schemas/itemTaxes'
        shippingTaxes:
          type: array
          description: Shipping taxes
          items:
            $ref: '#/components/schemas/shippingTaxes'
        feeTaxes:
          type: array
          description: Taxes related to fees
          nullable: true
          items:
            $ref: '#/components/schemas/feeTaxes'
  parameters:
    xFabricTenantId:
      in: header
      name: x-fabric-tenant-id
      description: A header used by fabric to identify the tenant making the request. You must include tenant id in the authentication header for an API request to access any of fabric’s endpoints. You can retrieve the tenant id , which is also called account id, from [Copilot](/v3/platform/settings/account-details/getting-the-account-id). This header is required.
      schema:
        type: string
      example: 617329dfd5288b0011332311
      required: true
    xFabricRequestId:
      in: header
      name: x-fabric-request-id
      description: Unique request ID
      schema:
        type: string
      example: 263e731c-45c8-11ed-b878-0242ac120002
      required: false
    xFabricChannelId:
      in: header
      name: x-fabric-channel-id
      description: x-fabric-channel-id identifies the sales channel where the API request is being made; primarily for multichannel use cases. The channel ids are 12 corresponding to US and 13 corresponding to Canada. The default channel id is 12. This field is required.
      schema:
        type: string
      example: '12'
      required: false
  headers:
    xFabricRequestId:
      description: Unique request ID
      schema:
        type: string
      example: 263e731c-45c8-11ed-b878-0242ac120002
      required: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'This is the authorization token used to authenticate the request. You must pass the access token generated from the system app. For more information, see the [Making your first API request](/v3/api-reference/getting-started/getting-started-with-fabric-apis#procedure) section.

        '